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