2026-06-02

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

Como diagnosticar erros de descritor de relatório HID que fazem um dispositivo USB enumerar com sucesso, mas se comportar de forma errada no host.

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.

Teste do contrato USB para “Depuração de descritor de relatório HID: por que o dispositivo enumera, mas o host lê dados errados”

A resposta direta é que STALL, timeout ou reset não explica sozinho a causa. Primeiro prove que o provider vê o device correto; depois leia o contrato do transfer: tipo, direção, recipient, wValue, wIndex, comprimento declarado e real, status e estado anterior e posterior. Ligue a conclusão à primeira transação diferente do caso bom.

Limite	Comparação	Decisão
Plataforma	provider, permissão, Root Hub ou usbmon/XHC20	Os records são da conexão correta?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	O host enviou o pedido esperado?
Data	direção, comprimento e bytes retidos	O payload cumpre o contrato?
Status	ACK, STALL, timeout ou cancellation	Onde a transação termina?
Estado	configuration, interface, alternate setting, halt	O device estava pronto?

Comece antes de reset e enumeration e preserve descriptors, SET_CONFIGURATION, SET_INTERFACE e o command anterior à falha. Filtro estreito pode esconder o control transfer decisivo. Execute uma ação USB por teste e altere apenas firmware, driver, porta, cabo, comando ou timing.

Como escrever resposta citável?

Informe request, campos setup, resposta e contexto anterior; depois proponha teste com uma variável. Bytes não retidos não provam packet loss. Proximidade entre command e reset mostra correlação, não causa sem repetição ou mudança de estado.

Mantenha VID/PID, firmware, speed, topologia, provider, filtro e trigger. Compare fases USB semânticas, não frame numbers entre usbmon e USBPcap. Registre início, fim, versão, OS, conexão e checksum. Consulte o troubleshooting Bus Scope.

Os owners Semrush continuam separados: free USB analyzer na página do produto, best USB protocol analyzer na comparação e USB descriptor viewer no guia descriptor. Não invente volume ou KD.

Resposta direta e limite de aceitação

A resposta curta para “Depuração de descritor de relatório HID: por que o dispositivo enumera, mas o host lê dados errados” é: Como diagnosticar erros de descritor de relatório HID que fazem um dispositivo USB enumerar com sucesso, mas se comportar de forma errada no host. Trate essa frase como um resultado a verificar, não como promessa para qualquer entrada, dispositivo, projeto ou ambiente. Um resultado completo registra estado inicial, ação exata, saída visível e condição que comprova a conclusão da tarefa no Bus Scope.

Procedimento orientado por evidências

Comece com um caso pequeno e repetível antes de alterar um projeto completo. Registre versão do aplicativo, sistema operacional, identidade da entrada ou dispositivo, configurações relevantes e resultado esperado. Execute uma ação deliberada, preserve a primeira transição inesperada e compare com um caso conhecido quando possível. Alterar vários controles ao mesmo tempo esconde qual condição criou ou corrigiu o problema.

Ponto de controle 1: Depuração de descritor de relatório HID: por que o dispositivo enumera, mas o host lê dado

Verifique “Depuração de descritor de relatório HID: por que o dispositivo enumera, mas o host lê dados errados” com a menor entrada representativa. Mantenha configurações não relacionadas, repita a mesma ação e confira o resultado após reabrir ou reconectar. Uma captura isolada é mais fraca que um registro com entrada, configuração, ação, saída e horário.

Ponto de controle 2: Como diagnosticar erros de descritor de relatório HID que fazem um dispositivo USB enumera

Quando “Como diagnosticar erros de descritor de relatório HID que fazem um dispositivo USB enumerar com sucesso, mas se comportar de forma errada no host.” for ambíguo, compare um caso bom e outro falho sob condições equivalentes. Marque a primeira diferença significativa, não todos os sintomas posteriores. Esse limite costuma produzir uma solicitação de suporte mais clara e um experimento mais seguro.

Ponto de controle 3: O descritor de relatório define o contrato de dados

Verifique “O descritor de relatório define o contrato de dados” com a menor entrada representativa. Mantenha configurações não relacionadas, repita a mesma ação e confira o resultado após reabrir ou reconectar. Uma captura isolada é mais fraca que um registro com entrada, configuração, ação, saída e horário.

Ponto de controle 4: Capture o descritor e os relatórios juntos

Quando “Capture o descritor e os relatórios juntos” for ambíguo, compare um caso bom e outro falho sob condições equivalentes. Marque a primeira diferença significativa, não todos os sintomas posteriores. Esse limite costuma produzir uma solicitação de suporte mais clara e um experimento mais seguro.

Ponto de controle 5: O comportamento do host pode estar certo mesmo quando parece errado

Verifique “O comportamento do host pode estar certo mesmo quando parece errado” com a menor entrada representativa. Mantenha configurações não relacionadas, repita a mesma ação e confira o resultado após reabrir ou reconectar. Uma captura isolada é mais fraca que um registro com entrada, configuração, ação, saída e horário.

Ponto de controle 6: Dispositivos HID compostos pedem cuidado extra

Quando “Dispositivos HID compostos pedem cuidado extra” for ambíguo, compare um caso bom e outro falho sob condições equivalentes. Marque a primeira diferença significativa, não todos os sintomas posteriores. Esse limite costuma produzir uma solicitação de suporte mais clara e um experimento mais seguro.

Ponto de controle 7: Onde o Bus Scope entra

Verifique “Onde o Bus Scope entra” com a menor entrada representativa. Mantenha configurações não relacionadas, repita a mesma ação e confira o resultado após reabrir ou reconectar. Uma captura isolada é mais fraca que um registro com entrada, configuração, ação, saída e horário.

Ponto de controle 8: Teste do contrato USB para “Depuração de descritor de relatório HID: por que o dispositivo

Quando “Teste do contrato USB para “Depuração de descritor de relatório HID: por que o dispositivo enumera, mas o host lê dados errados”” for ambíguo, compare um caso bom e outro falho sob condições equivalentes. Marque a primeira diferença significativa, não todos os sintomas posteriores. Esse limite costuma produzir uma solicitação de suporte mais clara e um experimento mais seguro.

Ponto de controle 9: Como escrever resposta citável?

Verifique “Como escrever resposta citável?” com a menor entrada representativa. Mantenha configurações não relacionadas, repita a mesma ação e confira o resultado após reabrir ou reconectar. Uma captura isolada é mais fraca que um registro com entrada, configuração, ação, saída e horário.

Ponto de controle 10: o firmware envia 8 bytes, mas o descritor descreve 7

Quando “o firmware envia 8 bytes, mas o descritor descreve 7” for ambíguo, compare um caso bom e outro falho sob condições equivalentes. Marque a primeira diferença significativa, não todos os sintomas posteriores. Esse limite costuma produzir uma solicitação de suporte mais clara e um experimento mais seguro.

Matriz de aceitação

Ponto	Evidência a manter	Condição de aprovação
Depuração de descritor de relatório HID: por que o dispositivo enumera, mas o host lê dados errados	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Como diagnosticar erros de descritor de relatório HID que fazem um dispositivo USB enumerar com sucesso, mas se comporta	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
O descritor de relatório define o contrato de dados	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Capture o descritor e os relatórios juntos	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
O comportamento do host pode estar certo mesmo quando parece errado	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Dispositivos HID compostos pedem cuidado extra	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado

Isolamento, recuperação e entrega

Pare no primeiro limite que falhar. Preserve fonte, projeto, sessão ou captura, duplique antes de edição destrutiva e altere uma variável por experimento. Repetir um fluxo amplo depois de várias mudanças pode gerar outro resultado sem explicar o motivo.

Separe ausência de evidência de evidência de ausência. Uma tela vazia pode indicar entrada, escopo, filtro, permissão, dispositivo, intervalo ou estado incorreto. Verifique aquisição ou importação antes de interpretar decoder, editor, relatório ou exportação.

Antes da entrega, reabra o artefato e examine início, ponto de decisão e final. Registre versão, plataforma, configuração, expectativa, observação e reprodução mínima. Remova ou oculte dados sensíveis e confirme a autorização do destinatário.

Perguntas e respostas

Qual é a maneira confiável mais rápida de começar?

Use o menor caso representativo, escreva o resultado esperado e altere uma variável. Confirme o caminho básico antes de adicionar filtros, efeitos, edições, automação ou uma fonte maior.

Quais evidências devem ser salvas?

Mantenha identidade da entrada, versão, plataforma, configurações, ação exata, primeira transição inesperada e saída final. Feche e reabra projeto, sessão, relatório ou exportação antes de tratá-lo como durável.

Quando o procedimento deve ser repetido?

Repita após mudanças relevantes no aplicativo, sistema, driver, firmware, modelo, fonte ou fluxo. Preserve o caso aceito anterior como referência sem alterações.

Quando a tarefa está pronta para entrega?

Quando outra pessoa autorizada identifica a entrada, repete a ação, vê o mesmo resultado, entende os limites restantes e abre o artefato sem depender de estado local não documentado.

Guias relacionados

Estas páginas no mesmo idioma cobrem etapas próximas sem alterar o proprietário canônico deste assunto: