Commit 295209ca authored by Andy Shevchenko's avatar Andy Shevchenko Committed by Greg Kroah-Hartman
Browse files

device property: Clarify description of returned value in some functions 



Some of the functions do not provide Return: section on absence of which
kernel-doc complains. Besides that several functions return the fwnode
handle with incremented reference count. Add a respective note to make sure
that the caller decrements it when it's not needed anymore.

While at it, unify the style of the Return: sections.

Reported-by: default avatarDaniel Kaehn <kaehndan@gmail.com>
Signed-off-by: default avatarAndy Shevchenko <andriy.shevchenko@linux.intel.com>
Acked-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: default avatarRafael J. Wysocki <rafael@kernel.org>
Link: https://lore.kernel.org/r/20230217133344.79278-1-andriy.shevchenko@linux.intel.com


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent f8fb5766

drivers/base/property.c

+90 −34
Original line number Diff line number Diff line
@@ -37,6 +37,8 @@ EXPORT_SYMBOL_GPL(__dev_fwnode_const); 
 * @propname: Name of the property

 *

 * Check if property @propname is present in the device firmware description.

 *

 * Return: true if property @propname is present. Otherwise, returns false.

 */

bool device_property_present(struct device *dev, const char *propname)

{
@@ -48,6 +50,8 @@ EXPORT_SYMBOL_GPL(device_property_present); 
 * fwnode_property_present - check if a property of a firmware node is present

 * @fwnode: Firmware node whose property to check

 * @propname: Name of the property

 *

 * Return: true if property @propname is present. Otherwise, returns false.

 */

bool fwnode_property_present(const struct fwnode_handle *fwnode,

			     const char *propname)
@@ -508,10 +512,10 @@ EXPORT_SYMBOL_GPL(fwnode_property_match_string); 
 * Obtain a reference based on a named property in an fwnode, with

 * integer arguments.

 *

 * Caller is responsible to call fwnode_handle_put() on the returned

 * args->fwnode pointer.

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * @args->fwnode pointer.

 *

 * Returns: %0 on success

 * Return: %0 on success

 *	    %-ENOENT when the index is out of bounds, the index has an empty

 *		     reference or the property was not found

 *	    %-EINVAL on parse error
@@ -547,8 +551,11 @@ EXPORT_SYMBOL_GPL(fwnode_property_get_reference_args); 
 *

 * @index can be used when the named reference holds a table of references.

 *

 * Returns pointer to the reference fwnode, or ERR_PTR. Caller is responsible to

 * call fwnode_handle_put() on the returned fwnode pointer.

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 *

 * Return: a pointer to the reference fwnode, when found. Otherwise,

 * returns an error pointer.

 */

struct fwnode_handle *fwnode_find_reference(const struct fwnode_handle *fwnode,

					    const char *name,
@@ -567,7 +574,7 @@ EXPORT_SYMBOL_GPL(fwnode_find_reference); 
 * fwnode_get_name - Return the name of a node

 * @fwnode: The firmware node

 *

 * Returns a pointer to the node name.

 * Return: a pointer to the node name, or %NULL.

 */

const char *fwnode_get_name(const struct fwnode_handle *fwnode)

{
@@ -579,7 +586,7 @@ EXPORT_SYMBOL_GPL(fwnode_get_name); 
 * fwnode_get_name_prefix - Return the prefix of node for printing purposes

 * @fwnode: The firmware node

 *

 * Returns the prefix of a node, intended to be printed right before the node.

 * Return: the prefix of a node, intended to be printed right before the node.

 * The prefix works also as a separator between the nodes.

 */

const char *fwnode_get_name_prefix(const struct fwnode_handle *fwnode)
@@ -591,7 +598,10 @@ const char *fwnode_get_name_prefix(const struct fwnode_handle *fwnode) 
 * fwnode_get_parent - Return parent firwmare node

 * @fwnode: Firmware whose parent is retrieved

 *

 * Return parent firmware node of the given node if possible or %NULL if no

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 *

 * Return: parent firmware node of the given node if possible or %NULL if no

 * parent was available.

 */

struct fwnode_handle *fwnode_get_parent(const struct fwnode_handle *fwnode)
@@ -608,8 +618,12 @@ EXPORT_SYMBOL_GPL(fwnode_get_parent); 
 * on the passed node, making it suitable for iterating through a

 * node's parents.

 *

 * Returns a node pointer with refcount incremented, use

 * fwnode_handle_put() on it when done.

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer. Note that this function also puts a reference to @fwnode

 * unconditionally.

 *

 * Return: parent firmware node of the given node if possible or %NULL if no

 * parent was available.

 */

struct fwnode_handle *fwnode_get_next_parent(struct fwnode_handle *fwnode)

{
@@ -629,8 +643,10 @@ EXPORT_SYMBOL_GPL(fwnode_get_next_parent); 
 * firmware node that has a corresponding struct device and returns that struct

 * device.

 *

 * The caller of this function is expected to call put_device() on the returned

 * device when they are done.

 * The caller is responsible for calling put_device() on the returned device

 * pointer.

 *

 * Return: a pointer to the device of the @fwnode's closest ancestor.

 */

struct device *fwnode_get_next_parent_dev(struct fwnode_handle *fwnode)

{
@@ -651,7 +667,7 @@ struct device *fwnode_get_next_parent_dev(struct fwnode_handle *fwnode) 
 * fwnode_count_parents - Return the number of parents a node has

 * @fwnode: The node the parents of which are to be counted

 *

 * Returns the number of parents a node has.

 * Return: the number of parents a node has.

 */

unsigned int fwnode_count_parents(const struct fwnode_handle *fwnode)

{
@@ -670,12 +686,12 @@ EXPORT_SYMBOL_GPL(fwnode_count_parents); 
 * @fwnode: The node the parent of which is requested

 * @depth: Distance of the parent from the node

 *

 * Returns the nth parent of a node. If there is no parent at the requested

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 *

 * Return: the nth parent of a node. If there is no parent at the requested

 * @depth, %NULL is returned. If @depth is 0, the functionality is equivalent to

 * fwnode_handle_get(). For @depth == 1, it is fwnode_get_parent() and so on.

 *

 * The caller is responsible for calling fwnode_handle_put() for the returned

 * node.

 */

struct fwnode_handle *fwnode_get_nth_parent(struct fwnode_handle *fwnode,

					    unsigned int depth)
@@ -700,7 +716,7 @@ EXPORT_SYMBOL_GPL(fwnode_get_nth_parent); 
 *

 * A node is considered an ancestor of itself too.

 *

 * Returns true if @ancestor is an ancestor of @child. Otherwise, returns false.

 * Return: true if @ancestor is an ancestor of @child. Otherwise, returns false.

 */

bool fwnode_is_ancestor_of(struct fwnode_handle *ancestor, struct fwnode_handle *child)

{
@@ -725,6 +741,10 @@ bool fwnode_is_ancestor_of(struct fwnode_handle *ancestor, struct fwnode_handle 
 * fwnode_get_next_child_node - Return the next child node handle for a node

 * @fwnode: Firmware node to find the next child node for.

 * @child: Handle to one of the node's child nodes or a %NULL handle.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer. Note that this function also puts a reference to @child

 * unconditionally.

 */

struct fwnode_handle *

fwnode_get_next_child_node(const struct fwnode_handle *fwnode,
@@ -735,10 +755,13 @@ fwnode_get_next_child_node(const struct fwnode_handle *fwnode, 
EXPORT_SYMBOL_GPL(fwnode_get_next_child_node);



/**

 * fwnode_get_next_available_child_node - Return the next

 * available child node handle for a node

 * fwnode_get_next_available_child_node - Return the next available child node handle for a node

 * @fwnode: Firmware node to find the next child node for.

 * @child: Handle to one of the node's child nodes or a %NULL handle.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer. Note that this function also puts a reference to @child

 * unconditionally.

 */

struct fwnode_handle *

fwnode_get_next_available_child_node(const struct fwnode_handle *fwnode,
@@ -762,7 +785,11 @@ EXPORT_SYMBOL_GPL(fwnode_get_next_available_child_node); 
/**

 * device_get_next_child_node - Return the next child node handle for a device

 * @dev: Device to find the next child node for.

 * @child: Handle to one of the device's child nodes or a null handle.

 * @child: Handle to one of the device's child nodes or a %NULL handle.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer. Note that this function also puts a reference to @child

 * unconditionally.

 */

struct fwnode_handle *device_get_next_child_node(const struct device *dev,

						 struct fwnode_handle *child)
@@ -787,6 +814,9 @@ EXPORT_SYMBOL_GPL(device_get_next_child_node); 
 * fwnode_get_named_child_node - Return first matching named child node handle

 * @fwnode: Firmware node to find the named child node for.

 * @childname: String to match child node name against.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 */

struct fwnode_handle *

fwnode_get_named_child_node(const struct fwnode_handle *fwnode,
@@ -800,6 +830,9 @@ EXPORT_SYMBOL_GPL(fwnode_get_named_child_node); 
 * device_get_named_child_node - Return first matching named child node handle

 * @dev: Device to find the named child node for.

 * @childname: String to match child node name against.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 */

struct fwnode_handle *device_get_named_child_node(const struct device *dev,

						  const char *childname)
@@ -812,7 +845,10 @@ EXPORT_SYMBOL_GPL(device_get_named_child_node); 
 * fwnode_handle_get - Obtain a reference to a device node

 * @fwnode: Pointer to the device node to obtain the reference to.

 *

 * Returns the fwnode handle.

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 *

 * Return: the fwnode handle.

 */

struct fwnode_handle *fwnode_handle_get(struct fwnode_handle *fwnode)

{
@@ -841,6 +877,8 @@ EXPORT_SYMBOL_GPL(fwnode_handle_put); 
 * fwnode_device_is_available - check if a device is available for use

 * @fwnode: Pointer to the fwnode of the device.

 *

 * Return: true if device is available for use. Otherwise, returns false.

 *

 * For fwnode node types that don't implement the .device_is_available()

 * operation, this function returns true.

 */
@@ -859,6 +897,8 @@ EXPORT_SYMBOL_GPL(fwnode_device_is_available); 
/**

 * device_get_child_node_count - return the number of child nodes for device

 * @dev: Device to cound the child nodes for

 *

 * Return: the number of child nodes for a given device.

 */

unsigned int device_get_child_node_count(const struct device *dev)

{
@@ -934,7 +974,7 @@ EXPORT_SYMBOL_GPL(device_get_phy_mode); 
 * @fwnode:	Pointer to the firmware node

 * @index:	Index of the IO range

 *

 * Returns a pointer to the mapped memory.

 * Return: a pointer to the mapped memory.

 */

void __iomem *fwnode_iomap(struct fwnode_handle *fwnode, int index)

{
@@ -947,8 +987,8 @@ EXPORT_SYMBOL(fwnode_iomap); 
 * @fwnode:	Pointer to the firmware node

 * @index:	Zero-based index of the IRQ

 *

 * Returns Linux IRQ number on success. Other values are determined

 * accordingly to acpi_/of_ irq_get() operation.

 * Return: Linux IRQ number on success. Other values are determined

 * according to acpi_irq_get() or of_irq_get() operation.

 */

int fwnode_irq_get(const struct fwnode_handle *fwnode, unsigned int index)

{
@@ -967,8 +1007,7 @@ EXPORT_SYMBOL(fwnode_irq_get); 
 * number of the IRQ resource corresponding to the index of the matched

 * string.

 *

 * Return:

 * Linux IRQ number on success, or negative errno otherwise.

 * Return: Linux IRQ number on success, or negative errno otherwise.

 */

int fwnode_irq_get_byname(const struct fwnode_handle *fwnode, const char *name)

{
@@ -990,7 +1029,11 @@ EXPORT_SYMBOL(fwnode_irq_get_byname); 
 * @fwnode: Pointer to the parent firmware node

 * @prev: Previous endpoint node or %NULL to get the first

 *

 * Returns an endpoint firmware node pointer or %NULL if no more endpoints

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer. Note that this function also puts a reference to @prev

 * unconditionally.

 *

 * Return: an endpoint firmware node pointer or %NULL if no more endpoints

 * are available.

 */

struct fwnode_handle *
@@ -1030,6 +1073,9 @@ EXPORT_SYMBOL_GPL(fwnode_graph_get_next_endpoint); 
 * fwnode_graph_get_port_parent - Return the device fwnode of a port endpoint

 * @endpoint: Endpoint firmware node of the port

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 *

 * Return: the firmware node of the device the @endpoint belongs to.

 */

struct fwnode_handle *
@@ -1051,6 +1097,9 @@ EXPORT_SYMBOL_GPL(fwnode_graph_get_port_parent); 
 * @fwnode: Endpoint firmware node pointing to the remote endpoint

 *

 * Extracts firmware node of a remote device the @fwnode points to.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 */

struct fwnode_handle *

fwnode_graph_get_remote_port_parent(const struct fwnode_handle *fwnode)
@@ -1071,6 +1120,9 @@ EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_port_parent); 
 * @fwnode: Endpoint firmware node pointing to the remote endpoint

 *

 * Extracts firmware node of a remote port the @fwnode points to.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 */

struct fwnode_handle *

fwnode_graph_get_remote_port(const struct fwnode_handle *fwnode)
@@ -1084,6 +1136,9 @@ EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_port); 
 * @fwnode: Endpoint firmware node pointing to the remote endpoint

 *

 * Extracts firmware node of a remote endpoint the @fwnode points to.

 *

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 */

struct fwnode_handle *

fwnode_graph_get_remote_endpoint(const struct fwnode_handle *fwnode)
@@ -1111,8 +1166,11 @@ static bool fwnode_graph_remote_available(struct fwnode_handle *ep) 
 * @endpoint: identifier of the endpoint node under the port node

 * @flags: fwnode lookup flags

 *

 * Return the fwnode handle of the local endpoint corresponding the port and

 * endpoint IDs or NULL if not found.

 * The caller is responsible for calling fwnode_handle_put() on the returned

 * fwnode pointer.

 *

 * Return: the fwnode handle of the local endpoint corresponding the port and

 * endpoint IDs or %NULL if not found.

 *

 * If FWNODE_GRAPH_ENDPOINT_NEXT is passed in @flags and the specified endpoint

 * has not been found, look for the closest endpoint ID greater than the
@@ -1120,9 +1178,6 @@ static bool fwnode_graph_remote_available(struct fwnode_handle *ep) 
 *

 * Does not return endpoints that belong to disabled devices or endpoints that

 * are unconnected, unless FWNODE_GRAPH_DEVICE_DISABLED is passed in @flags.

 *

 * The returned endpoint needs to be released by calling fwnode_handle_put() on

 * it when it is not needed any more.

 */

struct fwnode_handle *

fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
@@ -1328,7 +1383,8 @@ EXPORT_SYMBOL_GPL(fwnode_connection_find_match); 
 * @fwnode and other device nodes. @match will be used to convert the

 * connection description to data the caller is expecting to be returned

 * through the @matches array.

 * If @matches is NULL @matches_len is ignored and the total number of resolved

 *

 * If @matches is %NULL @matches_len is ignored and the total number of resolved

 * matches is returned.

 *

 * Return: Number of matches resolved, or negative errno.