[PATCH v5 1/3] driver core: add device_enumeration_failure_notify() helper

[Akshay Gujar]

Hotpluggable buses may detect that a device is physically present,
but enumeration can fail early due to protocol-level errors. Such
failures are currently only visible via kernel log messages, with no
structured notification to userspace.

Introduce device_enumeration_failure_notify(), a helper in the driver
core that emits a KOBJ_CHANGE uevent with

  DEVICE_ENUMERATION_FAILURE=<dev_name>

This helper is intended for use by bus drivers such as USB and PCI.

Signed-off-by: Akshay Gujar <Akshay.Gujar@xxxxxxxxxx>
---
 drivers/base/core.c    | 44 ++++++++++++++++++++++++++++++++++++++++++
 include/linux/device.h |  2 ++
 2 files changed, 46 insertions(+)

diff --git a/drivers/base/core.c b/drivers/base/core.c
index 4d026682944f2..6694a0c30f61b 100644
--- a/drivers/base/core.c
+++ b/drivers/base/core.c
@@ -3830,6 +3830,50 @@ int device_add(struct device *dev)
 }
 EXPORT_SYMBOL_GPL(device_add);
 
+/**
+ * device_enumeration_failure_notify - notify userspace of enumeration failure
+ * @dev: device that failed to enumerate a connected child
+ *
+ * Emit a KOBJ_CHANGE uevent with
+ * DEVICE_ENUMERATION_FAILURE=<dev_name>.
+ *
+ * If @dev has not yet emitted its ADD uevent, the event may be sent
+ * from the parent device instead.
+ *
+ * The caller must hold a reference to @dev.
+ *
+ * See Documentation/ABI/testing/sysfs-uevent for more details.
+ */
+void device_enumeration_failure_notify(struct device *dev)
+{
+	char *envp[2] = { NULL, NULL };
+	struct device *uevent_dev;
+
+	if (!dev)
+		return;
+
+	/*
+	 * If enumeration fails before @dev has emitted its ADD uevent, the
+	 * device may still be in an early state (e.g. without a bus or class
+	 * assigned). Emit the event from the parent device instead, while
+	 * including DEVICE_ENUMERATION_FAILURE=<dev_name>.
+	 *
+	 * The caller holds a reference to @dev, so dev->parent remains valid.
+	 */
+	uevent_dev = dev->kobj.state_add_uevent_sent ? dev : dev->parent;
+	if (!uevent_dev)
+		return;
+
+	envp[0] = kasprintf(GFP_KERNEL, "DEVICE_ENUMERATION_FAILURE=%s",
+			    dev_name(dev));
+	if (!envp[0])
+		return;
+
+	kobject_uevent_env(&uevent_dev->kobj, KOBJ_CHANGE, envp);
+	kfree(envp[0]);
+}
+EXPORT_SYMBOL_GPL(device_enumeration_failure_notify);
+
 /**
  * device_register - register a device with the system.
  * @dev: pointer to the device structure
diff --git a/include/linux/device.h b/include/linux/device.h
index 7b2baffdd2f55..39393c76c7ac7 100644
--- a/include/linux/device.h
+++ b/include/linux/device.h
@@ -1394,4 +1394,6 @@ static inline bool device_link_test(const struct device_link *link, u32 flags)
 #define MODULE_ALIAS_CHARDEV_MAJOR(major) \
 	MODULE_ALIAS("char-major-" __stringify(major) "-*")
 
+void device_enumeration_failure_notify(struct device *dev);
+
 #endif /* _DEVICE_H_ */
--
2.19.0