linux-kernel - [PATCH 1/2] driver core: bus.h: document bus notifiers better

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20230110124256.1663859-1-gregkh@linuxfoundation.org>
Date:   Tue, 10 Jan 2023 13:42:55 +0100
From:   Greg Kroah-Hartman <gregkh@...uxfoundation.org>
To:     linux-kernel@...r.kernel.org
Cc:     Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        "Rafael J. Wysocki" <rafael@...nel.org>
Subject: [PATCH 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.

Cc: "Rafael J. Wysocki" <rafael@...nel.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
---
 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,
+};
 
 extern struct kset *bus_get_kset(struct bus_type *bus);
 
-- 
2.39.0