ofnode.h 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Copyright (c) 2017 Google, Inc
  4. * Written by Simon Glass <sjg@chromium.org>
  5. */
  6. #ifndef _DM_OFNODE_H
  7. #define _DM_OFNODE_H
  8. /* TODO(sjg@chromium.org): Drop fdtdec.h include */
  9. #include <fdtdec.h>
  10. #include <dm/of.h>
  11. /* Enable checks to protect against invalid calls */
  12. #undef OF_CHECKS
  13. struct resource;
  14. /**
  15. * ofnode - reference to a device tree node
  16. *
  17. * This union can hold either a straightforward pointer to a struct device_node
  18. * in the live device tree, or an offset within the flat device tree. In the
  19. * latter case, the pointer value is just the integer offset within the flat DT.
  20. *
  21. * Thus we can reference nodes in both the live tree (once available) and the
  22. * flat tree (until then). Functions are available to translate between an
  23. * ofnode and either an offset or a struct device_node *.
  24. *
  25. * The reference can also hold a null offset, in which case the pointer value
  26. * here is NULL. This corresponds to a struct device_node * value of
  27. * NULL, or an offset of -1.
  28. *
  29. * There is no ambiguity as to whether ofnode holds an offset or a node
  30. * pointer: when the live tree is active it holds a node pointer, otherwise it
  31. * holds an offset. The value itself does not need to be unique and in theory
  32. * the same value could point to a valid device node or a valid offset. We
  33. * could arrange for a unique value to be used (e.g. by making the pointer
  34. * point to an offset within the flat device tree in the case of an offset) but
  35. * this increases code size slightly due to the subtraction. Since it offers no
  36. * real benefit, the approach described here seems best.
  37. *
  38. * For now these points use constant types, since we don't allow writing
  39. * the DT.
  40. *
  41. * @np: Pointer to device node, used for live tree
  42. * @of_offset: Pointer into flat device tree, used for flat tree. Note that this
  43. * is not a really a pointer to a node: it is an offset value. See above.
  44. */
  45. typedef union ofnode_union {
  46. const struct device_node *np; /* will be used for future live tree */
  47. long of_offset;
  48. } ofnode;
  49. struct ofnode_phandle_args {
  50. ofnode node;
  51. int args_count;
  52. uint32_t args[OF_MAX_PHANDLE_ARGS];
  53. };
  54. /**
  55. * _ofnode_to_np() - convert an ofnode to a live DT node pointer
  56. *
  57. * This cannot be called if the reference contains an offset.
  58. *
  59. * @node: Reference containing struct device_node * (possibly invalid)
  60. * @return pointer to device node (can be NULL)
  61. */
  62. static inline const struct device_node *ofnode_to_np(ofnode node)
  63. {
  64. #ifdef OF_CHECKS
  65. if (!of_live_active())
  66. return NULL;
  67. #endif
  68. return node.np;
  69. }
  70. /**
  71. * ofnode_to_offset() - convert an ofnode to a flat DT offset
  72. *
  73. * This cannot be called if the reference contains a node pointer.
  74. *
  75. * @node: Reference containing offset (possibly invalid)
  76. * @return DT offset (can be -1)
  77. */
  78. static inline int ofnode_to_offset(ofnode node)
  79. {
  80. #ifdef OF_CHECKS
  81. if (of_live_active())
  82. return -1;
  83. #endif
  84. return node.of_offset;
  85. }
  86. /**
  87. * ofnode_valid() - check if an ofnode is valid
  88. *
  89. * @return true if the reference contains a valid ofnode, false if it is NULL
  90. */
  91. static inline bool ofnode_valid(ofnode node)
  92. {
  93. if (of_live_active())
  94. return node.np != NULL;
  95. else
  96. return node.of_offset != -1;
  97. }
  98. /**
  99. * offset_to_ofnode() - convert a DT offset to an ofnode
  100. *
  101. * @of_offset: DT offset (either valid, or -1)
  102. * @return reference to the associated DT offset
  103. */
  104. static inline ofnode offset_to_ofnode(int of_offset)
  105. {
  106. ofnode node;
  107. if (of_live_active())
  108. node.np = NULL;
  109. else
  110. node.of_offset = of_offset;
  111. return node;
  112. }
  113. /**
  114. * np_to_ofnode() - convert a node pointer to an ofnode
  115. *
  116. * @np: Live node pointer (can be NULL)
  117. * @return reference to the associated node pointer
  118. */
  119. static inline ofnode np_to_ofnode(const struct device_node *np)
  120. {
  121. ofnode node;
  122. node.np = np;
  123. return node;
  124. }
  125. /**
  126. * ofnode_is_np() - check if a reference is a node pointer
  127. *
  128. * This function associated that if there is a valid live tree then all
  129. * references will use it. This is because using the flat DT when the live tree
  130. * is valid is not permitted.
  131. *
  132. * @node: reference to check (possibly invalid)
  133. * @return true if the reference is a live node pointer, false if it is a DT
  134. * offset
  135. */
  136. static inline bool ofnode_is_np(ofnode node)
  137. {
  138. #ifdef OF_CHECKS
  139. /*
  140. * Check our assumption that flat tree offsets are not used when a
  141. * live tree is in use.
  142. */
  143. assert(!ofnode_valid(node) ||
  144. (of_live_active() ? _ofnode_to_np(node)
  145. : _ofnode_to_np(node)));
  146. #endif
  147. return of_live_active() && ofnode_valid(node);
  148. }
  149. /**
  150. * ofnode_equal() - check if two references are equal
  151. *
  152. * @return true if equal, else false
  153. */
  154. static inline bool ofnode_equal(ofnode ref1, ofnode ref2)
  155. {
  156. /* We only need to compare the contents */
  157. return ref1.of_offset == ref2.of_offset;
  158. }
  159. /**
  160. * ofnode_null() - Obtain a null ofnode
  161. *
  162. * This returns an ofnode which points to no node. It works both with the flat
  163. * tree and livetree.
  164. */
  165. static inline ofnode ofnode_null(void)
  166. {
  167. ofnode node;
  168. if (of_live_active())
  169. node.np = NULL;
  170. else
  171. node.of_offset = -1;
  172. return node;
  173. }
  174. /**
  175. * ofnode_read_u32() - Read a 32-bit integer from a property
  176. *
  177. * @ref: valid node reference to read property from
  178. * @propname: name of the property to read from
  179. * @outp: place to put value (if found)
  180. * @return 0 if OK, -ve on error
  181. */
  182. int ofnode_read_u32(ofnode node, const char *propname, u32 *outp);
  183. /**
  184. * ofnode_read_s32() - Read a 32-bit integer from a property
  185. *
  186. * @ref: valid node reference to read property from
  187. * @propname: name of the property to read from
  188. * @outp: place to put value (if found)
  189. * @return 0 if OK, -ve on error
  190. */
  191. static inline int ofnode_read_s32(ofnode node, const char *propname,
  192. s32 *out_value)
  193. {
  194. return ofnode_read_u32(node, propname, (u32 *)out_value);
  195. }
  196. /**
  197. * ofnode_read_u32_default() - Read a 32-bit integer from a property
  198. *
  199. * @ref: valid node reference to read property from
  200. * @propname: name of the property to read from
  201. * @def: default value to return if the property has no value
  202. * @return property value, or @def if not found
  203. */
  204. u32 ofnode_read_u32_default(ofnode ref, const char *propname, u32 def);
  205. /**
  206. * ofnode_read_s32_default() - Read a 32-bit integer from a property
  207. *
  208. * @ref: valid node reference to read property from
  209. * @propname: name of the property to read from
  210. * @def: default value to return if the property has no value
  211. * @return property value, or @def if not found
  212. */
  213. int ofnode_read_s32_default(ofnode node, const char *propname, s32 def);
  214. /**
  215. * ofnode_read_u64() - Read a 64-bit integer from a property
  216. *
  217. * @node: valid node reference to read property from
  218. * @propname: name of the property to read from
  219. * @outp: place to put value (if found)
  220. * @return 0 if OK, -ve on error
  221. */
  222. int ofnode_read_u64(ofnode node, const char *propname, u64 *outp);
  223. /**
  224. * ofnode_read_u64_default() - Read a 64-bit integer from a property
  225. *
  226. * @ref: valid node reference to read property from
  227. * @propname: name of the property to read from
  228. * @def: default value to return if the property has no value
  229. * @return property value, or @def if not found
  230. */
  231. u64 ofnode_read_u64_default(ofnode node, const char *propname, u64 def);
  232. /**
  233. * ofnode_read_string() - Read a string from a property
  234. *
  235. * @ref: valid node reference to read property from
  236. * @propname: name of the property to read
  237. * @return string from property value, or NULL if there is no such property
  238. */
  239. const char *ofnode_read_string(ofnode node, const char *propname);
  240. /**
  241. * ofnode_read_u32_array() - Find and read an array of 32 bit integers
  242. *
  243. * @node: valid node reference to read property from
  244. * @propname: name of the property to read
  245. * @out_values: pointer to return value, modified only if return value is 0
  246. * @sz: number of array elements to read
  247. * @return 0 if OK, -ve on error
  248. *
  249. * Search for a property in a device node and read 32-bit value(s) from
  250. * it. Returns 0 on success, -EINVAL if the property does not exist,
  251. * -ENODATA if property does not have a value, and -EOVERFLOW if the
  252. * property data isn't large enough.
  253. *
  254. * The out_values is modified only if a valid u32 value can be decoded.
  255. */
  256. int ofnode_read_u32_array(ofnode node, const char *propname,
  257. u32 *out_values, size_t sz);
  258. /**
  259. * ofnode_read_bool() - read a boolean value from a property
  260. *
  261. * @node: valid node reference to read property from
  262. * @propname: name of property to read
  263. * @return true if property is present (meaning true), false if not present
  264. */
  265. bool ofnode_read_bool(ofnode node, const char *propname);
  266. /**
  267. * ofnode_find_subnode() - find a named subnode of a parent node
  268. *
  269. * @node: valid reference to parent node
  270. * @subnode_name: name of subnode to find
  271. * @return reference to subnode (which can be invalid if there is no such
  272. * subnode)
  273. */
  274. ofnode ofnode_find_subnode(ofnode node, const char *subnode_name);
  275. /**
  276. * ofnode_first_subnode() - find the first subnode of a parent node
  277. *
  278. * @node: valid reference to a valid parent node
  279. * @return reference to the first subnode (which can be invalid if the parent
  280. * node has no subnodes)
  281. */
  282. ofnode ofnode_first_subnode(ofnode node);
  283. /**
  284. * ofnode_next_subnode() - find the next sibling of a subnode
  285. *
  286. * @node: valid reference to previous node (sibling)
  287. * @return reference to the next subnode (which can be invalid if the node
  288. * has no more siblings)
  289. */
  290. ofnode ofnode_next_subnode(ofnode node);
  291. /**
  292. * ofnode_get_parent() - get the ofnode's parent (enclosing ofnode)
  293. *
  294. * @node: valid node to look up
  295. * @return ofnode reference of the parent node
  296. */
  297. ofnode ofnode_get_parent(ofnode node);
  298. /**
  299. * ofnode_get_name() - get the name of a node
  300. *
  301. * @node: valid node to look up
  302. * @return name of node
  303. */
  304. const char *ofnode_get_name(ofnode node);
  305. /**
  306. * ofnode_get_by_phandle() - get ofnode from phandle
  307. *
  308. * @phandle: phandle to look up
  309. * @return ofnode reference to the phandle
  310. */
  311. ofnode ofnode_get_by_phandle(uint phandle);
  312. /**
  313. * ofnode_read_size() - read the size of a property
  314. *
  315. * @node: node to check
  316. * @propname: property to check
  317. * @return size of property if present, or -EINVAL if not
  318. */
  319. int ofnode_read_size(ofnode node, const char *propname);
  320. /**
  321. * ofnode_get_addr_size_index() - get an address/size from a node
  322. * based on index
  323. *
  324. * This reads the register address/size from a node based on index
  325. *
  326. * @node: node to read from
  327. * @index: Index of address to read (0 for first)
  328. * @size: Pointer to size of the address
  329. * @return address, or FDT_ADDR_T_NONE if not present or invalid
  330. */
  331. phys_addr_t ofnode_get_addr_size_index(ofnode node, int index,
  332. fdt_size_t *size);
  333. /**
  334. * ofnode_get_addr_index() - get an address from a node
  335. *
  336. * This reads the register address from a node
  337. *
  338. * @node: node to read from
  339. * @index: Index of address to read (0 for first)
  340. * @return address, or FDT_ADDR_T_NONE if not present or invalid
  341. */
  342. phys_addr_t ofnode_get_addr_index(ofnode node, int index);
  343. /**
  344. * ofnode_get_addr() - get an address from a node
  345. *
  346. * This reads the register address from a node
  347. *
  348. * @node: node to read from
  349. * @return address, or FDT_ADDR_T_NONE if not present or invalid
  350. */
  351. phys_addr_t ofnode_get_addr(ofnode node);
  352. /**
  353. * ofnode_stringlist_search() - find a string in a string list and return index
  354. *
  355. * Note that it is possible for this function to succeed on property values
  356. * that are not NUL-terminated. That's because the function will stop after
  357. * finding the first occurrence of @string. This can for example happen with
  358. * small-valued cell properties, such as #address-cells, when searching for
  359. * the empty string.
  360. *
  361. * @node: node to check
  362. * @propname: name of the property containing the string list
  363. * @string: string to look up in the string list
  364. *
  365. * @return:
  366. * the index of the string in the list of strings
  367. * -ENODATA if the property is not found
  368. * -EINVAL on some other error
  369. */
  370. int ofnode_stringlist_search(ofnode node, const char *propname,
  371. const char *string);
  372. /**
  373. * ofnode_read_string_index() - obtain an indexed string from a string list
  374. *
  375. * Note that this will successfully extract strings from properties with
  376. * non-NUL-terminated values. For example on small-valued cell properties
  377. * this function will return the empty string.
  378. *
  379. * If non-NULL, the length of the string (on success) or a negative error-code
  380. * (on failure) will be stored in the integer pointer to by lenp.
  381. *
  382. * @node: node to check
  383. * @propname: name of the property containing the string list
  384. * @index: index of the string to return
  385. * @lenp: return location for the string length or an error code on failure
  386. *
  387. * @return:
  388. * length of string, if found or -ve error value if not found
  389. */
  390. int ofnode_read_string_index(ofnode node, const char *propname, int index,
  391. const char **outp);
  392. /**
  393. * ofnode_read_string_count() - find the number of strings in a string list
  394. *
  395. * @node: node to check
  396. * @propname: name of the property containing the string list
  397. * @return:
  398. * number of strings in the list, or -ve error value if not found
  399. */
  400. int ofnode_read_string_count(ofnode node, const char *property);
  401. /**
  402. * ofnode_parse_phandle_with_args() - Find a node pointed by phandle in a list
  403. *
  404. * This function is useful to parse lists of phandles and their arguments.
  405. * Returns 0 on success and fills out_args, on error returns appropriate
  406. * errno value.
  407. *
  408. * Caller is responsible to call of_node_put() on the returned out_args->np
  409. * pointer.
  410. *
  411. * Example:
  412. *
  413. * phandle1: node1 {
  414. * #list-cells = <2>;
  415. * }
  416. *
  417. * phandle2: node2 {
  418. * #list-cells = <1>;
  419. * }
  420. *
  421. * node3 {
  422. * list = <&phandle1 1 2 &phandle2 3>;
  423. * }
  424. *
  425. * To get a device_node of the `node2' node you may call this:
  426. * ofnode_parse_phandle_with_args(node3, "list", "#list-cells", 0, 1, &args);
  427. *
  428. * @node: device tree node containing a list
  429. * @list_name: property name that contains a list
  430. * @cells_name: property name that specifies phandles' arguments count
  431. * @cells_count: Cell count to use if @cells_name is NULL
  432. * @index: index of a phandle to parse out
  433. * @out_args: optional pointer to output arguments structure (will be filled)
  434. * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
  435. * @list_name does not exist, -EINVAL if a phandle was not found,
  436. * @cells_name could not be found, the arguments were truncated or there
  437. * were too many arguments.
  438. */
  439. int ofnode_parse_phandle_with_args(ofnode node, const char *list_name,
  440. const char *cells_name, int cell_count,
  441. int index,
  442. struct ofnode_phandle_args *out_args);
  443. /**
  444. * ofnode_count_phandle_with_args() - Count number of phandle in a list
  445. *
  446. * This function is useful to count phandles into a list.
  447. * Returns number of phandle on success, on error returns appropriate
  448. * errno value.
  449. *
  450. * @node: device tree node containing a list
  451. * @list_name: property name that contains a list
  452. * @cells_name: property name that specifies phandles' arguments count
  453. * @return number of phandle on success, -ENOENT if @list_name does not
  454. * exist, -EINVAL if a phandle was not found, @cells_name could not
  455. * be found.
  456. */
  457. int ofnode_count_phandle_with_args(ofnode node, const char *list_name,
  458. const char *cells_name);
  459. /**
  460. * ofnode_path() - find a node by full path
  461. *
  462. * @path: Full path to node, e.g. "/bus/spi@1"
  463. * @return reference to the node found. Use ofnode_valid() to check if it exists
  464. */
  465. ofnode ofnode_path(const char *path);
  466. /**
  467. * ofnode_get_chosen_prop() - get the value of a chosen property
  468. *
  469. * This looks for a property within the /chosen node and returns its value
  470. *
  471. * @propname: Property name to look for
  472. * @return property value if found, else NULL
  473. */
  474. const char *ofnode_get_chosen_prop(const char *propname);
  475. /**
  476. * ofnode_get_chosen_node() - get the chosen node
  477. *
  478. * @return the chosen node if present, else ofnode_null()
  479. */
  480. ofnode ofnode_get_chosen_node(const char *name);
  481. struct display_timing;
  482. /**
  483. * ofnode_decode_display_timing() - decode display timings
  484. *
  485. * Decode display timings from the supplied 'display-timings' node.
  486. * See doc/device-tree-bindings/video/display-timing.txt for binding
  487. * information.
  488. *
  489. * @node 'display-timing' node containing the timing subnodes
  490. * @index Index number to read (0=first timing subnode)
  491. * @config Place to put timings
  492. * @return 0 if OK, -FDT_ERR_NOTFOUND if not found
  493. */
  494. int ofnode_decode_display_timing(ofnode node, int index,
  495. struct display_timing *config);
  496. /**
  497. * ofnode_get_property()- - get a pointer to the value of a node property
  498. *
  499. * @node: node to read
  500. * @propname: property to read
  501. * @lenp: place to put length on success
  502. * @return pointer to property, or NULL if not found
  503. */
  504. const void *ofnode_get_property(ofnode node, const char *propname, int *lenp);
  505. /**
  506. * ofnode_is_available() - check if a node is marked available
  507. *
  508. * @node: node to check
  509. * @return true if node's 'status' property is "okay" (or is missing)
  510. */
  511. bool ofnode_is_available(ofnode node);
  512. /**
  513. * ofnode_get_addr_size() - get address and size from a property
  514. *
  515. * This does no address translation. It simply reads an property that contains
  516. * an address and a size value, one after the other.
  517. *
  518. * @node: node to read from
  519. * @propname: property to read
  520. * @sizep: place to put size value (on success)
  521. * @return address value, or FDT_ADDR_T_NONE on error
  522. */
  523. phys_addr_t ofnode_get_addr_size(ofnode node, const char *propname,
  524. phys_size_t *sizep);
  525. /**
  526. * ofnode_read_u8_array_ptr() - find an 8-bit array
  527. *
  528. * Look up a property in a node and return a pointer to its contents as a
  529. * byte array of given length. The property must have at least enough data
  530. * for the array (count bytes). It may have more, but this will be ignored.
  531. * The data is not copied.
  532. *
  533. * @node node to examine
  534. * @propname name of property to find
  535. * @sz number of array elements
  536. * @return pointer to byte array if found, or NULL if the property is not
  537. * found or there is not enough data
  538. */
  539. const uint8_t *ofnode_read_u8_array_ptr(ofnode node, const char *propname,
  540. size_t sz);
  541. /**
  542. * ofnode_read_pci_addr() - look up a PCI address
  543. *
  544. * Look at an address property in a node and return the PCI address which
  545. * corresponds to the given type in the form of fdt_pci_addr.
  546. * The property must hold one fdt_pci_addr with a lengh.
  547. *
  548. * @node node to examine
  549. * @type pci address type (FDT_PCI_SPACE_xxx)
  550. * @propname name of property to find
  551. * @addr returns pci address in the form of fdt_pci_addr
  552. * @return 0 if ok, -ENOENT if the property did not exist, -EINVAL if the
  553. * format of the property was invalid, -ENXIO if the requested
  554. * address type was not found
  555. */
  556. int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type,
  557. const char *propname, struct fdt_pci_addr *addr);
  558. /**
  559. * ofnode_read_pci_vendev() - look up PCI vendor and device id
  560. *
  561. * Look at the compatible property of a device node that represents a PCI
  562. * device and extract pci vendor id and device id from it.
  563. *
  564. * @param node node to examine
  565. * @param vendor vendor id of the pci device
  566. * @param device device id of the pci device
  567. * @return 0 if ok, negative on error
  568. */
  569. int ofnode_read_pci_vendev(ofnode node, u16 *vendor, u16 *device);
  570. /**
  571. * ofnode_read_addr_cells() - Get the number of address cells for a node
  572. *
  573. * This walks back up the tree to find the closest #address-cells property
  574. * which controls the given node.
  575. *
  576. * @node: Node to check
  577. * @return number of address cells this node uses
  578. */
  579. int ofnode_read_addr_cells(ofnode node);
  580. /**
  581. * ofnode_read_size_cells() - Get the number of size cells for a node
  582. *
  583. * This walks back up the tree to find the closest #size-cells property
  584. * which controls the given node.
  585. *
  586. * @node: Node to check
  587. * @return number of size cells this node uses
  588. */
  589. int ofnode_read_size_cells(ofnode node);
  590. /**
  591. * ofnode_read_simple_addr_cells() - Get the address cells property in a node
  592. *
  593. * This function matches fdt_address_cells().
  594. *
  595. * @np: Node pointer to check
  596. * @return value of #address-cells property in this node, or 2 if none
  597. */
  598. int ofnode_read_simple_addr_cells(ofnode node);
  599. /**
  600. * ofnode_read_simple_size_cells() - Get the size cells property in a node
  601. *
  602. * This function matches fdt_size_cells().
  603. *
  604. * @np: Node pointer to check
  605. * @return value of #size-cells property in this node, or 2 if none
  606. */
  607. int ofnode_read_simple_size_cells(ofnode node);
  608. /**
  609. * ofnode_pre_reloc() - check if a node should be bound before relocation
  610. *
  611. * Device tree nodes can be marked as needing-to-be-bound in the loader stages
  612. * via special device tree properties.
  613. *
  614. * Before relocation this function can be used to check if nodes are required
  615. * in either SPL or TPL stages.
  616. *
  617. * After relocation and jumping into the real U-Boot binary it is possible to
  618. * determine if a node was bound in one of SPL/TPL stages.
  619. *
  620. * There are 4 settings currently in use
  621. * - u-boot,dm-pre-proper: U-Boot proper pre-relocation only
  622. * - u-boot,dm-pre-reloc: legacy and indicates any of TPL or SPL
  623. * Existing platforms only use it to indicate nodes needed in
  624. * SPL. Should probably be replaced by u-boot,dm-spl for
  625. * new platforms.
  626. * - u-boot,dm-spl: SPL and U-Boot pre-relocation
  627. * - u-boot,dm-tpl: TPL and U-Boot pre-relocation
  628. *
  629. * @node: node to check
  630. * @return true if node is needed in SPL/TL, false otherwise
  631. */
  632. bool ofnode_pre_reloc(ofnode node);
  633. /**
  634. * ofnode_read_resource() - Read a resource from a node
  635. *
  636. * Read resource information from a node at the given index
  637. *
  638. * @node: Node to read from
  639. * @index: Index of resource to read (0 = first)
  640. * @res: Returns resource that was read, on success
  641. * @return 0 if OK, -ve on error
  642. */
  643. int ofnode_read_resource(ofnode node, uint index, struct resource *res);
  644. /**
  645. * ofnode_read_resource_byname() - Read a resource from a node by name
  646. *
  647. * Read resource information from a node matching the given name. This uses a
  648. * 'reg-names' string list property with the names matching the associated
  649. * 'reg' property list.
  650. *
  651. * @node: Node to read from
  652. * @name: Name of resource to read
  653. * @res: Returns resource that was read, on success
  654. * @return 0 if OK, -ve on error
  655. */
  656. int ofnode_read_resource_byname(ofnode node, const char *name,
  657. struct resource *res);
  658. /**
  659. * ofnode_by_compatible() - Find the next compatible node
  660. *
  661. * Find the next node after @from that is compatible with @compat
  662. *
  663. * @from: ofnode to start from (use ofnode_null() to start at the beginning)
  664. * @compat: Compatible string to match
  665. * @return ofnode found, or ofnode_null() if none
  666. */
  667. ofnode ofnode_by_compatible(ofnode from, const char *compat);
  668. /**
  669. * ofnode_by_prop_value() - Find the next node with given property value
  670. *
  671. * Find the next node after @from that has a @propname with a value
  672. * @propval and a length @proplen.
  673. *
  674. * @from: ofnode to start from (use ofnode_null() to start at the
  675. * beginning) @propname: property name to check @propval: property value to
  676. * search for @proplen: length of the value in propval @return ofnode
  677. * found, or ofnode_null() if none
  678. */
  679. ofnode ofnode_by_prop_value(ofnode from, const char *propname,
  680. const void *propval, int proplen);
  681. /**
  682. * ofnode_for_each_subnode() - iterate over all subnodes of a parent
  683. *
  684. * @node: child node (ofnode, lvalue)
  685. * @parent: parent node (ofnode)
  686. *
  687. * This is a wrapper around a for loop and is used like so:
  688. *
  689. * ofnode node;
  690. *
  691. * ofnode_for_each_subnode(node, parent) {
  692. * Use node
  693. * ...
  694. * }
  695. *
  696. * Note that this is implemented as a macro and @node is used as
  697. * iterator in the loop. The parent variable can be a constant or even a
  698. * literal.
  699. */
  700. #define ofnode_for_each_subnode(node, parent) \
  701. for (node = ofnode_first_subnode(parent); \
  702. ofnode_valid(node); \
  703. node = ofnode_next_subnode(node))
  704. /**
  705. * ofnode_translate_address() - Translate a device-tree address
  706. *
  707. * Translate an address from the device-tree into a CPU physical address. This
  708. * function walks up the tree and applies the various bus mappings along the
  709. * way.
  710. *
  711. * @ofnode: Device tree node giving the context in which to translate the
  712. * address
  713. * @in_addr: pointer to the address to translate
  714. * @return the translated address; OF_BAD_ADDR on error
  715. */
  716. u64 ofnode_translate_address(ofnode node, const fdt32_t *in_addr);
  717. /**
  718. * ofnode_translate_dma_address() - Translate a device-tree DMA address
  719. *
  720. * Translate a DMA address from the device-tree into a CPU physical address.
  721. * This function walks up the tree and applies the various bus mappings along
  722. * the way.
  723. *
  724. * @ofnode: Device tree node giving the context in which to translate the
  725. * DMA address
  726. * @in_addr: pointer to the DMA address to translate
  727. * @return the translated DMA address; OF_BAD_ADDR on error
  728. */
  729. u64 ofnode_translate_dma_address(ofnode node, const fdt32_t *in_addr);
  730. /**
  731. * ofnode_device_is_compatible() - check if the node is compatible with compat
  732. *
  733. * This allows to check whether the node is comaptible with the compat.
  734. *
  735. * @node: Device tree node for which compatible needs to be verified.
  736. * @compat: Compatible string which needs to verified in the given node.
  737. * @return true if OK, false if the compatible is not found
  738. */
  739. int ofnode_device_is_compatible(ofnode node, const char *compat);
  740. /**
  741. * ofnode_write_prop() - Set a property of a ofnode
  742. *
  743. * Note that the value passed to the function is *not* allocated by the
  744. * function itself, but must be allocated by the caller if necessary.
  745. *
  746. * @node: The node for whose property should be set
  747. * @propname: The name of the property to set
  748. * @len: The length of the new value of the property
  749. * @value: The new value of the property (must be valid prior to calling
  750. * the function)
  751. * @return 0 if successful, -ve on error
  752. */
  753. int ofnode_write_prop(ofnode node, const char *propname, int len,
  754. const void *value);
  755. /**
  756. * ofnode_write_string() - Set a string property of a ofnode
  757. *
  758. * Note that the value passed to the function is *not* allocated by the
  759. * function itself, but must be allocated by the caller if necessary.
  760. *
  761. * @node: The node for whose string property should be set
  762. * @propname: The name of the string property to set
  763. * @value: The new value of the string property (must be valid prior to
  764. * calling the function)
  765. * @return 0 if successful, -ve on error
  766. */
  767. int ofnode_write_string(ofnode node, const char *propname, const char *value);
  768. /**
  769. * ofnode_set_enabled() - Enable or disable a device tree node given by its
  770. * ofnode
  771. *
  772. * This function effectively sets the node's "status" property to either "okay"
  773. * or "disable", hence making it available for driver model initialization or
  774. * not.
  775. *
  776. * @node: The node to enable
  777. * @value: Flag that tells the function to either disable or enable the
  778. * node
  779. * @return 0 if successful, -ve on error
  780. */
  781. int ofnode_set_enabled(ofnode node, bool value);
  782. #endif