2026-06-02

Depuração de descritores USB em dispositivos HID e CDC: o contrato entre firmware e host

Como equipes de firmware diagnosticam dispositivos USB HID e CDC inspecionando descritores e transferências em vez de adivinhar a partir de erros do driver. Cobrimos descritor de relatório HID, descritores CDC, ACM e evidências de transferências.

Dispositivos HID e CDC são populares porque permitem que equipes de firmware entreguem interfaces USB úteis sem precisar escrever um driver dedicado para cada host. Essa conveniência depende de descritores bem escritos. Quando um teclado HID, sensor, ponte serial ou dispositivo composto falha, a causa raiz costuma estar na evidência dos descritores antes de aparecer no aplicativo.

Depurar descritores não é glamouroso, mas é um dos caminhos mais rápidos para fechar casos de suporte USB.

HID: o descritor de relatório é o contrato

Para dispositivos HID, o host precisa de mais do que as informações de endpoint. Ele precisa do descritor de relatório HID. Esse descritor define IDs de relatório, usages, tamanhos, contagens, faixas lógicas e a forma de interpretar cada byte.

Erros comuns em HID incluem:

tamanho do relatório não bate com o payload real do endpoint de interrupção
report ID é usado no firmware, mas não declarado de forma consistente
logical min e logical max não combinam com a representação dos dados
usage page ou usage não bate com a expectativa do host
bInterval do endpoint incompatível com o comportamento do dispositivo
suposição de boot protocol conflitando com o comportamento em report protocol

Um erro de host pode parecer vago. Uma captura que mostre os bytes do descritor e as transferências de interrupção pode tornar a divergência óbvia.

CDC: o layout de interface importa

Dispositivos CDC ACM costumam expor uma interface de comunicação e uma interface de dados. O host espera um conjunto coerente de descritores e requisições de classe. Um descritor funcional faltando, um erro de interface association ou um endpoint errado podem impedir que a porta serial virtual apareça.

Evidências para inspecionar:

classe e subclasse da interface
descritores CDC Header, ACM, Union e Call Management
endpoint de notificação
endpoints bulk IN e OUT
SET_LINE_CODING
SET_CONTROL_LINE_STATE
transferências de dados após a configuração

Se a porta serial aparece, mas nenhum byte trafega, o problema provavelmente é o endpoint ou o protocolo da aplicação. Se a porta serial nunca aparece, o primeiro lugar para olhar são os descritores e as requisições de classe.

Dispositivos compostos exigem disciplina extra

Dispositivos compostos podem combinar HID, CDC, armazenamento em massa, interfaces específicas do fabricante e muito mais. Isso é útil, mas multiplica os modos de falha. Um erro de descritor em uma única interface pode quebrar o vínculo com o driver para o dispositivo inteiro.

Para depurar dispositivos compostos, inspecione:

comprimento total da configuração
números de interface
descritores de Interface Association
unicidade dos endpoints
posicionamento dos descritores específicos de classe
requisições do host por interface

Não presuma que "o firmware envia os bytes certos" até a captura provar que o host viu a estrutura certa.

Por que os bytes brutos e a interpretação de classe importam juntos

Os bytes brutos são a verdade absoluta. A interpretação de classe é o que torna eles utilizáveis. Uma boa ferramenta de diagnóstico USB precisa mostrar os dois. O engenheiro precisa ver os bytes exatos do descritor quando algo dá errado, mas também precisa dos campos decodificados para não contar offsets à mão a cada caso.

O melhor fluxo de trabalho é:

inspecionar a árvore decodificada do descritor
saltar para os bytes brutos quando algum campo parecer suspeito
comparar as requisições do host com as respostas do firmware
inspecionar as transferências de endpoint após a configuração
salvar a sessão para reproduzir o caso ou passar adiante

Esse fluxo mantém o diagnóstico amarrado à evidência.

Onde o Bus Scope entra

O Bus Scope foi feito para equipes de firmware, laboratórios de hardware e fornecedores de dispositivos que precisam de uma resposta repetível para o motivo de uma falha USB. Ele reúne em uma bancada o contexto do device explorer, o detalhe de pacotes, os bytes brutos, os descritores, as observações de classe, os filtros e as sessões .bscope.

Para casos com HID e CDC, o Bus Scope deve ajudar a responder:

a enumeração terminou?
os descritores bateram com a classe pretendida?
o host enviou as requisições de classe esperadas?
as transferências de endpoint casaram com o que o relatório ou o line coding esperava?
isso é problema de firmware, de driver de host ou de protocolo da aplicação?

Essa é a diferença entre ver "driver falhou" e entender qual contrato USB foi quebrado.

Teste do contrato USB para “Depuração de descritores USB em dispositivos HID e CDC: o contrato entre firmware e host”

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 descritores USB em dispositivos HID e CDC: o contrato entre firmware e host” é: Como equipes de firmware diagnosticam dispositivos USB HID e CDC inspecionando descritores e transferências em vez de adivinhar a partir de erros do driver. Cobrimos descritor de relatório HID, descritores CDC, ACM e evidências de transferências. 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 descritores USB em dispositivos HID e CDC: o contrato entre firmware e host

Quando “Depuração de descritores USB em dispositivos HID e CDC: o contrato entre firmware e 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 2: Como equipes de firmware diagnosticam dispositivos USB HID e CDC inspecionando descritores

Verifique “Como equipes de firmware diagnosticam dispositivos USB HID e CDC inspecionando descritores e transferências em vez de adivinhar a partir de erros do d” 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 3: HID: o descritor de relatório é o contrato

Quando “HID: o descritor de relatório é o contrato” 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 4: CDC: o layout de interface importa

Verifique “CDC: o layout de interface importa” 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 5: Dispositivos compostos exigem disciplina extra

Quando “Dispositivos compostos exigem disciplina 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 6: Por que os bytes brutos e a interpretação de classe importam juntos

Verifique “Por que os bytes brutos e a interpretação de classe importam juntos” 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 7: Onde o Bus Scope entra

Quando “Onde o Bus Scope entra” 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 8: Teste do contrato USB para “Depuração de descritores USB em dispositivos HID e CDC: o cont

Verifique “Teste do contrato USB para “Depuração de descritores USB em dispositivos HID e CDC: o contrato entre firmware e host”” 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 9: Como escrever resposta citável?

Quando “Como escrever resposta citável?” 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 10: tamanho do relatório não bate com o payload real do endpoint de interrupção

Verifique “tamanho do relatório não bate com o payload real do endpoint de interrupção” 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.

Matriz de aceitação

Ponto	Evidência a manter	Condição de aprovação
Depuração de descritores USB em dispositivos HID e CDC: o contrato entre firmware e host	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Como equipes de firmware diagnosticam dispositivos USB HID e CDC inspecionando descritores e transferências em vez de ad	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
HID: o descritor de relatório é o contrato	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
CDC: o layout de interface importa	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Dispositivos compostos exigem disciplina extra	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Por que os bytes brutos e a interpretação de classe importam juntos	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: