Procedure consigliate: Uso degli URI

  • Articolo

In questo argomento vengono descritte le procedure consigliate per un driver client per l'allocazione, la compilazione e l'invio di un OGGETTO ALLO STACK di driver USB incluso in Windows 8.

Windows 8 include un nuovo stack di driver USB per supportare dispositivi USB (Universal Serial Bus) 3.0. Il nuovo stack di driver USB 3.0 implementa diverse nuove funzionalità, in base alla specifica USB 3.0. Inoltre, lo stack di driver include altre funzionalità che consentono a un driver client di eseguire in modo efficiente attività comuni. Ad esempio, il nuovo stack di driver accetta mdls concatenati che consente al driver client di inviare un buffer di trasferimento in pagine non contigue in memoria fisica.

Prima che un driver client possa usare le nuove funzionalità dello stack di driver USB per Windows 8, il driver deve registrarsi con lo stack di driver USB sottostante caricato da Windows per il dispositivo. Per registrare il driver client, chiamare USBD_CreateHandle e specificare una versione del contratto. Se il driver client deve compilare, eseguire e usare i miglioramenti e le nuove funzionalità in Windows 8, la versione del contratto client è USBD_CLIENT_CONTRACT_VERSION_602.

Per un driver client di versione USBD_CLIENT_CONTRACT_VERSION_602, lo stack di driver USB presuppone che il driver client sia conforme al set di regole seguente:

Lo stack di driver USB esegue le convalide sulle richieste ricevute e gestisce le violazioni quando possibile. In caso contrario, potrebbe verificarsi un comportamento non definito.

Non inviare richieste di I/O usando handle di pipe non aggiornati o non validi

Il driver client non deve usare handle di pipe non aggiornati per inviare richieste di I/O allo stack di driver USB. Un handle pipe non aggiornato fa riferimento a un handle di pipe ottenuto in una richiesta per selezionare una configurazione, un'interfaccia o un'impostazione alternativa che non è più selezionata nel dispositivo. Per evitare handle di pipe non aggiornati, ogni volta che il driver client seleziona una configurazione o un'interfaccia, il driver deve aggiornare la cache degli handle di pipe (in genere archiviati nel contesto del dispositivo). Alcune race condition possono comportare anche handle di pipe non aggiornati. Ad esempio, il driver client invia una richiesta di I/O usando un handle pipe sull'interfaccia selezionata. Prima del completamento della richiesta, il driver client seleziona un'impostazione alternativa che non usa lo stesso endpoint associato all'handle della pipe in uso. Entrambe le richieste in sospeso potrebbero causare una race condition che rende l'handle di pipe non valido.

Allocare gli URL chiamando routine di allocazione in Windows 8

Windows 8 fornisce nuove routine per l'allocazione, la compilazione e il rilascio di blocchi di richiesta USB (URB). Per allocare gli URB, un driver client windows Driver Model (WDM) deve usare sempre le nuove routine illustrate nell'elenco seguente:

Le routine nell'elenco precedente potrebbero collegare un contesto DELL'OPACO all'oggetto JSON allocato per migliorare il rilevamento e l'elaborazione. Il driver client non può visualizzare o modificare il contenuto del contesto DELL'OGGETTO. Per altre informazioni sull'allocazione DI MODALITÀ in Windows 8, vedere Allocazione e compilazione di URB.

Se un driver client Windows Driver Framework (WDF) che ne identifica la versione come USBD_CLIENT_CONTRACT_VERSION_602 durante la registrazione (vedere WdfUsbTargetDeviceCreateWithParameters), lo stack di driver USB prevede che il driver client alloca la memoria per l'OGGETTO ESEGUENDO una chiamata al nuovo WdfUsbTargetDeviceCreateUrb.

Non riutilizzare gli URL attivi associati alle richieste in sospeso

Lo stack di driver USB controlla deliberatamente i bug se rileva che è stato inviato di nuovo un OGGETTO ACTIVE PRIMA della richiesta associata all'OGGETTO. Un oggetto ODBC è attivo finché la richiesta è in sospeso e la routine di completamento IRP del driver client non è stata chiamata. Non eseguire le attività seguenti in un'istanza attiva DI.

  • Non inviare di nuovo un'istanza attiva DIS PER un'altra richiesta (associare IL METODO a un altro IRP).
  • Non modificare il contenuto di un OGGETTO ACTIVE.
  • Non liberare un'opzione ATTIVA.

Dopo aver chiamato la routine di completamento del driver client, i driver possono inviare di nuovo gli URL per determinati tipi di richiesta all'interno della routine di completamento. Per le sottomissione si applicano le regole seguenti:

  • Il driver client non deve riutilizzare un'istanza di CLASSE allocata da USBD_SelectConfigUrbAllocateAndBuild per qualsiasi tipo di richiesta diversa da una richiesta di configurazione selezionata per selezionare la stessa configurazione.

  • Il driver client non deve riutilizzare un'istruzione ODBC allocata da USBD_SelectInterfaceUrbAllocateAndBuild per qualsiasi tipo di richiesta diversa da una richiesta di interfaccia select per selezionare la stessa impostazione alternativa in un'interfaccia. Per un esempio, vedere La sezione Osservazioni in USBD_SelectInterfaceUrbAllocateAndBuild.

  • È necessario riutilizzare un'istanza DI CLASSE allocata da USBD_IsochUrbAllocate solo per le richieste di trasferimento isocrone. Al contrario, per una richiesta isocrona non deve essere utilizzata un'istanza DI/O allocata per altri tipi di richieste di I/O (controllo, bulk o interrupt).

    Ad esempio, un driver client alloca e compila una struttura ODBC per una richiesta di trasferimento bulk. Il driver client vuole anche inviare dati agli endpoint isocroni nel dispositivo. Al termine di una richiesta di trasferimento in blocco, il driver client non deve riformattare e inviare l'OGGETTO ODBC per una richiesta isocrona. Ciò è dovuto al fatto che un'istanza di CLASSE associata a una richiesta isocrona ha una lunghezza variabile a seconda del numero di pacchetti. Inoltre, i pacchetti sono necessari per avviare e terminare su un limite di frame. Il valore DI ALLOCATE (per il trasferimento bulk) potrebbe non adattarsi al layout del buffer necessario per un trasferimento isocrono e la richiesta potrebbe non riuscire.

  • Non è necessario riutilizzare un'istanza DI CLASSE allocata da USBD_UrbAllocate per un isochronous, una configurazione select o una richiesta di interfaccia select. È possibile riutilizzare l'oggetto CRITERI per la selezione di una configurazione NULL per disabilitare la configurazione selezionata nel dispositivo. L'oggetto ODBC non deve essere attivo e il driver client deve riformattare l'OGGETTO ESEGUENDO una chiamata alla macro UsbBuildSelectConfigurationRequest e passando NULL nel parametro ConfigurationDescriptor .

  • Prima di inviare di nuovo un'istanza DI, il driver client deve riformattare l'OGGETTO USANDO la macro UsbBuildXxx appropriata definita per il tipo di richiesta. È importante che il driver formatti l'ISTRUZIONE ISTRUZIONE, perché lo stack USB potrebbe aver modificato alcuni dei relativi contenuti.

    Si supponga, ad esempio, che un driver chiami UsbBuildInterruptOrBulkTransferRequest per inizializzare un OGGETTO PER una richiesta di trasferimento bulk (vedere _URB_BULK_OR_INTERRUPT_TRANSFER). Se il driver inizializza il membro TransferBufferMDL della struttura DELL'ISTRUZIONE SU NULL, lo stack di driver USB usa il buffer di trasferimento, specificato TransferBuffer, per scambiare dati con il dispositivo anziché con un MDL. Tuttavia, internamente, lo stack di driver USB potrebbe creare un MDL, archiviare un puntatore al file MDL in TransferBufferMDL e usare MDL per passare i dati nello stack. Anche se lo stack di driver USB libera la memoria MDL, TransferBufferMDL potrebbe non essere NULL quando il driver client sta elaborando l'OGGETTO NELLA routine di completamento. Per assicurarsi che i membri dell'OGGETTO VENGANO formattati correttamente, il driver deve chiamare nuovamente UsbBuildInterruptOrBulkTransferRequest per riformattare l'oggetto ODBC prima di inviare la richiesta,

Non usare il periodo di polling maggiore di 8 per trasferimenti ad alta velocità e SuperSpeed isochronous

Lo stack di driver USB supporta pipe ad alta velocità e SuperSpeed isochronous con un numero di periodo di polling di 1, 2, 4 o 8. Un driver client non deve inviare I/O a un endpoint con un periodo maggiore di 8. In questo modo potrebbe verificarsi un controllo di bug.

Assicurarsi che il numero di pacchetti isocroni che sia un multiplo di pacchetti per frame

Per i trasferimenti isocroni ad alta velocità e SuperSpeed, il numero di pacchetti isocroni per fotogramma viene calcolato come 8/periodo di polling. Il driver client deve assicurarsi che il valore NumberOfPackets specificato nell'OGGETTO _URB_ISOCH_TRANSFER (vedere _URB_ISOCH_TRANSFER) sia un multiplo di pacchetti per frame.

Lo stack di driver USB non supporta gli UR di trasferimento isocroni in cui NumberOfPackets non è un multiplo di pacchetti per frame.

Chiamare la routine a livello di IRQL documentato

Se si registra il driver client con USBD_CLIENT_CONTRACT_VERSION_602 come versione del contratto, lo stack di driver USB presuppone che il driver client abbia inviato la richiesta a livello di IRQL appropriato. Se un driver client invia una richiesta al DISPATCH_LEVEL, che deve essere inviata al PASSIVE_LEVEL. Dopo aver ricevuto la richiesta, in alcuni casi, lo stack di driver USB convalida il valore IRQL e non riesce la richiesta. In altri casi, tuttavia, lo stack di driver USB potrebbe generare un controllo di bug.

Invio di richieste a un dispositivo USB