of_access.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Originally from Linux v4.9
  4. * Copyright (C) 1996-2005 Paul Mackerras.
  5. *
  6. * Updates for PPC64 by Peter Bergner & David Engebretsen, IBM Corp.
  7. * Updates for SPARC64 by David S. Miller
  8. * Derived from PowerPC and Sparc prom.h files by Stephen Rothwell, IBM Corp.
  9. *
  10. * Copyright (c) 2017 Google, Inc
  11. * Written by Simon Glass <sjg@chromium.org>
  12. *
  13. * Modified for U-Boot
  14. * Copyright (c) 2017 Google, Inc
  15. */
  16. #ifndef _DM_OF_ACCESS_H
  17. #define _DM_OF_ACCESS_H
  18. #include <dm/of.h>
  19. /**
  20. * of_find_all_nodes - Get next node in global list
  21. * @prev: Previous node or NULL to start iteration
  22. * of_node_put() will be called on it
  23. *
  24. * Returns a node pointer with refcount incremented, use
  25. * of_node_put() on it when done.
  26. */
  27. struct device_node *of_find_all_nodes(struct device_node *prev);
  28. #define for_each_of_allnodes_from(from, dn) \
  29. for (dn = of_find_all_nodes(from); dn; dn = of_find_all_nodes(dn))
  30. #define for_each_of_allnodes(dn) for_each_of_allnodes_from(NULL, dn)
  31. /* Dummy functions to mirror Linux. These are not used in U-Boot */
  32. #define of_node_get(x) (x)
  33. static inline void of_node_put(const struct device_node *np) { }
  34. /**
  35. * of_n_addr_cells() - Get the number of address cells for a node
  36. *
  37. * This walks back up the tree to find the closest #address-cells property
  38. * which controls the given node.
  39. *
  40. * @np: Node pointer to check
  41. * @return number of address cells this node uses
  42. */
  43. int of_n_addr_cells(const struct device_node *np);
  44. /**
  45. * of_n_size_cells() - Get the number of size cells for a node
  46. *
  47. * This walks back up the tree to find the closest #size-cells property
  48. * which controls the given node.
  49. *
  50. * @np: Node pointer to check
  51. * @return number of size cells this node uses
  52. */
  53. int of_n_size_cells(const struct device_node *np);
  54. /**
  55. * of_simple_addr_cells() - Get the address cells property in a node
  56. *
  57. * This function matches fdt_address_cells().
  58. *
  59. * @np: Node pointer to check
  60. * @return value of #address-cells property in this node, or 2 if none
  61. */
  62. int of_simple_addr_cells(const struct device_node *np);
  63. /**
  64. * of_simple_size_cells() - Get the size cells property in a node
  65. *
  66. * This function matches fdt_size_cells().
  67. *
  68. * @np: Node pointer to check
  69. * @return value of #size-cells property in this node, or 2 if none
  70. */
  71. int of_simple_size_cells(const struct device_node *np);
  72. /**
  73. * of_find_property() - find a property in a node
  74. *
  75. * @np: Pointer to device node holding property
  76. * @name: Name of property
  77. * @lenp: If non-NULL, returns length of property
  78. * @return pointer to property, or NULL if not found
  79. */
  80. struct property *of_find_property(const struct device_node *np,
  81. const char *name, int *lenp);
  82. /**
  83. * of_get_property() - get a property value
  84. *
  85. * Find a property with a given name for a given node and return the value.
  86. *
  87. * @np: Pointer to device node holding property
  88. * @name: Name of property
  89. * @lenp: If non-NULL, returns length of property
  90. * @return pointer to property value, or NULL if not found
  91. */
  92. const void *of_get_property(const struct device_node *np, const char *name,
  93. int *lenp);
  94. /**
  95. * of_get_first_property()- get to the pointer of the first property
  96. *
  97. * Get pointer to the first property of the node, it is used to iterate
  98. * and read all the property with of_get_next_property_by_prop().
  99. *
  100. * @np: Pointer to device node
  101. * @return pointer to property or NULL if not found
  102. */
  103. const struct property *of_get_first_property(const struct device_node *np);
  104. /**
  105. * of_get_next_property() - get to the pointer of the next property
  106. *
  107. * Get pointer to the next property of the node, it is used to iterate
  108. * and read all the property with of_get_property_by_prop().
  109. *
  110. * @np: Pointer to device node
  111. * @property: pointer of the current property
  112. * @return pointer to next property or NULL if not found
  113. */
  114. const struct property *of_get_next_property(const struct device_node *np,
  115. const struct property *property);
  116. /**
  117. * of_get_property_by_prop() - get a property value of a node property
  118. *
  119. * Get value for the property identified by node and property pointer.
  120. *
  121. * @node: node to read
  122. * @property: pointer of the property to read
  123. * @propname: place to property name on success
  124. * @lenp: place to put length on success
  125. * @return pointer to property value or NULL if error
  126. */
  127. const void *of_get_property_by_prop(const struct device_node *np,
  128. const struct property *property,
  129. const char **name,
  130. int *lenp);
  131. /**
  132. * of_device_is_compatible() - Check if the node matches given constraints
  133. * @device: pointer to node
  134. * @compat: required compatible string, NULL or "" for any match
  135. * @type: required device_type value, NULL or "" for any match
  136. * @name: required node name, NULL or "" for any match
  137. *
  138. * Checks if the given @compat, @type and @name strings match the
  139. * properties of the given @device. A constraints can be skipped by
  140. * passing NULL or an empty string as the constraint.
  141. *
  142. * @return 0 for no match, and a positive integer on match. The return
  143. * value is a relative score with larger values indicating better
  144. * matches. The score is weighted for the most specific compatible value
  145. * to get the highest score. Matching type is next, followed by matching
  146. * name. Practically speaking, this results in the following priority
  147. * order for matches:
  148. *
  149. * 1. specific compatible && type && name
  150. * 2. specific compatible && type
  151. * 3. specific compatible && name
  152. * 4. specific compatible
  153. * 5. general compatible && type && name
  154. * 6. general compatible && type
  155. * 7. general compatible && name
  156. * 8. general compatible
  157. * 9. type && name
  158. * 10. type
  159. * 11. name
  160. */
  161. int of_device_is_compatible(const struct device_node *np, const char *compat,
  162. const char *type, const char *name);
  163. /**
  164. * of_device_is_available() - check if a device is available for use
  165. *
  166. * @device: Node to check for availability
  167. *
  168. * @return true if the status property is absent or set to "okay", false
  169. * otherwise
  170. */
  171. bool of_device_is_available(const struct device_node *np);
  172. /**
  173. * of_get_parent() - Get a node's parent, if any
  174. *
  175. * @node: Node to check
  176. * @eturns a node pointer, or NULL if none
  177. */
  178. struct device_node *of_get_parent(const struct device_node *np);
  179. /**
  180. * of_find_node_opts_by_path() - Find a node matching a full OF path
  181. *
  182. * @path: Either the full path to match, or if the path does not start with
  183. * '/', the name of a property of the /aliases node (an alias). In the
  184. * case of an alias, the node matching the alias' value will be returned.
  185. * @opts: Address of a pointer into which to store the start of an options
  186. * string appended to the end of the path with a ':' separator. Can be NULL
  187. *
  188. * Valid paths:
  189. * /foo/bar Full path
  190. * foo Valid alias
  191. * foo/bar Valid alias + relative path
  192. *
  193. * @return a node pointer or NULL if not found
  194. */
  195. struct device_node *of_find_node_opts_by_path(const char *path,
  196. const char **opts);
  197. static inline struct device_node *of_find_node_by_path(const char *path)
  198. {
  199. return of_find_node_opts_by_path(path, NULL);
  200. }
  201. /**
  202. * of_find_compatible_node() - find a node based on its compatible string
  203. *
  204. * Find a node based on type and one of the tokens in its "compatible" property
  205. * @from: Node to start searching from or NULL. the node you pass will not be
  206. * searched, only the next one will; typically, you pass what the previous
  207. * call returned.
  208. * @type: The type string to match "device_type" or NULL to ignore
  209. * @compatible: The string to match to one of the tokens in the device
  210. * "compatible" list.
  211. * @return node pointer or NULL if not found
  212. */
  213. struct device_node *of_find_compatible_node(struct device_node *from,
  214. const char *type, const char *compatible);
  215. /**
  216. * of_find_node_by_prop_value() - find a node with a given property value
  217. *
  218. * Find a node based on a property value.
  219. * @from: Node to start searching from or NULL. the node you pass will not be
  220. * searched, only the next one will; typically, you pass what the previous
  221. * call returned.
  222. * @propname: property name to check
  223. * @propval: property value to search for
  224. * @proplen: length of the value in propval
  225. * @return node pointer or NULL if not found
  226. */
  227. struct device_node *of_find_node_by_prop_value(struct device_node *from,
  228. const char *propname,
  229. const void *propval,
  230. int proplen);
  231. /**
  232. * of_find_node_by_phandle() - Find a node given a phandle
  233. *
  234. * @handle: phandle of the node to find
  235. *
  236. * @return node pointer, or NULL if not found
  237. */
  238. struct device_node *of_find_node_by_phandle(phandle handle);
  239. /**
  240. * of_read_u32() - Find and read a 32-bit integer from a property
  241. *
  242. * Search for a property in a device node and read a 32-bit value from
  243. * it.
  244. *
  245. * @np: device node from which the property value is to be read.
  246. * @propname: name of the property to be searched.
  247. * @outp: pointer to return value, modified only if return value is 0.
  248. *
  249. * @return 0 on success, -EINVAL if the property does not exist,
  250. * -ENODATA if property does not have a value, and -EOVERFLOW if the
  251. * property data isn't large enough.
  252. */
  253. int of_read_u32(const struct device_node *np, const char *propname, u32 *outp);
  254. /**
  255. * of_read_u32_index() - Find and read a 32-bit value from a multi-value
  256. * property
  257. *
  258. * Search for a property in a device node and read a 32-bit value from
  259. * it.
  260. *
  261. * @np: device node from which the property value is to be read.
  262. * @propname: name of the property to be searched.
  263. * @index: index of the u32 in the list of values
  264. * @outp: pointer to return value, modified only if return value is 0.
  265. *
  266. * @return 0 on success, -EINVAL if the property does not exist,
  267. * -ENODATA if property does not have a value, and -EOVERFLOW if the
  268. * property data isn't large enough.
  269. */
  270. int of_read_u32_index(const struct device_node *np, const char *propname,
  271. int index, u32 *outp);
  272. /**
  273. * of_read_u64() - Find and read a 64-bit integer from a property
  274. *
  275. * Search for a property in a device node and read a 64-bit value from
  276. * it.
  277. *
  278. * @np: device node from which the property value is to be read.
  279. * @propname: name of the property to be searched.
  280. * @outp: pointer to return value, modified only if return value is 0.
  281. *
  282. * @return 0 on success, -EINVAL if the property does not exist,
  283. * -ENODATA if property does not have a value, and -EOVERFLOW if the
  284. * property data isn't large enough.
  285. */
  286. int of_read_u64(const struct device_node *np, const char *propname, u64 *outp);
  287. /**
  288. * of_read_u32_array() - Find and read an array of 32 bit integers
  289. *
  290. * Search for a property in a device node and read 32-bit value(s) from
  291. * it.
  292. *
  293. * @np: device node from which the property value is to be read.
  294. * @propname: name of the property to be searched.
  295. * @out_values: pointer to return value, modified only if return value is 0.
  296. * @sz: number of array elements to read
  297. * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
  298. * if property does not have a value, and -EOVERFLOW is longer than sz.
  299. */
  300. int of_read_u32_array(const struct device_node *np, const char *propname,
  301. u32 *out_values, size_t sz);
  302. /**
  303. * of_property_match_string() - Find string in a list and return index
  304. *
  305. * This function searches a string list property and returns the index
  306. * of a specific string value.
  307. *
  308. * @np: pointer to node containing string list property
  309. * @propname: string list property name
  310. * @string: pointer to string to search for in string list
  311. * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
  312. * if property does not have a value, and -EOVERFLOW is longer than sz.
  313. */
  314. int of_property_match_string(const struct device_node *np, const char *propname,
  315. const char *string);
  316. int of_property_read_string_helper(const struct device_node *np,
  317. const char *propname, const char **out_strs,
  318. size_t sz, int index);
  319. /**
  320. * of_property_read_string_index() - Find and read a string from a multiple
  321. * strings property.
  322. * @np: device node from which the property value is to be read.
  323. * @propname: name of the property to be searched.
  324. * @index: index of the string in the list of strings
  325. * @out_string: pointer to null terminated return string, modified only if
  326. * return value is 0.
  327. *
  328. * Search for a property in a device tree node and retrieve a null
  329. * terminated string value (pointer to data, not a copy) in the list of strings
  330. * contained in that property.
  331. * Returns 0 on success, -EINVAL if the property does not exist, -ENODATA if
  332. * property does not have a value, and -EILSEQ if the string is not
  333. * null-terminated within the length of the property data.
  334. *
  335. * The out_string pointer is modified only if a valid string can be decoded.
  336. */
  337. static inline int of_property_read_string_index(const struct device_node *np,
  338. const char *propname,
  339. int index, const char **output)
  340. {
  341. int rc = of_property_read_string_helper(np, propname, output, 1, index);
  342. return rc < 0 ? rc : 0;
  343. }
  344. /**
  345. * of_property_count_strings() - Find and return the number of strings from a
  346. * multiple strings property.
  347. * @np: device node from which the property value is to be read.
  348. * @propname: name of the property to be searched.
  349. *
  350. * Search for a property in a device tree node and retrieve the number of null
  351. * terminated string contain in it. Returns the number of strings on
  352. * success, -EINVAL if the property does not exist, -ENODATA if property
  353. * does not have a value, and -EILSEQ if the string is not null-terminated
  354. * within the length of the property data.
  355. */
  356. static inline int of_property_count_strings(const struct device_node *np,
  357. const char *propname)
  358. {
  359. return of_property_read_string_helper(np, propname, NULL, 0, 0);
  360. }
  361. /**
  362. * of_parse_phandle - Resolve a phandle property to a device_node pointer
  363. * @np: Pointer to device node holding phandle property
  364. * @phandle_name: Name of property holding a phandle value
  365. * @index: For properties holding a table of phandles, this is the index into
  366. * the table
  367. *
  368. * Returns the device_node pointer with refcount incremented. Use
  369. * of_node_put() on it when done.
  370. */
  371. struct device_node *of_parse_phandle(const struct device_node *np,
  372. const char *phandle_name, int index);
  373. /**
  374. * of_parse_phandle_with_args() - Find a node pointed by phandle in a list
  375. *
  376. * @np: pointer to a device tree node containing a list
  377. * @list_name: property name that contains a list
  378. * @cells_name: property name that specifies phandles' arguments count
  379. * @index: index of a phandle to parse out
  380. * @out_args: optional pointer to output arguments structure (will be filled)
  381. * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
  382. * @list_name does not exist, -EINVAL if a phandle was not found,
  383. * @cells_name could not be found, the arguments were truncated or there
  384. * were too many arguments.
  385. *
  386. * This function is useful to parse lists of phandles and their arguments.
  387. * Returns 0 on success and fills out_args, on error returns appropriate
  388. * errno value.
  389. *
  390. * Caller is responsible to call of_node_put() on the returned out_args->np
  391. * pointer.
  392. *
  393. * Example:
  394. *
  395. * phandle1: node1 {
  396. * #list-cells = <2>;
  397. * }
  398. *
  399. * phandle2: node2 {
  400. * #list-cells = <1>;
  401. * }
  402. *
  403. * node3 {
  404. * list = <&phandle1 1 2 &phandle2 3>;
  405. * }
  406. *
  407. * To get a device_node of the `node2' node you may call this:
  408. * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
  409. */
  410. int of_parse_phandle_with_args(const struct device_node *np,
  411. const char *list_name, const char *cells_name,
  412. int index, struct of_phandle_args *out_args);
  413. /**
  414. * of_count_phandle_with_args() - Count the number of phandle in a list
  415. *
  416. * @np: pointer to a device tree node containing a list
  417. * @list_name: property name that contains a list
  418. * @cells_name: property name that specifies phandles' arguments count
  419. * @return number of phandle found, -ENOENT if
  420. * @list_name does not exist, -EINVAL if a phandle was not found,
  421. * @cells_name could not be found, the arguments were truncated or there
  422. * were too many arguments.
  423. *
  424. * Returns number of phandle found on success, on error returns appropriate
  425. * errno value.
  426. *
  427. */
  428. int of_count_phandle_with_args(const struct device_node *np,
  429. const char *list_name, const char *cells_name);
  430. /**
  431. * of_alias_scan() - Scan all properties of the 'aliases' node
  432. *
  433. * The function scans all the properties of the 'aliases' node and populates
  434. * the lookup table with the properties. It returns the number of alias
  435. * properties found, or an error code in case of failure.
  436. *
  437. * @return 9 if OK, -ENOMEM if not enough memory
  438. */
  439. int of_alias_scan(void);
  440. /**
  441. * of_alias_get_id - Get alias id for the given device_node
  442. *
  443. * Travels the lookup table to get the alias id for the given device_node and
  444. * alias stem.
  445. *
  446. * @np: Pointer to the given device_node
  447. * @stem: Alias stem of the given device_node
  448. * @return alias ID, if found, else -ENODEV
  449. */
  450. int of_alias_get_id(const struct device_node *np, const char *stem);
  451. /**
  452. * of_alias_get_highest_id - Get highest alias id for the given stem
  453. * @stem: Alias stem to be examined
  454. *
  455. * The function travels the lookup table to get the highest alias id for the
  456. * given alias stem.
  457. * @return alias ID, if found, else -1
  458. */
  459. int of_alias_get_highest_id(const char *stem);
  460. /**
  461. * of_get_stdout() - Get node to use for stdout
  462. *
  463. * @return node referred to by stdout-path alias, or NULL if none
  464. */
  465. struct device_node *of_get_stdout(void);
  466. #endif