Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows

Les périphériques USB modernes s'appuient souvent sur des descripteurs au-delà des descripteurs de périphérique et de configuration de base. Les descripteurs BOS, les descripteurs Microsoft OS, WCID, les platform capabilities WebUSB et les ID compatibles WinUSB peuvent contrôler la façon dont Windows lie les pilotes et dont les navigateurs ou outils découvrent les capacités du périphérique. Quand ces descripteurs sont erronés, les utilisateurs voient « WinUSB driver not binding », « WebUSB device not found », « USB BOS descriptor failed », « Microsoft OS descriptor invalid » ou « device works on Linux but not Windows ».

Bus Scope est utile car les problèmes pilotés par les descripteurs surviennent pendant l'énumération. Si vous ne capturez pas les requêtes de descripteurs, vous ne voyez peut-être que le symptôme final dans le Gestionnaire de périphériques ou l'application.

Ce qu'est le descripteur BOS

BOS signifie Binary Object Store. Il permet à un périphérique USB d'annoncer des platform capabilities et des informations additionnelles au niveau périphérique. Pour les appareils modernes, BOS peut inclure des capabilities pour :

• USB 2.0 extension
• capability SuperSpeed
• platform capability WebUSB
• platform capability Microsoft OS 2.0

Si le descripteur BOS est mal formé, Windows ou les outils basés navigateur peuvent ignorer les fonctionnalités ou échouer la validation.

Descripteurs Microsoft OS et WinUSB

Les descripteurs Microsoft OS peuvent aider Windows à lier WinUSB automatiquement sans INF personnalisé dans certains cas. Les anciens descripteurs de style WCID et les plus récents descripteurs Microsoft OS 2.0 sont tous deux rencontrés sur des appareils réels.

Les preuves importantes incluent :

• requête de descripteur string d'index 0xEE dans les anciens flux
• vendor code utilisé pour demander les descripteurs OS
• compatible ID tel que WINUSB
• propriétés étendues
• association de numéro d'interface
• fait que le périphérique stall correctement les requêtes de descripteurs non supportées

Si le firmware renvoie des données mal formées, Windows peut ne pas lier WinUSB même si le périphérique s'énumère.

WebUSB

WebUSB utilise les platform capabilities du BOS pour annoncer une landing page et une capability accessible au navigateur. Si l'entrée BOS est erronée, un navigateur peut ne pas exposer le périphérique comme attendu.

Symptômes :

• le navigateur ne trouve pas le périphérique
• le périphérique apparaît dans l'OS mais pas dans le sélecteur WebUSB
• URL de landing page manquante ou fausse
• le périphérique marche avec un outil natif mais pas avec un outil web

La trace du bus peut montrer si l'hôte a demandé le BOS et ce que le périphérique a renvoyé.

Comportement STALL valide

Pour certains mécanismes optionnels de descripteurs Microsoft, un périphérique qui ne supporte pas la fonctionnalité doit stall la requête. Un STALL n'est pas toujours un bug. Le bug est de renvoyer des données de descripteur invalides ou de prétendre supporter puis échouer la requête suivante.

C'est pourquoi le contexte du transfert de contrôle compte.

Complications des périphériques composites

Les descripteurs Microsoft OS ciblent souvent une interface précise. Les périphériques composites peuvent échouer si le descripteur pointe vers un mauvais numéro d'interface ou si Windows ne lie qu'une partie du périphérique.

Inspectez :

• les numéros d'interface
• les descripteurs Interface Association
• les sections compatible ID
• les en-têtes function subset
• si WinUSB est destiné à une interface ou à toutes

Checklist de débogage

Suivez ce flux :

1. Capturez dès le branchement.
2. Conservez descripteurs de périphérique, configuration, interface, endpoint et BOS.
3. Cherchez les requêtes de descripteurs Microsoft OS.
4. Décodez le vendor code et la longueur du descripteur.
5. Vérifiez les numéros d'interface dans les données de descripteur.
6. Vérifiez les valeurs compatible ID comme WINUSB.
7. Vérifiez si les requêtes non supportées stallent correctement.
8. Comparez le comportement d'énumération Windows et Linux.
9. Vérifiez la liaison dans le Gestionnaire de périphériques après énumération.
10. Conservez les octets de descripteurs pour le débogage firmware.

Diagnostic final

Les échecs de descripteurs USB BOS et Microsoft OS sont des problèmes de contrat de descripteurs. Le périphérique peut s'énumérer mais quand même échouer WinUSB, WebUSB ou la liaison de pilote spécifique à l'interface parce que des descripteurs optionnels sont mal formés, manquants ou mappés à la mauvaise interface.

Bus Scope aide en montrant directement l'énumération et les requêtes de descripteurs, pour que les échecs de liaison de pilote soient débogués à partir des preuves USB plutôt que des seuls symptômes OS.