usb-kernel-debug — what the Linux side of the link saw
Two kernel facilities, by the role Linux plays in the link:
| Linux is the … | usbmon URB capture (usbcap.py) |
dynamic debug (usb_dyndbg.sh) |
|---|---|---|
| PC host | yes — what the host exchanged | yes — why the host driver acted |
| gadget peer | no — a UDC has no usbmon | yes — dwc2/dwc3 + udc_core + libcomposite |
Neither sees inside the device's firmware or the wire itself: pair this
with a wire sniffer (the usb-sniffer skill, if installed) and target-side
debugging (GDB on the MCU) for those.
usbmon — capture (host role)
usbmon records host-side URBs — control / bulk / interrupt / isochronous transfers, descriptors, class requests, STALLs, short packets — i.e. exactly what the host exchanged with a device.
Requires usbmon loaded and /dev/usbmon* readable by your user (wireshark group); the script says so when tshark cannot open the interface — a fresh group membership needs a new login or sg wireshark -c '...'. Reading a finished .pcapng needs no group.
S=<skill dir>/scripts
$S/usbcap.py 1a86:55d4 10 # the bus of that plugged-in device, 10 s; --help for selectors and defaults
$S/usbcap.py 3 10 cap.pcapng --snaplen 64 # bus 3, URB headers only
Capture the device's own bus. A selector matching devices on several buses (1a86: with two adapters plugged in) is refused with the matches listed: pass the bus, or auto when you really want every bus. Full payloads by default; --snaplen 64 keeps only the 64-byte usbmon record (URB type, endpoint, status, lengths) for long or high-throughput captures, and 128 adds the first 64 bytes of payload, enough for setup packets and descriptor heads. An existing output file is refused, never overwritten. To catch enumeration, start the capture, then replug or reset the device.
usbmon — analyze
tshark -r cap.pcapng # one line per URB
tshark -r cap.pcapng -V | less # full dissection (descriptors decoded)
tshark -r cap.pcapng -Y 'usb.device_address==26' # filter to one device
Filter (-Y '<expr>')
| Goal | Expression |
|---|---|
| One device / endpoint | usb.device_address==26 / usb.endpoint_address==0x81 |
| IN (to host) / OUT (from host) | usb.endpoint_address.direction==1 / ==0 |
| Submit / Complete event | usb.urb_type=='S' / =='C' (char literal: single quotes) |
| Control / bulk / interrupt / iso | usb.transfer_type==2 / 3 / 1 / 0 |
| Only transfers carrying data | usb.data_len>0 |
| GET_DESCRIPTOR / SET_ADDRESS / SET_CONFIGURATION | usb.setup.bRequest==6 / 5 / 9 |
| SET_INTERFACE / CLEAR_FEATURE (clear-halt) | usb.setup.bRequest==11 / 1 |
| Descriptor type DEVICE/CONFIG/STRING/HID-report | usb.bDescriptorType==1 / 2 / 3 / 0x22 |
| Class / vendor requests | usb.bmRequestType.type!=0 |
| STALLs / errors | usb.urb_status!=0 && usb.urb_status!=-115 |
Combine with && — e.g. one endpoint's data: usb.endpoint_address==0x02 && usb.data_len>0.
usb.urb_status codes (errno): 0 success · -115 -EINPROGRESS (every Submit) · -71 -EPROTO (transaction error — device answered wrong or didn't service in time, after the HC's retries) · -32 -EPIPE (STALL) · -110 -ETIMEDOUT · -75 -EOVERFLOW (babble). A control transfer completing -71 ≠ a STALL: the device mis-/under-served it (e.g. EP0 starved under load), not a deliberate STALL from its control handler.
Decoding class requests: the plain -e usb.setup.bRequest field is often blank for class requests (CDC SET_LINE_CODING 0x20 / SET_CONTROL_LINE_STATE 0x22, bmRequestType==0x21) — Wireshark routes them to class fields. Use -V on the Submit frame to get the request name + wValue (for SET_CONTROL_LINE_STATE, wValue bit0=DTR, bit1=RTS).
Hard limit — usbmon is URB-level, not wire-level. It cannot show data toggle (DATA0/DATA1) or NAKs. A device-side stall and a toggle desync both look identical: Submits on an endpoint with no Completes. To tell them apart, pair usbmon with a wire sniffer, or with GDB on the device: read the endpoint control register (response/toggle bits) and the device stack's endpoint state at the moment of the hang.
Dynamic debug (either role)
Kernel dynamic debug shows the Linux side's reasoning that capture can't: port resets and their causes, enumeration retries, address (re)assignment, EP halts, xHCI ring/command errors. scripts/usb_dyndbg.sh (--help lists the allowlisted modules; run with sudo) flips the print flag for those USB modules only:
sudo $S/usb_dyndbg.sh on usbcore xhci_hcd # then reproduce while following `sudo dmesg -w`
sudo $S/usb_dyndbg.sh status # what is switched on right now
sudo $S/usb_dyndbg.sh off usbcore xhci_hcd # ALWAYS: left on, it floods the log and skews timing
Module choice by role: on a host, usbcore for enumeration/hub logic plus the controller driver lsusb -t shows for the bus; on a gadget peer, dwc2 (or dwc3) + udc_core + libcomposite, run on the peer itself (the script is self-contained, copy it over). Best for re-enumerates / enumeration stalls / port-reset storms, where usbmon shows the resets but not the host's reason.
Reading a capture
- Not recognized / re-enumerates: is
GET DESCRIPTOR (DEVICE)answered,bMaxPacketSize0sane? Repeated SET_ADDRESS or resets mean the device was too slow to respond; dynamic debug onusbcoreand the controller driver gives the host's reset reason. - Enumeration stalls: find the last good control transfer; the next request, often CONFIG, a string, or the first class request, is what the device mishandled.
- Control STALL: a control URB completing
-32(-EPIPE) is a STALL from the device's control handler, usually an unhandledbRequest(decode it with-V).-71is not a STALL, see the errno list. - Bulk / interrupt missing or short: on the endpoint, do Submits get Completes? An unexpected short (
usb.data_len < wMaxPacketSize) suggests a length bug; no completions can be the device never writing, a stalled endpoint or a toggle desync, which usbmon cannot separate. - A CDC read hangs with the IN endpoint idle: check EP0 first. Did
SET_CONTROL_LINE_STATEcomplete0or fail-71? If it failed, the device never saw DTR and may stop sourcing data by design. - ISO / audio dropouts: ISO URB cadence (~1/ms at full speed) and payload lengths; zero-length frames mean the device starved the endpoint.
- Wrong descriptors:
-Vdecodes them; checkbLength/wTotalLengthagainst what the device is meant to return.