[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

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

[Akshay Gujar]

On Fri, Jul 17, 2026 at 12:40:43PM +0000, Greg KH 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?

No. Passing &port_dev->dev directly drops the uevent in kobject_uevent_env() 
because dev_uevent_filter() returns 0 for usb_port devices (no bus/class).

The event must therefore be emitted from the port's registered parent,
the hub's usb_interface device (port_dev->dev.parent).

To keep the helper simple, v6 will explicitly take the emitting device 
and the failed identifier, removing all internal fallback logic:

    int device_enumeration_failure_notify(struct device *dev,
                                          const char *failed_id);

USB caller in hub_port_connect():

    device_enumeration_failure_notify(port_dev->dev.parent,
                                      dev_name(&port_dev->dev));

> > +	if (!uevent_dev)
> > +		return;
> 
> How can that happen?  A device will ALWAYS have a valid parent pointer.

With the fallback removed there is no parent handling in the helper
at all, so this check will be gone in v6.

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

Will return the error to the caller.

	ret = kobject_uevent_env(&dev->kobj, KOBJ_CHANGE, envp);
	kfree(envp[0]);
	return ret;

Will send v6 with these changes.

Thanks,
Akshay

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

[Akshay Gujar]

On Fri, Jul 17, 2026 at 12:37:32PM +0200, Greg KH 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?

No, DEVTYPE=usb_interface is correct, the example was captured on
real hardware. The uevent is not emitted from the port device itself.
usb_port devices have no bus or class, so dev_uevent_filter()
drops any event from them.It is emitted from the port's parent, 
the hub's usb_interface device, while the failing port is identified in the payload instead.

Per your feedback on patch 1/3, In v6, this becomes explicit in the API.
The caller passes the emitting device and the failed identifier as
separate arguments. I will also reword the Description to make clear
that the value is a bus-specific identifier of the port or slot that
failed to enumerate, not the name of the emitting device, so the
example cannot be misread.

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

checkpatch did not flag it. Will fix the missing newline at EOF in v6.

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

We currently consume this uevent via a netlink listener to show 
system popups/notifications when device enumeration fails. Once the kernel 
ABI stabilizes, a default udev rule example will be submitted separately.

Thanks,
Akshay

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

[Akshay Gujar]

On Fri, Jul 17, 2026 at 12:35:33PM +0200, Greg KH 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?

The uevent is currently emitted from the hub's usb_interface device,
not the port. usb_port devices have no bus or class, so
dev_uevent_filter() drops any uevent sent from them. The failing port
is identified in the payload (DEVICE_ENUMERATION_FAILURE=usb1-port1)
rather than by the emitting device. The documentation example was
captured from real hardware, which is why it shows DEVTYPE=usb_interface.

Per your feedback on patch 1/3, v6 will make this explicit, the helper
takes the emitting device and the failed identifier as separate
arguments, and the bus driver states both directly.

> And what about the dev_name() issue?

Yes, dev_name() can return NULL for a device that fails before
dev_set_name(), and kasprintf() would then hand userspace the
meaningless string "DEVICE_ENUMERATION_FAILURE=(null)".

The v6 interface will eliminates this, the identifier becomes an explicit
argument validated by the helper:

	int device_enumeration_failure_notify(struct device *dev,
					      const char *failed_id);

	if (!dev || !failed_id || !*failed_id)
		return -EINVAL;

so a NULL or empty identifier is rejected before anything reaches
userspace. For the current USB caller this could not occur (the port
device is named at registration), but the check is needed for a
generic helper.

Thanks,
Akshay

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

[Greg KH]

On Fri, Jul 24, 2026 at 10:25:06PM +0000, Akshay Gujar wrote:
> On Fri, Jul 17, 2026 at 12:37:32PM +0200, Greg KH 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?
> 
> No, DEVTYPE=usb_interface is correct, the example was captured on
> real hardware. The uevent is not emitted from the port device itself.
> usb_port devices have no bus or class, so dev_uevent_filter()
> drops any event from them.It is emitted from the port's parent, 
> the hub's usb_interface device, while the failing port is identified in the payload instead.

So shouldn't we fix the fact that usb_ports are not on the bus and add
them to one?  Would that make things more obvious here as to what port
the issue is happening on, and potentially allow userspace to actually
figure out which physical port the problem is?

> Per your feedback on patch 1/3, In v6, this becomes explicit in the API.
> The caller passes the emitting device and the failed identifier as
> separate arguments. I will also reword the Description to make clear
> that the value is a bus-specific identifier of the port or slot that
> failed to enumerate, not the name of the emitting device, so the
> example cannot be misread.
> 
> > > +               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?
> 
> checkpatch did not flag it. Will fix the missing newline at EOF in v6.
> 
> > And is there actually udev code to handle this being proposed anywhere?
> 
> We currently consume this uevent via a netlink listener to show 
> system popups/notifications when device enumeration fails. Once the kernel 
> ABI stabilizes, a default udev rule example will be submitted separately.

That's great, thanks!

greg k-h