USB-BOS- und Microsoft-OS-Deskriptor-Debugging: WebUSB, WinUSB, WCID und Windows-Treiberbindung

Moderne USB-Geräte verlassen sich oft auf Deskriptoren jenseits der einfachen Device- und Configuration-Deskriptoren. BOS-Deskriptoren, Microsoft-OS-Deskriptoren, WCID-Deskriptoren, WebUSB-Platform-Capabilities und WinUSB-kompatible IDs können steuern, wie Windows Treiber bindet und wie Browser oder Tools Device-Capabilities entdecken. Sind diese Deskriptoren falsch, sehen Nutzer "WinUSB driver not binding", "WebUSB device not found", "USB BOS descriptor failed", "Microsoft OS descriptor invalid" oder "device works on Linux but not Windows".

Bus Scope hilft, weil deskriptor-getriebene Probleme während der Enumeration passieren. Wenn Sie die Deskriptor-Requests nicht capturen, sehen Sie am Ende vielleicht nur das Symptom im Geräte-Manager oder in der App.

Was der BOS-Deskriptor ist

BOS steht für Binary Object Store. Er erlaubt einem USB-Gerät, Platform-Capabilities und zusätzliche Device-Level-Informationen zu annoncieren. Für moderne Geräte kann BOS Capabilities enthalten für:

• USB 2.0 Extension
• SuperSpeed-Capability
• WebUSB-Platform-Capability
• Microsoft-OS-2.0-Platform-Capability

Ist der BOS-Deskriptor fehlerhaft, ignorieren Windows oder browser-basierte Tools möglicherweise Features oder die Validierung schlägt fehl.

Microsoft-OS-Deskriptoren und WinUSB

Microsoft-OS-Deskriptoren können Windows helfen, WinUSB automatisch ohne custom INF zu binden. Ältere WCID-Stil-Deskriptoren und neuere Microsoft-OS-2.0-Deskriptoren tauchen beide in realen Geräten auf.

Wichtige Evidence:

• Request für String-Deskriptor-Index 0xEE in älteren Flows.
• Vendor-Code, der für OS-Deskriptor-Requests genutzt wird.
• Compatible ID wie WINUSB.
• Extended Properties.
• Interface-Nummer-Zuordnung.
• Ob das Gerät nicht unterstützte Deskriptor-Requests korrekt stalled.

Liefert die Firmware fehlerhafte Daten, bindet Windows WinUSB möglicherweise nicht, obwohl das Gerät enumeriert.

WebUSB

WebUSB nutzt BOS-Platform-Capability-Deskriptoren, um eine Landing-Page und eine vom Browser zugängliche Capability zu annoncieren. Ist der BOS-Eintrag falsch, zeigt ein Browser das Gerät möglicherweise nicht wie erwartet.

Symptome:

• Browser findet das Gerät nicht.
• Gerät erscheint im OS, aber nicht im WebUSB-Chooser.
• Landing-Page-URL fehlt oder ist falsch.
• Gerät läuft mit nativem Tool, aber nicht im Web-Tool.

Der Bus-Trace zeigt, ob der Host BOS angefragt hat und was das Gerät zurückgegeben hat.

Valides STALL-Verhalten

Für einige optionale Microsoft-Deskriptor-Mechanismen sollte ein Gerät, das das Feature nicht unterstützt, den Request stallen. Ein STALL ist nicht immer ein Bug. Der Bug ist, ungültige Deskriptor-Daten zurückzugeben oder Support zu beanspruchen und dann den Folge-Request scheitern zu lassen.

Deshalb zählt der Control-Transfer-Kontext.

Composite-Device-Komplikationen

Microsoft-OS-Deskriptoren zielen oft auf ein bestimmtes Interface. Composite-Devices können fehlschlagen, wenn der Deskriptor auf eine falsche Interface-Nummer zeigt oder Windows nur einen Teil des Geräts bindet.

Prüfen Sie:

• Interface-Nummern.
• Interface-Association-Deskriptoren.
• Compatible-ID-Sektionen.
• Function-Subset-Header.
• Ob WinUSB für ein Interface oder alle Interfaces gedacht ist.

Debug-Checkliste

Nutzen Sie diesen Workflow:

1. Ab Anstecken capturen.
2. Device-, Configuration-, Interface-, Endpoint- und BOS-Deskriptoren sichern.
3. Nach Microsoft-OS-Deskriptor-Requests suchen.
4. Vendor-Code und Deskriptor-Länge dekodieren.
5. Interface-Nummern in den Deskriptor-Daten prüfen.
6. Compatible-ID-Werte wie WINUSB verifizieren.
7. Prüfen, ob nicht unterstützte Requests korrekt stallen.
8. Windows- und Linux-Enumeration-Verhalten vergleichen.
9. Treiberbindung im Geräte-Manager nach Enumeration prüfen.
10. Deskriptor-Bytes für Firmware-Debugging sichern.

Enddiagnose

USB-BOS- und Microsoft-OS-Deskriptor-Fehler sind Deskriptor-Contract-Probleme. Das Gerät kann enumerieren und trotzdem WinUSB, WebUSB oder interface-spezifische Treiberbindung nicht erreichen, weil optionale Deskriptoren fehlerhaft, fehlend oder auf das falsche Interface gemappt sind.

Bus Scope hilft, indem es die Enumeration und die Deskriptor-Requests direkt zeigt, sodass Treiberbindungs-Fehler aus der USB-Evidence gedebuggt werden können statt nur aus OS-Symptomen.