Re: [PATCH v3 1/2] driver core: bus.h: document bus notifiers better

[Rafael J. Wysocki]

On Wed, Jan 11, 2023 at 10:23 AM Greg Kroah-Hartman
<gregkh@xxxxxxxxxxxxxxxxxxx> wrote:
>
> The bus notifier values are not documented all that well, so clean this
> up and make a real enumerated type for them and document them much
> better.  When doing this, remove the hex values and just rely on the
> enumerated type instead as that is all that is needed.
>
> Cc: "Rafael J. Wysocki" <rafael@xxxxxxxxxx>
> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

I would add a Co-developed-by for Randy along with his sign-off (which
was given IIRC).

Anyway

Reviewed-by: Rafael J. Wysocki <rafael@xxxxxxxxxx>

> Signed-off-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> ---
> v3: - fix up the documentation to be proper kernel-doc format thanks to
>       Randy.
>     - Remove the values entirely now that this is an enumerated type,
>       they are not needed.
>
> v2: - move the values to decimal from hex as pointed out by Rafael.
>
>  include/linux/device/bus.h | 42 +++++++++++++++++++++++++-------------
>  1 file changed, 28 insertions(+), 14 deletions(-)
>
> diff --git a/include/linux/device/bus.h b/include/linux/device/bus.h
> index d529f644e92b..7b4a48b5159b 100644
> --- a/include/linux/device/bus.h
> +++ b/include/linux/device/bus.h
> @@ -257,21 +257,35 @@ extern int bus_register_notifier(struct bus_type *bus,
>  extern int bus_unregister_notifier(struct bus_type *bus,
>                                    struct notifier_block *nb);
>
> -/* All 4 notifers below get called with the target struct device *
> - * as an argument. Note that those functions are likely to be called
> - * with the device lock held in the core, so be careful.
> +/**
> + * enum bus_notifier_event - Bus Notifier events that have happened
> + * @BUS_NOTIFY_ADD_DEVICE: device is added to this bus
> + * @BUS_NOTIFY_DEL_DEVICE: device is about to be removed from this bus
> + * @BUS_NOTIFY_REMOVED_DEVICE: device is successfully removed from this bus
> + * @BUS_NOTIFY_BIND_DRIVER: a driver is about to be bound to this device on this bus
> + * @BUS_NOTIFY_BOUND_DRIVER: a driver is successfully bound to this device on this bus
> + * @BUS_NOTIFY_UNBIND_DRIVER: a driver is about to be unbound from this device on this bus
> + * @BUS_NOTIFY_UNBOUND_DRIVER: a driver is successfully unbound from this device on this bus
> + * @BUS_NOTIFY_DRIVER_NOT_BOUND: a driver failed to be bound to this device on this bus
> + *
> + * These are the value passed to a bus notifier when a specific event happens.
> + *
> + * Note that bus notifiers are likely to be called with the device lock already
> + * held by the driver core, so be careful in any notifier callback as to what
> + * you do with the device structure.
> + *
> + * All bus notifiers are called with the target struct device * as an argument.
>   */
> -#define BUS_NOTIFY_ADD_DEVICE          0x00000001 /* device added */
> -#define BUS_NOTIFY_DEL_DEVICE          0x00000002 /* device to be removed */
> -#define BUS_NOTIFY_REMOVED_DEVICE      0x00000003 /* device removed */
> -#define BUS_NOTIFY_BIND_DRIVER         0x00000004 /* driver about to be
> -                                                     bound */
> -#define BUS_NOTIFY_BOUND_DRIVER                0x00000005 /* driver bound to device */
> -#define BUS_NOTIFY_UNBIND_DRIVER       0x00000006 /* driver about to be
> -                                                     unbound */
> -#define BUS_NOTIFY_UNBOUND_DRIVER      0x00000007 /* driver is unbound
> -                                                     from the device */
> -#define BUS_NOTIFY_DRIVER_NOT_BOUND    0x00000008 /* driver fails to be bound */
> +enum bus_notifier_event {
> +       BUS_NOTIFY_ADD_DEVICE,
> +       BUS_NOTIFY_DEL_DEVICE,
> +       BUS_NOTIFY_REMOVED_DEVICE,
> +       BUS_NOTIFY_BIND_DRIVER,
> +       BUS_NOTIFY_BOUND_DRIVER,
> +       BUS_NOTIFY_UNBIND_DRIVER,
> +       BUS_NOTIFY_UNBOUND_DRIVER,
> +       BUS_NOTIFY_DRIVER_NOT_BOUND,
> +};
>
>  extern struct kset *bus_get_kset(struct bus_type *bus);
>
> --
> 2.39.0
>