2026-06-02

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

Como diagnosticar descritores BOS, descritores Microsoft OS, WCID, driver binding automático do WinUSB, landing pages WebUSB, stalls de descritor e comportamento de enumeração 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:

Capture desde a conexão.
Preserve os descritores de device, configuration, interface, endpoint e BOS.
Procure requisições de descritor Microsoft OS.
Decodifique o vendor code e o tamanho do descritor.
Confira os números de interface nos dados do descritor.
Verifique valores de compatible ID como WINUSB.
Confira se requisições não suportadas travam corretamente.
Compare o comportamento de enumeração no Windows e no Linux.
Confira o vínculo no Gerenciador de Dispositivos depois da enumeração.
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.

Teste do contrato USB para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows”

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 descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows” é: Como diagnosticar descritores BOS, descritores Microsoft OS, WCID, driver binding automático do WinUSB, landing pages WebUSB, stalls de descritor e comportamento de enumeração no Windows. 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 descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no

Trate “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows” como uma etapa de aceitação separada para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 2: Como diagnosticar descritores BOS, descritores Microsoft OS, WCID, driver binding automáti

Converta “Como diagnosticar descritores BOS, descritores Microsoft OS, WCID, driver binding automático do WinUSB, landing pages WebUSB, stalls de descritor e co” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 3: O que é o descritor BOS

Trate “O que é o descritor BOS” como uma etapa de aceitação separada para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 4: Descritores Microsoft OS e WinUSB

Converta “Descritores Microsoft OS e WinUSB” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 5: WebUSB

Trate “WebUSB” como uma etapa de aceitação separada para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 6: Comportamento de STALL válido

Converta “Comportamento de STALL válido” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 7: Complicações em dispositivo composto

Trate “Complicações em dispositivo composto” como uma etapa de aceitação separada para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 8: Checklist de depuração

Converta “Checklist de depuração” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 9: Diagnóstico final

Trate “Diagnóstico final” como uma etapa de aceitação separada para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 10: Teste do contrato USB para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinU

Converta “Teste do contrato USB para “Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows”” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Matriz de aceitação

Ponto	Evidência a manter	Condição de aprovação
Depuração de descritor BOS e Microsoft OS no USB: WebUSB, WinUSB, WCID e driver binding no Windows	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Como diagnosticar descritores BOS, descritores Microsoft OS, WCID, driver binding automático do WinUSB, landing pages We	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
O que é o descritor BOS	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Descritores Microsoft OS e WinUSB	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
WebUSB	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Comportamento de STALL válido	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: