ofnode.h 31 KB

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