Step-by-Step: Dumping and Interpreting USB Descriptors with Thesycon

Thesycon USB Descriptor Dumper — Tips for Troubleshooting USB Descriptor IssuesUnderstanding USB descriptors is essential when developing, debugging, or troubleshooting USB devices. Thesycon’s USB Descriptor Dumper (often distributed as a small Windows utility) is a straightforward tool that extracts and presents the descriptors a USB device reports to the host. This article explains how the dumper works, what the common descriptor-related problems are, and practical tips to find and fix issues faster.

What the USB Descriptor Dumper Does

USB descriptors are small data structures the device sends to the host during enumeration to describe itself (device class, vendor/product IDs, configurations, interfaces, endpoints, string descriptors, and class-specific descriptors). Thesycon’s dumper queries a device and displays these descriptors in a human-readable format — including raw hex and parsed fields — which lets you verify whether the device reports correct values.

Why it helps: when USB enumeration or driver binding fails, a wrong or malformed descriptor is a frequent cause. The dumper isolates descriptor content so you can see exactly what the device presents.

Preparing for Troubleshooting

• Run the dumper as Administrator on Windows to ensure it can access device information.
• Use a known-good USB cable and a powered hub if the device draws substantial current; intermittent power can cause incomplete enumeration and inconsistent descriptors.
• If you have multiple devices of the same type, test each — flaky hardware can present different descriptors across attempts.
• Keep a reference — either the device’s intended descriptor listing from firmware source or a working unit’s dump — for comparison.

How to Read the Dumper Output (Key Fields to Check)

• Device Descriptor

  • bcdUSB: USB version supported (e.g., 0x0200 for USB 2.0).
  • idVendor / idProduct: Vendor and product IDs; match these against driver INF or OS expectations.
  • bDeviceClass / bDeviceSubClass / bDeviceProtocol: Device-level class codes (0x00 often means per-interface classing).
  • bNumConfigurations: Ensure it matches your firmware/design.

• Configuration Descriptor(s)

  • bConfigurationValue: Value used to select the configuration.
  • bmAttributes: Bus-powered vs self-powered vs remote wakeup bits need to be correct.
  • MaxPower: Make sure reported milliamps are accurate.

• Interface Descriptor(s)

  • bInterfaceNumber / bAlternateSetting: Check intended indexing and alternate settings.
  • bInterfaceClass / bInterfaceSubClass / bInterfaceProtocol: These must match expected class drivers (e.g., HID, CDC, MSC).
  • bNumEndpoints: Be sure the number of endpoint descriptors following equals this value.

• Endpoint Descriptor(s)

  • bEndpointAddress: Direction and endpoint number (IN/OUT).
  • bmAttributes: Transfer type (control, interrupt, bulk, isochronous) must match design.
  • wMaxPacketSize: Ensure packet size is valid for the USB speed and transfer type.
  • bInterval: For interrupt/isochronous endpoints, make sure polling interval is sensible.

• String Descriptors

  • Text fields for Manufacturer, Product, Serial: verify encoding (UTF-16LE) and that indexes referenced in other descriptors exist.

• Class-Specific Descriptors

  • For composite or class devices (CDC, HID, Audio), verify the class-specific descriptor structure and lengths match their specifications.

Common Descriptor Problems and How to Fix Them

1. Wrong Vendor/Product IDs

   • Symptom: OS doesn’t load intended driver or loads default generic driver.
   • Fix: Update firmware to report correct idVendor/idProduct or update driver INF to include device IDs.

2. Incorrect bNumConfigurations or mismatched configuration length

   • Symptom: Enumeration errors; host may ignore configuration.
   • Fix: Calculate configuration total length correctly (sum of configuration + all interface + endpoint + class-specific descriptors) and set wTotalLength accordingly.

3. Wrong endpoint direction or number

   • Symptom: Data flows fail or go to wrong endpoint.
   • Fix: Ensure bEndpointAddress has correct direction bit (0x80 = IN) and correct endpoint number.

4. Invalid wMaxPacketSize for high-speed or full-speed

   • Symptom: Transfer stalls or truncated packets.
   • Fix: Set proper wMaxPacketSize. For example, full-speed bulk max is 64 bytes; high-speed can be larger with additional packet size encodings.

5. Missing or incorrect string descriptor indexes

   • Symptom: Strings show as garbage or as blank; Windows shows “Unknown Device” text.
   • Fix: Make sure string indices referenced in device/config/interface descriptors match available string descriptors, and strings are UTF-16LE encoded with correct length byte.

6. Wrong bmAttributes or MaxPower

   • Symptom: Device may be rejected by hub or power management issues occur.
   • Fix: Report accurate power requirements and correct attributes bits (self-powered vs bus-powered).

7. Class-specific descriptor mismatches (e.g., CDC, HID)

   • Symptom: Class driver fails to bind or behaves unexpectedly.
   • Fix: Cross-check class spec (e.g., CDC Communications Class Subclass/Protocol), ensure the class-specific descriptor lengths, subtypes, and endpoints match the spec.

Troubleshooting Workflow — Step-by-Step

1. Capture a dump from the failing device and, if available, from a working device for side-by-side comparison.
2. Verify device and configuration descriptor fields first (bcdUSB, idVendor/idProduct, wTotalLength, bNumConfigurations).
3. Check each interface and its endpoints: confirm counts, addresses, types, sizes, and intervals.
4. Validate string descriptor indices and contents.
5. For composite devices, ensure the composite layout (interface association descriptors, if used) is correct and that descriptor ordering follows expectations.
6. If a descriptor looks malformed, trace back to the firmware code that forms the descriptor buffer (often an array or function that returns descriptor data).
7. Rebuild firmware with corrected descriptor values and retest. If driver installation issues remain, update the driver INF or rebind the driver through Device Manager.

Advanced Tips

• Use repeated dumps across multiple enumeration attempts to catch intermittent behavior (some bugs only appear sporadically).
• Watch for descriptor length fields off-by-one errors — they commonly cause parsers to skip data or fail validation.
• For composite devices, consider using Interface Association Descriptors (IADs) to group interfaces that share a function (this helps composite-class drivers match correctly).
• For isochronous endpoints ensure that the endpoint descriptor supports the required max packet and transactions per microframe (high-speed).
• When debugging with Windows, use Device Manager, Event Viewer, and tools like USBView alongside Thesycon’s dumper to cross-check what the OS reports.
• When possible, add runtime logging inside the device firmware to record what descriptor bytes are being sent, especially when descriptors are built dynamically.

Example: What to look for in a failing HID device dump

• Check device class: HID devices may have device class 0x00 with interface class 0x03 (HID). If device-level class is incorrectly set to 0x03 it may cause unexpected driver binding.
• Confirm presence and correctness of the HID descriptor (class-specific) referenced from the interface descriptor.
• Verify endpoint 0 is control (always), and interrupt IN endpoint exists with reasonable bInterval for HID polling.
• Ensure report descriptor length referenced in the HID descriptor matches the actual report descriptor length.

When to Suspect Hardware or USB Stack Issues

• If descriptors look correct but behavior is still incorrect, consider:
  • Hardware signal integrity (bad cable, poor PCB routing, USB transceiver issues).
  • Power-related problems (brown-outs during enumeration).
  • Host USB stack/driver bugs or OS-specific quirks; verify behavior on another host or OS.

Summary

Thesycon USB Descriptor Dumper is a powerful quick-check tool for enumerating and examining every descriptor a device offers. The typical flow is: capture dumps, compare to expected values, correct malformed/incorrect fields in firmware (or update host driver INF), and retest. Focus first on device/configuration descriptors and endpoint details — most USB enumeration and driver-binding issues trace back to mistakes there.

If you want, provide a descriptor dump (paste the dumper output) and I’ll point out likely problems and what to change in firmware.