| Message ID | 20240706-device_for_each_child_node-available-v1-1-8a3f7615e41c@gmail.com (mailing list archive) |
|---|---|
| State | Handled Elsewhere, archived |
| Headers | show |
| Series | use device_for_each_child_node() to access device child nodes | expand |
On Sat, 06 Jul 2024 17:23:33 +0200 Javier Carrasco <javier.carrasco.cruz@gmail.com> 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@kernel.org> > Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com> LGTM but I think needs at least a DT and ACPI ack. Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> 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)) >
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 + * + * 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))
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@kernel.org> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com> --- include/linux/property.h | 10 ++++++++++ 1 file changed, 10 insertions(+)