Depuração de dispositivo composto USB: números de interface, IAD, endpoints e vínculo de driver
Como depurar dispositivos compostos USB quando uma interface funciona, outra falha, ou o host vincula o driver errado. Cobre descritor de configuração, IAD, colisão de endpoints e ordem de declaração.
Dispositivos compostos USB são práticos e perigosos ao mesmo tempo. Um único dispositivo pode expor controles HID, serial CDC, armazenamento em massa, endpoints vendor, áudio, vídeo ou interfaces de diagnóstico. Quando tudo está descrito corretamente, o host vincula os drivers certos e cada função funciona. Quando um campo de descritor está errado, o dispositivo inteiro pode parecer instável.
Buscas como "USB composite device not recognized", "CDC interface not showing", "HID works but serial does not" ou "wrong driver binding USB interface" normalmente apontam para estrutura de descritor, numeração de interface, atribuição de endpoint ou comportamento do Interface Association Descriptor.
Dispositivo composto exige uma configuração coerente
O descritor de configuração é o mapa de nível superior. Ele precisa descrever o comprimento total, a quantidade de interfaces, os atributos de energia e todos os descritores aninhados de interface e endpoint. Se o wTotalLength estiver errado, o host pode não ler todas as funções. Se a contagem de interfaces estiver errada, o host pode ignorar as últimas. Se os endereços de endpoint colidirem, as transferências ficam ambíguas ou inválidas.
Inspecione:
- comprimento total da configuração
- quantidade de interfaces
- números de interface
- alternate settings
- endereços de endpoint
- direções de endpoint
- classe, subclasse e protocolo
- ordem dos descritores
A captura deve mostrar se o host pediu a configuração inteira e quais bytes o dispositivo devolveu.
IAD ajuda a agrupar interfaces relacionadas
Interface Association Descriptors são usados para agrupar várias interfaces que pertencem a uma mesma função, como comunicação CDC mais dados CDC. Sem o agrupamento correto, o host pode vincular drivers errados ou expor só parte da função.
Evidências de IAD para inspecionar:
- número da primeira interface
- quantidade de interfaces
- classe, subclasse e protocolo da função
- posicionamento antes das interfaces agrupadas
- coerência com os descritores de interface efetivos
Se o CDC serial não aparece, mas o HID funciona, a interface HID pode estar correta enquanto o agrupamento CDC está errado.
Colisão de endereço de endpoint passa despercebida com facilidade
Endereços de endpoint incluem direção. Endpoint 0x81 e 0x01 são direções diferentes, mas dois endpoints IN com o mesmo endereço não são válidos dentro da mesma configuração de dispositivo. Equipes de firmware às vezes copiam descritores de endpoint entre interfaces e esquecem de atualizar os endereços.
Sintomas comuns:
- uma interface funciona, outra fica muda
- o host manda transferências para o endpoint errado
- o driver de classe carrega, mas a aplicação não recebe dados
- STALL ou timeout no endpoint depois da configuração
- só uma função funciona por vez
A captura deve mostrar os descritores de endpoint e o tráfego de transferência lado a lado.
Vínculo de driver também é evidência
O host escolhe os drivers com base nos descritores. Um dispositivo que vincula errado pode ter evidência nos descritores que explica o motivo. Classe, subclasse, protocolo, interface association, compatible IDs e descritores específicos de SO podem afetar o vínculo.
Não diagnostique o vínculo de driver apenas pelo Gerenciador de Dispositivos ou por logs da aplicação. Compare as requisições de classe do host com a árvore de descritores. Se as requisições de classe esperadas nunca chegam, provavelmente o host não vinculou o driver esperado.
Onde o Bus Scope entra
O Bus Scope ajuda equipes de firmware a inspecionar dispositivos compostos nos dois níveis:
- mapa de descritores
- evidência de transferência depois do vínculo de driver
Uma boa sessão .bscope para depurar dispositivo composto mostra:
- todas as interfaces
- agrupamento por IAD
- atribuição de endpoints
- requisições de classe por interface
- bytes brutos dos descritores
- status das transferências após a configuração
Isso torna a conversa de suporte específica. Em vez de "o Windows não está gostando do nosso dispositivo composto", o relatório pode dizer "a interface 2 nunca recebe requisições de classe CDC porque o descritor de agrupamento não combina com o layout declarado".
Esse é o nível de evidência que a equipe de firmware precisa.