Re: [PATCH 1/6] device property: document device_for_each_child_node macro

From: Jonathan Cameron
Date: Sun Jul 07 2024 - 12:54:04 EST


On Sat, 06 Jul 2024 17:23:33 +0200
Javier Carrasco <javier.carrasco.cruz@xxxxxxxxx> wrote:

> There have been some misconceptions about this macro, which iterates
> over available child nodes from different backends.
>
> As that is not obvious by its name, some users have opted for the
> `fwnode_for_each_available_child_node()` macro instead.
> That requires an unnecessary, explicit access to the fwnode member
> of the device structure.
>
> Passing the device to `device_for_each_child_node()` is shorter,
> reflects more clearly the nature of the child nodes, and renders the
> same result.
>
> In general, `fwnode_for_each_available_child_node()` should be used
> whenever the parent node of the children to iterate over is a firmware
> node, and not the device itself.
>
> Document the `device_for_each_child node(dev, child)` macro to clarify
> its functionality.
>
> Suggested-by: Jonathan Cameron <jic23@xxxxxxxxxx>
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@xxxxxxxxx>

LGTM but I think needs at least a DT and ACPI ack.

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@xxxxxxxxxx>

One trivial tweak inline.

> ---
> include/linux/property.h | 10 ++++++++++
> 1 file changed, 10 insertions(+)
>
> diff --git a/include/linux/property.h b/include/linux/property.h
> index 61fc20e5f81f..ba8a3dc54786 100644
> --- a/include/linux/property.h
> +++ b/include/linux/property.h
> @@ -171,6 +171,16 @@ struct fwnode_handle *fwnode_get_next_available_child_node(
> struct fwnode_handle *device_get_next_child_node(const struct device *dev,
> struct fwnode_handle *child);
>
> +/**
> + * device_for_each_child_node - iterate over available child nodes of a device
> + * @dev: Pointer to the struct device
> + * @child: Pointer to an available child node in each loop iteration, if found

If it's not found then there are no loop iterations. So could drop the ,if found
I think.

> + *
> + * Unavailable nodes are skipped i.e. this macro is implicitly _available_.
> + * The reference to the child node must be dropped on early exits.
> + * See fwnode_handle_put().
> + * For a scoped version of this macro, use device_for_each_child_node_scoped().
> + */
> #define device_for_each_child_node(dev, child) \
> for (child = device_get_next_child_node(dev, NULL); child; \
> child = device_get_next_child_node(dev, child))
>