[PATCH v6 0/3] driver core: add enumeration failure uevent helper

[PATCH v6 0/3] driver core: add enumeration failure uevent helper

[Akshay Gujar]

Hotpluggable buses can detect that a device is physically present, but 
enumeration may still fail early due to protocol-level errors. Today,
such failures are only reported via kernel log messages, with no
structured userspace notification.
 
This series adds a small generic helper in the driver core that emits a
KOBJ_CHANGE uevent when enumeration fails, and wires it into the USB hub 
enumeration failure path as an initial user.
 
On emitting the event from the port device itself: I tried adding
usb_port to usb_bus_type and hit an oops in driver_sysfs_add(), seen on
an OTG host-mode switch. usb_port_driver is assigned directly to
port_dev->dev.driver but never registered through driver_register(), so
drv->p is NULL by the time the driver core creates the "driver" symlink.

Putting ports on the bus also exposes them to udev rules matching
SUBSYSTEM=="usb" on every system, which I would prefer to send
separately where it can get the review it deserves. 
 
This version therefore emits from the hub interface with the port named
in the payload, which is tested and working.

---
Changes in v6:
- Split helper into (dev, failed_id) arguments
- Return kobject_uevent_env() error to caller
- Reject NULL or empty failed_id
- Update ABI doc (date, DEVPATH, wording, newline at EOF)
- usb: hub: log warning if uevent fails

Changes in v5: 
- Update ABI doc (date, version)

Changes in v4:
- Remove duplicate kerneldoc from device.h; keep only in core.c
- Clarify @dev description
- Update ABI doc (date)

Changes in v3:
- Rename 'parent' to 'dev'
- Remove 'id_name'; derive identifier via dev_name()
- Improve comments and commit messages
- Add kernel-doc in device.h
- Update ABI doc (date, version, example)
- usb: hub: pass &port_dev->dev directly

Changes in v2:
- Move helper from USB-specific code into driver core
- Add ABI documentation
- Split into a 3-patch series

v5: https://lore.kernel.org/all/20260715114028.3627807-1-Akshay.Gujar@harman.com/
v4: https://lore.kernel.org/all/2026071012-hesitancy-doornail-3dab@gregkh/
v3: https://lore.kernel.org/all/0b39693a-d8b0-4c95-97ee-07b3882c4b6a@rowland.harvard.edu/
v2: https://lore.kernel.org/all/2026010726-grimy-variably-b10e@gregkh/
v1: https://lore.kernel.org/all/2025022131-silo-impeach-3f24@gregkh/

Akshay Gujar (3):
  driver core: add device_enumeration_failure_notify() helper
  Documentation: ABI: document DEVICE_ENUMERATION_FAILURE uevent
  usb: hub: send enumeration failure uevent

 Documentation/ABI/testing/sysfs-uevent | 37 ++++++++++++++++++++++++++
 drivers/base/core.c                    | 35 ++++++++++++++++++++++++
 drivers/usb/core/hub.c                 | 14 +++++++++-
 include/linux/device.h                 |  2 ++
 4 files changed, 87 insertions(+), 1 deletion(-)

base-commit: 02dc699f83d04069fdabc996fc22d47cda47a4a9
-- 
2.19.0

[PATCH v6 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=<failed_id>

The emitting device and the identifier are separate arguments because
the device being enumerated usually does not exist yet. The event is
emitted from a device the bus driver has already registered, and the
identifier names the port or slot that failed.

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

diff --git a/drivers/base/core.c b/drivers/base/core.c
index 4d026682944f2..af6901799df58 100644
--- a/drivers/base/core.c
+++ b/drivers/base/core.c
@@ -3830,6 +3830,41 @@ int device_add(struct device *dev)
 }
 EXPORT_SYMBOL_GPL(device_add);
 
+/**
+ * device_enumeration_failure_notify - notify userspace of enumeration failure
+ * @dev: device to emit the uevent from
+ * @failed_id: bus-specific identifier of the port or slot that failed to
+ *             enumerate, e.g. the port device name for USB
+ *
+ * Emit a KOBJ_CHANGE uevent from @dev carrying
+ * DEVICE_ENUMERATION_FAILURE=@failed_id.
+ *
+ * Return: 0 on success, a negative error code otherwise.
+ *
+ * See Documentation/ABI/testing/sysfs-uevent for more details.
+ */
+int device_enumeration_failure_notify(struct device *dev,
+				      const char *failed_id)
+{
+	char *envp[2] = { NULL, NULL };
+	int ret;
+
+	if (!failed_id || !*failed_id)
+		return -EINVAL;
+
+	envp[0] = kasprintf(GFP_KERNEL, "DEVICE_ENUMERATION_FAILURE=%s",
+			    failed_id);
+
+	if (!envp[0])
+		return -ENOMEM;
+
+	ret = kobject_uevent_env(&dev->kobj, KOBJ_CHANGE, envp);
+	kfree(envp[0]);
+
+	return ret;
+}
+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..7dc9b2316ea24 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) "-*")
 
+int device_enumeration_failure_notify(struct device *dev, const char *failed_id);
+
 #endif /* _DEVICE_H_ */
-- 
2.19.0

[PATCH v6 2/3] Documentation: ABI: document DEVICE_ENUMERATION_FAILURE uevent

[Akshay Gujar]

Document the DEVICE_ENUMERATION_FAILURE environment variable emitted
in KOBJ_CHANGE uevents when device enumeration fails.

Signed-off-by: Akshay Gujar <Akshay.Gujar@harman.com>
---
 Documentation/ABI/testing/sysfs-uevent | 37 ++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
index 0b6227706b35e..6ace99f99daa3 100644
--- a/Documentation/ABI/testing/sysfs-uevent
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -49,3 +49,40 @@ Description:
 
 Users:
                 udev, userspace tools generating synthetic uevents
+
+What:           DEVICE_ENUMERATION_FAILURE
+Date:           August 2026
+KernelVersion:  7.3
+Description:
+                Some devices are detected as physically present but fail
+                to enumerate, for example due to protocol-level errors or
+                invalid responses.
+
+                When this happens, a bus driver may emit a KOBJ_CHANGE
+                uevent containing:
+
+                  DEVICE_ENUMERATION_FAILURE=<identifier>
+
+		 The value is a bus-specific identifier of the port or slot
+		 on which enumeration failed, not the name of the device
+		 that emitted the event. For USB this is the port device
+		 name, e.g. "usb1-port1".
+
+                 Example (USB):
+
+                  ACTION=change
+                  SUBSYSTEM=usb
+                  DEVTYPE=usb_interface
+                  DEVPATH=/devices/.../usb1/1-0:1.0
+                  DEVICE_ENUMERATION_FAILURE=usb1-port1
+
+                The event is emitted from the hub interface that owns the
+                port, so DEVPATH refers to the interface. Appending the
+                identifier to DEVPATH gives the failing port:
+
+                  /sys/devices/.../usb1/1-0:1.0/usb1-port1/
+
+Users:
+		udev, userspace tools monitoring device enumeration
+		failures
+
-- 
2.19.0

[PATCH v6 3/3] usb: hub: send enumeration failure uevent

[Akshay Gujar]

Emit a structured uevent when USB device enumeration fails in
hub_port_connect(), supplementing the existing error log with a
notification userspace can act on.

The event is emitted from the port's parent, the hub interface, because
usb_port devices have neither a bus nor a class and dev_uevent_filter()
drops any uevent sent from them. The failing port is named in the
payload.

Signed-off-by: Akshay Gujar <Akshay.Gujar@harman.com>
---
 drivers/usb/core/hub.c | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/drivers/usb/core/hub.c b/drivers/usb/core/hub.c
index 5262e11c12cd3..78275dd702ceb 100644
--- a/drivers/usb/core/hub.c
+++ b/drivers/usb/core/hub.c
@@ -5613,9 +5613,21 @@ static void hub_port_connect(struct usb_hub *hub, int port1, u16 portstatus,
 	if (hub->hdev->parent ||
 			!hcd->driver->port_handed_over ||
 			!(hcd->driver->port_handed_over)(hcd, port1)) {
-		if (status != -ENOTCONN && status != -ENODEV)
+		if (status != -ENOTCONN && status != -ENODEV) {
+			int ret;
 			dev_err(&port_dev->dev,
 					"unable to enumerate USB device\n");
+
+			/* usb_port has no bus or class, so uevents from it
+			 * are dropped; emit from the hub interface instead.
+			 */
+			ret = device_enumeration_failure_notify(port_dev->dev.parent,
+								dev_name(&port_dev->dev));
+			if (ret)
+				dev_warn(&port_dev->dev,
+					 "failed to send enumeration failure uevent: %d\n",
+					 ret);
+		}
 	}
 
 done:
-- 
2.19.0