Отладка HID Feature Report: GET_REPORT, SET_REPORT, вендорные команды и потерянные настройки устройства

HID-устройства — это не только клавиатуры и мыши. Сюда входят ключи безопасности, датчики, пульты, вендорные инструменты, промышленные устройства, игровые контроллеры, UPS и кастомные интерфейсы конфигурации. Многие из этих устройств используют HID Feature Reports для конфигурации и статуса. Когда Feature Reports сбоят, пользователи ищут «HID Feature Report not working», «GET_REPORT failed», «SET_REPORT failed», «HID report ID mismatch», «USB HID vendor command timeout», потому что обычный ввод может работать, а конфигурация — нет.

Bus Scope полезен тем, что Feature Reports часто идут через endpoint 0 как управляющие передачи. Важны setup-пакет, тип репорта, report ID, длина и статус ответа.

Что такое Feature Reports

В HID есть несколько типов репортов:

• Input reports
• Output reports
• Feature reports

Input reports часто приходят на interrupt IN-конечные точки. Feature reports обычно запрашиваются управляющими передачами с GET_REPORT или SET_REPORT.

Если кнопки устройства работают, а панель настроек нет, проблема может быть в обработке Feature Reports.

Несовпадение Report ID и длины

Многие HID-устройства используют report IDs. Если хост включает report ID 3, а прошивка ждёт 0, запрос может упасть или вернуть неверные данные.

Частые баги:

• Прошивка опускает байт report ID.
• Хост шлёт неверную длину репорта.
• Дескриптор объявляет одну длину, прошивка возвращает другую.
• Feature report есть в прошивке, но не в дескрипторе.
• Дескриптор объявляет репорт, который прошивка никогда не реализует.

HID report descriptor и управляющую передачу нужно сравнивать.

Доказательства GET_REPORT и SET_REPORT

Ищите:

• request type setup-пакета.
• HID GET_REPORT или SET_REPORT.
• Report type Feature.
• Report ID.
• wLength.
• Байты data-стадии.
• STALL или тайм-аут.

Если устройство ставит stall на Feature Report, который заявлен в дескрипторе, подозревается несогласованность прошивки или дескриптора.

Вендорная конфигурация через HID

Многие продукты используют HID потому что он избегает кастомных kernel-драйверов. Вендорные настройки могут быть реализованы как Feature Reports.

Примеры:

• Сменить sample rate.
• Прочитать версию прошивки.
• Установить режим LED.
• Сконфигурировать диапазон датчика.
• Включить загрузчик.
• Прочитать калибровочные данные.

Если эти команды падают, устройство всё равно может выглядеть валидным HID.

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

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

1. Захватите перечисление и HID-дескриптор.
2. Сохраните HID report descriptor.
3. Определите объявления Feature Report.
4. Захватите сбойный GET_REPORT или SET_REPORT.
5. Проверьте report ID.
6. Проверьте запрошенную длину.
7. Сравните длину дескриптора с длиной передачи.
8. Ищите STALL, тайм-аут или короткий ответ.
9. Сравните работающие input-репорты со сбойными feature-репортами.
10. Сохраните дескриптор и управляющую передачу вместе.

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

Сбои HID Feature Report обычно в дескрипторе, report ID, длине, состоянии прошивки или обработке управляющей передачи. Input может работать, а конфигурация — нет.

Bus Scope помогает показать контракт HID-репорта и конкретную сбойную управляющую передачу, превращая баги Feature Reports из загадочных ошибок вендорного инструмента в диагностируемые случаи.