USB-Composite-Device-Debugging: Interface-Nummern, IAD, Endpoints und Treiberbindung
So debuggen Sie USB-Composite-Devices, wenn ein Interface läuft, ein anderes fehlschlägt oder der Host den falschen Treiber bindet.
USB-Composite-Devices sind praktisch und gefährlich. Ein einzelnes Gerät kann HID-Controls, CDC-Serial, Mass-Storage, herstellerspezifische Endpoints, Audio, Video oder Diagnose-Interfaces exponieren. Wenn alles korrekt beschrieben ist, bindet der Host die richtigen Treiber und jede Funktion läuft. Ist ein Deskriptor-Feld falsch, kann das ganze Gerät unzuverlässig wirken.
Suchen wie "USB composite device not recognized", "CDC interface not showing", "HID works but serial does not" oder "wrong driver binding USB interface" deuten meist auf Deskriptor-Struktur, Interface-Nummerierung, Endpoint-Zuweisung oder das Verhalten des Interface-Association-Deskriptors hin.
Composite-Devices brauchen eine kohärente Konfiguration
Der Configuration-Deskriptor ist die Top-Level-Karte. Er muss die Gesamtlänge, Anzahl der Interfaces, Power-Attributes und alle verschachtelten Interface- und Endpoint-Deskriptoren beschreiben. Ist wTotalLength falsch, liest der Host möglicherweise nicht alle Funktionen. Ist die Interface-Anzahl falsch, ignoriert der Host spätere Interfaces. Kollidieren Endpoint-Adressen, werden Transfers mehrdeutig oder ungültig.
Prüfen Sie:
- Configuration-Gesamtlänge
- Anzahl der Interfaces
- Interface-Nummern
- Alternate Settings
- Endpoint-Adressen
- Endpoint-Richtungen
- Class-, Subclass-, Protocol-Werte
- Deskriptor-Reihenfolge
Ein Capture sollte zeigen, ob der Host die volle Konfiguration angefragt hat und welche Bytes das Gerät zurückgegeben hat.
IAD hilft, zusammengehörige Interfaces zu gruppieren
Interface-Association-Deskriptoren werden oft genutzt, um mehrere Interfaces zu gruppieren, die zu einer Funktion gehören, etwa CDC-Communication plus CDC-Data. Ohne korrekte Gruppierung bindet der Host möglicherweise Treiber falsch oder legt nur einen Teil der Funktion offen.
IAD-Evidence zum Prüfen:
- erste Interface-Nummer
- Interface-Anzahl
- Function-Class, Subclass, Protocol
- Platzierung vor den gruppierten Interfaces
- Konsistenz mit den tatsächlichen Interface-Deskriptoren
Erscheint CDC-Serial nicht, aber HID läuft, ist das HID-Interface möglicherweise in Ordnung, während die CDC-Gruppierung falsch ist.
Endpoint-Adress-Kollisionen sind leicht zu übersehen
Endpoint-Adressen enthalten die Richtung. Endpoint 0x81 und 0x01 sind verschiedene Richtungen, aber zwei IN-Endpoints mit derselben Adresse sind innerhalb derselben Device-Konfiguration nicht erlaubt. Firmware-Teams kopieren manchmal Endpoint-Deskriptoren zwischen Interfaces und vergessen, die Adressen anzupassen.
Symptome:
- ein Interface läuft, ein anderes ist still
- Host sendet Transfers an unerwarteten Endpoint
- Klassentreiber lädt, aber App bekommt keine Daten
- Endpoint-STALL oder -Timeout nach Konfiguration
- nur eine Funktion läuft auf einmal
Der Capture sollte Endpoint-Deskriptoren und späteren Transfer-Traffic nebeneinander zeigen.
Treiberbindung ist auch Evidence
Der Host wählt Treiber basierend auf Deskriptoren. Ein Gerät, das falsch bindet, hat möglicherweise Deskriptor-Evidence, die erklärt, warum. Class, Subclass, Protocol, Interface-Association, Compatible-IDs und OS-spezifische Deskriptoren können die Bindung beeinflussen.
Diagnostizieren Sie Treiberbindung nicht nur aus dem Geräte-Manager oder App-Logs. Vergleichen Sie die klassenspezifischen Requests des Hosts mit dem Deskriptor-Baum. Kommen die erwarteten Klassen-Requests nie an, hat der Host wahrscheinlich nicht den erwarteten Treiber gebunden.
Wo Bus Scope passt
Bus Scope hilft Firmware-Teams, Composite-Devices auf beiden Ebenen zu inspizieren:
- Deskriptor-Map
- Transfer-Evidence nach Treiberbindung
Eine gute .bscope-Session für Composite-Debugging zeigt:
- alle Interfaces
- IAD-Gruppierung
- Endpoint-Zuweisungen
- klassenspezifische Requests pro Interface
- rohe Deskriptor-Bytes
- Transfer-Status nach Konfiguration
So wird das Support-Gespräch konkret. Statt "Windows mag unser Composite-Device nicht" kann der Report sagen "Interface 2 erhält keine CDC-Klassen-Requests, weil der Gruppierungs-Deskriptor nicht zum deklarierten Interface-Layout passt".
Das ist die Evidence-Ebene, die Firmware-Teams brauchen.