1 // SPDX-License-Identifier: GPL-2.0
3  * property.c - Unified device property interface.
15 #include <linux/property.h>
23 	return IS_ENABLED(CONFIG_OF) && dev->of_node ?  in __dev_fwnode()
24 		of_fwnode_handle(dev->of_node) : dev->fwnode;  in __dev_fwnode()
30 	return IS_ENABLED(CONFIG_OF) && dev->of_node ?  in __dev_fwnode_const()
31 		of_fwnode_handle(dev->of_node) : dev->fwnode;  in __dev_fwnode_const()
36  * device_property_present - check if a property of a device is present
37  * @dev: Device whose property is being checked
38  * @propname: Name of the property
40  * Check if property @propname is present in the device firmware description.
42  * Return: true if property @propname is present. Otherwise, returns false.
51  * fwnode_property_present - check if a property of a firmware node is present
52  * @fwnode: Firmware node whose property to check
53  * @propname: Name of the property
55  * Return: true if property @propname is present. Otherwise, returns false.
69 	return fwnode_call_bool_op(fwnode->secondary, property_present, propname);  in fwnode_property_present()
74  * device_property_read_bool - Return the value for a boolean property of a device
75  * @dev: Device whose property is being checked
76  * @propname: Name of the property
78  * Return if property @propname is true or false in the device firmware description.
80  * Return: true if property @propname is present. Otherwise, returns false.
89  * fwnode_property_read_bool - Return the value for a boolean property of a firmware node
90  * @fwnode: Firmware node whose property to check
91  * @propname: Name of the property
93  * Return if property @propname is true or false in the firmware description.
107 	return fwnode_call_bool_op(fwnode->secondary, property_read_bool, propname);  in fwnode_property_read_bool()
112  * device_property_read_u8_array - return a u8 array property of a device
113  * @dev: Device to get the property of
114  * @propname: Name of the property
125  *         %0 if the property was found (success),
126  *	   %-EINVAL if given arguments are not valid,
127  *	   %-ENODATA if the property does not have a value,
128  *	   %-EPROTO if the property is not an array of numbers,
129  *	   %-EOVERFLOW if the size of the property is not as expected.
130  *	   %-ENXIO if no suitable firmware interface is present.
140  * device_property_read_u16_array - return a u16 array property of a device
141  * @dev: Device to get the property of
142  * @propname: Name of the property
153  *         %0 if the property was found (success),
154  *	   %-EINVAL if given arguments are not valid,
155  *	   %-ENODATA if the property does not have a value,
156  *	   %-EPROTO if the property is not an array of numbers,
157  *	   %-EOVERFLOW if the size of the property is not as expected.
158  *	   %-ENXIO if no suitable firmware interface is present.
168  * device_property_read_u32_array - return a u32 array property of a device
169  * @dev: Device to get the property of
170  * @propname: Name of the property
181  *         %0 if the property was found (success),
182  *	   %-EINVAL if given arguments are not valid,
183  *	   %-ENODATA if the property does not have a value,
184  *	   %-EPROTO if the property is not an array of numbers,
185  *	   %-EOVERFLOW if the size of the property is not as expected.
186  *	   %-ENXIO if no suitable firmware interface is present.
196  * device_property_read_u64_array - return a u64 array property of a device
197  * @dev: Device to get the property of
198  * @propname: Name of the property
209  *         %0 if the property was found (success),
210  *	   %-EINVAL if given arguments are not valid,
211  *	   %-ENODATA if the property does not have a value,
212  *	   %-EPROTO if the property is not an array of numbers,
213  *	   %-EOVERFLOW if the size of the property is not as expected.
214  *	   %-ENXIO if no suitable firmware interface is present.
224  * device_property_read_string_array - return a string array property of device
225  * @dev: Device to get the property of
226  * @propname: Name of the property
236  * Return: number of values read on success if @val is non-NULL,
238  *	   %-EINVAL if given arguments are not valid,
239  *	   %-ENODATA if the property does not have a value,
240  *	   %-EPROTO or %-EILSEQ if the property is not an array of strings,
241  *	   %-EOVERFLOW if the size of the property is not as expected.
242  *	   %-ENXIO if no suitable firmware interface is present.
252  * device_property_read_string - return a string property of a device
253  * @dev: Device to get the property of
254  * @propname: Name of the property
257  * Function reads property @propname from the device firmware description and
258  * stores the value into @val if found. The value is checked to be a string.
260  * Return: %0 if the property was found (success),
261  *	   %-EINVAL if given arguments are not valid,
262  *	   %-ENODATA if the property does not have a value,
263  *	   %-EPROTO or %-EILSEQ if the property type is not a string.
264  *	   %-ENXIO if no suitable firmware interface is present.
274  * device_property_match_string - find a string in an array and return index
275  * @dev: Device to get the property of
276  * @propname: Name of the property holding the array
279  * Find a given string in a string array and if it is found return the
282  * Return: index, starting from %0, if the property was found (success),
283  *	   %-EINVAL if given arguments are not valid,
284  *	   %-ENODATA if the property does not have a value,
285  *	   %-EPROTO if the property is not an array of strings,
286  *	   %-ENXIO if no suitable firmware interface is present.
303 		return -EINVAL;  in fwnode_property_read_int_array()
307 	if (ret != -EINVAL)  in fwnode_property_read_int_array()
310 	return fwnode_call_int_op(fwnode->secondary, property_read_int_array, propname,  in fwnode_property_read_int_array()
315  * fwnode_property_read_u8_array - return a u8 array property of firmware node
316  * @fwnode: Firmware node to get the property of
317  * @propname: Name of the property
328  *         %0 if the property was found (success),
329  *	   %-EINVAL if given arguments are not valid,
330  *	   %-ENODATA if the property does not have a value,
331  *	   %-EPROTO if the property is not an array of numbers,
332  *	   %-EOVERFLOW if the size of the property is not as expected,
333  *	   %-ENXIO if no suitable firmware interface is present.
344  * fwnode_property_read_u16_array - return a u16 array property of firmware node
345  * @fwnode: Firmware node to get the property of
346  * @propname: Name of the property
357  *         %0 if the property was found (success),
358  *	   %-EINVAL if given arguments are not valid,
359  *	   %-ENODATA if the property does not have a value,
360  *	   %-EPROTO if the property is not an array of numbers,
361  *	   %-EOVERFLOW if the size of the property is not as expected,
362  *	   %-ENXIO if no suitable firmware interface is present.
373  * fwnode_property_read_u32_array - return a u32 array property of firmware node
374  * @fwnode: Firmware node to get the property of
375  * @propname: Name of the property
386  *         %0 if the property was found (success),
387  *	   %-EINVAL if given arguments are not valid,
388  *	   %-ENODATA if the property does not have a value,
389  *	   %-EPROTO if the property is not an array of numbers,
390  *	   %-EOVERFLOW if the size of the property is not as expected,
391  *	   %-ENXIO if no suitable firmware interface is present.
402  * fwnode_property_read_u64_array - return a u64 array property firmware node
403  * @fwnode: Firmware node to get the property of
404  * @propname: Name of the property
415  *         %0 if the property was found (success),
416  *	   %-EINVAL if given arguments are not valid,
417  *	   %-ENODATA if the property does not have a value,
418  *	   %-EPROTO if the property is not an array of numbers,
419  *	   %-EOVERFLOW if the size of the property is not as expected,
420  *	   %-ENXIO if no suitable firmware interface is present.
431  * fwnode_property_read_string_array - return string array property of a node
432  * @fwnode: Firmware node to get the property of
433  * @propname: Name of the property
437  * Read an string list property @propname from the given firmware node and store
443  * Return: number of values read on success if @val is non-NULL,
445  *	   %-EINVAL if given arguments are not valid,
446  *	   %-ENODATA if the property does not have a value,
447  *	   %-EPROTO or %-EILSEQ if the property is not an array of strings,
448  *	   %-EOVERFLOW if the size of the property is not as expected,
449  *	   %-ENXIO if no suitable firmware interface is present.
458 		return -EINVAL;  in fwnode_property_read_string_array()
462 	if (ret != -EINVAL)  in fwnode_property_read_string_array()
465 	return fwnode_call_int_op(fwnode->secondary, property_read_string_array, propname,  in fwnode_property_read_string_array()
471  * fwnode_property_read_string - return a string property of a firmware node
472  * @fwnode: Firmware node to get the property of
473  * @propname: Name of the property
476  * Read property @propname from the given firmware node and store the value into
477  * @val if found.  The value is checked to be a string.
479  * Return: %0 if the property was found (success),
480  *	   %-EINVAL if given arguments are not valid,
481  *	   %-ENODATA if the property does not have a value,
482  *	   %-EPROTO or %-EILSEQ if the property is not a string,
483  *	   %-ENXIO if no suitable firmware interface is present.
495  * fwnode_property_match_string - find a string in an array and return index
496  * @fwnode: Firmware node to get the property of
497  * @propname: Name of the property holding the array
500  * Find a given string in a string array and if it is found return the
503  * Return: index, starting from %0, if the property was found (success),
504  *	   %-EINVAL if given arguments are not valid,
505  *	   %-ENODATA if the property does not have a value,
506  *	   %-EPROTO if the property is not an array of strings,
507  *	   %-ENXIO if no suitable firmware interface is present.
520 		return -ENODATA;  in fwnode_property_match_string()
524 		return -ENOMEM;  in fwnode_property_match_string()
532 		ret = -ENODATA;  in fwnode_property_match_string()
541  * fwnode_property_match_property_string - find a property string value in an array and return index
542  * @fwnode: Firmware node to get the property of
543  * @propname: Name of the property holding the string value
547  * Find a property string value in a given @array and if it is found return
551  *	   %-ENOENT when the string value was not found in the @array,
552  *	   %-EINVAL if given arguments are not valid,
553  *	   %-ENODATA if the property does not have a value,
554  *	   %-EPROTO or %-EILSEQ if the property is not a string,
555  *	   %-ENXIO if no suitable firmware interface is present.
569 		ret = -ENOENT;  in fwnode_property_match_property_string()
576  * fwnode_property_get_reference_args() - Find a reference with arguments
577  * @fwnode:	Firmware node where to look for the reference
578  * @prop:	The name of the property
579  * @nargs_prop:	The name of the property telling the number of
580  *		arguments in the referred node. NULL if @nargs is known,
582  * @nargs:	Number of arguments. Ignored if @nargs_prop is non-NULL.
587  * Obtain a reference based on a named property in an fwnode, with
591  * @args->fwnode pointer.
594  *	    %-ENOENT when the index is out of bounds, the index has an empty
595  *		     reference or the property was not found
596  *	    %-EINVAL on parse error
606 		return -ENOENT;  in fwnode_property_get_reference_args()
613 	if (IS_ERR_OR_NULL(fwnode->secondary))  in fwnode_property_get_reference_args()
616 	return fwnode_call_int_op(fwnode->secondary, get_reference_args, prop, nargs_prop,  in fwnode_property_get_reference_args()
622  * fwnode_find_reference - Find named reference to a fwnode_handle
623  * @fwnode: Firmware node where to look for the reference
627  * @index can be used when the named reference holds a table of references.
632  * Return: a pointer to the reference fwnode, when found. Otherwise,
649  * fwnode_get_name - Return the name of a node
650  * @fwnode: The firmware node
652  * Return: a pointer to the node name, or %NULL.
661  * fwnode_get_name_prefix - Return the prefix of node for printing purposes
662  * @fwnode: The firmware node
664  * Return: the prefix of a node, intended to be printed right before the node.
665  * The prefix works also as a separator between the nodes.
673  * fwnode_name_eq - Return true if node name is equal
674  * @fwnode: The firmware node
675  * @name: The name to which to compare the node name
677  * Compare the name provided as an argument to the name of the node, stopping
679  * function is generally used for comparing node names while ignoring the
680  * possible unit address of the node.
682  * Return: true if the node name matches with the name provided in the @name
694 	len = strchrnul(node_name, '@') - node_name;  in fwnode_name_eq()
701  * fwnode_get_parent - Return parent firwmare node
707  * Return: parent firmware node of the given node if possible or %NULL if no
717  * fwnode_get_next_parent - Iterate to the node's parent
721  * on the passed node, making it suitable for iterating through a
722  * node's parents.
725  * fwnode pointer. Note that this function also puts a reference to @fwnode
728  * Return: parent firmware node of the given node if possible or %NULL if no
742  * fwnode_count_parents - Return the number of parents a node has
743  * @fwnode: The node the parents of which are to be counted
745  * Return: the number of parents a node has.
760  * fwnode_get_nth_parent - Return an nth parent of a node
761  * @fwnode: The node the parent of which is requested
762  * @depth: Distance of the parent from the node
767  * Return: the nth parent of a node. If there is no parent at the requested
780 		if (--depth == 0)  in fwnode_get_nth_parent()
788  * fwnode_get_next_child_node - Return the next child node handle for a node
789  * @fwnode: Firmware node to find the next child node for.
790  * @child: Handle to one of the node's child nodes or a %NULL handle.
793  * fwnode pointer. Note that this function also puts a reference to @child
798 			   struct fwnode_handle *child)  in fwnode_get_next_child_node()  argument
800 	return fwnode_call_ptr_op(fwnode, get_next_child_node, child);  in fwnode_get_next_child_node()
805  * fwnode_get_next_available_child_node - Return the next available child node handle for a node
806  * @fwnode: Firmware node to find the next child node for.
807  * @child: Handle to one of the node's child nodes or a %NULL handle.
810  * fwnode pointer. Note that this function also puts a reference to @child
815 				     struct fwnode_handle *child)  in fwnode_get_next_available_child_node()  argument
817 	struct fwnode_handle *next_child = child;  in fwnode_get_next_available_child_node()
833  * device_get_next_child_node - Return the next child node handle for a device
834  * @dev: Device to find the next child node for.
835  * @child: Handle to one of the device's child nodes or a %NULL handle.
838  * fwnode pointer. Note that this function also puts a reference to @child
842 						 struct fwnode_handle *child)  in device_get_next_child_node()  argument
850 	/* Try to find a child in primary fwnode */  in device_get_next_child_node()
851 	next = fwnode_get_next_child_node(fwnode, child);  in device_get_next_child_node()
856 	return fwnode_get_next_child_node(fwnode->secondary, child);  in device_get_next_child_node()
861  * fwnode_get_named_child_node - Return first matching named child node handle
862  * @fwnode: Firmware node to find the named child node for.
863  * @childname: String to match child node name against.
877  * device_get_named_child_node - Return first matching named child node handle
878  * @dev: Device to find the named child node for.
879  * @childname: String to match child node name against.
892  * fwnode_handle_get - Obtain a reference to a device node
893  * @fwnode: Pointer to the device node to obtain the reference to.
910  * fwnode_device_is_available - check if a device is available for use
915  * For fwnode node types that don't implement the .device_is_available()
931  * device_get_child_node_count - return the number of child nodes for device
932  * @dev: Device to count the child nodes for
934  * Return: the number of child nodes for a given device.
938 	struct fwnode_handle *child;  in device_get_child_node_count()  local
941 	device_for_each_child_node(dev, child)  in device_get_child_node_count()
964  * fwnode_get_phy_mode - Get phy mode for given firmware node
965  * @fwnode:	Pointer to the given node
967  * The function gets phy interface string from property 'phy-mode' or
968  * 'phy-connection-type', and return its index in phy_modes table, or errno in
976 	err = fwnode_property_read_string(fwnode, "phy-mode", &pm);  in fwnode_get_phy_mode()
979 						  "phy-connection-type", &pm);  in fwnode_get_phy_mode()
987 	return -ENODEV;  in fwnode_get_phy_mode()
992  * device_get_phy_mode - Get phy mode for given device
995  * The function gets phy interface string from property 'phy-mode' or
996  * 'phy-connection-type', and return its index in phy_modes table, or errno in
1006  * fwnode_iomap - Maps the memory mapped IO for a given fwnode
1007  * @fwnode:	Pointer to the firmware node
1010  * Return: a pointer to the mapped memory.
1019  * fwnode_irq_get - Get IRQ directly from a fwnode
1020  * @fwnode:	Pointer to the firmware node
1021  * @index:	Zero-based index of the IRQ
1032 		return -EINVAL;  in fwnode_irq_get()
1039  * fwnode_irq_get_byname - Get IRQ from a fwnode using its name
1040  * @fwnode:	Pointer to the firmware node
1044  * Find a match to the string @name in the 'interrupt-names' string array
1056 		return -EINVAL;  in fwnode_irq_get_byname()
1058 	index = fwnode_property_match_string(fwnode, "interrupt-names",  name);  in fwnode_irq_get_byname()
1067  * fwnode_graph_get_next_endpoint - Get next endpoint firmware node
1068  * @fwnode: Pointer to the parent firmware node
1069  * @prev: Previous endpoint node or %NULL to get the first
1072  * fwnode pointer. Note that this function also puts a reference to @prev
1075  * Return: an endpoint firmware node pointer or %NULL if no more endpoints
1086 	 * If this function is in a loop and the previous iteration returned  in fwnode_graph_get_next_endpoint()
1087 	 * an endpoint from fwnode->secondary, then we need to use the secondary  in fwnode_graph_get_next_endpoint()
1103 	ep = fwnode_graph_get_next_endpoint(parent->secondary, NULL);  in fwnode_graph_get_next_endpoint()
1112  * fwnode_graph_get_port_parent - Return the device fwnode of a port endpoint
1113  * @endpoint: Endpoint firmware node of the port
1118  * Return: the firmware node of the device the @endpoint belongs to.
1135  * fwnode_graph_get_remote_port_parent - Return fwnode of a remote device
1136  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1138  * Extracts firmware node of a remote device the @fwnode points to.
1158  * fwnode_graph_get_remote_port - Return fwnode of a remote port
1159  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1161  * Extracts firmware node of a remote port the @fwnode points to.
1174  * fwnode_graph_get_remote_endpoint - Return fwnode of a remote endpoint
1175  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1177  * Extracts firmware node of a remote endpoint the @fwnode points to.
1202  * fwnode_graph_get_endpoint_by_id - get endpoint by port and endpoint numbers
1204  * @port: identifier of the port node
1205  * @endpoint: identifier of the endpoint node under the port node
1269  * fwnode_graph_get_endpoint_count - Count endpoints on a device node
1270  * @fwnode: The node related to a device
1272  * Count endpoints in a device node.
1294  * fwnode_graph_parse_endpoint - parse common endpoint node properties
1298  * Parse @fwnode representing a graph endpoint node and store the
1299  * information in @endpoint. The caller must hold a reference to
1323 	struct fwnode_handle *node;  in fwnode_graph_devcon_matches()  local
1334 		node = fwnode_graph_get_remote_port_parent(ep);  in fwnode_graph_devcon_matches()
1335 		if (!fwnode_device_is_available(node)) {  in fwnode_graph_devcon_matches()
1336 			fwnode_handle_put(node);  in fwnode_graph_devcon_matches()
1340 		ret = match(node, con_id, data);  in fwnode_graph_devcon_matches()
1341 		fwnode_handle_put(node);  in fwnode_graph_devcon_matches()
1357 	struct fwnode_handle *node;  in fwnode_devcon_matches()  local
1366 		node = fwnode_find_reference(fwnode, con_id, i);  in fwnode_devcon_matches()
1367 		if (IS_ERR(node))  in fwnode_devcon_matches()
1370 		ret = match(node, NULL, data);  in fwnode_devcon_matches()
1371 		fwnode_handle_put(node);  in fwnode_devcon_matches()
1383  * fwnode_connection_find_match - Find connection from a device node
1384  * @fwnode: Device node with the connection
1389  * Find a connection with unique identifier @con_id between @fwnode and another
1390  * device node. @match will be used to convert the connection description to
1413  * fwnode_connection_find_matches - Find connections from a device node
1414  * @fwnode: Device node with the connection
1440 		return -EINVAL;  in fwnode_connection_find_matches()
1447 		matches_len -= count_graph;  in fwnode_connection_find_matches()