Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando

Dispositivos HID não são só teclados e mouses. Incluem chaves de segurança, sensores, painéis de controle, ferramentas vendor, dispositivos industriais, controles, nobreaks e interfaces de configuração customizadas. Muitos desses dispositivos usam HID Feature Reports para configuração e status. Quando os Feature Reports falham, a busca costuma ser por "HID Feature Report not working", "GET_REPORT failed", "SET_REPORT failed", "HID report ID mismatch" e "USB HID vendor command timeout" porque a entrada normal pode funcionar enquanto a configuração não.

O Bus Scope ajuda porque Feature Reports geralmente trafegam pelo endpoint zero como transferências de controle. Importam o pacote de setup, o report type, o report ID, o tamanho e o status de resposta.

O que são Feature Reports

HID tem vários tipos de relatório:

• Input reports
• Output reports
• Feature reports

Input reports geralmente chegam pelos endpoints interrupt IN. Feature reports são normalmente solicitados com transferências de controle usando GET_REPORT ou SET_REPORT.

Se os botões de um dispositivo funcionam, mas o painel de configuração falha, o tratamento de Feature Report pode ser o motivo.

Incompatibilidades de Report ID e tamanho

Muitos dispositivos HID usam report IDs. Se o host inclui report ID 3 e o firmware espera report ID 0, a requisição pode falhar ou devolver dados errados.

Bugs comuns:

• Firmware omite o byte de report ID.
• Host envia o tamanho errado do relatório.
• Descritor declara um tamanho, firmware devolve outro.
• Feature report existe no firmware, mas não no descritor.
• Descritor declara relatório que o firmware nunca implementa.

O descritor de relatório HID e a transferência de controle precisam ser comparados.

Evidência em GET_REPORT e SET_REPORT

Procure por:

• request type do pacote de setup.
• HID GET_REPORT ou SET_REPORT.
• Report type Feature.
• Report ID.
• wLength.
• Bytes do data stage.
• STALL ou timeout.

Se o dispositivo trava um Feature Report que o descritor anuncia, a consistência entre firmware e descritor é a suspeita.

Configuração vendor via HID

Muitos produtos usam HID justamente para evitar drivers customizados no kernel. Configurações vendor podem ser implementadas como Feature Reports.

Exemplos:

• Mudar a taxa de amostragem.
• Ler a versão de firmware.
• Definir o modo de LED.
• Configurar a faixa do sensor.
• Habilitar o bootloader.
• Ler dados de calibração.

Se esses comandos falham, o dispositivo ainda pode aparecer como um HID válido.

Checklist de depuração

Use este processo:

1. Capture a enumeração e o descritor HID.
2. Salve o descritor de relatório HID.
3. Identifique as definições de Feature Report.
4. Capture o GET_REPORT ou SET_REPORT que falhou.
5. Confira o report ID.
6. Confira o tamanho requisitado.
7. Compare o tamanho do descritor com o tamanho da transferência.
8. Procure STALL, timeout ou resposta curta.
9. Compare os input reports que funcionam com os feature reports que falham.
10. Preserve descritor e transferência de controle juntos.

Diagnóstico final

Falhas em HID Feature Report geralmente são problemas de descritor, report ID, tamanho, estado do firmware ou tratamento da transferência de controle. A entrada pode funcionar enquanto a configuração falha.

O Bus Scope ajuda a expor o contrato de relatório HID e a transferência de controle exata que falhou, tornando bugs de Feature Report diagnosticáveis em vez de erros misteriosos da ferramenta vendor.