drivers/usbhost: Report each device as it is enumerated.

[Fishwaldo]

Summary

This is mainly a quality of life improvement for anyone debugging USB on NuttX.

When a device is plugged in, the host says nothing about it. If a class driver claims it, a node appears in /dev and you can infer what happened. If nothing claims it, an unsupported device or a supported one whose driver is not in the build, there is no output at all, and no way to tell the difference between "unsupported device" and "nothing plugged in". The information exists; it is simply thrown away unless you enable CONFIG_DEBUG_USB_INFO, which then buries it in everything else the stack has to say.

CONFIG_USBHOST_ANNOUNCE reports each device once as it is enumerated, in a shape people will recognise from other systems: where it is, what it is, its vendor, product and release, and the maker, product and serial number the device reports in its own string descriptors.

usb 0-5.2: new device, idVendor=46f4, idProduct=0001, bcdDevice=0.00
usb 0-5.2: mass storage, driver attached
usb 0-5.2: Product: QEMU USB HARDDRIVE
usb 0-5.2: Manufacturer: QEMU
usb 0-5.2: SerialNumber: 1-0000:00:04.0-1.2

Three details are deliberate. The port is given as the path from the root hub and named by bus, because a device on a hub's first port and one on a controller's first port are otherwise reported identically. The report is made after binding rather than from within it, because a composite device never reaches the ordinary class lookup, usbhost_composite() binds it first, and reporting from there leaves precisely the multi-function devices unmentioned. And whether a driver claimed the device is tracked explicitly rather than read from the returned status, which the per-interface loop sets to OK regardless.

Impact

• User visible: one line per device plus its strings, when the option is on. Nothing else changes.
• Default n, so no existing configuration is affected.
• Cost when enabled: three extra control transfers per device, for the three strings, taken once at enumeration and only because a report was asked for.
• All host controllers: this is in usbhost_enumerate(), the common path all 27 in-tree HCDs use.
• New field: struct usbhost_roothubport_s gains a bus number so a port can be named on a system with more than one controller. A driver that does not set it reports zero, which is the only bus it has.
• Compatibility, hardware, documentation, security: unaffected.

Testing

Host: macOS 15.5 (Apple Silicon). qemu: 10.1.5 with KVM on Fedora 43 x86_64.

Four devices behind a hub on qemu-xhci: mass storage, a keyboard, and a USB audio device that NuttX has no driver for. Same tree and topology in both runs, differing only in CONFIG_USBHOST_ANNOUNCE.

Without the option, the entire bus, in full:

/dev:
 kbda
 sda

Two nodes appeared. Nothing says the hub exists, and nothing says the audio device was ever attached.

With the option:

usb 0-5:   hub, driver attached              Product: QEMU USB Hub
usb 0-5.2: mass storage, driver attached     Product: QEMU USB HARDDRIVE
usb 0-5.3: keyboard, driver attached         Product: QEMU USB Keyboard
usb 0-5.4: audio, no driver                  Product: QEMU USB Audio

The unclaimed audio device is the point: it produces no /dev node either way, so without this there is nothing at all to tell you it is present, what it is, or why nothing happened.

These runs were made with #19745 applied underneath, because qemu-intel64:jumbo is the only in-tree configuration with a USB host controller and on current master that controller does not initialise. The change itself is in the common enumeration path and is independent of any host controller.

[github-actions]

MemBrowse Memory Report

No memory changes detected for:

• arduino-mega2560
• esp32-devkitc
• hifive1-revb
• mirtoo
• qemu-armv8a
• qemu-intel64
• rx65n-rsk2mb
• s698pm-dkit
• stm32-nucleo-f103rb

[Fishwaldo]

Thanks for the review @xiaoxiang781216 updated based on your feedback