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

[Randy Dunlap <rdunlap@infradead.org>]

On 1/11/23 01:54, Rafael J. Wysocki wrote:
> On Wed, Jan 11, 2023 at 10:23 AM Greg Kroah-Hartman
> <gregkh@linuxfoundation.org> 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@kernel.org>
>> Cc: Randy Dunlap <rdunlap@infradead.org>
> 
> I would add a Co-developed-by for Randy along with his sign-off (which
> was given IIRC).

or
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Either way; doesn't matter.

> Anyway
> 
> Reviewed-by: Rafael J. Wysocki <rafael@kernel.org>
> 
>> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>> ---
>> 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
>>

-- 
~Randy