Specifica delle direttive WDF nei file INF

Un file INF che installa un driver WDF deve contenere due sezioni specifiche di WDF:

• Sezione [DDInstall.wdf] per ogni sezione [DDInstall]
• Sezione [wdf-service-install] con il nome di sezione specificato in una direttiva KmdfService o UmdfService in [DDInstall.wdf]

Queste sezioni contengono direttive specifiche di WDF. Le direttive specifiche di UMDF iniziano con il prefisso UMDF e le direttive specifiche di KMDF iniziano con il prefisso KMDF.

L'esempio di codice seguente illustra le direttive specifiche di UMDF:

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

L'esempio di codice seguente mostra le direttive specifiche di KMDF:

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

[Direttive UMDF per le sezioni DDInstall.WDF]

Di seguito è riportato un esempio di codice. Di seguito è descritta di seguito ogni direttiva specifica di UMDF nella sezione DDInstall.WDF.

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

UmdfService

`UmdfService = <serviceName>, <sectionName>

Associa un driver UMDF a una sezione [wdf-service-install] che contiene informazioni necessarie per installare il driver UMDF. Il parametro serviceName specifica il driver UMDF ed è limitato a un massimo di 31 caratteri. Il parametro sectionName fa riferimento alla sezione [wdf-service-install]. Un file INF valido richiede in genere almeno una direttiva UmdfService . Tuttavia, se un driver UMDF fa parte del sistema operativo, non è necessaria una direttiva UmdfService per il driver UMDF. Pertanto, un file INF valido potrebbe non avere direttive UmdfService , anche se la maggior parte dei file INF ha una direttiva UmdfService per ogni driver UMDF.

UmdfHostProcessSharing

Questa direttiva è supportata nelle versioni UMDF 1.11 e successive.

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

Determina se uno stack di dispositivi viene inserito in un pool di processi condiviso (ProcessSharingEnabled) o in un singolo processo (ProcessSharingDisabled). Il valore predefinito è ProcessSharingEnabled. Questa direttiva è specifica del dispositivo anziché specifica del driver.

Per altre informazioni sul pool di dispositivi, vedere Uso del pool di dispositivi nei driver UMDF.

UmdfDirectHardwareAccess

Questa direttiva è supportata nelle versioni UMDF 1.11 e successive.

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

Indica se il framework deve consentire al driver di usare una delle funzionalità di accesso diretto all'hardware, ad esempio l'accesso ai registri e alle porte dei dispositivi, l'analisi delle risorse hardware assegnate al dispositivo, la gestione degli interrupt hardware o l'acquisizione delle risorse di connessione.

Se UmdfDirectHardwareAccess è impostato su AllowDirectHardwareAccess, il framework consente al driver di usare interfacce UMDF che eseguono l'accesso diretto all'hardware.

È necessario specificare AllowDirectHardwareAccess se il driver UMDF accede a risorse hardware come registri o porte, interrupt, pin di I/O (GPIO) per utilizzo generico o connessioni di bus seriali come I2C, SPI e porta seriale. Il driver riceve tutte queste risorse tramite i parametri ResourcesRaw e ResourcesTranslated della relativa funzione di callback EvtDevicePrepareHardware .

Nota

A partire da UMDF versione 2.15, un driver UMDF non deve specificare AllowDirectHardwareAccess per ricevere elenchi di risorse hardware nella routine di callback EvtDevicePrepareHardware . Se non lo specifichi, il driver non dispone dei diritti di accesso per usare queste risorse, con un'eccezione: se al dispositivo viene assegnata una o più risorse di connessione (CmResourceTypeConnection) e una o più risorse di interrupt (CmResourceTypeInterrupt), il driver può chiamare WdfInterruptCreate dalla routine di callback EvtDevicePrepareHardware (ma non da EvtDriverDeviceAdd).

Per informazioni sulla connessione di un driver UMDF a determinati tipi di risorse, vedere:

• Risorse hardware per User-Mode driver di periferica SPB
• ID di connessione per dispositivi periferici SPB-Connected
• Connessione di un driver di periferica UMDF a una porta seriale

Se UmdfDirectHardwareAccess è impostato su RejectDirectHardwareAccess, il framework non consente ai driver di usare funzionalità di accesso diretto all'hardware. Il valore predefinito è RejectDirectHardwareAccess.

Per informazioni su come un driver UMDF accede alle risorse hardware, vedere Ricerca e mapping delle risorse hardware.

UmdfHostPriority

Questa direttiva è supportata nelle versioni 2.15 e successive di UMDF.

UmdfHostPriority = <PriorityHigh>

Un driver client HID di UMDF può impostare UmdfHostPriority su PriorityHigh per aumentare la priorità del thread. Questa direttiva deve essere usata solo per i driver di tocco o di input sensibili al tempo di risposta dell'utente. Quando un driver specifica PriorityHigh, il sistema lo inserisce in un pool di dispositivi separato insieme ad altri driver con priorità simile. Poiché il pool di dispositivi aggiuntivi usa più memoria, è consigliabile usare questa impostazione con cautela. Per altre informazioni sul pool di dispositivi, vedere Uso del pool di dispositivi nei driver UMDF.

UmdfRegisterAccessMode

Questa direttiva è supportata nelle versioni UMDF 1.11 e successive.

UmdfRegisterAccessMode = <RegisterAccessUsingSystemCall | RegisterAccessUsingUserModeMapping>

Indica se il framework deve eseguire il mapping dei registri nello spazio indirizzi in modalità utente (in modo che una chiamata di sistema non sia coinvolta nell'accesso ai registri) o usare una chiamata di sistema per accedere ai registri.

Se UmdfRegisterAccessMode è impostato su RegisterAccessUsingSystemCall, il framework usa una chiamata di sistema per accedere ai registri.

Se UmdfRegisterAccessMode è impostato su RegisterAccessUsingUserModeMapping, il framework esegue il mapping dei registri nello spazio indirizzi in modalità utente in modo che una chiamata di sistema non sia necessaria per accedere ai registri. Il valore predefinito è RegisterAccessUsingSystemCall.

UmdfServiceOrder

UmdfServiceOrder = <serviceName1> [, <serviceName2> ...]

Elenca l'ordine in cui il co-programma di installazione installa i driver UMDF nello stack di dispositivi. Anche se il co-programma di installazione installa un solo driver UMDF nello stack di dispositivi, il file INF deve contenere questa direttiva. I parametri serviceNameXx corrispondono ai parametri serviceName per ogni direttiva UmdfService . Poiché i driver UMDF vengono aggiunti allo stack di dispositivi nell'ordine in cui sono elencati, il primo parametro specifica il driver UMDF più basso nello stack di dispositivi.

Per assicurarsi che un co-programma di installazione di UMDF installi il dispositivo, è necessario che sia presente una sola direttiva UmdfServiceOrder in una determinata sezione DDInstall specifica di WDF. Ovvero, la direttiva UmdfServiceOrder non può essere importata usando le direttive Include e Needs .

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

Informa il framework sul livello massimo di rappresentazione che il driver UMDF può avere. Una direttiva UmdfImpersonationLevel è facoltativa; se non viene specificato un livello di rappresentazione, l'impostazione predefinita è Identificazione. Quando un'applicazione apre un handle di file, l'applicazione può concedere un livello di rappresentazione maggiore al driver. Tuttavia, il driver non può chiamare il metodo IWDFIoRequest::Impersonate per richiedere un livello di rappresentazione maggiore del livello specificato da UmdfImpersonationLevel . I valori possibili per questa direttiva sono:

• Anonimo

• Identificazione

• Rappresentazione

• Delegation

Questi valori corrispondono ai valori specificati nell'enumerazione SECURITY_IMPERSONATION_LEVEL .

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <Copy | Reject>

Indica se il framework accetterà (copia) o rifiuterà (rifiuta) le richieste di I/O di un dispositivo, se gli oggetti richiesta contengono codici di controllo di I/O che specificano il metodo di accesso al buffer METHOD_NEITHER . Una direttiva UmdfMethodNeitherAction è facoltativa. Se la direttiva non viene specificata, il valore predefinito è Reject.

Per altre informazioni sul supporto del metodo di accesso al buffer METHOD_NEITHER nei driver basati su UMDF, vedere Uso di I/O con buffer né di I/O diretto nei driver UMDF.

UmdfDispatcher

UmdfDispatcher = <FileHandle | WinUsbNativeUSB | >

Informa il framework in cui inviare I/O dopo che l'I/O passa attraverso la parte in modalità utente dello stack di dispositivi. Per impostazione predefinita, l'I/O viene inviato al reflectionor (WUDFRd.sys). Impostando UmdfDispatcher su WinUsb, il driver indica a UMDF di inviare I/O all'architettura WinUsb. A partire da UMDF 2.15, specificando NativeUSB , il riflettore può gestire l'I/O USB.

• Se qualsiasi driver nello stack usa una destinazione basata su handle file, impostare questa direttiva su FileHandle.
• Se il driver usa UMDF 2.15 o versione successiva e usa destinazioni di I/O USB, impostare questa direttiva su NativeUSB.
• Se il driver è pre-UMDF 2.15 e usa destinazioni di I/O USB, impostare questa direttiva su WinUsb.

Una direttiva UmdfDispatcher è facoltativa.

Nell'esempio di codice seguente viene illustrata la direttiva UmdfDispatcher in una sezione DDInstall specifica di WDF.

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

Questa direttiva è supportata nelle versioni 1.9 e successive di UMDF.

UmdfKernelModeClientPolicy = <AllowKernelModeClients RejectKernelModeClients | >

Per consentire ai driver in modalità kernel di caricare sopra un driver in modalità utente nelle versioni precedenti di UMDF, vedere Supporto client in modalità kernel nelle versioni precedenti di UMDF.

Indica se il framework deve consentire al driver di ricevere richieste di I/O dai driver in modalità kernel.

Se UmdfKernelModeClientPolicy è impostato su AllowKernelModeClients, il framework consente ai driver in modalità kernel di caricare sopra un driver in modalità utente e fornisce richieste di I/O dai driver in modalità kernel al driver in modalità utente.

Se UmdfKernelModeClientPolicy è impostato su RejectKernelModeClients, il framework non consente ai driver in modalità kernel di caricare sopra un driver in modalità utente e non recapita richieste di I/O da qualsiasi driver in modalità kernel al driver in modalità utente. Se il file INF di un driver non contiene questa direttiva, il valore predefinito è RejectKernelModeClients. Per altre informazioni, vedere Supporto dei client in modalità kernel.

UmdfFileObjectPolicy

Questa direttiva è supportata nelle versioni UMDF 1.11 e successive.

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects AllowNullAndUnknownFileObjects | >

Indica se il framework deve consentire l'elaborazione delle richieste di I/O (IWDFIoRequest) che non sono associate a un oggetto file (IWDFFile) o sono associate a un oggetto file sconosciuto (un oggetto file per cui un driver non ha precedentemente visto una richiesta di creazione).

Se UmdfFileObjectPolicy è impostato su RejectNullAndUnknownFileObjects, il framework non consente l'elaborazione delle richieste associate a un oggetto file NULL o sconosciuto.

Se UmdfFileObjectPolicy è impostato su AllowNullAndUnknownFileObjects, il framework consente l'elaborazione delle richieste associate a un oggetto file NULL o sconosciuto.

Il valore predefinito è RejectNullAndUnknownFileObjects.

UmdfFsContextUsePolicy

Questa direttiva è supportata nelle versioni UMDF 1.11 e successive.

UmdfFsContextUsePolicy = <CanUseFsContextCanUseFsContext2 | | CannotUseFsContexts>

Indica se il framework può archiviare informazioni interne in membri di contesto specifici di un oggetto file WDM. Se un driver in modalità kernel nello stesso stack usa un particolare membro dell'oggetto file, è possibile usare questa direttiva per richiedere che il framework non usi la stessa posizione.

Se UmdfFsContextUsePolicy è impostato su CanUseFsContext, il framework archivia le informazioni nel membro FsContext dell'oggetto file WDM.

Se UmdfFsContextUsePolicy è impostato su CanUseFsContext2, il framework archivia le informazioni nel membro FsContext2 dell'oggetto file WDM.

Se UmdfFsContextUsePolicy è impostato su CannotUseFsContexts, il framework non usa FsContext o FsContext2.

Il valore predefinito è CanUseFsContext.

[Direttive UMDF per la sezione wdf-service-install]

Di seguito è riportato un esempio di codice. Ogni direttiva specifica di UMDF nella sezione [wdf-service-install] è descritta di seguito. Il nome della sezione viene specificato in una direttiva UmdfService nella sezione [DDInstall.wdf].

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

UmdfLibraryVersion

UmdfLibraryVersion = <versione>

Informa il co-installer sul numero di versione del framework usato dal driver UMDF. Il formato della stringa di versione è <principale>.<minore>.<servizio>. Quando i driver nello stack di dispositivi usano più versioni del framework, il file INF copia più co-installers-uno per ogni versione del framework nella stessa posizione nel disco rigido. Tuttavia, il file INF aggiunge solo il co-installer di versione più alto al valore del Registro di sistema CoInstallers32 . Per altre informazioni sulla copia dei co-installer, vedere Uso del co-programma di installazione di UMDF.

Il co-installer verifica la stringa di versione e lo usa per individuare il co-installer specifico della versione per il driver UMDF. Il co-installer estrae quindi il framework dal co-installer specifico della versione.

ServiceBinary

ServiceBinary = <binarypath>

Informa UMDF su dove posizionare il file binario del driver UMDF sul disco rigido.

I driver UMDF devono essere copiati e eseguiti dalla Windows\System32\Drivers\UMDF directory.

DriverCLSID

Nota Questa direttiva è supportata solo in UMDF 1.x, deprecata. Per altre informazioni, vedere Guida alla progettazione di UMDF 1.x.

DriverCLSID = <{CLSID}>

Informa UMDF sull'identificatore di classe (CLSID) del driver UMDF. Quando UMDF carica il driver UMDF, l'host UMDF usa il CLSID del driver UMDF per creare un'istanza dell'interfaccia IDriverEntry del driver UMDF.

UmdfExtensions

UmdfExtensions = <cxServiceName>

Obbligatorio per i driver che comunicano con i driver di estensione della classe forniti da Microsoft. Il parametro cxServiceName corrisponde al servizio associato al file binario del driver di estensione della classe.

I nomi di servizio per i driver di estensione della classe possono trovarsi come sottochiave nella chiave del Registro di sistema seguente: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services

[Direttive KMDF per le sezioni DDInstall.WDF]

Di seguito è riportato un esempio di codice. Di seguito è descritta di seguito ogni direttiva specifica del servizio kmDF nella sezione DDInstall.WDF.

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

KmdfService

KmdfService = <serviceName,<sectionName>>

Associa un driver KMDF a una sezione [wdf-service-install] che contiene informazioni necessarie per installare il driver KMDF. Il parametro serviceName specifica il driver KMDF ed è limitato a un massimo di 31 caratteri di lunghezza. Il parametro sectionName fa riferimento alla sezione [wdf-service-install] . Un file INF valido richiede in genere almeno una direttiva KmdfService . Tuttavia, se un driver KMDF fa parte del sistema operativo, non è necessaria una direttiva KmdfService per il driver KMDF. Pertanto, un file INF valido potrebbe non avere direttive KmdfService , anche se la maggior parte dei file INF ha una direttiva KmdfService per ogni driver KMDF.

[Direttive KMDF per la sezione wdf-service-install]

Di seguito è riportato un esempio di codice. Ogni direttiva specifica di KMDF nella sezione [wdf-service-install] è descritta di seguito. Il nome della sezione deriva dalla direttiva KmdfService nella sezione DDInstall.wdf.

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

KmdfLibraryVersion

KmdfLibraryVersion = <version>

Il formato della stringa di versione è major.minor. In genere, è consigliabile specificare $KMDFVERSION$ e quindi il processo di compilazione WDK lo sostituirà con il numero di versione corretto.