ofnode.h 30 KB

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