183d290c5STom Rini /* SPDX-License-Identifier: GPL-2.0+ */
24984de2bSSimon Glass /*
34984de2bSSimon Glass * Copyright (c) 2017 Google, Inc
44984de2bSSimon Glass * Written by Simon Glass <sjg@chromium.org>
54984de2bSSimon Glass */
64984de2bSSimon Glass
74984de2bSSimon Glass #ifndef _DM_OFNODE_H
84984de2bSSimon Glass #define _DM_OFNODE_H
94984de2bSSimon Glass
109e512045SSimon Glass /* TODO(sjg@chromium.org): Drop fdtdec.h include */
119e512045SSimon Glass #include <fdtdec.h>
129e512045SSimon Glass #include <dm/of.h>
139e512045SSimon Glass
149e512045SSimon Glass /* Enable checks to protect against invalid calls */
159e512045SSimon Glass #undef OF_CHECKS
169e512045SSimon Glass
17dcf98852SSimon Glass struct resource;
18dcf98852SSimon Glass
194984de2bSSimon Glass /**
204984de2bSSimon Glass * ofnode - reference to a device tree node
214984de2bSSimon Glass *
224984de2bSSimon Glass * This union can hold either a straightforward pointer to a struct device_node
234984de2bSSimon Glass * in the live device tree, or an offset within the flat device tree. In the
244984de2bSSimon Glass * latter case, the pointer value is just the integer offset within the flat DT.
254984de2bSSimon Glass *
264984de2bSSimon Glass * Thus we can reference nodes in both the live tree (once available) and the
274984de2bSSimon Glass * flat tree (until then). Functions are available to translate between an
284984de2bSSimon Glass * ofnode and either an offset or a struct device_node *.
294984de2bSSimon Glass *
304984de2bSSimon Glass * The reference can also hold a null offset, in which case the pointer value
319e512045SSimon Glass * here is NULL. This corresponds to a struct device_node * value of
324984de2bSSimon Glass * NULL, or an offset of -1.
334984de2bSSimon Glass *
344984de2bSSimon Glass * There is no ambiguity as to whether ofnode holds an offset or a node
354984de2bSSimon Glass * pointer: when the live tree is active it holds a node pointer, otherwise it
364984de2bSSimon Glass * holds an offset. The value itself does not need to be unique and in theory
374984de2bSSimon Glass * the same value could point to a valid device node or a valid offset. We
384984de2bSSimon Glass * could arrange for a unique value to be used (e.g. by making the pointer
394984de2bSSimon Glass * point to an offset within the flat device tree in the case of an offset) but
404984de2bSSimon Glass * this increases code size slightly due to the subtraction. Since it offers no
414984de2bSSimon Glass * real benefit, the approach described here seems best.
424984de2bSSimon Glass *
434984de2bSSimon Glass * For now these points use constant types, since we don't allow writing
444984de2bSSimon Glass * the DT.
454984de2bSSimon Glass *
464984de2bSSimon Glass * @np: Pointer to device node, used for live tree
47afc1a78aSBaruch Siach * @of_offset: Pointer into flat device tree, used for flat tree. Note that this
484984de2bSSimon Glass * is not a really a pointer to a node: it is an offset value. See above.
494984de2bSSimon Glass */
504984de2bSSimon Glass typedef union ofnode_union {
514984de2bSSimon Glass const struct device_node *np; /* will be used for future live tree */
524984de2bSSimon Glass long of_offset;
534984de2bSSimon Glass } ofnode;
544984de2bSSimon Glass
559e512045SSimon Glass struct ofnode_phandle_args {
569e512045SSimon Glass ofnode node;
579e512045SSimon Glass int args_count;
589e512045SSimon Glass uint32_t args[OF_MAX_PHANDLE_ARGS];
599e512045SSimon Glass };
609e512045SSimon Glass
619e512045SSimon Glass /**
629e512045SSimon Glass * _ofnode_to_np() - convert an ofnode to a live DT node pointer
639e512045SSimon Glass *
649e512045SSimon Glass * This cannot be called if the reference contains an offset.
659e512045SSimon Glass *
669e512045SSimon Glass * @node: Reference containing struct device_node * (possibly invalid)
679e512045SSimon Glass * @return pointer to device node (can be NULL)
689e512045SSimon Glass */
ofnode_to_np(ofnode node)699e512045SSimon Glass static inline const struct device_node *ofnode_to_np(ofnode node)
709e512045SSimon Glass {
719e512045SSimon Glass #ifdef OF_CHECKS
729e512045SSimon Glass if (!of_live_active())
739e512045SSimon Glass return NULL;
749e512045SSimon Glass #endif
759e512045SSimon Glass return node.np;
769e512045SSimon Glass }
779e512045SSimon Glass
784984de2bSSimon Glass /**
794984de2bSSimon Glass * ofnode_to_offset() - convert an ofnode to a flat DT offset
804984de2bSSimon Glass *
814984de2bSSimon Glass * This cannot be called if the reference contains a node pointer.
824984de2bSSimon Glass *
834984de2bSSimon Glass * @node: Reference containing offset (possibly invalid)
844984de2bSSimon Glass * @return DT offset (can be -1)
854984de2bSSimon Glass */
ofnode_to_offset(ofnode node)864984de2bSSimon Glass static inline int ofnode_to_offset(ofnode node)
874984de2bSSimon Glass {
889e512045SSimon Glass #ifdef OF_CHECKS
899e512045SSimon Glass if (of_live_active())
909e512045SSimon Glass return -1;
919e512045SSimon Glass #endif
924984de2bSSimon Glass return node.of_offset;
934984de2bSSimon Glass }
944984de2bSSimon Glass
954984de2bSSimon Glass /**
964984de2bSSimon Glass * ofnode_valid() - check if an ofnode is valid
974984de2bSSimon Glass *
984984de2bSSimon Glass * @return true if the reference contains a valid ofnode, false if it is NULL
994984de2bSSimon Glass */
ofnode_valid(ofnode node)1004984de2bSSimon Glass static inline bool ofnode_valid(ofnode node)
1014984de2bSSimon Glass {
1029e512045SSimon Glass if (of_live_active())
1039e512045SSimon Glass return node.np != NULL;
1049e512045SSimon Glass else
1054984de2bSSimon Glass return node.of_offset != -1;
1064984de2bSSimon Glass }
1074984de2bSSimon Glass
1084984de2bSSimon Glass /**
1094984de2bSSimon Glass * offset_to_ofnode() - convert a DT offset to an ofnode
1104984de2bSSimon Glass *
1114984de2bSSimon Glass * @of_offset: DT offset (either valid, or -1)
1124984de2bSSimon Glass * @return reference to the associated DT offset
1134984de2bSSimon Glass */
offset_to_ofnode(int of_offset)1144984de2bSSimon Glass static inline ofnode offset_to_ofnode(int of_offset)
1154984de2bSSimon Glass {
1164984de2bSSimon Glass ofnode node;
1174984de2bSSimon Glass
1189e512045SSimon Glass if (of_live_active())
1199e512045SSimon Glass node.np = NULL;
1209e512045SSimon Glass else
1214984de2bSSimon Glass node.of_offset = of_offset;
1224984de2bSSimon Glass
1234984de2bSSimon Glass return node;
1244984de2bSSimon Glass }
1254984de2bSSimon Glass
1264984de2bSSimon Glass /**
1279e512045SSimon Glass * np_to_ofnode() - convert a node pointer to an ofnode
1289e512045SSimon Glass *
1299e512045SSimon Glass * @np: Live node pointer (can be NULL)
1309e512045SSimon Glass * @return reference to the associated node pointer
1319e512045SSimon Glass */
np_to_ofnode(const struct device_node * np)1329e512045SSimon Glass static inline ofnode np_to_ofnode(const struct device_node *np)
1339e512045SSimon Glass {
1349e512045SSimon Glass ofnode node;
1359e512045SSimon Glass
1369e512045SSimon Glass node.np = np;
1379e512045SSimon Glass
1389e512045SSimon Glass return node;
1399e512045SSimon Glass }
1409e512045SSimon Glass
1419e512045SSimon Glass /**
1429e512045SSimon Glass * ofnode_is_np() - check if a reference is a node pointer
1439e512045SSimon Glass *
1449e512045SSimon Glass * This function associated that if there is a valid live tree then all
1459e512045SSimon Glass * references will use it. This is because using the flat DT when the live tree
1469e512045SSimon Glass * is valid is not permitted.
1479e512045SSimon Glass *
1489e512045SSimon Glass * @node: reference to check (possibly invalid)
1499e512045SSimon Glass * @return true if the reference is a live node pointer, false if it is a DT
1509e512045SSimon Glass * offset
1519e512045SSimon Glass */
ofnode_is_np(ofnode node)1529e512045SSimon Glass static inline bool ofnode_is_np(ofnode node)
1539e512045SSimon Glass {
1549e512045SSimon Glass #ifdef OF_CHECKS
1559e512045SSimon Glass /*
1569e512045SSimon Glass * Check our assumption that flat tree offsets are not used when a
1579e512045SSimon Glass * live tree is in use.
1589e512045SSimon Glass */
1599e512045SSimon Glass assert(!ofnode_valid(node) ||
1609e512045SSimon Glass (of_live_active() ? _ofnode_to_np(node)
1619e512045SSimon Glass : _ofnode_to_np(node)));
1629e512045SSimon Glass #endif
1639e512045SSimon Glass return of_live_active() && ofnode_valid(node);
1649e512045SSimon Glass }
1659e512045SSimon Glass
1669e512045SSimon Glass /**
1674984de2bSSimon Glass * ofnode_equal() - check if two references are equal
1684984de2bSSimon Glass *
1694984de2bSSimon Glass * @return true if equal, else false
1704984de2bSSimon Glass */
ofnode_equal(ofnode ref1,ofnode ref2)1714984de2bSSimon Glass static inline bool ofnode_equal(ofnode ref1, ofnode ref2)
1724984de2bSSimon Glass {
1734984de2bSSimon Glass /* We only need to compare the contents */
1744984de2bSSimon Glass return ref1.of_offset == ref2.of_offset;
1754984de2bSSimon Glass }
1764984de2bSSimon Glass
1779e512045SSimon Glass /**
1789e512045SSimon Glass * ofnode_null() - Obtain a null ofnode
1799e512045SSimon Glass *
1809e512045SSimon Glass * This returns an ofnode which points to no node. It works both with the flat
1819e512045SSimon Glass * tree and livetree.
1829e512045SSimon Glass */
ofnode_null(void)1839e512045SSimon Glass static inline ofnode ofnode_null(void)
1849e512045SSimon Glass {
1859e512045SSimon Glass ofnode node;
1869e512045SSimon Glass
1879e512045SSimon Glass if (of_live_active())
1889e512045SSimon Glass node.np = NULL;
1899e512045SSimon Glass else
1909e512045SSimon Glass node.of_offset = -1;
1919e512045SSimon Glass
1929e512045SSimon Glass return node;
1939e512045SSimon Glass }
1949e512045SSimon Glass
1959e512045SSimon Glass /**
1969e512045SSimon Glass * ofnode_read_u32() - Read a 32-bit integer from a property
1979e512045SSimon Glass *
1989e512045SSimon Glass * @ref: valid node reference to read property from
1999e512045SSimon Glass * @propname: name of the property to read from
2009e512045SSimon Glass * @outp: place to put value (if found)
2019e512045SSimon Glass * @return 0 if OK, -ve on error
2029e512045SSimon Glass */
2039e512045SSimon Glass int ofnode_read_u32(ofnode node, const char *propname, u32 *outp);
2049e512045SSimon Glass
2059e512045SSimon Glass /**
2069e512045SSimon Glass * ofnode_read_s32() - Read a 32-bit integer from a property
2079e512045SSimon Glass *
2089e512045SSimon Glass * @ref: valid node reference to read property from
2099e512045SSimon Glass * @propname: name of the property to read from
2109e512045SSimon Glass * @outp: place to put value (if found)
2119e512045SSimon Glass * @return 0 if OK, -ve on error
2129e512045SSimon Glass */
ofnode_read_s32(ofnode node,const char * propname,s32 * out_value)2139e512045SSimon Glass static inline int ofnode_read_s32(ofnode node, const char *propname,
2149e512045SSimon Glass s32 *out_value)
2159e512045SSimon Glass {
2169e512045SSimon Glass return ofnode_read_u32(node, propname, (u32 *)out_value);
2179e512045SSimon Glass }
2189e512045SSimon Glass
2199e512045SSimon Glass /**
2209e512045SSimon Glass * ofnode_read_u32_default() - Read a 32-bit integer from a property
2219e512045SSimon Glass *
2229e512045SSimon Glass * @ref: valid node reference to read property from
2239e512045SSimon Glass * @propname: name of the property to read from
2249e512045SSimon Glass * @def: default value to return if the property has no value
2259e512045SSimon Glass * @return property value, or @def if not found
2269e512045SSimon Glass */
2279e512045SSimon Glass int ofnode_read_u32_default(ofnode ref, const char *propname, u32 def);
2289e512045SSimon Glass
2299e512045SSimon Glass /**
2309e512045SSimon Glass * ofnode_read_s32_default() - Read a 32-bit integer from a property
2319e512045SSimon Glass *
2329e512045SSimon Glass * @ref: valid node reference to read property from
2339e512045SSimon Glass * @propname: name of the property to read from
2349e512045SSimon Glass * @def: default value to return if the property has no value
2359e512045SSimon Glass * @return property value, or @def if not found
2369e512045SSimon Glass */
2379e512045SSimon Glass int ofnode_read_s32_default(ofnode node, const char *propname, s32 def);
2389e512045SSimon Glass
2399e512045SSimon Glass /**
240afb30129SLukas Auer * ofnode_read_u64() - Read a 64-bit integer from a property
241afb30129SLukas Auer *
242afb30129SLukas Auer * @node: valid node reference to read property from
243afb30129SLukas Auer * @propname: name of the property to read from
244afb30129SLukas Auer * @outp: place to put value (if found)
245afb30129SLukas Auer * @return 0 if OK, -ve on error
246afb30129SLukas Auer */
247afb30129SLukas Auer int ofnode_read_u64(ofnode node, const char *propname, u64 *outp);
248afb30129SLukas Auer
249afb30129SLukas Auer /**
2507e5196c4SSimon Glass * ofnode_read_u64_default() - Read a 64-bit integer from a property
2517e5196c4SSimon Glass *
2527e5196c4SSimon Glass * @ref: valid node reference to read property from
2537e5196c4SSimon Glass * @propname: name of the property to read from
2547e5196c4SSimon Glass * @def: default value to return if the property has no value
2557e5196c4SSimon Glass * @return property value, or @def if not found
2567e5196c4SSimon Glass */
2577e5196c4SSimon Glass int ofnode_read_u64_default(ofnode node, const char *propname, u64 def);
2587e5196c4SSimon Glass
2597e5196c4SSimon Glass /**
2609e512045SSimon Glass * ofnode_read_string() - Read a string from a property
2619e512045SSimon Glass *
2629e512045SSimon Glass * @ref: valid node reference to read property from
2639e512045SSimon Glass * @propname: name of the property to read
2649e512045SSimon Glass * @return string from property value, or NULL if there is no such property
2659e512045SSimon Glass */
2669e512045SSimon Glass const char *ofnode_read_string(ofnode node, const char *propname);
2679e512045SSimon Glass
2689e512045SSimon Glass /**
269bed77496SSimon Glass * ofnode_read_u32_array() - Find and read an array of 32 bit integers
2709e512045SSimon Glass *
2719e512045SSimon Glass * @node: valid node reference to read property from
2729e512045SSimon Glass * @propname: name of the property to read
2739e512045SSimon Glass * @out_values: pointer to return value, modified only if return value is 0
2749e512045SSimon Glass * @sz: number of array elements to read
275fbe8d033SSimon Glass * @return 0 if OK, -ve on error
2769e512045SSimon Glass *
2779e512045SSimon Glass * Search for a property in a device node and read 32-bit value(s) from
2789e512045SSimon Glass * it. Returns 0 on success, -EINVAL if the property does not exist,
2799e512045SSimon Glass * -ENODATA if property does not have a value, and -EOVERFLOW if the
2809e512045SSimon Glass * property data isn't large enough.
2819e512045SSimon Glass *
2829e512045SSimon Glass * The out_values is modified only if a valid u32 value can be decoded.
2839e512045SSimon Glass */
2849e512045SSimon Glass int ofnode_read_u32_array(ofnode node, const char *propname,
2859e512045SSimon Glass u32 *out_values, size_t sz);
2869e512045SSimon Glass
2879e512045SSimon Glass /**
2889e512045SSimon Glass * ofnode_read_bool() - read a boolean value from a property
2899e512045SSimon Glass *
2909e512045SSimon Glass * @node: valid node reference to read property from
2919e512045SSimon Glass * @propname: name of property to read
2929e512045SSimon Glass * @return true if property is present (meaning true), false if not present
2939e512045SSimon Glass */
2949e512045SSimon Glass bool ofnode_read_bool(ofnode node, const char *propname);
2959e512045SSimon Glass
2969e512045SSimon Glass /**
2979e512045SSimon Glass * ofnode_find_subnode() - find a named subnode of a parent node
2989e512045SSimon Glass *
2999e512045SSimon Glass * @node: valid reference to parent node
3009e512045SSimon Glass * @subnode_name: name of subnode to find
3019e512045SSimon Glass * @return reference to subnode (which can be invalid if there is no such
3029e512045SSimon Glass * subnode)
3039e512045SSimon Glass */
3049e512045SSimon Glass ofnode ofnode_find_subnode(ofnode node, const char *subnode_name);
3059e512045SSimon Glass
3069e512045SSimon Glass /**
3079e512045SSimon Glass * ofnode_first_subnode() - find the first subnode of a parent node
3089e512045SSimon Glass *
3099e512045SSimon Glass * @node: valid reference to a valid parent node
3109e512045SSimon Glass * @return reference to the first subnode (which can be invalid if the parent
3119e512045SSimon Glass * node has no subnodes)
3129e512045SSimon Glass */
3139e512045SSimon Glass ofnode ofnode_first_subnode(ofnode node);
3149e512045SSimon Glass
3159e512045SSimon Glass /**
3169e512045SSimon Glass * ofnode_next_subnode() - find the next sibling of a subnode
3179e512045SSimon Glass *
3189e512045SSimon Glass * @node: valid reference to previous node (sibling)
3199e512045SSimon Glass * @return reference to the next subnode (which can be invalid if the node
3209e512045SSimon Glass * has no more siblings)
3219e512045SSimon Glass */
3229e512045SSimon Glass ofnode ofnode_next_subnode(ofnode node);
3239e512045SSimon Glass
3249e512045SSimon Glass /**
325e2d5997fSPhilipp Tomsich * ofnode_get_parent() - get the ofnode's parent (enclosing ofnode)
326e2d5997fSPhilipp Tomsich *
327e2d5997fSPhilipp Tomsich * @node: valid node to look up
328e2d5997fSPhilipp Tomsich * @return ofnode reference of the parent node
329e2d5997fSPhilipp Tomsich */
330e2d5997fSPhilipp Tomsich ofnode ofnode_get_parent(ofnode node);
331e2d5997fSPhilipp Tomsich
332e2d5997fSPhilipp Tomsich /**
3339e512045SSimon Glass * ofnode_get_name() - get the name of a node
3349e512045SSimon Glass *
3359e512045SSimon Glass * @node: valid node to look up
336*33810b4eSBaruch Siach * @return name of node
3379e512045SSimon Glass */
3389e512045SSimon Glass const char *ofnode_get_name(ofnode node);
3399e512045SSimon Glass
3409e512045SSimon Glass /**
341b4f20767SKever Yang * ofnode_get_by_phandle() - get ofnode from phandle
342b4f20767SKever Yang *
343b4f20767SKever Yang * @phandle: phandle to look up
344b4f20767SKever Yang * @return ofnode reference to the phandle
345b4f20767SKever Yang */
346b4f20767SKever Yang ofnode ofnode_get_by_phandle(uint phandle);
347b4f20767SKever Yang
348b4f20767SKever Yang /**
3499e512045SSimon Glass * ofnode_read_size() - read the size of a property
3509e512045SSimon Glass *
3519e512045SSimon Glass * @node: node to check
3529e512045SSimon Glass * @propname: property to check
3539e512045SSimon Glass * @return size of property if present, or -EINVAL if not
3549e512045SSimon Glass */
3559e512045SSimon Glass int ofnode_read_size(ofnode node, const char *propname);
3569e512045SSimon Glass
3579e512045SSimon Glass /**
358bed77496SSimon Glass * ofnode_get_addr_index() - get an address from a node
359bed77496SSimon Glass *
360bed77496SSimon Glass * This reads the register address from a node
361bed77496SSimon Glass *
362bed77496SSimon Glass * @node: node to read from
363bed77496SSimon Glass * @index: Index of address to read (0 for first)
364bed77496SSimon Glass * @return address, or FDT_ADDR_T_NONE if not present or invalid
365bed77496SSimon Glass */
366bed77496SSimon Glass phys_addr_t ofnode_get_addr_index(ofnode node, int index);
367bed77496SSimon Glass
368bed77496SSimon Glass /**
369bed77496SSimon Glass * ofnode_get_addr() - get an address from a node
370bed77496SSimon Glass *
371bed77496SSimon Glass * This reads the register address from a node
372bed77496SSimon Glass *
373bed77496SSimon Glass * @node: node to read from
374bed77496SSimon Glass * @return address, or FDT_ADDR_T_NONE if not present or invalid
375bed77496SSimon Glass */
376bed77496SSimon Glass phys_addr_t ofnode_get_addr(ofnode node);
377bed77496SSimon Glass
378bed77496SSimon Glass /**
3799e512045SSimon Glass * ofnode_stringlist_search() - find a string in a string list and return index
3809e512045SSimon Glass *
3819e512045SSimon Glass * Note that it is possible for this function to succeed on property values
3829e512045SSimon Glass * that are not NUL-terminated. That's because the function will stop after
3839e512045SSimon Glass * finding the first occurrence of @string. This can for example happen with
3849e512045SSimon Glass * small-valued cell properties, such as #address-cells, when searching for
3859e512045SSimon Glass * the empty string.
3869e512045SSimon Glass *
3879e512045SSimon Glass * @node: node to check
3889e512045SSimon Glass * @propname: name of the property containing the string list
3899e512045SSimon Glass * @string: string to look up in the string list
3909e512045SSimon Glass *
3919e512045SSimon Glass * @return:
3929e512045SSimon Glass * the index of the string in the list of strings
3939e512045SSimon Glass * -ENODATA if the property is not found
3949e512045SSimon Glass * -EINVAL on some other error
3959e512045SSimon Glass */
3969e512045SSimon Glass int ofnode_stringlist_search(ofnode node, const char *propname,
3979e512045SSimon Glass const char *string);
3989e512045SSimon Glass
3999e512045SSimon Glass /**
4008c293d6aSSimon Glass * ofnode_read_string_index() - obtain an indexed string from a string list
4019e512045SSimon Glass *
4029e512045SSimon Glass * Note that this will successfully extract strings from properties with
4039e512045SSimon Glass * non-NUL-terminated values. For example on small-valued cell properties
4049e512045SSimon Glass * this function will return the empty string.
4059e512045SSimon Glass *
4069e512045SSimon Glass * If non-NULL, the length of the string (on success) or a negative error-code
4079e512045SSimon Glass * (on failure) will be stored in the integer pointer to by lenp.
4089e512045SSimon Glass *
4099e512045SSimon Glass * @node: node to check
4109e512045SSimon Glass * @propname: name of the property containing the string list
4119e512045SSimon Glass * @index: index of the string to return
4129e512045SSimon Glass * @lenp: return location for the string length or an error code on failure
4139e512045SSimon Glass *
4149e512045SSimon Glass * @return:
4159e512045SSimon Glass * length of string, if found or -ve error value if not found
4169e512045SSimon Glass */
4179e512045SSimon Glass int ofnode_read_string_index(ofnode node, const char *propname, int index,
4189e512045SSimon Glass const char **outp);
4199e512045SSimon Glass
4209e512045SSimon Glass /**
4218c293d6aSSimon Glass * ofnode_read_string_count() - find the number of strings in a string list
4228c293d6aSSimon Glass *
4238c293d6aSSimon Glass * @node: node to check
4248c293d6aSSimon Glass * @propname: name of the property containing the string list
4258c293d6aSSimon Glass * @return:
4268c293d6aSSimon Glass * number of strings in the list, or -ve error value if not found
4278c293d6aSSimon Glass */
4288c293d6aSSimon Glass int ofnode_read_string_count(ofnode node, const char *property);
4298c293d6aSSimon Glass
4308c293d6aSSimon Glass /**
4319e512045SSimon Glass * ofnode_parse_phandle_with_args() - Find a node pointed by phandle in a list
4329e512045SSimon Glass *
4339e512045SSimon Glass * This function is useful to parse lists of phandles and their arguments.
4349e512045SSimon Glass * Returns 0 on success and fills out_args, on error returns appropriate
4359e512045SSimon Glass * errno value.
4369e512045SSimon Glass *
4379e512045SSimon Glass * Caller is responsible to call of_node_put() on the returned out_args->np
4389e512045SSimon Glass * pointer.
4399e512045SSimon Glass *
4409e512045SSimon Glass * Example:
4419e512045SSimon Glass *
4429e512045SSimon Glass * phandle1: node1 {
4439e512045SSimon Glass * #list-cells = <2>;
4449e512045SSimon Glass * }
4459e512045SSimon Glass *
4469e512045SSimon Glass * phandle2: node2 {
4479e512045SSimon Glass * #list-cells = <1>;
4489e512045SSimon Glass * }
4499e512045SSimon Glass *
4509e512045SSimon Glass * node3 {
4519e512045SSimon Glass * list = <&phandle1 1 2 &phandle2 3>;
4529e512045SSimon Glass * }
4539e512045SSimon Glass *
4549e512045SSimon Glass * To get a device_node of the `node2' node you may call this:
4559e512045SSimon Glass * ofnode_parse_phandle_with_args(node3, "list", "#list-cells", 0, 1, &args);
4569e512045SSimon Glass *
4579e512045SSimon Glass * @node: device tree node containing a list
4589e512045SSimon Glass * @list_name: property name that contains a list
4599e512045SSimon Glass * @cells_name: property name that specifies phandles' arguments count
4609e512045SSimon Glass * @cells_count: Cell count to use if @cells_name is NULL
4619e512045SSimon Glass * @index: index of a phandle to parse out
4629e512045SSimon Glass * @out_args: optional pointer to output arguments structure (will be filled)
4639e512045SSimon Glass * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
4649e512045SSimon Glass * @list_name does not exist, -EINVAL if a phandle was not found,
4659e512045SSimon Glass * @cells_name could not be found, the arguments were truncated or there
4669e512045SSimon Glass * were too many arguments.
4679e512045SSimon Glass */
4689e512045SSimon Glass int ofnode_parse_phandle_with_args(ofnode node, const char *list_name,
4699e512045SSimon Glass const char *cells_name, int cell_count,
4709e512045SSimon Glass int index,
4719e512045SSimon Glass struct ofnode_phandle_args *out_args);
4729e512045SSimon Glass
4739e512045SSimon Glass /**
474642346aeSPatrice Chotard * ofnode_count_phandle_with_args() - Count number of phandle in a list
475642346aeSPatrice Chotard *
476642346aeSPatrice Chotard * This function is useful to count phandles into a list.
477642346aeSPatrice Chotard * Returns number of phandle on success, on error returns appropriate
478642346aeSPatrice Chotard * errno value.
479642346aeSPatrice Chotard *
480642346aeSPatrice Chotard * @node: device tree node containing a list
481642346aeSPatrice Chotard * @list_name: property name that contains a list
482642346aeSPatrice Chotard * @cells_name: property name that specifies phandles' arguments count
483642346aeSPatrice Chotard * @return number of phandle on success, -ENOENT if @list_name does not
484642346aeSPatrice Chotard * exist, -EINVAL if a phandle was not found, @cells_name could not
485642346aeSPatrice Chotard * be found.
486642346aeSPatrice Chotard */
487642346aeSPatrice Chotard int ofnode_count_phandle_with_args(ofnode node, const char *list_name,
488642346aeSPatrice Chotard const char *cells_name);
489642346aeSPatrice Chotard
490642346aeSPatrice Chotard /**
4919e512045SSimon Glass * ofnode_path() - find a node by full path
4929e512045SSimon Glass *
4939e512045SSimon Glass * @path: Full path to node, e.g. "/bus/spi@1"
4949e512045SSimon Glass * @return reference to the node found. Use ofnode_valid() to check if it exists
4959e512045SSimon Glass */
4969e512045SSimon Glass ofnode ofnode_path(const char *path);
4979e512045SSimon Glass
4989e512045SSimon Glass /**
4999e512045SSimon Glass * ofnode_get_chosen_prop() - get the value of a chosen property
5009e512045SSimon Glass *
5019e512045SSimon Glass * This looks for a property within the /chosen node and returns its value
5029e512045SSimon Glass *
5039e512045SSimon Glass * @propname: Property name to look for
504fbe8d033SSimon Glass * @return property value if found, else NULL
5059e512045SSimon Glass */
5069e512045SSimon Glass const char *ofnode_get_chosen_prop(const char *propname);
5079e512045SSimon Glass
5089e512045SSimon Glass /**
5099e512045SSimon Glass * ofnode_get_chosen_node() - get the chosen node
5109e512045SSimon Glass *
5119e512045SSimon Glass * @return the chosen node if present, else ofnode_null()
5129e512045SSimon Glass */
5139e512045SSimon Glass ofnode ofnode_get_chosen_node(const char *name);
5149e512045SSimon Glass
5159e512045SSimon Glass struct display_timing;
5169e512045SSimon Glass /**
5179e512045SSimon Glass * ofnode_decode_display_timing() - decode display timings
5189e512045SSimon Glass *
5199e512045SSimon Glass * Decode display timings from the supplied 'display-timings' node.
5209e512045SSimon Glass * See doc/device-tree-bindings/video/display-timing.txt for binding
5219e512045SSimon Glass * information.
5229e512045SSimon Glass *
5239e512045SSimon Glass * @node 'display-timing' node containing the timing subnodes
5249e512045SSimon Glass * @index Index number to read (0=first timing subnode)
5259e512045SSimon Glass * @config Place to put timings
5269e512045SSimon Glass * @return 0 if OK, -FDT_ERR_NOTFOUND if not found
5279e512045SSimon Glass */
5289e512045SSimon Glass int ofnode_decode_display_timing(ofnode node, int index,
5299e512045SSimon Glass struct display_timing *config);
5309e512045SSimon Glass
5319e512045SSimon Glass /**
53261e51babSMasahiro Yamada * ofnode_get_property()- - get a pointer to the value of a node property
5339e512045SSimon Glass *
5349e512045SSimon Glass * @node: node to read
5359e512045SSimon Glass * @propname: property to read
5369e512045SSimon Glass * @lenp: place to put length on success
5379e512045SSimon Glass * @return pointer to property, or NULL if not found
5389e512045SSimon Glass */
53961e51babSMasahiro Yamada const void *ofnode_get_property(ofnode node, const char *propname, int *lenp);
5409e512045SSimon Glass
5419e512045SSimon Glass /**
5429e512045SSimon Glass * ofnode_is_available() - check if a node is marked available
5439e512045SSimon Glass *
5449e512045SSimon Glass * @node: node to check
5459e512045SSimon Glass * @return true if node's 'status' property is "okay" (or is missing)
5469e512045SSimon Glass */
5479e512045SSimon Glass bool ofnode_is_available(ofnode node);
5489e512045SSimon Glass
5499e512045SSimon Glass /**
5509e512045SSimon Glass * ofnode_get_addr_size() - get address and size from a property
5519e512045SSimon Glass *
5529e512045SSimon Glass * This does no address translation. It simply reads an property that contains
5539e512045SSimon Glass * an address and a size value, one after the other.
5549e512045SSimon Glass *
5559e512045SSimon Glass * @node: node to read from
5569e512045SSimon Glass * @propname: property to read
5579e512045SSimon Glass * @sizep: place to put size value (on success)
5589e512045SSimon Glass * @return address value, or FDT_ADDR_T_NONE on error
5599e512045SSimon Glass */
5609e512045SSimon Glass phys_addr_t ofnode_get_addr_size(ofnode node, const char *propname,
5619e512045SSimon Glass phys_size_t *sizep);
5629e512045SSimon Glass
5639e512045SSimon Glass /**
5649e512045SSimon Glass * ofnode_read_u8_array_ptr() - find an 8-bit array
5659e512045SSimon Glass *
5669e512045SSimon Glass * Look up a property in a node and return a pointer to its contents as a
5679e512045SSimon Glass * byte array of given length. The property must have at least enough data
5689e512045SSimon Glass * for the array (count bytes). It may have more, but this will be ignored.
5699e512045SSimon Glass * The data is not copied.
5709e512045SSimon Glass *
5719e512045SSimon Glass * @node node to examine
5729e512045SSimon Glass * @propname name of property to find
5739e512045SSimon Glass * @sz number of array elements
5749e512045SSimon Glass * @return pointer to byte array if found, or NULL if the property is not
5759e512045SSimon Glass * found or there is not enough data
5769e512045SSimon Glass */
5779e512045SSimon Glass const uint8_t *ofnode_read_u8_array_ptr(ofnode node, const char *propname,
5789e512045SSimon Glass size_t sz);
5799e512045SSimon Glass
5809e512045SSimon Glass /**
5819e512045SSimon Glass * ofnode_read_pci_addr() - look up a PCI address
5829e512045SSimon Glass *
5839e512045SSimon Glass * Look at an address property in a node and return the PCI address which
5849e512045SSimon Glass * corresponds to the given type in the form of fdt_pci_addr.
5859e512045SSimon Glass * The property must hold one fdt_pci_addr with a lengh.
5869e512045SSimon Glass *
5879e512045SSimon Glass * @node node to examine
5889e512045SSimon Glass * @type pci address type (FDT_PCI_SPACE_xxx)
5899e512045SSimon Glass * @propname name of property to find
5909e512045SSimon Glass * @addr returns pci address in the form of fdt_pci_addr
5919e512045SSimon Glass * @return 0 if ok, -ENOENT if the property did not exist, -EINVAL if the
5929e512045SSimon Glass * format of the property was invalid, -ENXIO if the requested
5939e512045SSimon Glass * address type was not found
5949e512045SSimon Glass */
5959e512045SSimon Glass int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type,
5969e512045SSimon Glass const char *propname, struct fdt_pci_addr *addr);
5979e512045SSimon Glass
5989e512045SSimon Glass /**
5997b9cbaddSBin Meng * ofnode_read_pci_vendev() - look up PCI vendor and device id
6007b9cbaddSBin Meng *
6017b9cbaddSBin Meng * Look at the compatible property of a device node that represents a PCI
6027b9cbaddSBin Meng * device and extract pci vendor id and device id from it.
6037b9cbaddSBin Meng *
6047b9cbaddSBin Meng * @param node node to examine
6057b9cbaddSBin Meng * @param vendor vendor id of the pci device
6067b9cbaddSBin Meng * @param device device id of the pci device
6077b9cbaddSBin Meng * @return 0 if ok, negative on error
6087b9cbaddSBin Meng */
6097b9cbaddSBin Meng int ofnode_read_pci_vendev(ofnode node, u16 *vendor, u16 *device);
6107b9cbaddSBin Meng
6117b9cbaddSBin Meng /**
6129e512045SSimon Glass * ofnode_read_addr_cells() - Get the number of address cells for a node
6139e512045SSimon Glass *
6149e512045SSimon Glass * This walks back up the tree to find the closest #address-cells property
6159e512045SSimon Glass * which controls the given node.
6169e512045SSimon Glass *
6179e512045SSimon Glass * @node: Node to check
6189e512045SSimon Glass * @return number of address cells this node uses
6199e512045SSimon Glass */
6209e512045SSimon Glass int ofnode_read_addr_cells(ofnode node);
6219e512045SSimon Glass
6229e512045SSimon Glass /**
6239e512045SSimon Glass * ofnode_read_size_cells() - Get the number of size cells for a node
6249e512045SSimon Glass *
6259e512045SSimon Glass * This walks back up the tree to find the closest #size-cells property
6269e512045SSimon Glass * which controls the given node.
6279e512045SSimon Glass *
6289e512045SSimon Glass * @node: Node to check
6299e512045SSimon Glass * @return number of size cells this node uses
6309e512045SSimon Glass */
6319e512045SSimon Glass int ofnode_read_size_cells(ofnode node);
6329e512045SSimon Glass
6339e512045SSimon Glass /**
634878d68c0SSimon Glass * ofnode_read_simple_addr_cells() - Get the address cells property in a node
635878d68c0SSimon Glass *
636878d68c0SSimon Glass * This function matches fdt_address_cells().
637878d68c0SSimon Glass *
638878d68c0SSimon Glass * @np: Node pointer to check
639878d68c0SSimon Glass * @return value of #address-cells property in this node, or 2 if none
640878d68c0SSimon Glass */
641878d68c0SSimon Glass int ofnode_read_simple_addr_cells(ofnode node);
642878d68c0SSimon Glass
643878d68c0SSimon Glass /**
644878d68c0SSimon Glass * ofnode_read_simple_size_cells() - Get the size cells property in a node
645878d68c0SSimon Glass *
646878d68c0SSimon Glass * This function matches fdt_size_cells().
647878d68c0SSimon Glass *
648878d68c0SSimon Glass * @np: Node pointer to check
649878d68c0SSimon Glass * @return value of #size-cells property in this node, or 2 if none
650878d68c0SSimon Glass */
651878d68c0SSimon Glass int ofnode_read_simple_size_cells(ofnode node);
652878d68c0SSimon Glass
653878d68c0SSimon Glass /**
6549e512045SSimon Glass * ofnode_pre_reloc() - check if a node should be bound before relocation
6559e512045SSimon Glass *
6569e512045SSimon Glass * Device tree nodes can be marked as needing-to-be-bound in the loader stages
6579e512045SSimon Glass * via special device tree properties.
6589e512045SSimon Glass *
6599e512045SSimon Glass * Before relocation this function can be used to check if nodes are required
6609e512045SSimon Glass * in either SPL or TPL stages.
6619e512045SSimon Glass *
6629e512045SSimon Glass * After relocation and jumping into the real U-Boot binary it is possible to
6639e512045SSimon Glass * determine if a node was bound in one of SPL/TPL stages.
6649e512045SSimon Glass *
6659e512045SSimon Glass * There are 3 settings currently in use
6669e512045SSimon Glass * -
6679e512045SSimon Glass * - u-boot,dm-pre-reloc: legacy and indicates any of TPL or SPL
6689e512045SSimon Glass * Existing platforms only use it to indicate nodes needed in
6699e512045SSimon Glass * SPL. Should probably be replaced by u-boot,dm-spl for
6709e512045SSimon Glass * new platforms.
6719e512045SSimon Glass *
6729e512045SSimon Glass * @node: node to check
673fbe8d033SSimon Glass * @return true if node is needed in SPL/TL, false otherwise
6749e512045SSimon Glass */
6759e512045SSimon Glass bool ofnode_pre_reloc(ofnode node);
6769e512045SSimon Glass
677c98ad443SSimon Glass /**
678c98ad443SSimon Glass * ofnode_read_resource() - Read a resource from a node
679c98ad443SSimon Glass *
680c98ad443SSimon Glass * Read resource information from a node at the given index
681c98ad443SSimon Glass *
682c98ad443SSimon Glass * @node: Node to read from
683c98ad443SSimon Glass * @index: Index of resource to read (0 = first)
684c98ad443SSimon Glass * @res: Returns resource that was read, on success
685c98ad443SSimon Glass * @return 0 if OK, -ve on error
686c98ad443SSimon Glass */
687dcf98852SSimon Glass int ofnode_read_resource(ofnode node, uint index, struct resource *res);
688c98ad443SSimon Glass
689c98ad443SSimon Glass /**
690c98ad443SSimon Glass * ofnode_read_resource_byname() - Read a resource from a node by name
691c98ad443SSimon Glass *
692c98ad443SSimon Glass * Read resource information from a node matching the given name. This uses a
693c98ad443SSimon Glass * 'reg-names' string list property with the names matching the associated
694c98ad443SSimon Glass * 'reg' property list.
695c98ad443SSimon Glass *
696c98ad443SSimon Glass * @node: Node to read from
697c98ad443SSimon Glass * @name: Name of resource to read
698c98ad443SSimon Glass * @res: Returns resource that was read, on success
699c98ad443SSimon Glass * @return 0 if OK, -ve on error
700c98ad443SSimon Glass */
7017b8b47bdSMasahiro Yamada int ofnode_read_resource_byname(ofnode node, const char *name,
7027b8b47bdSMasahiro Yamada struct resource *res);
703dcf98852SSimon Glass
7043991f42eSSimon Glass /**
705c60f671bSSimon Glass * ofnode_by_compatible() - Find the next compatible node
706c60f671bSSimon Glass *
707c60f671bSSimon Glass * Find the next node after @from that is compatible with @compat
708c60f671bSSimon Glass *
709c60f671bSSimon Glass * @from: ofnode to start from (use ofnode_null() to start at the beginning)
710c60f671bSSimon Glass * @compat: Compatible string to match
711c60f671bSSimon Glass * @return ofnode found, or ofnode_null() if none
712c60f671bSSimon Glass */
713c60f671bSSimon Glass ofnode ofnode_by_compatible(ofnode from, const char *compat);
714c60f671bSSimon Glass
715c60f671bSSimon Glass /**
71661fba0faSJens Wiklander * ofnode_by_prop_value() - Find the next node with given property value
71761fba0faSJens Wiklander *
71861fba0faSJens Wiklander * Find the next node after @from that has a @propname with a value
71961fba0faSJens Wiklander * @propval and a length @proplen.
72061fba0faSJens Wiklander *
72161fba0faSJens Wiklander * @from: ofnode to start from (use ofnode_null() to start at the
72261fba0faSJens Wiklander * beginning) @propname: property name to check @propval: property value to
72361fba0faSJens Wiklander * search for @proplen: length of the value in propval @return ofnode
72461fba0faSJens Wiklander * found, or ofnode_null() if none
72561fba0faSJens Wiklander */
72661fba0faSJens Wiklander ofnode ofnode_by_prop_value(ofnode from, const char *propname,
72761fba0faSJens Wiklander const void *propval, int proplen);
72861fba0faSJens Wiklander
72961fba0faSJens Wiklander /**
7303991f42eSSimon Glass * ofnode_for_each_subnode() - iterate over all subnodes of a parent
7313991f42eSSimon Glass *
7323991f42eSSimon Glass * @node: child node (ofnode, lvalue)
7333991f42eSSimon Glass * @parent: parent node (ofnode)
7343991f42eSSimon Glass *
7353991f42eSSimon Glass * This is a wrapper around a for loop and is used like so:
7363991f42eSSimon Glass *
7373991f42eSSimon Glass * ofnode node;
7383991f42eSSimon Glass *
7393991f42eSSimon Glass * ofnode_for_each_subnode(node, parent) {
7403991f42eSSimon Glass * Use node
7413991f42eSSimon Glass * ...
7423991f42eSSimon Glass * }
7433991f42eSSimon Glass *
7443991f42eSSimon Glass * Note that this is implemented as a macro and @node is used as
7453991f42eSSimon Glass * iterator in the loop. The parent variable can be a constant or even a
7463991f42eSSimon Glass * literal.
7473991f42eSSimon Glass */
7483991f42eSSimon Glass #define ofnode_for_each_subnode(node, parent) \
7493991f42eSSimon Glass for (node = ofnode_first_subnode(parent); \
7503991f42eSSimon Glass ofnode_valid(node); \
7513991f42eSSimon Glass node = ofnode_next_subnode(node))
7523991f42eSSimon Glass
753147c6074SMario Six /**
754147c6074SMario Six * ofnode_translate_address() - Tranlate a device-tree address
755147c6074SMario Six *
756147c6074SMario Six * Translate an address from the device-tree into a CPU physical address. This
757147c6074SMario Six * function walks up the tree and applies the various bus mappings along the
758147c6074SMario Six * way.
759147c6074SMario Six *
760147c6074SMario Six * @ofnode: Device tree node giving the context in which to translate the
761147c6074SMario Six * address
762147c6074SMario Six * @in_addr: pointer to the address to translate
763147c6074SMario Six * @return the translated address; OF_BAD_ADDR on error
764147c6074SMario Six */
765147c6074SMario Six u64 ofnode_translate_address(ofnode node, const fdt32_t *in_addr);
7665ccc2c21SMasahiro Yamada
7675ccc2c21SMasahiro Yamada /**
7685ccc2c21SMasahiro Yamada * ofnode_device_is_compatible() - check if the node is compatible with compat
7695ccc2c21SMasahiro Yamada *
7705ccc2c21SMasahiro Yamada * This allows to check whether the node is comaptible with the compat.
7715ccc2c21SMasahiro Yamada *
7725ccc2c21SMasahiro Yamada * @node: Device tree node for which compatible needs to be verified.
7735ccc2c21SMasahiro Yamada * @compat: Compatible string which needs to verified in the given node.
7745ccc2c21SMasahiro Yamada * @return true if OK, false if the compatible is not found
7755ccc2c21SMasahiro Yamada */
7765ccc2c21SMasahiro Yamada int ofnode_device_is_compatible(ofnode node, const char *compat);
777e369e58dSMario Six
778e369e58dSMario Six /**
779e369e58dSMario Six * ofnode_write_prop() - Set a property of a ofnode
780e369e58dSMario Six *
781e369e58dSMario Six * Note that the value passed to the function is *not* allocated by the
782e369e58dSMario Six * function itself, but must be allocated by the caller if necessary.
783e369e58dSMario Six *
784e369e58dSMario Six * @node: The node for whose property should be set
785e369e58dSMario Six * @propname: The name of the property to set
786e369e58dSMario Six * @len: The length of the new value of the property
787e369e58dSMario Six * @value: The new value of the property (must be valid prior to calling
788e369e58dSMario Six * the function)
789e369e58dSMario Six * @return 0 if successful, -ve on error
790e369e58dSMario Six */
791e369e58dSMario Six int ofnode_write_prop(ofnode node, const char *propname, int len,
792e369e58dSMario Six const void *value);
793e369e58dSMario Six
794e369e58dSMario Six /**
795e369e58dSMario Six * ofnode_write_string() - Set a string property of a ofnode
796e369e58dSMario Six *
797e369e58dSMario Six * Note that the value passed to the function is *not* allocated by the
798e369e58dSMario Six * function itself, but must be allocated by the caller if necessary.
799e369e58dSMario Six *
800e369e58dSMario Six * @node: The node for whose string property should be set
801e369e58dSMario Six * @propname: The name of the string property to set
802e369e58dSMario Six * @value: The new value of the string property (must be valid prior to
803e369e58dSMario Six * calling the function)
804e369e58dSMario Six * @return 0 if successful, -ve on error
805e369e58dSMario Six */
806e369e58dSMario Six int ofnode_write_string(ofnode node, const char *propname, const char *value);
807e369e58dSMario Six
808e369e58dSMario Six /**
809e369e58dSMario Six * ofnode_set_enabled() - Enable or disable a device tree node given by its
810e369e58dSMario Six * ofnode
811e369e58dSMario Six *
812e369e58dSMario Six * This function effectively sets the node's "status" property to either "okay"
813e369e58dSMario Six * or "disable", hence making it available for driver model initialization or
814e369e58dSMario Six * not.
815e369e58dSMario Six *
816e369e58dSMario Six * @node: The node to enable
817e369e58dSMario Six * @value: Flag that tells the function to either disable or enable the
818e369e58dSMario Six * node
819e369e58dSMario Six * @return 0 if successful, -ve on error
820e369e58dSMario Six */
821e369e58dSMario Six int ofnode_set_enabled(ofnode node, bool value);
822e369e58dSMario Six
8234984de2bSSimon Glass #endif
824