driver core: bus.h: document bus notifiers better
Greg Kroah-Hartman
maintainerPATCH v2 1/2 driver core: bus.h: document bus notifiers better
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. Also change the values from being in hex to just decimal as it didn't make any sense to have them in hex.
---
v2: move the values to decimal from hex as pointed out by Rafael.
include/linux/device/bus.h | 43 +++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 14 deletions(-)
include/linux/device/bus.h +29 -14
@@ -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 =1 , +BUS_NOTIFY_DEL_DEVICE =2 , +BUS_NOTIFY_REMOVED_DEVICE =3 , +BUS_NOTIFY_BIND_DRIVER =4 , +BUS_NOTIFY_BOUND_DRIVER =5 , +BUS_NOTIFY_UNBIND_DRIVER =6 , +BUS_NOTIFY_UNBOUND_DRIVER =7 , +BUS_NOTIFY_DRIVER_NOT_BOUND =8 , +};extern struct kset *bus_get_kset (struct bus_type *bus);
Signature · 1 line
2.39.0
Greg Kroah-Hartman
maintainerPATCH v2 2/2 driver core: bus: move bus notifier logic into bus.c
The logic to touch the bus notifier was open-coded in numberous places in the driver core. Clean that up by creating a local bus_notify() function and have everyone call this function instead, making the reading of the caller code simpler and easier to maintain over time.
---
v2: Added Rafael's reviewed-by
drivers/base/base.h | 1 + drivers/base/bus.c | 8 ++++++++ drivers/base/core.c | 13 +++---------- drivers/base/dd.c | 28 +++++++--------------------- 4 files changed, 19 insertions(+), 31 deletions(-)
drivers/base/base.h +1 -0
@@ -130,6 +130,7 @@ struct kobject *virtual_device_parent(struct device *dev);extern int bus_add_device (struct device *dev);extern void bus_probe_device (struct device *dev);extern void bus_remove_device (struct device *dev); +void bus_notify (struct device *dev,enum bus_notifier_event value);extern int bus_add_driver (struct device_driver *drv);extern void bus_remove_driver (struct device_driver *drv);
drivers/base/bus.c +8 -0
@@ -850,6 +850,14 @@ int bus_unregister_notifier(struct bus_type *bus, struct notifier_block *nb) }EXPORT_SYMBOL_GPL (bus_unregister_notifier); +void bus_notify (struct device *dev,enum bus_notifier_event value) +{ +struct bus_type *bus = dev->bus; + +if (bus) +blocking_notifier_call_chain (&bus->p->bus_notifier, value, dev); +} +struct kset *bus_get_kset (struct bus_type *bus) {return &bus->p->subsys;
drivers/base/core.c +3 -10
@@ -3453,10 +3453,7 @@ int device_add(struct device *dev)/* Notify clients of device addition. This call must come * after dpm_sysfs_add() and before kobject_uevent(). */ -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_ADD_DEVICE , dev); - +bus_notify (dev,BUS_NOTIFY_ADD_DEVICE );kobject_uevent (&dev->kobj,KOBJ_ADD );/*
@@ -3636,9 +3633,7 @@ void device_del(struct device *dev)* before dpm_sysfs_remove(). */ noio_flag =memalloc_noio_save (); -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_DEL_DEVICE , dev); +bus_notify (dev,BUS_NOTIFY_DEL_DEVICE );dpm_sysfs_remove (dev);if (parent)
@@ -3669,9 +3664,7 @@ void device_del(struct device *dev)device_platform_notify_remove (dev);device_links_purge (dev); -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_REMOVED_DEVICE , dev); +bus_notify (dev,BUS_NOTIFY_REMOVED_DEVICE );kobject_uevent (&dev->kobj,KOBJ_REMOVE ); glue_dir =get_glue_dir (dev);kobject_del (&dev->kobj);
drivers/base/dd.c +7 -21
@@ -413,10 +413,7 @@ static void driver_bound(struct device *dev)driver_deferred_probe_del (dev);driver_deferred_probe_trigger (); -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_BOUND_DRIVER , dev); - +bus_notify (dev,BUS_NOTIFY_BOUND_DRIVER );kobject_uevent (&dev->kobj,KOBJ_BIND ); }
@@ -435,9 +432,7 @@ static int driver_sysfs_add(struct device *dev) {int ret; -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_BIND_DRIVER , dev); +bus_notify (dev,BUS_NOTIFY_BIND_DRIVER ); ret =sysfs_create_link (&dev->driver->p->kobj, &dev->kobj,kobject_name (&dev->kobj));
@@ -502,9 +497,8 @@ int device_bind_driver(struct device *dev)device_links_force_bind (dev);driver_bound (dev); } -else if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_DRIVER_NOT_BOUND , dev); +else +bus_notify (dev,BUS_NOTIFY_DRIVER_NOT_BOUND );return ret; }EXPORT_SYMBOL_GPL (device_bind_driver);
@@ -695,9 +689,7 @@ static int really_probe(struct device *dev, struct device_driver *drv) probe_failed:driver_sysfs_remove (dev); sysfs_failed: -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_DRIVER_NOT_BOUND , dev); +bus_notify (dev,BUS_NOTIFY_DRIVER_NOT_BOUND );if (dev->bus && dev->bus->dma_cleanup) dev->bus->dma_cleanup (dev); pinctrl_bind_failed:
@@ -1243,10 +1235,7 @@ static void __device_release_driver(struct device *dev, struct device *parent)driver_sysfs_remove (dev); -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_UNBIND_DRIVER , - dev); +bus_notify (dev,BUS_NOTIFY_UNBIND_DRIVER );pm_runtime_put_sync (dev);
@@ -1260,11 +1249,8 @@ static void __device_release_driver(struct device *dev, struct device *parent)klist_remove (&dev->p->knode_driver);device_pm_check_callbacks (dev); -if (dev->bus) -blocking_notifier_call_chain (&dev->bus->p->bus_notifier, -BUS_NOTIFY_UNBOUND_DRIVER , - dev); +bus_notify (dev,BUS_NOTIFY_UNBOUND_DRIVER );kobject_uevent (&dev->kobj,KOBJ_UNBIND ); } }
Signature · 1 line
2.39.0
Hi Greg,
Quoted 18 lines · Greg Kroah-Hartman
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. Also change the values from being in hex to just decimal as it didn't make any sense to have them in hex.
Cc "Rafael J. Wysocki" <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>---
v2: move the values to decimal from hex as pointed out by Rafael.include/linux/device/bus.h | 43 +++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 14 deletions(-)include/linux/device/bus.h +0
-0
include/linux/device/bus.h extern int bus_register_notifier(struct bus_type *bus, · line 262
Quoted 6 lines
include/linux/device/bus.h +0
-3@@ -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.
If you want this to be kernel-doc format with no warnings,
(a) all of the " * BUS_NOTIFY_..." lines should be " * @BUS_NOTIFY_...";
(b) all of the " * @BUS_NOTIFY_..." lines should be immediately after the second ("enum") line. (at [1])
(c) In the heading "enum" line, s/: / - /, but that's just for consistency and to follow kernel-doc documented format; it seems that kernel-doc takes that separator either way.
The patch below (on top of this one) makes all of these changes.
include/linux/device/bus.h extern int bus_register_notifier(struct bus_type *bus, · line 261
Quoted 2 lines
include/linux/device/bus.h +2
-0+/** +* enum bus_notifier_event: Bus Notifier events that have happened
[1]
Quoted 32 lines
include/linux/device/bus.h +20
-11+* +* 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 =1 , +BUS_NOTIFY_DEL_DEVICE =2 ,
include/linux/device/bus.h extern int bus_register_notifier(struct bus_type *bus, · line 292
Quoted 10 lines
include/linux/device/bus.h +7
-0+BUS_NOTIFY_REMOVED_DEVICE =3 , +BUS_NOTIFY_BIND_DRIVER =4 , +BUS_NOTIFY_BOUND_DRIVER =5 , +BUS_NOTIFY_UNBIND_DRIVER =6 , +BUS_NOTIFY_UNBOUND_DRIVER =7 , + BUS_NOTIFY_DRIVER_NOT_BOUND = 8, +};extern struct kset *bus_get_kset (struct bus_type *bus);
--- include/linux/device/bus.h | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-)
include/linux/device/bus.h +9 -10
@@ -271,7 +271,15 @@ extern int bus_unregister_notifier(struc struct notifier_block *nb);/** -* enum bus_notifier_event: Bus Notifier events that have happened +* 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. *
@@ -280,15 +288,6 @@ extern int bus_unregister_notifier(struc* 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 */ enum bus_notifier_event {BUS_NOTIFY_ADD_DEVICE =1 ,
Signature · 1 line
~Randy
Greg Kroah-Hartman
maintainerQuoted 36 lines · Randy Dunlap
Hi Greg,
Quoted 18 lines · Greg Kroah-Hartman
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. Also change the values from being in hex to just decimal as it didn't make any sense to have them in hex.
Cc "Rafael J. Wysocki" <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>---
v2: move the values to decimal from hex as pointed out by Rafael.include/linux/device/bus.h | 43 +++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 14 deletions(-)include/linux/device/bus.h +0
-0include/linux/device/bus.h extern int bus_register_notifier(struct bus_type *bus, · line 262
Quoted 6 lines
include/linux/device/bus.h +0
-3@@ -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. If you want this to be kernel-doc format with no warnings,
(a) all of the " *BUS_NOTIFY_..." lines should be " * @BUS_NOTIFY_...";
(b) all of the " * @BUS_NOTIFY_..." lines should be immediately after the second ("enum") line. (at [1])
(c) In the heading "enum" line, s/: / - /, but that's just for consistency and to follow kernel-doc documented format; it seems that kernel-doc takes that separator either way.
Quoted 1 line
The patch below (on top of this one) makes all of these changes.
Ah, thank you so much for that, I'll merge your changes into here, and also drop the explicit values for the enums as that really does not matter at all.
thanks,
greg k-h