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

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

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