Re: [PATCH 1/4] software node: support automatic secondary fwnode assignment

[Andy Shevchenko <andriy.shevchenko@linux.intel.com>]

On Thu, Mar 19, 2026 at 05:10:54PM +0100, Bartosz Golaszewski wrote:
> Provide a structure and a set of functions allowing to set up automatic
> secondary firmware node assignment for platform devices. It uses
> a behind-the-scenes bus notifier for a group of named software nodes. It
> will wait for bus events and when a device is added, it will check its
> name against the software node's name and - on match - assign the
> software node as the secondary firmware node of the device's *real*
> firmware node.

...

> +/**
> + * software_node_register_auto_secondary() - set up automatic assignment of
> + *                                           secondary firmware nodes
> + * @auto_sec: Context data to use.
> + *
> + * NOTE: All software nodes passed in @auto_sec must be named.

> + * Returns:

Is it with 's' in other kernel-doc? The official is "Return", the 's' variant
is supported, but not documented.

> + * 0 on success, negative error number on failure.

The Return section must be last in the kernel-doc description. This is documented.

> + * This registers the software node group passed in @auto_sec and sets up
> + * automatic assignment of them as secondary firmware nodes of real nodes
> + * attached to appropriate devices on the bus specified in @auto_sec. The
> + * software nodes must be named and their names must be the same as the
> + * devices they should reference. The assignment happens when the device is
> + * first added to the bus.
> + */

...

> +/**
> + * struct software_node_auto_secondary - context data for automatic secondary
> + *                                       fwnode assignment
> + * @nb: Private bus notifier data - don't use

Mark it with __private then.

> + * @node_group: NULL-terminated array of software node addresses
> + * @bus: Bus on which to wait for devices

If bus is not compiled into kernel, this optionally has to support NULL
in the code (I haven't checked the code, though).

> + */
> +struct software_node_auto_secondary {
> +	struct notifier_block nb;

	struct notifier_block __private nb;

> +	const struct software_node * const *node_group;
> +	const struct bus_type *bus;
> +};

-- 
With Best Regards,
Andy Shevchenko