Depuração de descritor de relatório HID: por que o dispositivo enumera, mas o host lê dados errados

HID é atraente porque muitos dispositivos funcionam sem drivers customizados. Teclados, sensores, knobs, leitores de código de barras, painéis de controle e dispositivos HID vendor-specific se beneficiam de uma pilha padrão do host. Mas o HID também empurra a complexidade para o descritor de relatório. Um dispositivo pode enumerar corretamente e mesmo assim enviar dados que o host interpreta errado.

Essa é uma das armadilhas mais comuns de firmware USB: confundir sucesso de enumeração com corretude do HID.

O descritor de relatório define o contrato de dados

O descritor de relatório HID diz ao host como interpretar os bytes. Ele define usages, tamanhos de report, contagens, faixas lógicas, faixas físicas, collections e report IDs. Se o descritor diz uma coisa e o firmware envia outra, o host segue o descritor.

Problemas comuns:

• o firmware envia 8 bytes, mas o descritor descreve 7
• report ID está faltando ou sobrando
• valores signed são descritos como unsigned
• logical min/max não bate com a faixa real
• usage page está errado
• bits de padding são contados errado
• múltiplos relatórios compartilham um layout confuso
• input e output reports se misturam

O sintoma pode aparecer na aplicação como valores errados, botões que não respondem, relatórios ignorados ou leituras intermitentes.

Capture o descritor e os relatórios juntos

Depurar HID só pelo descritor de relatório é incompleto. Depurar só pelos bytes do payload também é incompleto. Você precisa dos dois.

Uma captura útil de HID mostra:

• device descriptor
• configuration e interface descriptors
• HID descriptor
• requisição e resposta do report descriptor
• interrupt IN reports
• interrupt OUT reports, se houver
• control transfers para feature reports
• report IDs e tamanhos de payload

Aí o engenheiro consegue comparar o layout declarado com os bytes reais. Se o descritor diz Report Count 3 e o payload de interrupt traz quatro valores, a captura precisa tornar isso visível.

O comportamento do host pode estar certo mesmo quando parece errado

Desenvolvedores de firmware às vezes acham que o host está perdendo dados. Na verdade, o host pode estar interpretando de acordo com o descritor que recebeu. Se o descritor declara padding ou um report ID diferente, os dados podem aparecer deslocados, truncados ou ignorados.

Por isso um bom relatório de suporte deve incluir os bytes brutos. A interpretação decodificada ajuda, mas os bytes brutos encerram a discussão. As perguntas viram:

• o que o firmware enviou?
• o que o firmware declarou?
• o que o host pediu?
• o que o host recebeu?

Essa é a fronteira certa para a depuração de HID.

Dispositivos HID compostos pedem cuidado extra

Dispositivos compostos podem expor HID junto com CDC, armazenamento ou interfaces vendor-specific. A parte de HID pode estar correta sozinha, mas ser afetada por erros de numeração de interface, atribuição de endpoint ou comprimento total do descritor.

Para depuração de HID composto, inspecione:

• interface association, quando aplicável
• número da interface
• unicidade de endereço de endpoint
• localização do HID descriptor
• comprimento do report descriptor
• roteamento de class-specific requests

Quando o host pede o report descriptor para a interface errada ou recebe o tamanho errado, o tráfego de relatórios posterior fica enganoso.

Onde o Bus Scope entra

O Bus Scope foi feito para equipes de firmware e dispositivos que precisam de uma depuração USB orientada a evidência. Para casos de descritor de relatório HID, ele deve deixar o engenheiro inspecionar a árvore do descritor, os bytes brutos, o tráfego de endpoint e a sessão .bscope salva juntos.

O resultado prático deve ser um relatório que diz:

• o descritor de relatório HID foi pedido e devolvido
• tamanho do relatório declarado pelo descritor
• tamanho efetivo do payload de interrupt
• comportamento de report ID
• divergência ou coerência entre declaração e tráfego
• próxima ação em descritor de firmware, empacotamento de relatório ou expectativas do parser de host

Isso é mais útil do que "dispositivo HID não funciona". Transforma um problema de entrada vago em uma divergência concreta de contrato USB.