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

[Greg KH <gregkh@linuxfoundation.org>]

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