2026-06-02

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

Как отлаживать BOS-дескрипторы USB, Microsoft OS-дескрипторы, WCID, автопривязку драйвера WinUSB, landing pages WebUSB, stall дескрипторов и поведение перечисления в 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 к одному интерфейсу или ко всем.

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

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

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

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

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

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

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

Краткий ответ: STALL, timeout или reset сам по себе не объясняет причину. Сначала докажите, что provider видит нужный device, затем прочитайте контракт transfer: тип, направление, recipient, wValue, wIndex, заявленная и фактическая длина, status и состояние до/после. Свяжите вывод с первой транзакцией, отличающейся от исправного запуска.

Граница	Сравнение	Решение
Платформа	provider, права, Root Hub или usbmon/XHC20	Records относятся к нужному соединению?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	Host отправил ожидаемый запрос?
Data	направление, длина и сохранённые bytes	Payload соответствует контракту?
Status	ACK, STALL, timeout или cancellation	Где завершилась транзакция?
Состояние	configuration, interface, alternate setting, halt	Device был готов к запросу?

Начинайте до reset и enumeration, сохраняя descriptors, SET_CONFIGURATION, SET_INTERFACE и command перед отказом. Узкий endpoint filter может скрыть решающий control transfer. В одном опыте выполняйте одно USB-действие и меняйте только firmware, driver, port, cable, host command или timing.

Как написать цитируемый ответ?

Укажите request, setup fields, ответ и предыдущее состояние, затем тест с одной переменной. Не сохранённые из-за retention bytes не доказывают packet loss. Близость command и reset показывает корреляцию, но не причину без повторения или перехода состояния.

Сохраняйте VID/PID, firmware, speed, topology, provider, filter и trigger. Сравнивайте смысловые USB-фазы, а не frame numbers usbmon и USBPcap. Запишите начало, конец, версию, OS, подключение и checksum. Используйте устранение неполадок Bus Scope.

Semrush owners разделены: free USB analyzer принадлежит продукту, best USB protocol analyzer — сравнению, USB descriptor viewer — руководству descriptor. Для этой support-страницы не создаётся выдуманный volume или KD.

Прямой ответ и граница приемки

Краткий ответ по теме «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows»: Как отлаживать BOS-дескрипторы USB, Microsoft OS-дескрипторы, WCID, автопривязку драйвера WinUSB, landing pages WebUSB, stall дескрипторов и поведение перечисления в Windows. Считайте это проверяемым результатом, а не обещанием для любого входа, устройства, проекта или окружения. Полный результат фиксирует исходное состояние, точное действие, видимый выход и условие, подтверждающее завершение задачи в Bus Scope.

Порядок работы от доказательств

Начните с небольшого повторяемого случая до изменения полного проекта. Запишите версию приложения, систему, идентификатор входа или устройства, важные настройки и ожидаемый результат. Выполните одно осознанное действие, сохраните первый неожиданный переход и сравните с исправным случаем, если он есть. Одновременная смена нескольких параметров скрывает условие, создавшее или устранившее проблему.

Контрольная точка 1: Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Win

Рассматривайте «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows» как отдельную границу приемки для «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows». Зафиксируйте состояние до действия, первое видимое изменение и конечное состояние. Если результат отличается от заявленной цели, вернитесь к последней подтвержденной точке, а не продолжайте на предположениях.

Контрольная точка 2: Как отлаживать BOS-дескрипторы USB, Microsoft OS-дескрипторы, WCID, автопривязку драйвера

Сформулируйте для «Как отлаживать BOS-дескрипторы USB, Microsoft OS-дескрипторы, WCID, автопривязку драйвера WinUSB, landing pages WebUSB, stall дескрипторов и поведение» воспроизводимое условие успеха или отказа. Укажите, что должно присутствовать, отсутствовать и какое восстановление безопасно. Сохраняйте исходный проект или захват до прохождения той же проверки исправленной копией.

Контрольная точка 3: Что такое BOS-дескриптор

Рассматривайте «Что такое BOS-дескриптор» как отдельную границу приемки для «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows». Зафиксируйте состояние до действия, первое видимое изменение и конечное состояние. Если результат отличается от заявленной цели, вернитесь к последней подтвержденной точке, а не продолжайте на предположениях.

Контрольная точка 4: Microsoft OS-дескрипторы и WinUSB

Сформулируйте для «Microsoft OS-дескрипторы и WinUSB» воспроизводимое условие успеха или отказа. Укажите, что должно присутствовать, отсутствовать и какое восстановление безопасно. Сохраняйте исходный проект или захват до прохождения той же проверки исправленной копией.

Контрольная точка 5: WebUSB

Рассматривайте «WebUSB» как отдельную границу приемки для «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows». Зафиксируйте состояние до действия, первое видимое изменение и конечное состояние. Если результат отличается от заявленной цели, вернитесь к последней подтвержденной точке, а не продолжайте на предположениях.

Контрольная точка 6: Корректное поведение STALL

Сформулируйте для «Корректное поведение STALL» воспроизводимое условие успеха или отказа. Укажите, что должно присутствовать, отсутствовать и какое восстановление безопасно. Сохраняйте исходный проект или захват до прохождения той же проверки исправленной копией.

Контрольная точка 7: Сложности составных устройств

Рассматривайте «Сложности составных устройств» как отдельную границу приемки для «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows». Зафиксируйте состояние до действия, первое видимое изменение и конечное состояние. Если результат отличается от заявленной цели, вернитесь к последней подтвержденной точке, а не продолжайте на предположениях.

Контрольная точка 8: Чек-лист отладки

Сформулируйте для «Чек-лист отладки» воспроизводимое условие успеха или отказа. Укажите, что должно присутствовать, отсутствовать и какое восстановление безопасно. Сохраняйте исходный проект или захват до прохождения той же проверки исправленной копией.

Контрольная точка 9: Итоговый диагноз

Рассматривайте «Итоговый диагноз» как отдельную границу приемки для «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows». Зафиксируйте состояние до действия, первое видимое изменение и конечное состояние. Если результат отличается от заявленной цели, вернитесь к последней подтвержденной точке, а не продолжайте на предположениях.

Контрольная точка 10: Проверка USB-контракта для «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, W

Сформулируйте для «Проверка USB-контракта для «Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows»» воспроизводимое условие успеха или отказа. Укажите, что должно присутствовать, отсутствовать и какое восстановление безопасно. Сохраняйте исходный проект или захват до прохождения той же проверки исправленной копией.

Матрица приемки

Точка	Сохраняемое доказательство	Критерий успеха
Отладка USB BOS и Microsoft OS-дескрипторов: WebUSB, WinUSB, WCID и привязка драйверов Windows	Исходное состояние, одно действие и результат	Второй оператор воспроизводит заявленный результат
Как отлаживать BOS-дескрипторы USB, Microsoft OS-дескрипторы, WCID, автопривязку драйвера WinUSB, landing pages WebUSB,	Исходное состояние, одно действие и результат	Второй оператор воспроизводит заявленный результат
Что такое BOS-дескриптор	Исходное состояние, одно действие и результат	Второй оператор воспроизводит заявленный результат
Microsoft OS-дескрипторы и WinUSB	Исходное состояние, одно действие и результат	Второй оператор воспроизводит заявленный результат
WebUSB	Исходное состояние, одно действие и результат	Второй оператор воспроизводит заявленный результат
Корректное поведение STALL	Исходное состояние, одно действие и результат	Второй оператор воспроизводит заявленный результат

Изоляция, восстановление и передача

Остановитесь на первой неуспешной границе. Сохраните источник, проект, сеанс или захват, сделайте копию перед разрушающим редактированием и меняйте одну переменную за опыт. Повтор широкого процесса после нескольких изменений может дать иной результат без объяснения причины.

Отличайте отсутствие доказательств от доказательства отсутствия. Пустой экран может означать неверный вход, область, фильтр, права, устройство, период или состояние проекта. Подтвердите получение или импорт до толкования decoder, редактора, отчета или экспорта.

Перед передачей повторно откройте артефакт и проверьте начало, точку решения и конец. Запишите версию, платформу, конфигурацию, ожидание, наблюдение и минимальное воспроизведение. Удалите или скройте чувствительные данные и проверьте полномочия получателя.

Вопросы и ответы

Как надежнее всего начать?

Возьмите минимальный репрезентативный случай, запишите ожидаемый результат и меняйте одну переменную. Подтвердите базовый путь до добавления фильтров, эффектов, правок, автоматизации или большого источника.

Какие доказательства сохранять?

Сохраните идентификатор входа, версию, платформу, настройки, точное действие, первый неожиданный переход и конечный выход. Закройте и повторно откройте проект, сеанс, отчет или экспорт.

Когда повторять процедуру?

После значимого изменения приложения, системы, драйвера, прошивки, модели, источника или процесса. Сохраните предыдущий принятый случай как неизменную основу сравнения.

Когда результат готов к передаче?

Когда другой уполномоченный человек определяет вход, повторяет действие, видит тот же результат, понимает ограничения и открывает артефакт без недокументированного локального состояния.

Связанные руководства

Эти страницы на том же языке описывают соседние этапы, не меняя канонического владельца темы: