Depuração de Device Qualifier e Other Speed Configuration em USB: problemas de descritor entre high-speed e full-speed

Dispositivos USB que suportam tanto full-speed quanto high-speed precisam descrever como se comportam na outra velocidade. Buscas como "USB Device Qualifier descriptor", "Other Speed Configuration descriptor", "high speed device enumerates as full speed", "USB descriptor mismatch" e "device works on USB 2.0 but fails on hub" acontecem quando o mesmo produto se comporta de forma diferente dependendo da porta, do cabo, do hub ou do host controller.

O Bus Scope ajuda porque o diagnóstico exige comparar requisições de descritor, velocidade real, packet sizes de endpoint, descritores de configuração e decisões do host durante a enumeração.

O que é o descritor Device Qualifier

O descritor Device Qualifier descreve como um dispositivo capaz de high-speed se comportaria na outra velocidade. Se o dispositivo está em high-speed, o qualifier diz ao host sobre o comportamento em full-speed. Se está em full-speed, pode descrever a capacidade de high-speed.

Campos importantes:

• Versão de USB.
• Classe do dispositivo.
• Subclasse.
• Protocolo.
• Max packet size do endpoint zero.
• Número de configurações.

Se esse descritor estiver faltando, malformado ou inconsistente, a enumeração pode passar em um host e falhar em outro.

Other Speed Configuration

O descritor Other Speed Configuration descreve os detalhes da configuração na velocidade oposta. Packet sizes de endpoint, polling intervals e suposições de bandwidth podem mudar.

Padrões comuns de falha:

• A configuração em full-speed anuncia packet sizes de endpoint que só fazem sentido em high-speed.
• A configuração em high-speed esquece uma interface.
• A contagem de descritores other-speed não bate com a configuração real.
• Firmware devolve um STALL quando o host espera um descritor.
• Host aceita o dispositivo, mas vincula o driver errado.
• Dispositivo funciona em um hub e falha em outro.

Esses problemas são difíceis de ver pelos logs da aplicação.

Dispositivo high-speed enumera como full-speed

Um caso frequente de suporte é "USB high-speed device detected as full-speed". Isso pode ser causado por qualidade de cabo, topologia de hub, integridade de sinal, comportamento de chirp do firmware, design elétrico ou problemas de descritor.

Evidência de pacote ajuda a separar as camadas:

• A negociação de high-speed aconteceu?
• O host pediu o Device Qualifier?
• O dispositivo devolveu bytes válidos de descritor?
• Os endpoint descriptors bateram com a velocidade selecionada?
• O host resetou e tentou de novo?
• O dispositivo reenumerou depois em outra velocidade?

Se o trace mostra que o dispositivo nunca chegou a high-speed, correções de descritor podem não bastar. Se o trace mostra enumeração em high-speed, mas outros descritores other-speed inválidos, o firmware é o suspeito mais forte.

Mismatch de max packet size entre velocidades

Os endpoint descriptors podem mudar entre full-speed e high-speed. Um endpoint bulk pode ser 64 bytes em full-speed e 512 bytes em high-speed.

Sintomas de falha:

• Transferências falham só em portas high-speed.
• Transferências falham só via um hub full-speed antigo.
• Buffer do firmware combina com uma velocidade, mas o descritor anuncia outra.
• Driver de host manda transferências maiores do que o firmware esperava.
• Dispositivo devolve short packets em fronteiras inesperadas.

Isso se conecta diretamente à depuração de wMaxPacketSize.

Dispositivos compostos

Dispositivos compostos tornam os descritores other-speed mais frágeis. Um dispositivo pode expor HID, CDC, vendor-specific, mass storage e interfaces de update de firmware. A árvore other-speed precisa permanecer consistente.

Bugs comuns:

• Interface Association Descriptor faltando em uma das velocidades.
• Números de interface diferentes entre as velocidades.
• Endereços de endpoint mudando sem aviso.
• Uma interface com other-speed descriptor válido e outra sem.
• Windows vinculando um driver diferente depois de reenumeração.

Para produtos com firmware custom, esse é um erro clássico de copiar e colar.

STALL pode ser válido ou suspeito

Algumas requisições de descritor podem legitimamente travar em dispositivos que não suportam a capacidade pedida. Mas, em dispositivos com capacidade de high-speed, falhas repetidas em torno de Device Qualifier ou Other Speed Configuration merecem atenção.

O relatório deve preservar:

• request type.
• descriptor type.
• wValue.
• wIndex.
• wLength.
• Dados devolvidos.
• Status de STALL ou timeout.

O Bus Scope deve tornar essas control transfers legíveis em vez de obrigar o engenheiro a decodificar bytes brutos manualmente.

Checklist de depuração

Use este fluxo:

1. Capture desde a conexão física.
2. Registre a velocidade real negociada.
3. Inspecione o Device Descriptor.
4. Inspecione o descritor Device Qualifier.
5. Inspecione o descritor Other Speed Configuration.
6. Compare packet sizes dos endpoints entre as velocidades.
7. Confira os números de interface e os endereços de endpoint.
8. Teste porta direta, hub e dock USB-C.
9. Compare o comportamento de enumeração entre Windows e Linux.
10. Preserve falhas e retries de requisição de descritor.

Diagnóstico final

Bugs em Device Qualifier e Other Speed Configuration em USB são problemas de consistência de descritor. Eles explicam por que um dispositivo pode funcionar em uma velocidade e falhar em outra, ou se comportar diferente atrás de hubs e docks.

O Bus Scope ajuda a capturar a evidência exata da enumeração: requisições de descritor, bytes other-speed, tamanhos de endpoint, STALLs, resets e consequências no vínculo de driver.