| Message ID | 20230217133344.79278-1-andriy.shevchenko@linux.intel.com |
|---|---|
| State | Accepted |
| Commit | 295209ca7b5b3aa6375d6190311b2ae804dbcf65 |
| Headers | show |
| Series | [v1,1/1] device property: Clarify description of returned value in some functions | expand |
On Fri, Feb 17, 2023 at 2:33 PM Andy Shevchenko <andriy.shevchenko@linux.intel.com> wrote: > > 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: Daniel Kaehn <kaehndan@gmail.com> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> > Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com> Acked-by: Rafael J. Wysocki <rafael@kernel.org> or please let me know if I need to pick it up. > --- > > v2: rephrased the note, added tag, removed unrelated change > (all requested by Sakari) > > drivers/base/property.c | 124 +++++++++++++++++++++++++++++----------- > 1 file changed, 90 insertions(+), 34 deletions(-) > > diff --git a/drivers/base/property.c b/drivers/base/property.c > index 083a95791d3b..3fc25e568598 100644 > --- a/drivers/base/property.c > +++ b/drivers/base/property.c > @@ -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. > -- > 2.39.1 >
On Wed, Feb 22, 2023 at 08:16:15PM +0100, Rafael J. Wysocki wrote: > On Fri, Feb 17, 2023 at 2:33 PM Andy Shevchenko > <andriy.shevchenko@linux.intel.com> wrote: > > > > 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: Daniel Kaehn <kaehndan@gmail.com> > > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> > > Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com> > > Acked-by: Rafael J. Wysocki <rafael@kernel.org> > > or please let me know if I need to pick it up. I can take it, thanks. greg k-h
diff --git a/drivers/base/property.c b/drivers/base/property.c index 083a95791d3b..3fc25e568598 100644 --- a/drivers/base/property.c +++ b/drivers/base/property.c @@ -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.