Descrittori USB standard
Un dispositivo USB fornisce informazioni su se stesso nelle strutture di dati denominate descrittori USB. In questa sezione vengono fornite informazioni su descrittori di dispositivo, configurazione, interfaccia ed endpoint e modi per recuperarli da un dispositivo USB.
Descrittori USB mappati al layout del dispositivo
Il software host ottiene i descrittori da un dispositivo collegato inviando varie richieste di controllo standard all'endpoint predefinito (Ottenere le richieste del descrittore, vedere la sezione 9.4.3 della specifica USB). Tali richieste specificano il tipo di descrittore da recuperare. In risposta a tali richieste, il dispositivo invia descrittori che includono informazioni sul dispositivo, le relative configurazioni, interfacce e gli endpoint correlati. I descrittori di dispositivo contengono informazioni sull'intero dispositivo. I descrittori di configurazione contengono informazioni su ogni configurazione del dispositivo. I descrittori di stringa contengono stringhe di testo Unicode.
Ogni dispositivo USB espone un descrittore del dispositivo che indica le informazioni di classe, il fornitore e gli identificatori del prodotto del dispositivo e il numero di configurazioni. Ogni configurazione espone il descrittore di configurazione che indica il numero di interfacce e caratteristiche di potenza. Ogni interfaccia espone un descrittore di interfaccia per ognuna delle impostazioni alternative che contiene informazioni sulla classe e sul numero di endpoint. Ogni endpoint all'interno di ogni interfaccia espone i descrittori di endpoint che indicano il tipo di endpoint e le dimensioni massime dei pacchetti.
Si consideri ad esempio il layout del dispositivo della scheda OSR FX2 (vedere Layout del dispositivo USB). A livello di dispositivo, il dispositivo espone un descrittore di dispositivo e un descrittore di endpoint per l'endpoint predefinito. A livello di configurazione, il dispositivo espone un descrittore di configurazione per Configuration 0. A livello di interfaccia, espone un descrittore di interfaccia per l'impostazione alternativa 0. A livello di endpoint, espone tre descrittori di endpoint.
Descrittore di dispositivo USB
Ogni dispositivo USB (Universal Serial Bus) deve essere in grado di fornire un singolo descrittore di dispositivo contenente informazioni pertinenti sul dispositivo. Windows usa tali informazioni per derivare vari set di informazioni. Ad esempio, i campi idVendor e idProduct specificano rispettivamente identificatori fornitore e prodotto. Windows usa questi valori di campo per costruire un ID hardware per il dispositivo. Per visualizzare l'ID hardware di un dispositivo specifico, aprire Gestione dispositivi e visualizzare le proprietà del dispositivo. Nella scheda Dettagli il valore della proprietà Ids hardware indica l'ID hardware ("USB\XXX") generato da Windows. Il campo bcdUSB indica la versione della specifica USB a cui è conforme il dispositivo. Ad esempio, 0x0200 indica che il dispositivo è progettato in base alla specifica USB 2.0. Il valore bcdDevice indica il numero di revisione definito dal dispositivo. Lo stack di driver USB usa bcdDevice, insieme a idVendor e idProduct, per generare ID hardware e compatibili per il dispositivo. È possibile visualizzare gli identificatori in Gestione dispositivi. Il descrittore del dispositivo indica anche il numero totale di configurazioni supportate dal dispositivo.
L'host ottiene il descrittore del dispositivo tramite un trasferimento di controllo. Microsoft fornisce interfacce di programmazione per ottenere il descrittore.
| Se stai scrivendo un... | Chiamare... |
|---|---|
| App UWP che usa Windows.Devices.Usb | UsbDevice.DeviceDescriptor |
| App desktop Win32 che usa funzioni WinUSB | WinUsb_GetDescriptor |
| Driver client basato su UMDF | IWDFUsbTargetDevice::RetrieveDescriptor |
| Driver client basato su KMDF | WdfUsbTargetDeviceGetDeviceDescriptor |
| Driver client basato su WDM | UsbBuildGetDescriptorRequest _URB_CONTROL_DESCRIPTOR_REQUEST |
Descrittore di configurazione USB
Una configurazione USB contiene una serie di interfacce. Ogni interfaccia è costituita da una o più impostazioni alternative e ogni impostazione alternativa è costituita da un set di endpoint (vedere Layout del dispositivo USB). Un descrittore di configurazione descrive l'intera configurazione include le interfacce, le impostazioni alternative e i relativi endpoint. Ognuna di queste entità viene descritta anche nel formato descrittore. Un descrittore di configurazione può includere anche descrittori personalizzati definiti dal produttore del dispositivo.
Pertanto, solo la parte iniziale di un descrittore di configurazione è fissa, 9 byte. Il resto è variabile a seconda del numero di interfacce e delle relative impostazioni alternative e degli endpoint supportati dal dispositivo. In questo set di documentazione i 9 byte iniziali vengono definiti descrittore di configurazione. I primi due byte del descrittore indicano la lunghezza totale.
La tabella seguente illustra il descrittore di configurazione per il dispositivo webcam USB:
| Campo | Valore |
|---|---|
| wTotalLength | 0x02CA |
| bNumInterfaces | 0x02 |
| bConfigurationValue | 0x01 |
| iConfiguration | 0x00 |
| bmAttributes | 0x80 (bus alimentato) |
| MaxPower | 0xFA (500 mA) |
Il campo bConfigurationValue indica il numero della configurazione definita nel firmware del dispositivo. Una configurazione USB indica anche determinate caratteristiche di alimentazione. bmAttributes contiene una maschera di bit che indica se la configurazione supporta la funzionalità di riattivazione remota e se il dispositivo è alimentato da bus o auto-alimentato. Il campo MaxPower specifica la potenza massima (in unità milliamp) che il dispositivo può estrarre dall'host, quando il dispositivo è alimentato dal bus. Il descrittore di configurazione indica anche il numero totale di interfacce (bNumInterfaces) supportate dal dispositivo.
| Se stai scrivendo un... | Chiamare... |
|---|---|
| App UWP che usa Windows.Devices.Usb | UsbDevice.ConfigurationDescriptor per ottenere la parte di lunghezza fissa. UsbConfiguration.Descriptors per ottenere l'intero set di configurazione. |
| App desktop Win32 che usa funzioni WinUSB | WinUsb_GetDescriptor |
| Driver client basato su UMDF | IWDFUsbTargetDevice::RetrieveDescriptor |
| Driver client basato su KMDF | WdfUsbTargetDeviceRetrieveConfigDescriptor |
| Driver client basato su WDM | UsbBuildGetDescriptorRequest _URB_CONTROL_GET_CONFIGURATION_REQUEST |
Descrittore di interfaccia USB
Un descrittore di interfaccia contiene informazioni su un'impostazione alternativa di un'interfaccia USB.
La tabella seguente illustra il descrittore di interfaccia per l'impostazione alternativa 0 dell'interfaccia 0 per il dispositivo webcam:
| Campo | Valore |
|---|---|
| bInterfaceNumber | 0x00 |
| bAlternateSetting | 0x00 |
| bNumEndpoints | 0x01 |
| bInterfaceClass | 0x0E |
| bInterfaceSubClass | 0x02 |
| bInterfaceProtocol | 0x00 |
| iInterface | 0x02 |
| 0x0409 | "Microsoft LifeCam VX-5000" |
| 0x0409 | "Microsoft LifeCam VX-5000" |
Nell'esempio precedente si notino i valori dei campi bInterfaceNumber e bAlternateSetting . Questi campi contengono valori di indice usati dall'host per attivare l'interfaccia e una delle impostazioni alternative. Per l'attivazione, un'applicazione o un driver specifica il valore di indice nella chiamata di funzione. In base a queste informazioni, lo stack di driver USB crea quindi una richiesta di controllo standard (SET INTERFACE) e la invia al dispositivo. Si noti il campo bInterfaceClass . Il descrittore di interfaccia o il descrittore per una delle impostazioni alternative specifica un codice di classe, una sottoclasse e un protocollo. Il valore di 0x0E indica che l'interfaccia è per la classe del dispositivo video. Si noti anche il campo iInterface . Questo valore indica che sono presenti due descrittori stringa aggiunti al descrittore di interfaccia. I descrittori di stringa contengono descrizioni Unicode usate durante l'enumerazione del dispositivo per identificare la funzionalità.
| Se stai scrivendo un... | Chiamare... |
|---|---|
| App UWP che usa Windows.Devices.Usb | UsbInterfaceSetting.Descriptors per ottenere un descrittore specifico per una determinata impostazione alternativa. UsbInterface.Descriptors per ottenere descrittori per tutte le impostazioni di un'interfaccia. |
| App desktop Win32 che usa funzioni WinUSB | WinUsb_GetDescriptor |
| Driver client basato su UMDF | IWDFUsbInterface::GetInterfaceDescriptor |
| Driver client basato su KMDF | WdfUsbInterfaceGetDescriptor |
| Driver client basato su WDM | UsbBuildGetDescriptorRequest _URB_CONTROL_GET_CONFIGURATION_REQUEST e quindi analizzare per ogni descrittore di interfaccia. Per altre informazioni, vedere Come selezionare una configurazione per un dispositivo USB. |
Descrittore endpoint USB
Ogni endpoint, in un'interfaccia, descrive un singolo flusso di input o output per il dispositivo. Un dispositivo che supporta flussi per diversi tipi di funzioni ha più interfacce. Un dispositivo che supporta diversi flussi relativi a una funzione può supportare più endpoint in una singola interfaccia.
Tutti i tipi di endpoint (ad eccezione dell'endpoint predefinito) devono fornire descrittori di endpoint in modo che l'host possa ottenere informazioni sull'endpoint. Un descrittore di endpoint include informazioni, ad esempio l'indirizzo, il tipo, la direzione e la quantità di dati che l'endpoint può gestire. I trasferimenti di dati all'endpoint sono basati su tali informazioni.
La tabella seguente illustra un descrittore di endpoint per il dispositivo webcam:
| Campo | Valore |
|---|---|
| bEndpointAddress | 0x82 IN |
| bmAttributes | 0x01 |
| wMaxPacketSize | 0x0080 (128) |
| bInterval | 0x01 |
Il campo bEndpointAddress specifica l'indirizzo endpoint univoco che contiene il numero di endpoint (Bit 3..0) e la direzione dell'endpoint (Bit 7). Leggendo questi valori nell'esempio precedente, è possibile determinare che il descrittore descrive un endpoint IN il cui numero di endpoint è 2. L'attributo bmAttributes indica che il tipo di endpoint è isochronous. WMaxPacketSizefield indica il numero massimo di byte che l'endpoint può inviare o ricevere in una singola transazione. I bit 12..11 indicano il numero totale di transazioni che possono essere inviate per microframe. BInterval indica la frequenza con cui l'endpoint può inviare o ricevere dati.
| Se stai scrivendo un... | Chiamare... |
|---|---|
| App UWP che usa Windows.Devices.Usb | UsbEndpointDescriptor |
| App desktop Win32 che usa funzioni WinUSB | WinUsb_GetDescriptor |
| Driver client basato su UMDF | WDFUsbTargetPipe::GetInformation |
| Driver client basato su KMDF | WdfUsbTargetPipeGetInformation |
| Driver client basato su WDM | UsbBuildGetDescriptorRequest _URB_CONTROL_GET_CONFIGURATION_REQUEST e quindi analizzare per ogni descrittore di endpoint. Per altre informazioni, vedere Come selezionare una configurazione per un dispositivo USB. |