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

[PATCH v5 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 introduces 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.
 
The USB change is intentionally minimal and serves as an initial user of
the generic helper. Other subsystems may use the helper independently if
needed.

---
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

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 | 25 +++++++++++++++
 drivers/base/core.c                    | 44 ++++++++++++++++++++++++++
 drivers/usb/core/hub.c                 |  4 ++-
 include/linux/device.h                 |  2 ++
 4 files changed, 74 insertions(+), 1 deletion(-)

base-commit: 0f26556c5eeea62cc934fa8938b148aa5844a6b6
-- 
2.19.0

[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@harman.com>
---
 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

[PATCH v5 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 | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
index 0b6227706b35e..e362c34aa2ef6 100644
--- a/Documentation/ABI/testing/sysfs-uevent
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -49,3 +49,28 @@ Description:
 
 Users:
                 udev, userspace tools generating synthetic uevents
+
+What:          DEVICE_ENUMERATION_FAILURE
+Date:          July 2026
+KernelVersion: 7.3
+Description:
+               Some devices may be detected but fail to enumerate
+               due to protocol-level errors or invalid responses.
+
+               A KOBJ_CHANGE uevent includes the following environment
+               variable when this occurs:
+
+                 DEVICE_ENUMERATION_FAILURE=<dev_name>
+
+               The value is the kernel device name of the device for
+               which enumeration failed, as returned by dev_name().
+
+               Example (USB):
+
+               ACTION=change
+               SUBSYSTEM=usb
+               DEVTYPE=usb_interface
+               DEVICE_ENUMERATION_FAILURE=usb1-port1
+
+Users:
+               udev, userspace tools monitoring device enumeration failures
\ No newline at end of file
-- 
2.19.0

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

[Akshay Gujar]

Enumeration failure is currently only reported via kernel log.

Emit a KOBJ_CHANGE uevent with DEVICE_ENUMERATION_FAILURE=<dev_name>
when enumeration fails in hub_port_connect().

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

diff --git a/drivers/usb/core/hub.c b/drivers/usb/core/hub.c
index 5262e11c12cd3..2f2fd90aca66a 100644
--- a/drivers/usb/core/hub.c
+++ b/drivers/usb/core/hub.c
@@ -5613,9 +5613,11 @@ 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) {
 			dev_err(&port_dev->dev,
 					"unable to enumerate USB device\n");
+			device_enumeration_failure_notify(&port_dev->dev);
+		}
 	}
 
 done:
-- 
2.19.0

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

[Greg KH]

On Wed, Jul 15, 2026 at 11:40:25AM +0000, Akshay Gujar wrote:
> 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 introduces 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.
>  
> The USB change is intentionally minimal and serves as an initial user of
> the generic helper. Other subsystems may use the helper independently if
> needed.

There are some review comments on the documentation patch here:
	https://sashiko.dev/#/patchset/20260715114028.3627807-1-Akshay.Gujar@harman.com
that look correct.  This will not be an interface message, but a device
message, right?

And what about the dev_name() issue?

thanks,

greg k-h

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

[Greg KH]

On Wed, Jul 15, 2026 at 11:40:27AM +0000, Akshay Gujar wrote:
> 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 | 25 +++++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
> index 0b6227706b35e..e362c34aa2ef6 100644
> --- a/Documentation/ABI/testing/sysfs-uevent
> +++ b/Documentation/ABI/testing/sysfs-uevent
> @@ -49,3 +49,28 @@ Description:
>  
>  Users:
>                  udev, userspace tools generating synthetic uevents
> +
> +What:          DEVICE_ENUMERATION_FAILURE
> +Date:          July 2026
> +KernelVersion: 7.3
> +Description:
> +               Some devices may be detected but fail to enumerate
> +               due to protocol-level errors or invalid responses.
> +
> +               A KOBJ_CHANGE uevent includes the following environment
> +               variable when this occurs:
> +
> +                 DEVICE_ENUMERATION_FAILURE=<dev_name>
> +
> +               The value is the kernel device name of the device for
> +               which enumeration failed, as returned by dev_name().
> +
> +               Example (USB):
> +
> +               ACTION=change
> +               SUBSYSTEM=usb
> +               DEVTYPE=usb_interface

This will be the port device, not the usb interface, right?

> +               DEVICE_ENUMERATION_FAILURE=usb1-port1

That looks right.

> +
> +Users:
> +               udev, userspace tools monitoring device enumeration failures
> \ No newline at end of file

Didn't checkpatch complain about this?

And is there actually udev code to handle this being proposed anywhere?

thanks,

greg k-h

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

[Greg KH]

On Wed, Jul 15, 2026 at 11:40:26AM +0000, Akshay Gujar wrote:
> 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@harman.com>
> ---
>  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;

This is going to confuse people, if events show up for a parent device,
and for an actual device, in different busses/times, right?  Why
shouldn't the device itself always just be the one as it's up to the bus
to determine when to call this?

For your USB example, is the uevent sent state ever hit yet when you
want to emit this?

> +	if (!uevent_dev)
> +		return;

How can that happen?  A device will ALWAYS have a valid parent pointer.

> +
> +	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);

You loose this error if something went wrong?

thanks,

greg k-h