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

[Greg Kroah-Hartman]

On Tue, Jan 10, 2023 at 01:52:24PM +0100, Rafael J. Wysocki wrote:
> On Tue, Jan 10, 2023 at 1:43 PM 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.
> >
> > Cc: "Rafael J. Wysocki" <rafael@xxxxxxxxxx>
> > Signed-off-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> > ---
> >  include/linux/device/bus.h | 43 +++++++++++++++++++++++++-------------
> >  1 file changed, 29 insertions(+), 14 deletions(-)
> >
> > diff --git a/include/linux/device/bus.h b/include/linux/device/bus.h
> > index d529f644e92b..1e1a593348bc 100644
> > --- a/include/linux/device/bus.h
> > +++ b/include/linux/device/bus.h
> > @@ -257,21 +257,36 @@ 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
> > + *
> > + * 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.
> > + *
> > + * 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
> >   */
> > -#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 =         0x00000001,
> > +       BUS_NOTIFY_DEL_DEVICE =         0x00000002,
> > +       BUS_NOTIFY_REMOVED_DEVICE =     0x00000003,
> > +       BUS_NOTIFY_BIND_DRIVER =        0x00000004,
> > +       BUS_NOTIFY_BOUND_DRIVER =       0x00000005,
> > +       BUS_NOTIFY_UNBIND_DRIVER =      0x00000006,
> > +       BUS_NOTIFY_UNBOUND_DRIVER =     0x00000007,
> > +       BUS_NOTIFY_DRIVER_NOT_BOUND =   0x00000008,
> 
> I'm wondering why the values are in hex (the 0x prefix doesn't matter
> for these numbers AFAICS) and what the initial zeros are for (AFAICS
> they don't matter either).

I have no idea why they are this way.  I'll go change them to just be
decimal, thanks!

greg k-h