Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows

Современные USB-устройства часто опираются на дескрипторы шире базовых device и configuration. BOS-дескрипторы, Microsoft OS-дескрипторы, WCID-дескрипторы, platform capabilities WebUSB и Compatible IDs WinUSB могут управлять тем, как Windows привязывает драйверы и как браузеры или инструменты обнаруживают возможности устройства. Когда эти дескрипторы неверны, пользователи видят «WinUSB driver not binding», «WebUSB device not found», «USB BOS descriptor failed», «Microsoft OS descriptor invalid», «device works on Linux but not Windows».

Bus Scope полезен тем, что дескрипторные проблемы случаются во время перечисления. Если не захватить запросы дескрипторов, вы можете увидеть только финальный симптом в Диспетчере устройств или в приложении.

Что такое BOS-дескриптор

BOS означает Binary Object Store. Он позволяет USB-устройству объявлять platform capabilities и дополнительную device-level информацию. Для современных устройств BOS может включать capabilities для:

• расширения USB 2.0
• SuperSpeed capability
• WebUSB platform capability
• Microsoft OS 2.0 platform capability

Если BOS-дескриптор сформирован некорректно, Windows или браузерные инструменты могут игнорировать фичи или падать на валидации.

Microsoft OS-дескрипторы и WinUSB

Microsoft OS-дескрипторы могут помочь Windows автоматически привязать WinUSB без кастомного INF в некоторых случаях. Более старые WCID-стиль дескрипторы и более новые Microsoft OS 2.0 дескрипторы встречаются в реальных устройствах.

Важные доказательства:

• Запрос строкового дескриптора с индексом 0xEE в старых потоках.
• Вендорный код, используемый для запроса OS-дескрипторов.
• Compatible ID вроде WINUSB.
• Extended properties.
• Привязка к номеру интерфейса.
• Правильно ли устройство ставит stall на неподдерживаемых запросах дескрипторов.

Если прошивка возвращает неверные данные, Windows может не привязать WinUSB, даже если устройство перечислится.

WebUSB

WebUSB использует platform capability descriptors в BOS для объявления landing page и доступной из браузера capability. Если запись BOS неверна, браузер может не выставить устройство как ожидается.

Симптомы:

• Браузер не может найти устройство.
• Устройство видно в ОС, но не в WebUSB-chooser.
• URL landing page отсутствует или неверен.
• Устройство работает с нативным инструментом, но не с веб-инструментом.

Трасса шины покажет, запросил ли хост BOS и что вернуло устройство.

Корректное поведение STALL

Для некоторых опциональных механизмов Microsoft-дескрипторов устройство, которое не поддерживает фичу, должно поставить stall на запрос. STALL — не всегда баг. Баг — вернуть неверные данные дескриптора или заявить поддержку, а потом упасть на follow-up-запросе.

Вот почему важен контекст управляющей передачи.

Сложности составных устройств

Microsoft OS-дескрипторы часто целятся в конкретный интерфейс. Составные устройства могут упасть, если дескриптор указывает на неверный номер интерфейса или если Windows привязывает только часть устройства.

Изучите:

• Номера интерфейсов.
• Interface association descriptors.
• Секции Compatible ID.
• Function subset headers.
• Задумано ли применение WinUSB к одному интерфейсу или ко всем.

Чек-лист отладки

Используйте такой сценарий:

1. Захватите с момента подключения.
2. Сохраните device, configuration, interface, endpoint и BOS-дескрипторы.
3. Ищите запросы Microsoft OS-дескриптора.
4. Декодируйте вендорный код и длину дескриптора.
5. Проверьте номера интерфейсов в данных дескриптора.
6. Сверьте значения Compatible ID, такие как WINUSB.
7. Проверьте, корректно ли устройство ставит stall на неподдерживаемых запросах.
8. Сравните поведение перечисления в Windows и Linux.
9. Проверьте привязку в Диспетчере устройств после перечисления.
10. Сохраните байты дескрипторов для отладки прошивки.

Итоговый диагноз

Сбои USB BOS и Microsoft OS-дескрипторов — это проблемы контракта дескрипторов. Устройство может перечислиться, но всё равно не получить WinUSB, WebUSB или привязку драйвера к интерфейсу, потому что опциональные дескрипторы искажены, отсутствуют или привязаны к неправильному интерфейсу.

Bus Scope помогает тем, что показывает запросы перечисления и дескрипторов напрямую, и сбои привязки драйверов отлаживаются по USB-доказательствам, а не только по симптомам ОС.