of_access.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444
  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_device_is_compatible() - Check if the node matches given constraints
  96. * @device: pointer to node
  97. * @compat: required compatible string, NULL or "" for any match
  98. * @type: required device_type value, NULL or "" for any match
  99. * @name: required node name, NULL or "" for any match
  100. *
  101. * Checks if the given @compat, @type and @name strings match the
  102. * properties of the given @device. A constraints can be skipped by
  103. * passing NULL or an empty string as the constraint.
  104. *
  105. * @return 0 for no match, and a positive integer on match. The return
  106. * value is a relative score with larger values indicating better
  107. * matches. The score is weighted for the most specific compatible value
  108. * to get the highest score. Matching type is next, followed by matching
  109. * name. Practically speaking, this results in the following priority
  110. * order for matches:
  111. *
  112. * 1. specific compatible && type && name
  113. * 2. specific compatible && type
  114. * 3. specific compatible && name
  115. * 4. specific compatible
  116. * 5. general compatible && type && name
  117. * 6. general compatible && type
  118. * 7. general compatible && name
  119. * 8. general compatible
  120. * 9. type && name
  121. * 10. type
  122. * 11. name
  123. */
  124. int of_device_is_compatible(const struct device_node *np, const char *compat,
  125. const char *type, const char *name);
  126. /**
  127. * of_device_is_available() - check if a device is available for use
  128. *
  129. * @device: Node to check for availability
  130. *
  131. * @return true if the status property is absent or set to "okay", false
  132. * otherwise
  133. */
  134. bool of_device_is_available(const struct device_node *np);
  135. /**
  136. * of_get_parent() - Get a node's parent, if any
  137. *
  138. * @node: Node to check
  139. * @eturns a node pointer, or NULL if none
  140. */
  141. struct device_node *of_get_parent(const struct device_node *np);
  142. /**
  143. * of_find_node_opts_by_path() - Find a node matching a full OF path
  144. *
  145. * @path: Either the full path to match, or if the path does not start with
  146. * '/', the name of a property of the /aliases node (an alias). In the
  147. * case of an alias, the node matching the alias' value will be returned.
  148. * @opts: Address of a pointer into which to store the start of an options
  149. * string appended to the end of the path with a ':' separator. Can be NULL
  150. *
  151. * Valid paths:
  152. * /foo/bar Full path
  153. * foo Valid alias
  154. * foo/bar Valid alias + relative path
  155. *
  156. * @return a node pointer or NULL if not found
  157. */
  158. struct device_node *of_find_node_opts_by_path(const char *path,
  159. const char **opts);
  160. static inline struct device_node *of_find_node_by_path(const char *path)
  161. {
  162. return of_find_node_opts_by_path(path, NULL);
  163. }
  164. /**
  165. * of_find_compatible_node() - find a node based on its compatible string
  166. *
  167. * Find a node based on type and one of the tokens in its "compatible" property
  168. * @from: Node to start searching from or NULL. the node you pass will not be
  169. * searched, only the next one will; typically, you pass what the previous
  170. * call returned.
  171. * @type: The type string to match "device_type" or NULL to ignore
  172. * @compatible: The string to match to one of the tokens in the device
  173. * "compatible" list.
  174. * @return node pointer or NULL if not found
  175. */
  176. struct device_node *of_find_compatible_node(struct device_node *from,
  177. const char *type, const char *compatible);
  178. /**
  179. * of_find_node_by_prop_value() - find a node with a given property value
  180. *
  181. * Find a node based on a property value.
  182. * @from: Node to start searching from or NULL. the node you pass will not be
  183. * searched, only the next one will; typically, you pass what the previous
  184. * call returned.
  185. * @propname: property name to check
  186. * @propval: property value to search for
  187. * @proplen: length of the value in propval
  188. * @return node pointer or NULL if not found
  189. */
  190. struct device_node *of_find_node_by_prop_value(struct device_node *from,
  191. const char *propname,
  192. const void *propval,
  193. int proplen);
  194. /**
  195. * of_find_node_by_phandle() - Find a node given a phandle
  196. *
  197. * @handle: phandle of the node to find
  198. *
  199. * @return node pointer, or NULL if not found
  200. */
  201. struct device_node *of_find_node_by_phandle(phandle handle);
  202. /**
  203. * of_read_u32() - Find and read a 32-bit integer from a property
  204. *
  205. * Search for a property in a device node and read a 32-bit value from
  206. * it.
  207. *
  208. * @np: device node from which the property value is to be read.
  209. * @propname: name of the property to be searched.
  210. * @outp: pointer to return value, modified only if return value is 0.
  211. *
  212. * @return 0 on success, -EINVAL if the property does not exist,
  213. * -ENODATA if property does not have a value, and -EOVERFLOW if the
  214. * property data isn't large enough.
  215. */
  216. int of_read_u32(const struct device_node *np, const char *propname, u32 *outp);
  217. /**
  218. * of_read_u64() - Find and read a 64-bit integer from a property
  219. *
  220. * Search for a property in a device node and read a 64-bit value from
  221. * it.
  222. *
  223. * @np: device node from which the property value is to be read.
  224. * @propname: name of the property to be searched.
  225. * @outp: pointer to return value, modified only if return value is 0.
  226. *
  227. * @return 0 on success, -EINVAL if the property does not exist,
  228. * -ENODATA if property does not have a value, and -EOVERFLOW if the
  229. * property data isn't large enough.
  230. */
  231. int of_read_u64(const struct device_node *np, const char *propname, u64 *outp);
  232. /**
  233. * of_read_u32_array() - Find and read an array of 32 bit integers
  234. *
  235. * Search for a property in a device node and read 32-bit value(s) from
  236. * it.
  237. *
  238. * @np: device node from which the property value is to be read.
  239. * @propname: name of the property to be searched.
  240. * @out_values: pointer to return value, modified only if return value is 0.
  241. * @sz: number of array elements to read
  242. * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
  243. * if property does not have a value, and -EOVERFLOW is longer than sz.
  244. */
  245. int of_read_u32_array(const struct device_node *np, const char *propname,
  246. u32 *out_values, size_t sz);
  247. /**
  248. * of_property_match_string() - Find string in a list and return index
  249. *
  250. * This function searches a string list property and returns the index
  251. * of a specific string value.
  252. *
  253. * @np: pointer to node containing string list property
  254. * @propname: string list property name
  255. * @string: pointer to string to search for in string list
  256. * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
  257. * if property does not have a value, and -EOVERFLOW is longer than sz.
  258. */
  259. int of_property_match_string(const struct device_node *np, const char *propname,
  260. const char *string);
  261. int of_property_read_string_helper(const struct device_node *np,
  262. const char *propname, const char **out_strs,
  263. size_t sz, int index);
  264. /**
  265. * of_property_read_string_index() - Find and read a string from a multiple
  266. * strings property.
  267. * @np: device node from which the property value is to be read.
  268. * @propname: name of the property to be searched.
  269. * @index: index of the string in the list of strings
  270. * @out_string: pointer to null terminated return string, modified only if
  271. * return value is 0.
  272. *
  273. * Search for a property in a device tree node and retrieve a null
  274. * terminated string value (pointer to data, not a copy) in the list of strings
  275. * contained in that property.
  276. * Returns 0 on success, -EINVAL if the property does not exist, -ENODATA if
  277. * property does not have a value, and -EILSEQ if the string is not
  278. * null-terminated within the length of the property data.
  279. *
  280. * The out_string pointer is modified only if a valid string can be decoded.
  281. */
  282. static inline int of_property_read_string_index(const struct device_node *np,
  283. const char *propname,
  284. int index, const char **output)
  285. {
  286. int rc = of_property_read_string_helper(np, propname, output, 1, index);
  287. return rc < 0 ? rc : 0;
  288. }
  289. /**
  290. * of_property_count_strings() - Find and return the number of strings from a
  291. * multiple strings property.
  292. * @np: device node from which the property value is to be read.
  293. * @propname: name of the property to be searched.
  294. *
  295. * Search for a property in a device tree node and retrieve the number of null
  296. * terminated string contain in it. Returns the number of strings on
  297. * success, -EINVAL if the property does not exist, -ENODATA if property
  298. * does not have a value, and -EILSEQ if the string is not null-terminated
  299. * within the length of the property data.
  300. */
  301. static inline int of_property_count_strings(const struct device_node *np,
  302. const char *propname)
  303. {
  304. return of_property_read_string_helper(np, propname, NULL, 0, 0);
  305. }
  306. /**
  307. * of_parse_phandle - Resolve a phandle property to a device_node pointer
  308. * @np: Pointer to device node holding phandle property
  309. * @phandle_name: Name of property holding a phandle value
  310. * @index: For properties holding a table of phandles, this is the index into
  311. * the table
  312. *
  313. * Returns the device_node pointer with refcount incremented. Use
  314. * of_node_put() on it when done.
  315. */
  316. struct device_node *of_parse_phandle(const struct device_node *np,
  317. const char *phandle_name, int index);
  318. /**
  319. * of_parse_phandle_with_args() - Find a node pointed by phandle in a list
  320. *
  321. * @np: pointer to a device tree node containing a list
  322. * @list_name: property name that contains a list
  323. * @cells_name: property name that specifies phandles' arguments count
  324. * @index: index of a phandle to parse out
  325. * @out_args: optional pointer to output arguments structure (will be filled)
  326. * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
  327. * @list_name does not exist, -EINVAL if a phandle was not found,
  328. * @cells_name could not be found, the arguments were truncated or there
  329. * were too many arguments.
  330. *
  331. * This function is useful to parse lists of phandles and their arguments.
  332. * Returns 0 on success and fills out_args, on error returns appropriate
  333. * errno value.
  334. *
  335. * Caller is responsible to call of_node_put() on the returned out_args->np
  336. * pointer.
  337. *
  338. * Example:
  339. *
  340. * phandle1: node1 {
  341. * #list-cells = <2>;
  342. * }
  343. *
  344. * phandle2: node2 {
  345. * #list-cells = <1>;
  346. * }
  347. *
  348. * node3 {
  349. * list = <&phandle1 1 2 &phandle2 3>;
  350. * }
  351. *
  352. * To get a device_node of the `node2' node you may call this:
  353. * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
  354. */
  355. int of_parse_phandle_with_args(const struct device_node *np,
  356. const char *list_name, const char *cells_name,
  357. int index, struct of_phandle_args *out_args);
  358. /**
  359. * of_count_phandle_with_args() - Count the number of phandle in a list
  360. *
  361. * @np: pointer to a device tree node containing a list
  362. * @list_name: property name that contains a list
  363. * @cells_name: property name that specifies phandles' arguments count
  364. * @return number of phandle found, -ENOENT if
  365. * @list_name does not exist, -EINVAL if a phandle was not found,
  366. * @cells_name could not be found, the arguments were truncated or there
  367. * were too many arguments.
  368. *
  369. * Returns number of phandle found on success, on error returns appropriate
  370. * errno value.
  371. *
  372. */
  373. int of_count_phandle_with_args(const struct device_node *np,
  374. const char *list_name, const char *cells_name);
  375. /**
  376. * of_alias_scan() - Scan all properties of the 'aliases' node
  377. *
  378. * The function scans all the properties of the 'aliases' node and populates
  379. * the lookup table with the properties. It returns the number of alias
  380. * properties found, or an error code in case of failure.
  381. *
  382. * @return 9 if OK, -ENOMEM if not enough memory
  383. */
  384. int of_alias_scan(void);
  385. /**
  386. * of_alias_get_id - Get alias id for the given device_node
  387. *
  388. * Travels the lookup table to get the alias id for the given device_node and
  389. * alias stem.
  390. *
  391. * @np: Pointer to the given device_node
  392. * @stem: Alias stem of the given device_node
  393. * @return alias ID, if found, else -ENODEV
  394. */
  395. int of_alias_get_id(const struct device_node *np, const char *stem);
  396. /**
  397. * of_alias_get_highest_id - Get highest alias id for the given stem
  398. * @stem: Alias stem to be examined
  399. *
  400. * The function travels the lookup table to get the highest alias id for the
  401. * given alias stem.
  402. * @return alias ID, if found, else -1
  403. */
  404. int of_alias_get_highest_id(const char *stem);
  405. /**
  406. * of_get_stdout() - Get node to use for stdout
  407. *
  408. * @return node referred to by stdout-path alias, or NULL if none
  409. */
  410. struct device_node *of_get_stdout(void);
  411. #endif