include/dm/ofnode.h

5  * SPDX-License-Identifier:	GPL-2.0+
21  * ofnode - reference to a device tree node
24  * in the live device tree, or an offset within the flat device tree. In the
27  * Thus we can reference nodes in both the live tree (once available) and the
33  * NULL, or an offset of -1.
36  * pointer: when the live tree is active it holds a node pointer, otherwise it
47  * @np: Pointer to device node, used for live tree
52 	const struct device_node *np;	/* will be used for future live tree */
63  * ofprop - reference to a property of a device tree node
67  * a pointer to a struct property in the live device tree.
69  * Thus we can reference arguments in both the live tree and the flat tree.
72  * a struct property NULL pointer or an offset of -1.
76  * @prop: Pointer to property, used for live treee.
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)
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)
153  * np_to_ofnode() - convert a node pointer to an ofnode
155  * @np: Live node pointer (can be NULL)
168  * ofnode_is_np() - check if a reference is a node pointer
170  * This function associated that if there is a valid live tree then all
171  * references will use it. This is because using the flat DT when the live tree
175  * @return true if the reference is a live node pointer, false if it is a DT
183 	 * live tree is in use.  in ofnode_is_np()
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
227  * @return 0 if OK, -ve on error
232  * ofnode_read_s32() - Read a 32-bit integer from a property
237  * @return 0 if OK, -ve on error
246  * ofnode_read_u32_default() - Read a 32-bit integer from a property
256  * ofnode_read_u64() - Read a 64-bit integer from a property
261  * @return 0 if OK, -ve on error
266  * ofnode_read_s32_default() - Read a 32-bit integer from a property
276  * ofnode_read_string() - Read a string from a property
285  * ofnode_read_u32_array() - Find and read an array of 32 bit integers
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
303  * ofnode_write_u32_array() - Find and write an array of 32 bit integers
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.
316  * ofnode_read_bool() - read a boolean value from a property
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
381  * @return size of property if present, or -EINVAL if not
386  * ofnode_get_addr_index() - get an address from a node
397  * ofnode_get_addr() - get an address from a node
407  * ofnode_stringlist_search() - find a string in a string list and return index
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
421  *   -ENODATA if the property is not found
422  *   -EINVAL on some other error
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
443  *   length of string, if found or -ve error value if not found
449  * ofnode_read_string_count() - find the number of strings in a string list
454  *   number of strings in the list, or -ve error value if not found
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);
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,
502  * ofnode_count_phandle_with_args() - Count number of phandle in a list
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
519  * ofnode_path() - find a node by full path
527  * ofnode_get_chosen_prop() - get the value of a chosen property
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
559  * ofnode_get_property() - get a pointer to the value of a node property
569  * ofnode_get_first_property()- get the reference of the first property
576  * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
581  * ofnode_get_next_property() - get the reference of the next property
587  * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
592  * ofnode_get_property_by_prop() - get a pointer to the value of a 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
605  * ofnode_is_available() - check if a node is marked available
613  * ofnode_get_addr_size() - get address and size from a property
627  * ofnode_read_u8_array_ptr() - find an 8-bit array
644  * ofnode_read_pci_addr() - look up a PCI address
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
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
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
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
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
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
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