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)) >
