Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows

Dispositivos USB modernos geralmente dependem de descritores além do device descriptor e configuration descriptor básicos. Descritores BOS, descritores Microsoft OS, descritores WCID, platform capabilities de WebUSB e compatible IDs de WinUSB controlam como o Windows vincula drivers e como browsers ou ferramentas descobrem capacidades do dispositivo. Quando esses descritores estão errados, a busca é por "WinUSB driver not binding", "WebUSB device not found", "USB BOS descriptor failed", "Microsoft OS descriptor invalid" ou "device works on Linux but not Windows".

O Bus Scope ajuda porque problemas orientados a descritor acontecem durante a enumeração. Se você não captura as requisições de descritor, talvez veja apenas o sintoma final no Gerenciador de Dispositivos ou na aplicação.

O que é o descritor BOS

BOS significa Binary Object Store. Ele permite que um dispositivo USB anuncie platform capabilities e informações adicionais a nível de dispositivo. Para dispositivos modernos, o BOS pode incluir capabilities para:

• USB 2.0 extension
• SuperSpeed capability
• WebUSB platform capability
• Microsoft OS 2.0 platform capability

Se o descritor BOS estiver malformado, o Windows ou ferramentas baseadas em browser podem ignorar features ou reprovar a validação.

Descritores Microsoft OS e WinUSB

Descritores Microsoft OS podem ajudar o Windows a vincular o WinUSB automaticamente, sem INF customizado, em alguns cenários. Tanto descritores antigos estilo WCID quanto os novos Microsoft OS 2.0 aparecem em dispositivos reais.

Evidências importantes:

• Requisição do descritor de string de índice 0xEE em fluxos antigos.
• Vendor code usado para requisitar descritores de SO.
• Compatible ID como WINUSB.
• Extended properties.
• Associação com número de interface.
• Se o dispositivo trava corretamente requisições não suportadas.

Se o firmware devolve dado malformado, o Windows pode não vincular o WinUSB mesmo com o dispositivo enumerando.

WebUSB

WebUSB usa platform capability descriptors dentro do BOS para anunciar uma landing page e a capacidade de acesso pelo browser. Se a entrada do BOS estiver errada, o browser pode não expor o dispositivo como esperado.

Sintomas:

• O browser não encontra o dispositivo.
• O dispositivo aparece no SO, mas não no seletor WebUSB.
• A URL da landing page está faltando ou errada.
• O dispositivo funciona com a ferramenta nativa, mas não com a ferramenta web.

O trace do barramento pode mostrar se o host pediu o BOS e o que o dispositivo devolveu.

Comportamento de STALL válido

Para alguns mecanismos opcionais de descritor Microsoft, um dispositivo que não suporta a feature deve travar a requisição. Um STALL nem sempre é bug. O bug é devolver dados de descritor inválidos, ou declarar suporte e depois falhar a requisição subsequente.

É por isso que o contexto da transferência de controle importa.

Complicações em dispositivo composto

Descritores Microsoft OS geralmente miram uma interface específica. Dispositivos compostos podem falhar se o descritor aponta para o número de interface errado ou se o Windows vincula só parte do dispositivo.

Inspecione:

• Números de interface.
• Interface Association Descriptors.
• Seções de Compatible ID.
• Function subset headers.
• Se o WinUSB é para uma interface ou para todas.

Checklist de depuração

Use este fluxo:

1. Capture desde a conexão.
2. Preserve os descritores de device, configuration, interface, endpoint e BOS.
3. Procure requisições de descritor Microsoft OS.
4. Decodifique o vendor code e o tamanho do descritor.
5. Confira os números de interface nos dados do descritor.
6. Verifique valores de compatible ID como WINUSB.
7. Confira se requisições não suportadas travam corretamente.
8. Compare o comportamento de enumeração no Windows e no Linux.
9. Confira o vínculo no Gerenciador de Dispositivos depois da enumeração.
10. Preserve os bytes do descritor para depuração de firmware.

Diagnóstico final

Falhas de descritor BOS e Microsoft OS no USB são problemas de contrato de descritor. O dispositivo pode enumerar, mas mesmo assim falhar em WinUSB, WebUSB ou driver binding específico por interface, porque descritores opcionais estão malformados, faltando ou mapeados para a interface errada.

O Bus Scope ajuda mostrando a enumeração e as requisições de descritor diretamente, para que falhas de driver binding possam ser depuradas a partir da evidência USB em vez de só pelos sintomas no SO.