USB-Deskriptor-Debugging für HID- und CDC-Geräte

HID- und CDC-Geräte sind beliebt, weil sie Firmware-Teams erlauben, nützliche USB-Interfaces auszuliefern, ohne für jeden Host einen Custom-Treiber zu schreiben. Dieser Komfort hängt davon ab, dass Deskriptoren präzise sind. Wenn eine HID-Tastatur, ein Sensor, eine Serial-Bridge oder ein Composite-Device ausfällt, liegt die Root-Cause oft in der Deskriptor-Evidence, bevor sie in der App erscheint.

Deskriptor-Debugging ist nicht glamourös, aber einer der schnellsten Wege, USB-Support-Cases zu lösen.

HID: Der Report-Deskriptor ist der Contract

Für HID-Geräte braucht der Host mehr als Endpoint-Informationen. Er braucht den HID-Report-Deskriptor. Dieser Deskriptor definiert Report-IDs, Usages, Größen, Counts, logische Bereiche und wie Bytes interpretiert werden sollen.

Häufige HID-Fehler:

• Report-Länge passt nicht zu tatsächlichen Interrupt-Payloads
• Report-ID wird in der Firmware genutzt, aber nicht konsistent deklariert
• Logical-Min/Max passen nicht zur Datenrepräsentation
• Usage-Page oder Usage passt nicht zu Host-Erwartungen
• Endpoint-Intervall ist unrealistisch für das Geräteverhalten
• Boot-Protocol-Annahmen kollidieren mit Report-Protocol-Verhalten

Ein Host-Fehler mag vage wirken. Ein Capture, der Deskriptor-Bytes und Interrupt-Transfers zeigt, kann den Mismatch offensichtlich machen.

CDC: Interface-Layout zählt

CDC-ACM-Geräte legen meist ein Communication-Interface und ein Data-Interface offen. Der Host erwartet einen kohärenten Satz Deskriptoren und klassenspezifische Requests. Ein fehlender Functional-Deskriptor, falsche Interface-Association oder Endpoint-Mismatch kann verhindern, dass der virtuelle Serial-Port erscheint.

Zu prüfende Evidence:

• Interface-Class und Subclass
• CDC-Header-, ACM-, Union- und Call-Management-Deskriptoren
• Notification-Endpoint
• Bulk-IN- und Bulk-OUT-Endpoints
• SET_LINE_CODING
• SET_CONTROL_LINE_STATE
• Datentransfers nach Konfiguration

Erscheint der Serial-Port, aber es fließen keine Bytes, liegt das Problem möglicherweise im Endpoint-Verhalten oder im App-Protokoll. Erscheint der Serial-Port nie, sind Deskriptoren und Klassen-Requests der erste Blickpunkt.

Composite-Devices brauchen Extra-Disziplin

Composite-Devices können HID, CDC, Mass Storage, herstellerspezifische Interfaces und mehr kombinieren. Das ist nützlich, vervielfacht aber die Fehlermodi. Ein Deskriptor-Fehler in einem Interface kann das Host-Binding für das ganze Gerät beeinflussen.

Für Composite-Debugging prüfen Sie:

• Configuration-Gesamtlänge
• Interface-Nummern
• Interface-Association-Deskriptoren
• Endpoint-Eindeutigkeit
• Platzierung der klassenspezifischen Deskriptoren
• Host-Requests pro Interface

Nehmen Sie nicht an, dass "die Firmware die richtigen Bytes sendet", bevor der Capture belegt, dass der Host die richtige Struktur gesehen hat.

Warum Rohbytes und Klassen-Interpretation beide zählen

Rohbytes sind die Ground Truth. Klassen-Interpretation macht sie nutzbar. Ein gutes USB-Diagnose-Tool sollte beides zeigen. Engineers müssen die exakten Deskriptor-Bytes sehen, wenn etwas falsch ist, aber sie brauchen auch dekodierte Felder, um nicht manuell Offsets in jedem Fall zu zählen.

Der beste Workflow:

1. den dekodierten Deskriptor-Baum inspizieren
2. zu den Rohbytes für verdächtige Felder springen
3. Host-Requests mit Firmware-Antworten vergleichen
4. Endpoint-Transfers nach Konfiguration inspizieren
5. die Session für Reproduktion oder Support-Handoff speichern

Dieser Workflow hält die Diagnose an Evidence gebunden.

Wo Bus Scope passt

Bus Scope ist für Firmware-Teams, Hardware-Labs und Device-Vendors gebaut, die eine wiederholbare Antwort darauf brauchen, warum USB-Traffic scheitert. Es hält Device-Explorer-Kontext, Paket-Detail, Rohbytes, Deskriptoren, Klassen-Observations, Filter und gespeicherte .bscope-Sessions in einer Workbench zusammen.

Für HID- und CDC-Fälle hilft Bus Scope, diese Fragen zu beantworten:

• ist die Enumeration vollständig durchgelaufen?
• haben die Deskriptoren zur gedachten Klasse gepasst?
• hat der Host die erwarteten Klassen-Requests gesendet?
• haben die Endpoint-Transfers zu den Report- oder Line-Coding-Erwartungen gepasst?
• ist das ein Firmware-, Host-Treiber- oder App-Protokoll-Problem?

Das ist der Unterschied zwischen "driver failed" und dem Verständnis, welcher USB-Contract gebrochen wurde.