2026-06-02

Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows

I dispositivi USB moderni spesso dipendono da descrittori che vanno oltre i descrittori di base del dispositivo e della configurazione.

I dispositivi USB moderni spesso dipendono da descrittori che vanno oltre i descrittori di base del dispositivo e della configurazione. BOS descriptors, Microsoft OS descriptors, WCID descriptors, WebUSB platform capabilities e ID compatibili WinUSB possono determinare come Windows associa i driver e come browser o strumenti rilevano le capacità del dispositivo. Quando questi descrittori sono errati, gli utenti vedono errori come "WinUSB driver not binding", "WebUSB device not found", "USB BOS descriptor failed", "Microsoft OS descriptor invalid" oppure "device works on Linux but not Windows".

Bus Scope è utile perché i problemi guidati dai descrittori avvengono durante l'enumerazione. Se non acquisisci le richieste dei descrittori, potresti vedere solo il sintomo finale in Gestione dispositivi o nell'applicazione.

Che cos'è il descrittore BOS

BOS significa Binary Object Store. Permette a un dispositivo USB di dichiarare capacità di piattaforma e informazioni aggiuntive a livello di dispositivo. Nei dispositivi moderni, BOS può includere capacità per:

estensione USB 2.0
capacità SuperSpeed
WebUSB platform capability
Microsoft OS 2.0 platform capability

Se il descrittore BOS è malformato, Windows o gli strumenti basati su browser possono ignorare le funzionalità o fallire la validazione.

Microsoft OS descriptors e WinUSB

I Microsoft OS descriptors possono aiutare Windows ad associare automaticamente WinUSB senza un INF personalizzato in alcuni casi. Nei dispositivi reali si incontrano sia i vecchi descrittori in stile WCID sia i più recenti Microsoft OS 2.0 descriptors.

Le evidenze importanti includono:

richiesta dello string descriptor index 0xEE nei flussi più vecchi
vendor code usato per richiedere OS descriptors
Compatible ID come WINUSB
extended properties
associazione del numero di interfaccia
se il dispositivo manda correttamente in STALL le richieste di descrittori non supportate

Se il firmware restituisce dati malformati, Windows potrebbe non associare WinUSB anche se il dispositivo viene enumerato.

WebUSB

WebUSB usa BOS platform capability descriptors per dichiarare una landing page e una capacità accessibile dal browser. Se la voce BOS è sbagliata, un browser potrebbe non esporre il dispositivo come previsto.

Sintomi:

il browser non trova il dispositivo
il dispositivo appare nel sistema operativo ma non nel WebUSB chooser
l'URL della landing page manca o è errato
il dispositivo funziona con uno strumento nativo ma non con uno strumento web

La traccia del bus può mostrare se l'host ha richiesto BOS e cosa ha restituito il dispositivo.

Comportamento STALL valido

Per alcuni meccanismi opzionali dei Microsoft descriptor, un dispositivo che non supporta la funzionalità deve mandare la richiesta in STALL. Uno STALL non è sempre un bug. Il bug è restituire dati di descrittore non validi, oppure dichiarare supporto e poi fallire la richiesta successiva.

Per questo il contesto del control transfer è importante.

Complicazioni dei dispositivi composite

I Microsoft OS descriptors spesso puntano a una specifica interfaccia. I dispositivi composite possono fallire se il descrittore indica il numero di interfaccia sbagliato o se Windows associa il driver solo a una parte del dispositivo.

Ispeziona:

numeri di interfaccia
Interface Association Descriptors
sezioni Compatible ID
function subset headers
se WinUSB è previsto per una sola interfaccia o per tutte le interfacce

Checklist di debug

Usa questo flusso:

Acquisisci dal momento del plug-in.
Conserva descrittori di dispositivo, configurazione, interfaccia, endpoint e BOS.
Cerca le richieste Microsoft OS descriptor.
Decodifica vendor code e lunghezza del descrittore.
Controlla i numeri di interfaccia nei dati del descrittore.
Verifica valori Compatible ID come WINUSB.
Controlla se le richieste non supportate vanno correttamente in STALL.
Confronta il comportamento di enumerazione tra Windows e Linux.
Controlla il binding in Gestione dispositivi dopo l'enumerazione.
Conserva i byte dei descrittori per il debug firmware.

Diagnosi finale

I problemi con USB BOS e Microsoft OS descriptor sono problemi di contratto dei descrittori. Il dispositivo può essere enumerato ma fallire comunque WinUSB, WebUSB o il binding del driver per una specifica interfaccia perché i descrittori opzionali sono malformati, mancanti o mappati all'interfaccia sbagliata.

Bus Scope aiuta mostrando direttamente l'enumerazione e le richieste dei descrittori, così i fallimenti di driver-binding si possono diagnosticare dalle evidenze USB invece che solo dai sintomi del sistema operativo.

Prova del contratto USB per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows»

La risposta diretta è che STALL, timeout o reset non spiega da solo la causa. Prima dimostra che il provider vede il device corretto; poi leggi il contratto del transfer: tipo, direzione, recipient, wValue, wIndex, lunghezza dichiarata e reale, status e stato precedente e successivo. In «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows» collega la conclusione alla prima transazione diversa dal caso buono.

Confine	Confronto	Decisione
Piattaforma	provider, permessi, Root Hub o usbmon/XHC20	I record provengono dalla connessione corretta?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	L’host invia la richiesta prevista?
Data	direzione, lunghezza e bytes conservati	Il payload rispetta il contratto?
Status	ACK, STALL, timeout o cancellation	Dove termina la transazione?
Stato	configuration, interface, alternate setting, endpoint halt	Il device era pronto?

Inizia prima di reset ed enumeration e conserva descriptors, SET_CONFIGURATION, SET_INTERFACE e il comando precedente al guasto. Un filtro endpoint stretto può nascondere il control transfer decisivo. Esegui un’azione USB documentata per prova e cambia solo firmware, driver, porta, cavo, comando o timing.

Come scrivere una risposta citabile?

Indica request, campi setup, risposta e contesto precedente; poi una prova con una variabile. Bytes non trattenuti non provano packet loss. La vicinanza fra command e reset dimostra correlazione, non causa senza ripetizione o cambio di stato.

Quando è valido il confronto?

Mantieni VID/PID, firmware, speed, topologia, provider, filtro e trigger. Confronta fasi USB semantiche, non frame numbers tra usbmon e USBPcap. Registra inizio, fine, versione, OS, connessione e checksum. Usa il troubleshooting Bus Scope.

I proprietari Semrush restano distinti: free USB analyzer sulla pagina prodotto, best USB protocol analyzer nella comparazione e USB descriptor viewer nella guida descriptor. Nessun volume o KD viene inventato.

Risposta diretta e confine di accettazione

La risposta breve a «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows» è: I dispositivi USB moderni spesso dipendono da descrittori che vanno oltre i descrittori di base del dispositivo e della configurazione. Tratta questa frase come un risultato da verificare, non come una promessa per ogni input, dispositivo, progetto o ambiente. Un risultato completo registra stato iniziale, azione esatta, output visibile e condizione che dimostra la conclusione dell’attività in Bus Scope.

Procedura basata sulle prove

Parti da un caso piccolo e ripetibile prima di modificare un progetto intero. Registra versione, sistema operativo, identità dell’input o dispositivo, impostazioni rilevanti e risultato atteso. Esegui un’azione deliberata, conserva la prima transizione inattesa e confrontala con un caso noto quando disponibile. Cambiare più controlli insieme nasconde quale condizione ha creato o corretto il problema.

Punto di controllo 1: Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows

Tratta «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows» come un confine di accettazione separato per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows». Registra lo stato prima dell’azione, il primo cambiamento visibile e lo stato finale. Se il risultato non coincide con l’obiettivo descritto, torna all’ultimo punto confermato invece di proseguire per ipotesi.

Punto di controllo 2: I dispositivi USB moderni spesso dipendono da descrittori che vanno oltre i descrittori di

Trasforma «I dispositivi USB moderni spesso dipendono da descrittori che vanno oltre i descrittori di base del dispositivo e della configurazione.» in una dichiarazione pass/fail ripetibile. Indica cosa deve essere presente, cosa deve mancare e quale ripristino è sicuro. Mantieni intatto il progetto o la cattura originale finché la copia corretta non supera lo stesso controllo.

Punto di controllo 3: Che cos'è il descrittore BOS

Tratta «Che cos'è il descrittore BOS» come un confine di accettazione separato per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows». Registra lo stato prima dell’azione, il primo cambiamento visibile e lo stato finale. Se il risultato non coincide con l’obiettivo descritto, torna all’ultimo punto confermato invece di proseguire per ipotesi.

Punto di controllo 4: Microsoft OS descriptors e WinUSB

Trasforma «Microsoft OS descriptors e WinUSB» in una dichiarazione pass/fail ripetibile. Indica cosa deve essere presente, cosa deve mancare e quale ripristino è sicuro. Mantieni intatto il progetto o la cattura originale finché la copia corretta non supera lo stesso controllo.

Punto di controllo 5: WebUSB

Tratta «WebUSB» come un confine di accettazione separato per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows». Registra lo stato prima dell’azione, il primo cambiamento visibile e lo stato finale. Se il risultato non coincide con l’obiettivo descritto, torna all’ultimo punto confermato invece di proseguire per ipotesi.

Punto di controllo 6: Comportamento STALL valido

Trasforma «Comportamento STALL valido» in una dichiarazione pass/fail ripetibile. Indica cosa deve essere presente, cosa deve mancare e quale ripristino è sicuro. Mantieni intatto il progetto o la cattura originale finché la copia corretta non supera lo stesso controllo.

Punto di controllo 7: Complicazioni dei dispositivi composite

Tratta «Complicazioni dei dispositivi composite» come un confine di accettazione separato per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows». Registra lo stato prima dell’azione, il primo cambiamento visibile e lo stato finale. Se il risultato non coincide con l’obiettivo descritto, torna all’ultimo punto confermato invece di proseguire per ipotesi.

Punto di controllo 8: Checklist di debug

Trasforma «Checklist di debug» in una dichiarazione pass/fail ripetibile. Indica cosa deve essere presente, cosa deve mancare e quale ripristino è sicuro. Mantieni intatto il progetto o la cattura originale finché la copia corretta non supera lo stesso controllo.

Punto di controllo 9: Diagnosi finale

Tratta «Diagnosi finale» come un confine di accettazione separato per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows». Registra lo stato prima dell’azione, il primo cambiamento visibile e lo stato finale. Se il risultato non coincide con l’obiettivo descritto, torna all’ultimo punto confermato invece di proseguire per ipotesi.

Punto di controllo 10: Prova del contratto USB per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID

Trasforma «Prova del contratto USB per «Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows»» in una dichiarazione pass/fail ripetibile. Indica cosa deve essere presente, cosa deve mancare e quale ripristino è sicuro. Mantieni intatto il progetto o la cattura originale finché la copia corretta non supera lo stesso controllo.

Matrice di accettazione

Punto	Prova da conservare	Criterio di superamento
Debug USB BOS e Microsoft OS Descriptor: WebUSB, WinUSB, WCID e driver Windows	Stato iniziale, un’azione e stato risultante	Una seconda persona riproduce il risultato
I dispositivi USB moderni spesso dipendono da descrittori che vanno oltre i descrittori di base del dispositivo e della	Stato iniziale, un’azione e stato risultante	Una seconda persona riproduce il risultato
Che cos'è il descrittore BOS	Stato iniziale, un’azione e stato risultante	Una seconda persona riproduce il risultato
Microsoft OS descriptors e WinUSB	Stato iniziale, un’azione e stato risultante	Una seconda persona riproduce il risultato
WebUSB	Stato iniziale, un’azione e stato risultante	Una seconda persona riproduce il risultato
Comportamento STALL valido	Stato iniziale, un’azione e stato risultante	Una seconda persona riproduce il risultato

Isolamento, ripristino e consegna

Fermati al primo confine che fallisce. Conserva sorgente, progetto, sessione o cattura, crea una copia prima di modifiche distruttive e cambia una variabile per esperimento. Ripetere un flusso ampio dopo più cambiamenti può dare un esito diverso senza spiegarlo.

Separa assenza di prove da prova di assenza. Una vista vuota può indicare input, ambito, filtro, permesso, dispositivo, intervallo o stato errato. Verifica acquisizione o importazione prima di interpretare decoder, editor, report o esportazione.

Prima della consegna, riapri l’artefatto e controlla inizio, punto decisionale e fine. Registra versione, piattaforma, configurazione, attesa, osservazione e riproduzione minima. Rimuovi o oscura dati sensibili e verifica l’autorizzazione del destinatario.

Domande e risposte

Qual è il modo affidabile più rapido per iniziare?

Usa il più piccolo caso rappresentativo, scrivi il risultato atteso e cambia una variabile. Conferma il percorso base prima di aggiungere filtri, effetti, modifiche, automazione o una sorgente maggiore.

Quali prove vanno salvate?

Conserva identità dell’input, versione, piattaforma, impostazioni, azione esatta, prima transizione inattesa e output finale. Chiudi e riapri progetto, sessione, report o export prima di considerarli durevoli.

Quando va ripetuta la procedura?

Ripetila dopo cambiamenti rilevanti ad applicazione, sistema, driver, firmware, modello, sorgente o workflow. Conserva il caso accettato precedente come riferimento non modificato.

Quando il risultato è pronto per la consegna?

Quando un’altra persona autorizzata identifica l’input, ripete l’azione, vede lo stesso risultato, comprende i limiti e apre l’artefatto senza stato locale non documentato.

Guide correlate

Queste pagine nella stessa lingua coprono le fasi vicine senza cambiare il proprietario canonico dell’argomento: