include/dm/ofnode.h

5  * SPDX-License-Identifier:	GPL-2.0+
21  * ofnode - reference to a device tree node
33  * NULL, or an offset of -1.
58 	int args_count;
63  * ofprop - reference to a property of a device tree node
65  * This struct hold the reference on one property of one node,
67  * a pointer to a struct property in the live device tree.
71  * The property reference can also hold a null reference. This corresponds to
72  * a struct property NULL pointer or an offset of -1.
76  * @prop: Pointer to property, used for live treee.
82 		int offset;
83 		const struct property *prop;
88  * _ofnode_to_np() - convert an ofnode to a live DT node pointer
105  * ofnode_to_offset() - convert an ofnode to a flat DT offset
110  * @return DT offset (can be -1)
112 static inline int ofnode_to_offset(ofnode node)  in ofnode_to_offset()
116 		return -1;  in ofnode_to_offset()
122  * ofnode_valid() - check if an ofnode is valid
131 		return node.of_offset != -1;  in ofnode_valid()
135  * offset_to_ofnode() - convert a DT offset to an ofnode
137  * @of_offset: DT offset (either valid, or -1)
140 static inline ofnode offset_to_ofnode(int of_offset)  in offset_to_ofnode()
153  * np_to_ofnode() - convert a node pointer to an ofnode
168  * ofnode_is_np() - check if a reference is a node pointer
193  * ofnode_equal() - check if two references are equal
204  * ofnode_null() - Obtain a null ofnode
216 		node.of_offset = -1;  in ofnode_null()
222  * ofnode_read_u32() - Read a 32-bit integer from a property
224  * @ref:	valid node reference to read property from
225  * @propname:	name of the property to read from
227  * @return 0 if OK, -ve on error
229 int ofnode_read_u32(ofnode node, const char *propname, u32 *outp);
232  * ofnode_read_s32() - Read a 32-bit integer from a property
234  * @ref:	valid node reference to read property from
235  * @propname:	name of the property to read from
237  * @return 0 if OK, -ve on error
239 static inline int ofnode_read_s32(ofnode node, const char *propname,  in ofnode_read_s32()
246  * ofnode_read_u32_default() - Read a 32-bit integer from a property
248  * @ref:	valid node reference to read property from
249  * @propname:	name of the property to read from
250  * @def:	default value to return if the property has no value
251  * @return property value, or @def if not found
253 int ofnode_read_u32_default(ofnode ref, const char *propname, u32 def);
256  * ofnode_read_u64() - Read a 64-bit integer from a property
258  * @ref:	valid node reference to read property from
259  * @propname:	name of the property to read from
261  * @return 0 if OK, -ve on error
263 int ofnode_read_u64(ofnode node, const char *propname, u64 *outp);
266  * ofnode_read_s32_default() - Read a 32-bit integer from a property
268  * @ref:	valid node reference to read property from
269  * @propname:	name of the property to read from
270  * @def:	default value to return if the property has no value
271  * @return property value, or @def if not found
273 int ofnode_read_s32_default(ofnode node, const char *propname, s32 def);
276  * ofnode_read_string() - Read a string from a property
278  * @ref:	valid node reference to read property from
279  * @propname:	name of the property to read
280  * @return string from property value, or NULL if there is no such property
285  * ofnode_read_u32_array() - Find and read an array of 32 bit integers
287  * @node:	valid node reference to read property from
288  * @propname:	name of the property to read
292  * Search for a property in a device node and read 32-bit value(s) from
293  * it. Returns 0 on success, -EINVAL if the property does not exist,
294  * -ENODATA if property does not have a value, and -EOVERFLOW if the
295  * property data isn't large enough.
299 int ofnode_read_u32_array(ofnode node, const char *propname,
303  * ofnode_write_u32_array() - Find and write an array of 32 bit integers
305  * @node:	valid node reference to read property from
306  * @propname:	name of the property to read
309  * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
310  * if property does not have a value, and -EOVERFLOW is longer than sz.
312 int ofnode_write_u32_array(ofnode node, const char *propname,
316  * ofnode_read_bool() - read a boolean value from a property
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
325  * ofnode_find_subnode() - find a named subnode of a parent node
335  * ofnode_first_subnode() - find the first subnode of a parent node
344  * ofnode_next_subnode() - find the next sibling of a subnode
353  * ofnode_get_parent() - get the ofnode's parent (enclosing ofnode)
361  * ofnode_get_name() - get the name of a node
369  * ofnode_get_by_phandle() - get ofnode from phandle
377  * ofnode_read_size() - read the size of a property
380  * @propname: property to check
381  * @return size of property if present, or -EINVAL if not
383 int ofnode_read_size(ofnode node, const char *propname);
386  * ofnode_get_addr_index() - get an address from a node
394 phys_addr_t ofnode_get_addr_index(ofnode node, int index);
397  * ofnode_get_addr() - get an address from a node
407  * ofnode_stringlist_search() - find a string in a string list and return index
409  * Note that it is possible for this function to succeed on property values
410  * that are not NUL-terminated. That's because the function will stop after
412  * small-valued cell properties, such as #address-cells, when searching for
416  * @propname: name of the property containing the string list
421  *   -ENODATA if the property is not found
422  *   -EINVAL on some other error
424 int ofnode_stringlist_search(ofnode node, const char *propname,
428  * ofnode_read_string_index() - obtain an indexed string from a string list
431  * non-NUL-terminated values. For example on small-valued cell properties
434  * If non-NULL, the length of the string (on success) or a negative error-code
438  * @propname: name of the property containing the string list
443  *   length of string, if found or -ve error value if not found
445 int ofnode_read_string_index(ofnode node, const char *propname, int index,
449  * ofnode_read_string_count() - find the number of strings in a string list
452  * @propname: name of the property containing the string list
454  *   number of strings in the list, or -ve error value if not found
456 int ofnode_read_string_count(ofnode node, const char *property);
459  * ofnode_parse_phandle_with_args() - Find a node pointed by phandle in a list
465  * Caller is responsible to call of_node_put() on the returned out_args->np
471  *	#list-cells = <2>;
475  *	#list-cells = <1>;
483  * ofnode_parse_phandle_with_args(node3, "list", "#list-cells", 0, 1, &args);
486  * @list_name:	property name that contains a list
487  * @cells_name:	property name that specifies phandles' arguments count
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,
496 int ofnode_parse_phandle_with_args(ofnode node, const char *list_name,
497 				   const char *cells_name, int cell_count,
498 				   int index,
502  * ofnode_count_phandle_with_args() - Count number of phandle in a list
509  * @list_name:	property name that contains a list
510  * @cells_name:	property name that specifies phandles' arguments count
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
515 int ofnode_count_phandle_with_args(ofnode node, const char *list_name,
519  * ofnode_path() - find a node by full path
527  * ofnode_get_chosen_prop() - get the value of a chosen property
529  * This looks for a property within the /chosen node and returns its value
531  * @propname: Property name to look for
536  * ofnode_get_chosen_node() - get the chosen node
544  * ofnode_decode_display_timing() - decode display timings
546  * Decode display timings from the supplied 'display-timings' node.
547  * See doc/device-tree-bindings/video/display-timing.txt for binding
550  * @node	'display-timing' node containing the timing subnodes
553  * @return 0 if OK, -FDT_ERR_NOTFOUND if not found
555 int ofnode_decode_display_timing(ofnode node, int index,
559  * ofnode_get_property() - get a pointer to the value of a node property
562  * @propname: property to read
564  * @return pointer to property, or NULL if not found
566 const void *ofnode_get_property(ofnode node, const char *propname, int *lenp);
569  * ofnode_get_first_property()- get the reference of the first property
571  * Get reference to the first property of the node, it is used to iterate
572  * and read all the property with ofnode_get_property_by_prop().
576  * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
578 int ofnode_get_first_property(ofnode node, struct ofprop *prop);
581  * ofnode_get_next_property() - get the reference of the next property
583  * Get reference to the next property of the node, it is used to iterate
584  * and read all the property with ofnode_get_property_by_prop().
587  * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
589 int ofnode_get_next_property(struct ofprop *prop);
592  * ofnode_get_property_by_prop() - get a pointer to the value of a property
594  * Get value for the property identified by the provided reference.
596  * @prop: reference on property
597  * @propname: If non-NULL, place to property name on success,
598  * @lenp: If non-NULL, place to put length on success
599  * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
602 					const char **propname, int *lenp);
605  * ofnode_is_available() - check if a node is marked available
608  * @return true if node's 'status' property is "okay" (or is missing)
613  * ofnode_get_addr_size() - get address and size from a property
615  * This does no address translation. It simply reads an property that contains
619  * @propname: property to read
627  * ofnode_read_u8_array_ptr() - find an 8-bit array
629  * Look up a property in a node and return a pointer to its contents as a
630  * byte array of given length. The property must have at least enough data
635  * @propname	name of property to find
637  * @return pointer to byte array if found, or NULL if the property is not
644  * ofnode_read_pci_addr() - look up a PCI address
646  * Look at an address property in a node and return the PCI address which
648  * The property must hold one fdt_pci_addr with a lengh.
652  * @propname	name of property to find
654  * @return 0 if ok, -ENOENT if the property did not exist, -EINVAL if the
655  *		format of the property was invalid, -ENXIO if the requested
658 int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type,
662  * ofnode_read_addr_cells() - Get the number of address cells for a node
664  * This walks back up the tree to find the closest #address-cells property
670 int ofnode_read_addr_cells(ofnode node);
673  * ofnode_read_size_cells() - Get the number of size cells for a node
675  * This walks back up the tree to find the closest #size-cells property
681 int ofnode_read_size_cells(ofnode node);
684  * ofnode_read_simple_addr_cells() - Get the address cells property in a node
689  * @return value of #address-cells property in this node, or 2 if none
691 int ofnode_read_simple_addr_cells(ofnode node);
694  * ofnode_read_simple_size_cells() - Get the size cells property in a node
699  * @return value of #size-cells property in this node, or 2 if none
701 int ofnode_read_simple_size_cells(ofnode node);
704  * ofnode_pre_reloc() - check if a node should be bound before relocation
706  * Device tree nodes can be marked as needing-to-be-bound in the loader stages
712  * After relocation and jumping into the real U-Boot binary it is possible to
716  * -
717  * - u-boot,dm-pre-reloc: legacy and indicates any of TPL or SPL
719  *   SPL. Should probably be replaced by u-boot,dm-spl for
727 int ofnode_read_resource(ofnode node, uint index, struct resource *res);
728 int ofnode_read_resource_byname(ofnode node, const char *name,
732  * ofnode_for_each_subnode() - iterate over all subnodes of a parent
756  * ofnode_translate_address() - Tranlate a device-tree address
758  * Translate an address from the device-tree into a CPU physical address. This