Spécification de directives WDF dans les fichiers INF

  • Article

Un fichier INF qui installe un pilote WDF doit contenir deux sections spécifiques à WDF :

  • Section [DDInstall.wdf] pour chaque section [DDInstall]
  • Section [wdf-service-install], avec le nom de section spécifié dans une directive KmdfService ou UmdfService dans [DDInstall.wdf]

Ces sections contiennent des directives spécifiques à WDF. Les directives spécifiques à UMDF commencent par le préfixe UMDF, et les directives spécifiques à KMDF commencent par le préfixe KMDF.

L’exemple de code suivant montre des directives spécifiques à UMDF :

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

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

L’exemple de code suivant montre des directives spécifiques à KMDF :

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

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

[Directives UMDF pour les sections DDInstall.WDF]

Voici un exemple de code. Chaque directive spécifique à UMDF dans la section DDInstall.WDF est décrite ci-dessous.

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

UmdfService

`UmdfService = <serviceName>, <sectionName>

Associe un pilote UMDF à une section [wdf-service-install] qui contient les informations requises pour installer le pilote UMDF. Le paramètre serviceName spécifie le pilote UMDF et est limité à un maximum de 31 caractères. Le paramètre sectionName fait référence à la section [wdf-service-install]. Un fichier INF valide nécessite généralement au moins une directive UmdfService . Toutefois, si un pilote UMDF fait partie du système d’exploitation, une directive UmdfService pour le pilote UMDF n’est pas requise. Par conséquent, un fichier INF valide peut ne pas avoir de directives UmdfService , bien que la plupart des fichiers INF aient une directive UmdfService pour chaque pilote UMDF.

UmdfHostProcessSharing

Cette directive est prise en charge dans UMDF versions 1.11 et ultérieures.

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

Détermine si une pile d’appareils est placée dans un pool de processus partagé (ProcessSharingEnabled) ou dans son propre processus individuel (ProcessSharingDisabled). La valeur par défaut est ProcessSharingEnabled. Cette directive est spécifique à l’appareil plutôt qu’au pilote.

Pour plus d’informations sur le regroupement d’appareils, consultez Utilisation du regroupement d’appareils dans les pilotes UMDF.

UmdfDirectHardwareAccess

Cette directive est prise en charge dans UMDF versions 1.11 et ultérieures.

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

Indique si l’infrastructure doit autoriser le pilote à utiliser l’une des fonctionnalités d’accès direct au matériel, telles que l’accès aux registres et aux ports d’appareil, l’analyse des ressources matérielles affectées à l’appareil, la gestion des interruptions matérielles ou l’acquisition de ressources de connexion.

Si UmdfDirectHardwareAccess est défini sur AllowDirectHardwareAccess, l’infrastructure permet au pilote d’utiliser des interfaces UMDF qui effectuent un accès direct au matériel.

Vous devez spécifier AllowDirectHardwareAccess si votre pilote UMDF accède à des ressources matérielles telles que des registres ou des ports, des interruptions, des broches d’E/S à usage général (GPIO) ou des connexions de bus série telles que I2C, SPI et port série. Votre pilote reçoit toutes ces ressources via les paramètres ResourcesRaw et ResourcesTranslated de sa fonction de rappel EvtDevicePrepareHardware .

Notes

À compter d’UMDF version 2.15, un pilote UMDF n’a pas besoin de spécifier AllowDirectHardwareAccess pour recevoir des listes de ressources matérielles dans sa routine de rappel EvtDevicePrepareHardware . Si vous ne le spécifiez pas, le pilote ne dispose pas des droits d’accès nécessaires pour utiliser ces ressources, à une exception près : si l’appareil se voit attribuer une ou plusieurs ressources de connexion (CmResourceTypeConnection) et une ou plusieurs ressources d’interruption (CmResourceTypeInterrupt), le pilote peut appeler WdfInterruptCreate à partir de sa routine de rappel EvtDevicePrepareHardware (mais pas à partir d’EvtDriverDeviceAdd).

Pour plus d’informations sur la connexion d’un pilote UMDF à des types particuliers de ressources, consultez :

Si UmdfDirectHardwareAccess est défini sur RejectDirectHardwareAccess, l’infrastructure n’autorise pas les pilotes à utiliser des fonctionnalités d’accès direct au matériel. La valeur par défaut est RejectDirectHardwareAccess.

Pour plus d’informations sur la façon dont un pilote UMDF accède aux ressources matérielles, consultez Recherche et mappage des ressources matérielles.

UmdfHostPriority

Cette directive est prise en charge dans UMDF versions 2.15 et ultérieures.

UmdfHostPriority = <PriorityHigh>

Un pilote client HID UMDF peut définir UmdfHostPriority sur PriorityHigh pour augmenter sa priorité de thread. Cette directive ne doit être utilisée que pour les pilotes tactiles ou d’entrée sensibles au temps de réponse de l’utilisateur. Lorsqu’un pilote spécifie PriorityHigh, le système le place dans un pool de périphériques distinct avec d’autres pilotes de priorité similaire. Étant donné que le pool d’appareils supplémentaire utilise plus de mémoire, vous devez utiliser ce paramètre avec précaution. Pour plus d’informations sur le regroupement d’appareils, consultez Utilisation du regroupement d’appareils dans les pilotes UMDF.

UmdfRegisterAccessMode

Cette directive est prise en charge dans UMDF versions 1.11 et ultérieures.

UmdfRegisterAccessMode = <RegisterAccessUsingSystemCall | RegisterAccessUsingUserModeMapping>

Indique si l’infrastructure doit mapper les registres dans l’espace d’adressage en mode utilisateur (afin qu’un appel système ne soit pas impliqué dans l’accès aux registres) ou utiliser un appel système pour accéder aux registres.

Si UmdfRegisterAccessMode est défini sur RegisterAccessUsingSystemCall, l’infrastructure utilise un appel système pour accéder aux registres.

Si UmdfRegisterAccessMode est défini sur RegisterAccessUsingUserModeMapping, l’infrastructure mappe les registres dans l’espace d’adressage en mode utilisateur afin qu’un appel système ne soit pas nécessaire pour accéder aux registres. La valeur par défaut est RegisterAccessUsingSystemCall.

UmdfServiceOrder

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

Répertorie l’ordre dans lequel le co-programme d’installation installe les pilotes UMDF sur la pile des appareils. Même si le co-programme d’installation n’installe qu’un seul pilote UMDF sur la pile de périphériques, le fichier INF doit contenir cette directive. Les paramètres serviceNameXx correspondent aux paramètres serviceName pour chaque directive UmdfService . Étant donné que les pilotes UMDF sont ajoutés à la pile d’appareils dans l’ordre dans lequel ils sont répertoriés, le premier paramètre spécifie le pilote UMDF le plus bas dans la pile de périphériques.

Pour garantir qu’un co-programme d’installation UMDF installe l’appareil, une seule directive UmdfServiceOrder doit être présente dans une section DDInstall spécifique à WDF donnée. Autrement dit, la directive UmdfServiceOrder ne peut pas être importée à l’aide des directives Include et Needs .

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

Informe l’infrastructure du niveau maximal d’emprunt d’identité que le pilote UMDF peut avoir. Une directive UmdfImpersonationLevel est facultative ; si aucun niveau d’emprunt d’identité n’est spécifié, la valeur par défaut est Identification. Lorsqu’une application ouvre un handle de fichier, l’application peut accorder un niveau d’emprunt d’identité plus élevé au pilote. Toutefois, le pilote ne peut pas appeler la méthode IWDFIoRequest::Impersonate pour demander un niveau d’emprunt d’identité supérieur au niveau spécifié par UmdfImpersonationLevel . Les valeurs possibles pour cette directive sont les suivantes :

  • Anonyme

  • Identification

  • Emprunt d'identité

  • La délégation

Ces valeurs correspondent aux valeurs spécifiées dans l’énumération SECURITY_IMPERSONATION_LEVEL .

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <Copy | Reject>

Indique si l’infrastructure accepte (Copier) ou rejette (Rejeter) les demandes d’E/S d’un appareil, si les objets de demande contiennent des codes de contrôle d’E/S qui spécifient la méthode d’accès à la mémoire tampon METHOD_NEITHER. Une directive UmdfMethodNeitherAction est facultative. Si la directive n’est pas spécifiée, la valeur par défaut est Reject.

Pour plus d’informations sur la prise en charge de la méthode d’accès à la mémoire tampon METHOD_NEITHER dans les pilotes basés sur UMDF, consultez Utilisation de ni d’E/S mises en mémoire tampon ni d’E/S directes dans les pilotes UMDF.

UmdfDispatcher

UmdfDispatcher = <FileHandle | WinUsb | NativeUSB>

Indique à l’infrastructure où envoyer les E/S une fois que les E/S passent par la partie en mode utilisateur de la pile d’appareils. Par défaut, les E/S sont envoyées au réflecteur (WUDFRd.sys). En définissant UmdfDispatcher sur WinUsb, le pilote indique à UMDF d’envoyer des E/S à l’architecture WinUsb. À compter d’UMDF 2.15, si vous spécifiez NativeUSB , le réflecteur gère les E/S USB.

  • Si un pilote de la pile utilise une cible basée sur un handle de fichier, définissez cette directive sur FileHandle.
  • Si le pilote utilise UMDF 2.15 ou version ultérieure et utilise des cibles d’E/S USB, définissez cette directive sur NativeUSB.
  • Si le pilote est antérieur à UMDF 2.15 et utilise des cibles d’E/S USB, définissez cette directive sur WinUsb.

Une directive UmdfDispatcher est facultative.

L’exemple de code suivant montre la directive UmdfDispatcher dans une section DDInstall spécifique à WDF.

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

Cette directive est prise en charge dans les versions UMDF 1.9 et ultérieures.

UmdfKernelModeClientPolicy = <AllowKernelModeClients | RejectKernelModeClients>

Pour autoriser le chargement des pilotes en mode noyau au-dessus d’un pilote en mode utilisateur dans les versions antérieures d’UMDF, consultez Prise en charge du client en mode noyau dans les versions antérieures d’UMDF.

Indique si l’infrastructure doit autoriser le pilote à recevoir des demandes d’E/S de pilotes en mode noyau.

Si UmdfKernelModeClientPolicy est défini sur AllowKernelModeClients, l’infrastructure permet aux pilotes en mode noyau de se charger au-dessus d’un pilote en mode utilisateur et remet les demandes d’E/S des pilotes en mode noyau au pilote en mode utilisateur.

Si UmdfKernelModeClientPolicy est défini sur RejectKernelModeClients, l’infrastructure n’autorise pas le chargement des pilotes en mode noyau au-dessus d’un pilote en mode utilisateur et ne remet pas les demandes d’E/S des pilotes en mode noyau au pilote en mode utilisateur. Si le fichier INF d’un pilote ne contient pas cette directive, la valeur par défaut est RejectKernelModeClients. Pour plus d’informations, consultez Prise en charge des clients en mode noyau.

UmdfFileObjectPolicy

Cette directive est prise en charge dans UMDF versions 1.11 et ultérieures.

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects | AllowNullAndUnknownFileObjectss>

Indique si l’infrastructure doit autoriser le traitement des demandes d’E/S (IWDFIoRequest) qui ne sont pas associées à un objet de fichier (IWDFFile) ou qui sont associées à un objet fichier inconnu (objet file pour lequel un pilote n’a pas encore vu de demande de création).

Si UmdfFileObjectPolicy est défini sur RejectNullAndUnknownFileObjects, l’infrastructure n’autorise pas le traitement des demandes associées à un objet de fichier NULL ou inconnu.

Si UmdfFileObjectPolicy est défini sur AllowNullAndUnknownFileObjects, l’infrastructure autorise le traitement des requêtes associées à un objet de fichier NULL ou inconnu.

La valeur par défaut est RejectNullAndUnknownFileObjects.

UmdfFsContextUsePolicy

Cette directive est prise en charge dans UMDF versions 1.11 et ultérieures.

UmdfFsContextUsePolicy = <CanUseFsContext | CanUseFsContext2 | CannotUseFsContexts>

Indique si l’infrastructure peut stocker des informations internes dans des membres de contexte spécifiques d’un objet de fichier WDM. Si un pilote en mode noyau dans la même pile utilise un membre particulier de l’objet file, vous pouvez utiliser cette directive pour demander que l’infrastructure n’utilise pas le même emplacement.

Si UmdfFsContextUsePolicy est défini sur CanUseFsContext, l’infrastructure stocke les informations dans le membre FsContext de l’objet de fichier WDM.

Si UmdfFsContextUsePolicy est défini sur CanUseFsContext2, l’infrastructure stocke des informations dans le membre FsContext2 de l’objet de fichier WDM.

Si UmdfFsContextUsePolicy est défini sur CannotUseFsContexts, le framework n’utilise pas FsContext ou FsContext2.

La valeur par défaut est CanUseFsContext.

[Directives UMDF pour la section wdf-service-install]

Voici un exemple de code. Chaque directive spécifique à UMDF dans la section [wdf-service-install] est décrite ci-dessous. Le nom de la section est spécifié dans une directive UmdfService de la section [DDInstall.wdf].

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

UmdfLibraryVersion

UmdfLibraryVersion = <version>

Informe le co-programme d’installation du numéro de version du framework que le pilote UMDF utilisera. Le format de la chaîne de version est <majeur>.<mineur.><service>. Lorsque les pilotes de la pile de périphériques utilisent plusieurs versions de l’infrastructure, le fichier INF copie plusieurs co-programmes d’installation (un pour chaque version du framework) au même emplacement sur le lecteur de disque dur. Toutefois, le fichier INF ajoute uniquement le co-programme d’installation de version la plus élevée à la valeur de Registre CoInstallers32 . Pour plus d’informations sur la copie de co-programmes d’installation, consultez Utilisation du co-programme d’installation UMDF.

Le co-programme d’installation vérifie la chaîne de version et l’utilise pour localiser le co-programme d’installation spécifique à la version pour le pilote UMDF. Le co-programme d’installation extrait ensuite le framework du co-programme d’installation spécifique à la version.

ServiceBinary

ServiceBinary = <binarypath>

Indique à UMDF où placer le fichier binaire du pilote UMDF sur le lecteur de disque dur.

Les pilotes UMDF doivent être copiés dans le Windows\System32\Drivers\UMDF répertoire et exécutés à partir de .

DriverCLSID

Note Cette directive est uniquement prise en charge dans UMDF 1.x, qui est déconseillé. Pour plus d’informations, consultez le Guide de conception UMDF 1.x.

DriverCLSID = <{CLSID}>

Informe UMDF sur l’identificateur de classe (CLSID) du pilote UMDF. Quand UMDF charge le pilote UMDF, l’hôte UMDF utilise le CLSID du pilote UMDF pour créer un instance de l’interface IDriverEntry du pilote UMDF.

UmdfExtensions

UmdfExtensions = <cxServiceName>

Obligatoire pour les pilotes qui communiquent avec les pilotes d’extension de classe fournis par Microsoft. Le paramètre cxServiceName correspond au service associé au binaire du pilote d’extension de classe.

Les noms de service pour les pilotes d’extension de classe peuvent se trouver en tant que sous-clé sous la clé de Registre suivante : HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services

[Sections Directives KMDF pour DDInstall.WDF]

Voici un exemple de code. Chaque directive spécifique à KMDF dans la section DDInstall.WDF est décrite ci-dessous.

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

KmdfService

KmdfService = <serviceName>, <sectionName>

Associe un pilote KMDF à une section [wdf-service-install] qui contient les informations requises pour installer le pilote KMDF. Le paramètre serviceName spécifie le pilote KMDF et est limité à un maximum de 31 caractères. Le paramètre sectionName fait référence à la section [wdf-service-install]. Un fichier INF valide nécessite généralement au moins une directive KmdfService . Toutefois, si un pilote KMDF fait partie du système d’exploitation, une directive KmdfService pour le pilote KMDF n’est pas nécessaire. Par conséquent, un fichier INF valide peut ne pas avoir de directives KmdfService , bien que la plupart des fichiers INF aient une directive KmdfService pour chaque pilote KMDF.

[Section Directives KMDF pour wdf-service-install]

Voici un exemple de code. Chaque directive spécifique à KMDF dans la section [wdf-service-install] est décrite ci-dessous. Le nom de la section provient de la directive KmdfService dans la section DDInstall.wdf.

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

KmdfLibraryVersion

KmdfLibraryVersion = <version>

Le format de la chaîne de version est major.minor. Normalement, vous devez spécifier $KMDFVERSION$ et le processus de génération WDK le remplacera par le numéro de version correct.