1 // SPDX-License-Identifier: GPL-2.0
3  * property.c - Unified device property interface.
22 	return IS_ENABLED(CONFIG_OF) && dev->of_node ?  in dev_fwnode()
23 		of_fwnode_handle(dev->of_node) : dev->fwnode;  in dev_fwnode()
28  * device_property_present - check if a property of a device is present
41  * fwnode_property_present - check if a property of a firmware node is present
42  * @fwnode: Firmware node whose property to check
57 	return fwnode_call_bool_op(fwnode->secondary, property_present, propname);  in fwnode_property_present()
62  * device_property_read_u8_array - return a u8 array property of a device
76  *	   %-EINVAL if given arguments are not valid,
77  *	   %-ENODATA if the property does not have a value,
78  *	   %-EPROTO if the property is not an array of numbers,
79  *	   %-EOVERFLOW if the size of the property is not as expected.
80  *	   %-ENXIO if no suitable firmware interface is present.
90  * device_property_read_u16_array - return a u16 array property of a device
104  *	   %-EINVAL if given arguments are not valid,
105  *	   %-ENODATA if the property does not have a value,
106  *	   %-EPROTO if the property is not an array of numbers,
107  *	   %-EOVERFLOW if the size of the property is not as expected.
108  *	   %-ENXIO if no suitable firmware interface is present.
118  * device_property_read_u32_array - return a u32 array property of a device
132  *	   %-EINVAL if given arguments are not valid,
133  *	   %-ENODATA if the property does not have a value,
134  *	   %-EPROTO if the property is not an array of numbers,
135  *	   %-EOVERFLOW if the size of the property is not as expected.
136  *	   %-ENXIO if no suitable firmware interface is present.
146  * device_property_read_u64_array - return a u64 array property of a device
160  *	   %-EINVAL if given arguments are not valid,
161  *	   %-ENODATA if the property does not have a value,
162  *	   %-EPROTO if the property is not an array of numbers,
163  *	   %-EOVERFLOW if the size of the property is not as expected.
164  *	   %-ENXIO if no suitable firmware interface is present.
174  * device_property_read_string_array - return a string array property of device
186  * Return: number of values read on success if @val is non-NULL,
188  *	   %-EINVAL if given arguments are not valid,
189  *	   %-ENODATA if the property does not have a value,
190  *	   %-EPROTO or %-EILSEQ if the property is not an array of strings,
191  *	   %-EOVERFLOW if the size of the property is not as expected.
192  *	   %-ENXIO if no suitable firmware interface is present.
202  * device_property_read_string - return a string property of a device
211  *	   %-EINVAL if given arguments are not valid,
212  *	   %-ENODATA if the property does not have a value,
213  *	   %-EPROTO or %-EILSEQ if the property type is not a string.
214  *	   %-ENXIO if no suitable firmware interface is present.
224  * device_property_match_string - find a string in an array and return index
233  *	   %-EINVAL if given arguments are not valid,
234  *	   %-ENODATA if the property does not have a value,
235  *	   %-EPROTO if the property is not an array of strings,
236  *	   %-ENXIO if no suitable firmware interface is present.
253 		return -EINVAL;  in fwnode_property_read_int_array()
257 	if (ret != -EINVAL)  in fwnode_property_read_int_array()
260 	return fwnode_call_int_op(fwnode->secondary, property_read_int_array, propname,  in fwnode_property_read_int_array()
265  * fwnode_property_read_u8_array - return a u8 array property of firmware node
266  * @fwnode: Firmware node to get the property of
279  *	   %-EINVAL if given arguments are not valid,
280  *	   %-ENODATA if the property does not have a value,
281  *	   %-EPROTO if the property is not an array of numbers,
282  *	   %-EOVERFLOW if the size of the property is not as expected,
283  *	   %-ENXIO if no suitable firmware interface is present.
294  * fwnode_property_read_u16_array - return a u16 array property of firmware node
295  * @fwnode: Firmware node to get the property of
308  *	   %-EINVAL if given arguments are not valid,
309  *	   %-ENODATA if the property does not have a value,
310  *	   %-EPROTO if the property is not an array of numbers,
311  *	   %-EOVERFLOW if the size of the property is not as expected,
312  *	   %-ENXIO if no suitable firmware interface is present.
323  * fwnode_property_read_u32_array - return a u32 array property of firmware node
324  * @fwnode: Firmware node to get the property of
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_u64_array - return a u64 array property firmware node
353  * @fwnode: Firmware node to get the property of
366  *	   %-EINVAL if given arguments are not valid,
367  *	   %-ENODATA if the property does not have a value,
368  *	   %-EPROTO if the property is not an array of numbers,
369  *	   %-EOVERFLOW if the size of the property is not as expected,
370  *	   %-ENXIO if no suitable firmware interface is present.
381  * fwnode_property_read_string_array - return string array property of a node
382  * @fwnode: Firmware node to get the property of
387  * Read an string list property @propname from the given firmware node and store
393  * Return: number of values read on success if @val is non-NULL,
395  *	   %-EINVAL if given arguments are not valid,
396  *	   %-ENODATA if the property does not have a value,
397  *	   %-EPROTO or %-EILSEQ if the property is not an array of strings,
398  *	   %-EOVERFLOW if the size of the property is not as expected,
399  *	   %-ENXIO if no suitable firmware interface is present.
408 		return -EINVAL;  in fwnode_property_read_string_array()
412 	if (ret != -EINVAL)  in fwnode_property_read_string_array()
415 	return fwnode_call_int_op(fwnode->secondary, property_read_string_array, propname,  in fwnode_property_read_string_array()
421  * fwnode_property_read_string - return a string property of a firmware node
422  * @fwnode: Firmware node to get the property of
426  * Read property @propname from the given firmware node and store the value into
430  *	   %-EINVAL if given arguments are not valid,
431  *	   %-ENODATA if the property does not have a value,
432  *	   %-EPROTO or %-EILSEQ if the property is not a string,
433  *	   %-ENXIO if no suitable firmware interface is present.
445  * fwnode_property_match_string - find a string in an array and return index
446  * @fwnode: Firmware node to get the property of
454  *	   %-EINVAL if given arguments are not valid,
455  *	   %-ENODATA if the property does not have a value,
456  *	   %-EPROTO if the property is not an array of strings,
457  *	   %-ENXIO if no suitable firmware interface is present.
470 		return -ENODATA;  in fwnode_property_match_string()
474 		return -ENOMEM;  in fwnode_property_match_string()
482 		ret = -ENODATA;  in fwnode_property_match_string()
490  * fwnode_property_get_reference_args() - Find a reference with arguments
491  * @fwnode:	Firmware node where to look for the reference
494  *		arguments in the referred node. NULL if @nargs is known,
496  * @nargs:	Number of arguments. Ignored if @nargs_prop is non-NULL.
504  * args->fwnode pointer.
507  *	    %-ENOENT when the index is out of bounds, the index has an empty
509  *	    %-EINVAL on parse error
519 		return -ENOENT;  in fwnode_property_get_reference_args()
526 	if (IS_ERR_OR_NULL(fwnode->secondary))  in fwnode_property_get_reference_args()
529 	return fwnode_call_int_op(fwnode->secondary, get_reference_args, prop, nargs_prop,  in fwnode_property_get_reference_args()
535  * fwnode_find_reference - Find named reference to a fwnode_handle
536  * @fwnode: Firmware node where to look for the reference
559  * fwnode_get_name - Return the name of a node
560  * @fwnode: The firmware node
562  * Returns a pointer to the node name.
571  * fwnode_get_name_prefix - Return the prefix of node for printing purposes
572  * @fwnode: The firmware node
574  * Returns the prefix of a node, intended to be printed right before the node.
583  * fwnode_get_parent - Return parent firwmare node
586  * Return parent firmware node of the given node if possible or %NULL if no
596  * fwnode_get_next_parent - Iterate to the node's parent
600  * on the passed node, making it suitable for iterating through a
601  * node's parents.
603  * Returns a node pointer with refcount incremented, use
617  * fwnode_get_next_parent_dev - Find device of closest ancestor fwnode
618  * @fwnode: firmware node
620  * Given a firmware node (@fwnode), this function finds its closest ancestor
621  * firmware node that has a corresponding struct device and returns that struct
643  * fwnode_count_parents - Return the number of parents a node has
644  * @fwnode: The node the parents of which are to be counted
646  * Returns the number of parents a node has.
661  * fwnode_get_nth_parent - Return an nth parent of a node
662  * @fwnode: The node the parent of which is requested
663  * @depth: Distance of the parent from the node
665  * Returns the nth parent of a node. If there is no parent at the requested
670  * node.
681 		if (--depth == 0)  in fwnode_get_nth_parent()
689  * fwnode_is_ancestor_of - Test if @ancestor is ancestor of @child
691  * @child: Firmware which is tested for being the child
693  * A node is considered an ancestor of itself too.
695  * Returns true if @ancestor is an ancestor of @child. Otherwise, returns false.
697 bool fwnode_is_ancestor_of(struct fwnode_handle *ancestor, struct fwnode_handle *child)  in fwnode_is_ancestor_of()  argument
704 	if (child == ancestor)  in fwnode_is_ancestor_of()
707 	fwnode_for_each_parent_node(child, parent) {  in fwnode_is_ancestor_of()
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.
719  * @child: Handle to one of the node's child nodes or a %NULL handle.
723 			   struct fwnode_handle *child)  in fwnode_get_next_child_node()  argument
725 	return fwnode_call_ptr_op(fwnode, get_next_child_node, child);  in fwnode_get_next_child_node()
730  * fwnode_get_next_available_child_node - Return the next
731  * available child node handle for a node
732  * @fwnode: Firmware node to find the next child node for.
733  * @child: Handle to one of the node's child nodes or a %NULL handle.
737 				     struct fwnode_handle *child)  in fwnode_get_next_available_child_node()  argument
739 	struct fwnode_handle *next_child = child;  in fwnode_get_next_available_child_node()
755  * device_get_next_child_node - Return the next child node handle for a device
756  * @dev: Device to find the next child node for.
757  * @child: Handle to one of the device's child nodes or a null handle.
760 						 struct fwnode_handle *child)  in device_get_next_child_node()  argument
768 	/* Try to find a child in primary fwnode */  in device_get_next_child_node()
769 	next = fwnode_get_next_child_node(fwnode, child);  in device_get_next_child_node()
774 	return 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
793  * @dev: Device to find the named child node for.
794  * @childname: String to match child node name against.
804  * fwnode_handle_get - Obtain a reference to a device node
805  * @fwnode: Pointer to the device node to obtain the reference to.
819  * fwnode_handle_put - Drop reference to a device node
820  * @fwnode: Pointer to the device node to drop the reference to.
823  * with break or return to prevent stale device node references from being left
833  * fwnode_device_is_available - check if a device is available for use
836  * For fwnode node types that don't implement the .device_is_available()
852  * device_get_child_node_count - return the number of child nodes for device
853  * @dev: Device to cound the child nodes for
857 	struct fwnode_handle *child;  in device_get_child_node_count()  local
860 	device_for_each_child_node(dev, child)  in device_get_child_node_count()
883  * fwnode_get_phy_mode - Get phy mode for given firmware node
884  * @fwnode:	Pointer to the given node
886  * The function gets phy interface string from property 'phy-mode' or
887  * 'phy-connection-type', and return its index in phy_modes table, or errno in
895 	err = fwnode_property_read_string(fwnode, "phy-mode", &pm);  in fwnode_get_phy_mode()
898 						  "phy-connection-type", &pm);  in fwnode_get_phy_mode()
906 	return -ENODEV;  in fwnode_get_phy_mode()
911  * device_get_phy_mode - Get phy mode for given device
914  * The function gets phy interface string from property 'phy-mode' or
915  * 'phy-connection-type', and return its index in phy_modes table, or errno in
925  * fwnode_iomap - Maps the memory mapped IO for a given fwnode
926  * @fwnode:	Pointer to the firmware node
938  * fwnode_irq_get - Get IRQ directly from a fwnode
939  * @fwnode:	Pointer to the firmware node
940  * @index:	Zero-based index of the IRQ
952  * fwnode_irq_get_byname - Get IRQ from a fwnode using its name
953  * @fwnode:	Pointer to the firmware node
957  * Find a match to the string @name in the 'interrupt-names' string array
970 		return -EINVAL;  in fwnode_irq_get_byname()
972 	index = fwnode_property_match_string(fwnode, "interrupt-names",  name);  in fwnode_irq_get_byname()
981  * fwnode_graph_get_next_endpoint - Get next endpoint firmware node
982  * @fwnode: Pointer to the parent firmware node
983  * @prev: Previous endpoint node or %NULL to get the first
985  * Returns an endpoint firmware node pointer or %NULL if no more endpoints
997 	 * an endpoint from fwnode->secondary, then we need to use the secondary  in fwnode_graph_get_next_endpoint()
1011 	return fwnode_graph_get_next_endpoint(parent->secondary, NULL);  in fwnode_graph_get_next_endpoint()
1016  * fwnode_graph_get_port_parent - Return the device fwnode of a port endpoint
1017  * @endpoint: Endpoint firmware node of the port
1019  * Return: the firmware node of the device the @endpoint belongs to.
1036  * fwnode_graph_get_remote_port_parent - Return fwnode of a remote device
1037  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1039  * Extracts firmware node of a remote device the @fwnode points to.
1056  * fwnode_graph_get_remote_port - Return fwnode of a remote port
1057  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1059  * Extracts firmware node of a remote port the @fwnode points to.
1069  * fwnode_graph_get_remote_endpoint - Return fwnode of a remote endpoint
1070  * @fwnode: Endpoint firmware node pointing to the remote endpoint
1072  * Extracts firmware node of a remote endpoint the @fwnode points to.
1094  * fwnode_graph_get_endpoint_by_id - get endpoint by port and endpoint numbers
1096  * @port: identifier of the port node
1097  * @endpoint: identifier of the endpoint node under the port node
1161  * fwnode_graph_get_endpoint_count - Count endpoints on a device node
1162  * @fwnode: The node related to a device
1164  * Count endpoints in a device node.
1186  * fwnode_graph_parse_endpoint - parse common endpoint node properties
1190  * Parse @fwnode representing a graph endpoint node and store the
1215 	struct fwnode_handle *node;  in fwnode_graph_devcon_matches()  local
1226 		node = fwnode_graph_get_remote_port_parent(ep);  in fwnode_graph_devcon_matches()
1227 		if (!fwnode_device_is_available(node)) {  in fwnode_graph_devcon_matches()
1228 			fwnode_handle_put(node);  in fwnode_graph_devcon_matches()
1232 		ret = match(node, con_id, data);  in fwnode_graph_devcon_matches()
1233 		fwnode_handle_put(node);  in fwnode_graph_devcon_matches()
1249 	struct fwnode_handle *node;  in fwnode_devcon_matches()  local
1258 		node = fwnode_find_reference(fwnode, con_id, i);  in fwnode_devcon_matches()
1259 		if (IS_ERR(node))  in fwnode_devcon_matches()
1262 		ret = match(node, NULL, data);  in fwnode_devcon_matches()
1263 		fwnode_handle_put(node);  in fwnode_devcon_matches()
1275  * fwnode_connection_find_match - Find connection from a device node
1276  * @fwnode: Device node with the connection
1282  * device node. @match will be used to convert the connection description to
1305  * fwnode_connection_find_matches - Find connections from a device node
1306  * @fwnode: Device node with the connection
1331 		return -EINVAL;  in fwnode_connection_find_matches()
1338 		matches_len -= count_graph;  in fwnode_connection_find_matches()