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

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 é:

1. inspecionar a árvore decodificada do descritor
2. saltar para os bytes brutos quando algum campo parecer suspeito
3. comparar as requisições do host com as respostas do firmware
4. inspecionar as transferências de endpoint após a configuração
5. 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.