1 // SPDX-License-Identifier: GPL-2.0
3  * property.c - Unified device property interface.
23 	return IS_ENABLED(CONFIG_OF) && dev->of_node ?  in dev_fwnode()
24 		of_fwnode_handle(dev->of_node) : dev->fwnode;  in dev_fwnode()
29  * device_property_present - check if a property of a device is present
31  * @propname: Name of the property
33  * Check if property @propname is present in the device firmware description.
42  * fwnode_property_present - check if a property of a firmware node is present
43  * @fwnode: Firmware node whose property to check
44  * @propname: Name of the property
53 	    !IS_ERR_OR_NULL(fwnode->secondary))  in fwnode_property_present()
54 		ret = fwnode_call_bool_op(fwnode->secondary, property_present,  in fwnode_property_present()
61  * device_property_read_u8_array - return a u8 array property of a device
63  * @propname: Name of the property
68  * firmware description and stores them to @val if found.
72  *	   %-EINVAL if given arguments are not valid,
73  *	   %-ENODATA if the property does not have a value,
74  *	   %-EPROTO if the property is not an array of numbers,
75  *	   %-EOVERFLOW if the size of the property is not as expected.
76  *	   %-ENXIO if no suitable firmware interface is present.
86  * device_property_read_u16_array - return a u16 array property of a device
88  * @propname: Name of the property
93  * firmware description and stores them to @val if found.
97  *	   %-EINVAL if given arguments are not valid,
98  *	   %-ENODATA if the property does not have a value,
99  *	   %-EPROTO if the property is not an array of numbers,
100  *	   %-EOVERFLOW if the size of the property is not as expected.
101  *	   %-ENXIO if no suitable firmware interface is present.
111  * device_property_read_u32_array - return a u32 array property of a device
113  * @propname: Name of the property
118  * firmware description and stores them to @val if found.
122  *	   %-EINVAL if given arguments are not valid,
123  *	   %-ENODATA if the property does not have a value,
124  *	   %-EPROTO if the property is not an array of numbers,
125  *	   %-EOVERFLOW if the size of the property is not as expected.
126  *	   %-ENXIO if no suitable firmware interface is present.
136  * device_property_read_u64_array - return a u64 array property of a device
138  * @propname: Name of the property
143  * firmware description and stores them to @val if found.
147  *	   %-EINVAL if given arguments are not valid,
148  *	   %-ENODATA if the property does not have a value,
149  *	   %-EPROTO if the property is not an array of numbers,
150  *	   %-EOVERFLOW if the size of the property is not as expected.
151  *	   %-ENXIO if no suitable firmware interface is present.
161  * device_property_read_string_array - return a string array property of device
163  * @propname: Name of the property
168  * firmware description and stores them to @val if found.
170  * Return: number of values read on success if @val is non-NULL,
172  *	   %-EINVAL if given arguments are not valid,
173  *	   %-ENODATA if the property does not have a value,
174  *	   %-EPROTO or %-EILSEQ if the property is not an array of strings,
175  *	   %-EOVERFLOW if the size of the property is not as expected.
176  *	   %-ENXIO if no suitable firmware interface is present.
186  * device_property_read_string - return a string property of a device
188  * @propname: Name of the property
191  * Function reads property @propname from the device firmware description and
195  *	   %-EINVAL if given arguments are not valid,
196  *	   %-ENODATA if the property does not have a value,
197  *	   %-EPROTO or %-EILSEQ if the property type is not a string.
198  *	   %-ENXIO if no suitable firmware interface is present.
208  * device_property_match_string - find a string in an array and return index
210  * @propname: Name of the property holding the array
217  *	   %-EINVAL if given arguments are not valid,
218  *	   %-ENODATA if the property does not have a value,
219  *	   %-EPROTO if the property is not an array of strings,
220  *	   %-ENXIO if no suitable firmware interface is present.
238 	if (ret == -EINVAL && !IS_ERR_OR_NULL(fwnode) &&  in fwnode_property_read_int_array()
239 	    !IS_ERR_OR_NULL(fwnode->secondary))  in fwnode_property_read_int_array()
241 			fwnode->secondary, property_read_int_array, propname,  in fwnode_property_read_int_array()
248  * fwnode_property_read_u8_array - return a u8 array property of firmware node
249  * @fwnode: Firmware node to get the property of
250  * @propname: Name of the property
259  *	   %-EINVAL if given arguments are not valid,
260  *	   %-ENODATA if the property does not have a value,
261  *	   %-EPROTO if the property is not an array of numbers,
262  *	   %-EOVERFLOW if the size of the property is not as expected,
263  *	   %-ENXIO if no suitable firmware interface is present.
274  * fwnode_property_read_u16_array - return a u16 array property of firmware node
275  * @fwnode: Firmware node to get the property of
276  * @propname: Name of the property
285  *	   %-EINVAL if given arguments are not valid,
286  *	   %-ENODATA if the property does not have a value,
287  *	   %-EPROTO if the property is not an array of numbers,
288  *	   %-EOVERFLOW if the size of the property is not as expected,
289  *	   %-ENXIO if no suitable firmware interface is present.
300  * fwnode_property_read_u32_array - return a u32 array property of firmware node
301  * @fwnode: Firmware node to get the property of
302  * @propname: Name of the property
311  *	   %-EINVAL if given arguments are not valid,
312  *	   %-ENODATA if the property does not have a value,
313  *	   %-EPROTO if the property is not an array of numbers,
314  *	   %-EOVERFLOW if the size of the property is not as expected,
315  *	   %-ENXIO if no suitable firmware interface is present.
326  * fwnode_property_read_u64_array - return a u64 array property firmware node
327  * @fwnode: Firmware node to get the property of
328  * @propname: Name of the property
337  *	   %-EINVAL if given arguments are not valid,
338  *	   %-ENODATA if the property does not have a value,
339  *	   %-EPROTO if the property is not an array of numbers,
340  *	   %-EOVERFLOW if the size of the property is not as expected,
341  *	   %-ENXIO if no suitable firmware interface is present.
352  * fwnode_property_read_string_array - return string array property of a node
353  * @fwnode: Firmware node to get the property of
354  * @propname: Name of the property
358  * Read an string list property @propname from the given firmware node and store
361  * Return: number of values read on success if @val is non-NULL,
363  *	   %-EINVAL if given arguments are not valid,
364  *	   %-ENODATA if the property does not have a value,
365  *	   %-EPROTO or %-EILSEQ if the property is not an array of strings,
366  *	   %-EOVERFLOW if the size of the property is not as expected,
367  *	   %-ENXIO if no suitable firmware interface is present.
377 	if (ret == -EINVAL && !IS_ERR_OR_NULL(fwnode) &&  in fwnode_property_read_string_array()
378 	    !IS_ERR_OR_NULL(fwnode->secondary))  in fwnode_property_read_string_array()
379 		ret = fwnode_call_int_op(fwnode->secondary,  in fwnode_property_read_string_array()
387  * fwnode_property_read_string - return a string property of a firmware node
388  * @fwnode: Firmware node to get the property of
389  * @propname: Name of the property
392  * Read property @propname from the given firmware node and store the value into
396  *	   %-EINVAL if given arguments are not valid,
397  *	   %-ENODATA if the property does not have a value,
398  *	   %-EPROTO or %-EILSEQ if the property is not a string,
399  *	   %-ENXIO if no suitable firmware interface is present.
411  * fwnode_property_match_string - find a string in an array and return index
412  * @fwnode: Firmware node to get the property of
413  * @propname: Name of the property holding the array
420  *	   %-EINVAL if given arguments are not valid,
421  *	   %-ENODATA if the property does not have a value,
422  *	   %-EPROTO if the property is not an array of strings,
423  *	   %-ENXIO if no suitable firmware interface is present.
436 		return -ENODATA;  in fwnode_property_match_string()
440 		return -ENOMEM;  in fwnode_property_match_string()
448 		ret = -ENODATA;  in fwnode_property_match_string()
456  * fwnode_property_get_reference_args() - Find a reference with arguments
457  * @fwnode:	Firmware node where to look for the reference
458  * @prop:	The name of the property
459  * @nargs_prop:	The name of the property telling the number of
462  * @nargs:	Number of arguments. Ignored if @nargs_prop is non-NULL.
470  * args->fwnode pointer.
473  *	    %-ENOENT when the index is out of bounds, the index has an empty
475  *	    %-EINVAL on parse error
488  * fwnode_find_reference - Find named reference to a fwnode_handle
489  * @fwnode: Firmware node where to look for the reference
490  * @name: The name of the reference
499 					    const char *name,  in fwnode_find_reference()  argument
505 	ret = fwnode_property_get_reference_args(fwnode, name, NULL, 0, index,  in fwnode_find_reference()
512  * device_remove_properties - Remove properties from a device object.
516  * firmware node with device_add_properties(). Memory allocated to the
526 	if (is_software_node(fwnode->secondary)) {  in device_remove_properties()
527 		fwnode_remove_software_node(fwnode->secondary);  in device_remove_properties()
534  * device_add_properties - Add a collection of properties to a device object.
542  * is no real firmware node associated with @dev! In that case the callers
560  * fwnode_get_name - Return the name of a node
561  * @fwnode: The firmware node
563  * Returns a pointer to the node name.
572  * fwnode_get_name_prefix - Return the prefix of node for printing purposes
573  * @fwnode: The firmware node
584  * fwnode_get_parent - Return parent firwmare node
585  * @fwnode: Firmware whose parent is retrieved
587  * Return parent firmware node of the given node if possible or %NULL if no
597  * fwnode_get_next_parent - Iterate to the node's parent
598  * @fwnode: Firmware whose parent is retrieved
618  * fwnode_get_next_parent_dev - Find device of closest ancestor fwnode
619  * @fwnode: firmware node
621  * Given a firmware node (@fwnode), this function finds its closest ancestor
622  * firmware node that has a corresponding struct device and returns that struct
644  * fwnode_count_parents - Return the number of parents a node has
664  * fwnode_get_nth_parent - Return an nth parent of a node
690  * fwnode_is_ancestor_of - Test if @test_ancestor is ancestor of @test_child
691  * @test_ancestor: Firmware which is tested for being an ancestor
692  * @test_child: Firmware which is tested for being the child
717  * fwnode_get_next_child_node - Return the next child node handle for a node
718  * @fwnode: Firmware node to find the next child node for.
730  * fwnode_get_next_available_child_node - Return the next
732  * @fwnode: Firmware node to find the next child node for.
755  * device_get_next_child_node - Return the next child node handle for a device
771 	if (fwnode && !IS_ERR_OR_NULL(fwnode->secondary))  in device_get_next_child_node()
772 		next = fwnode_get_next_child_node(fwnode->secondary, child);  in device_get_next_child_node()
779  * fwnode_get_named_child_node - Return first matching named child node handle
780  * @fwnode: Firmware node to find the named child node for.
781  * @childname: String to match child node name against.
792  * device_get_named_child_node - Return first matching named child node handle
794  * @childname: String to match child node name against.
804  * fwnode_handle_get - Obtain a reference to a device node
819  * fwnode_handle_put - Drop reference to a device node
833  * fwnode_device_is_available - check if a device is available for use
849  * device_get_child_node_count - return the number of child nodes for device
897  * fwnode_get_phy_mode - Get phy mode for given firmware node
900  * The function gets phy interface string from property 'phy-mode' or
901  * 'phy-connection-type', and return its index in phy_modes table, or errno in
909 	err = fwnode_property_read_string(fwnode, "phy-mode", &pm);  in fwnode_get_phy_mode()
912 						  "phy-connection-type", &pm);  in fwnode_get_phy_mode()
920 	return -ENODEV;  in fwnode_get_phy_mode()
925  * device_get_phy_mode - Get phy mode for given device
928  * The function gets phy interface string from property 'phy-mode' or
929  * 'phy-connection-type', and return its index in phy_modes table, or errno in
939 				 const char *name, char *addr,  in fwnode_get_mac_addr()  argument
942 	int ret = fwnode_property_read_u8_array(fwnode, name, addr, alen);  in fwnode_get_mac_addr()
950  * fwnode_get_mac_address - Get the MAC from the firmware node
951  * @fwnode:	Pointer to the firmware node
955  * Search the firmware node for the best MAC address to use.  'mac-address' is
957  * address. If that isn't set, then 'local-mac-address' is checked next,
965  * All-zero MAC addresses are rejected, because those could be properties that
966  * exist in the firmware tables, but were not updated by the firmware.  For
967  * example, the DTS could define 'mac-address' and 'local-mac-address', with
968  * zero MAC addresses.  Some older U-Boots only initialized 'local-mac-address'.
969  * In this case, the real MAC is in 'local-mac-address', and 'mac-address'
976 	res = fwnode_get_mac_addr(fwnode, "mac-address", addr, alen);  in fwnode_get_mac_address()
980 	res = fwnode_get_mac_addr(fwnode, "local-mac-address", addr, alen);  in fwnode_get_mac_address()
989  * device_get_mac_address - Get the MAC for a given device
1001  * fwnode_irq_get - Get IRQ directly from a fwnode
1002  * @fwnode:	Pointer to the firmware node
1003  * @index:	Zero-based index of the IRQ
1025  * fwnode_graph_get_next_endpoint - Get next endpoint firmware node
1026  * @fwnode: Pointer to the parent firmware node
1029  * Returns an endpoint firmware node pointer or %NULL if no more endpoints
1041 	 * an endpoint from fwnode->secondary, then we need to use the secondary  in fwnode_graph_get_next_endpoint()
1052 	    !IS_ERR_OR_NULL(parent) && !IS_ERR_OR_NULL(parent->secondary))  in fwnode_graph_get_next_endpoint()
1053 		ep = fwnode_graph_get_next_endpoint(parent->secondary, NULL);  in fwnode_graph_get_next_endpoint()
1060  * fwnode_graph_get_port_parent - Return the device fwnode of a port endpoint
1061  * @endpoint: Endpoint firmware node of the port
1063  * Return: the firmware node of the device the @endpoint belongs to.
1080  * fwnode_graph_get_remote_port_parent - Return fwnode of a remote device
1081  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1083  * Extracts firmware node of a remote device the @fwnode points to.
1100  * fwnode_graph_get_remote_port - Return fwnode of a remote port
1101  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1103  * Extracts firmware node of a remote port the @fwnode points to.
1113  * fwnode_graph_get_remote_endpoint - Return fwnode of a remote endpoint
1114  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1116  * Extracts firmware node of a remote endpoint the @fwnode points to.
1126  * fwnode_graph_get_remote_node - get remote parent node for given port/endpoint
1164  * fwnode_graph_get_endpoint_by_id - get endpoint by port and endpoint numbers
1239  * fwnode_graph_parse_endpoint - parse common endpoint node properties
1308  * fwnode_connection_find_match - Find connection from a device node