Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM

  • Article

Notes

À compter de Windows 10 version 2004, le vérificateur de pilotes statiques (SDV) n’a plus besoin d’annotations pour identifier les types de rôles des routines de répartition pour les pilotes WDM. Suivez les conseils de la section Initialisations de base et avancées de cette page.

Pour informer SDV des points d’entrée du pilote lorsque vous analysez un pilote WDM, vous devez déclarer des fonctions à l’aide de déclarations de type de rôle de fonction. Les types de rôles de fonction sont définis dans Wdm.h. Chaque point d’entrée de la routine DriverEntry dans votre pilote WDM doit être déclaré en spécifiant le type de rôle correspondant. Les types de rôles sont des typedefs prédéfinis qui correspondent aux points d’entrée reconnus dans un pilote WDM.

Par exemple, pour créer une déclaration de type de rôle de fonction pour la routine de déchargement d’un pilote appelée CsampUnload, utilisez la déclaration de type de rôle prédéfinie typedef DRIVER_UNLOAD. La déclaration de type de rôle de fonction doit apparaître avant la définition de fonction.

DRIVER_UNLOAD CsampUnload;

La définition de la fonction CsampUnload reste inchangée :

VOID
CsampUnload(
    IN PDRIVER_OBJECT DriverObject
    )
{
    ...
}

SDV reconnaît les types de points d’entrée indiqués dans le tableau suivant.

Type de rôle de fonction WDM Routine WDM

DRIVER_INITIALIZE

DriverEntry

DRIVER_STARTIO

StartIO

DRIVER_UNLOAD

Décharger

DRIVER_ADD_DEVICE

AddDevice

Dispatch_type(type) DRIVER_DISPATCH

Routine(s) de répartition utilisées par le pilote. Consultez Écriture de routines de répartition.

IO_COMPLETION_ROUTINE

IoCompletion

La routine IoCompletion est définie en appelant IoSetCompletionRoutine ou IoSetCompletionRoutineEx et en passant le pointeur de fonction vers la routine IoCompletion comme deuxième paramètre.

DRIVER_CANCEL

Annuler

La routine Cancel est définie en appelant IoSetCancelRoutine et en passant le pointeur de fonction vers la routine d’annulation pour l’IRP en tant que deuxième paramètre de la fonction.

IO_DPC_ROUTINE

DpcForIsr

La routine DpcForIsr est inscrite en appelant IoInitializeDpcRequest et en passant le pointeur de fonction vers la routine DpcForIsr comme deuxième paramètre. Pour mettre en file d’attente la DPC, appelez IoQueueDpc à partir de la routine ISR en utilisant le même objet DPC.

KDEFERRED_ROUTINE

CustomDpc

La routine CustomDpc est définie en appelant KeInitializeDpc et en passant le pointeur de fonction vers customDpc comme deuxième paramètre. Pour mettre en file d’attente le CustomDpc pour le pilote, appelez KeInsertQueueDpc à partir de la routine ISR en utilisant le même objet DPC.

KSERVICE_ROUTINE

InterruptService

La routine InterruptService (ISR) traite une interruption d’appareil et planifie le traitement post-interruption des données reçues, si nécessaire.

REQUEST_POWER_COMPLETE

La routine de rappel PowerCompletion termine le traitement d’un IRP d’alimentation. Si le pilote doit effectuer des tâches supplémentaires une fois que tous les autres pilotes ont terminé l’IRP, il inscrit une routine de rappel PowerCompletion pendant l’appel à la routine PoRequestPowerIrp qui alloue l’IRP.

WORKER_THREAD_ROUTINE

Routine

Routine est la routine de rappel spécifiée dans le deuxième paramètre de la fonction ExInitializeWorkItem .

La routine ne doit être déclarée de cette façon que si le pilote appelle ExQueueWorkItem pour ajouter l’élément de travail à une file d’attente système.

Déclaration des routines de répartition des pilotes

À compter de Windows 10 version 2004, les déclarations de type de rôle de fonction pour les routines de distribution sont affinées automatiquement avec leur catégorie IRP en fonction de l’initialisation de la table DriverObject-MajorFunction> dans la routine DriverEntry d’un pilote WDM.

Un pilote Foo doit effectuer des déclarations de rôle en utilisant le style de déclaration de base ou avancé pour être conforme à SDV.

Initialisations de base et avancées

Le style de base peut être vu dans l’exemple ci-dessous (notez que les noms de routine de répartition FooCreate et FooCleanup ne sont que des exemples, n’importe quel nom approprié peut être utilisé) :

DriverObject->MajorFunction[IRP_MJ_CREATE] = FooCreate; //Basic style
DriverObject->MajorFunction[IRP_MJ_CLEANUP] = FooCleanup;

Une approche plus avancée peut être adoptée pour raccourcir la liste requise. Bien que la même routine de répartition soit utilisée pour plusieurs catégories IRP, un pilote peut encoder deux initialisations de cette façon :

DriverObject->MajorFunction[IRP_MJ_CREATE] = 
DriverObject->MajorFunction[IRP_MJ_CLEANUP] = FooCreateCleanup; // Advanced style for a multi-role dispatch routine

Pour qu’un pilote puisse exécuter SDV correctement, il doit uniquement utiliser le style de base ou avancé ci-dessus. La vérification SDV sur le pilote ne fonctionnera pas comme prévu si l’une de ces deux méthodes n’est pas utilisée.

Paramètres de fonction et types de rôles de fonction

Comme requis dans le langage de programmation C, les types de paramètres que vous utilisez dans la définition de fonction doivent correspondre aux types de paramètres du prototype de fonction, ou dans ce cas, au type de rôle de fonction. SDV dépend des signatures de fonction pour l’analyse et ignore les fonctions dont les signatures ne correspondent pas.

Par exemple, vous devez déclarer une routine IoCompletion à l’aide du type de rôle de fonction IO_COMPLETION_ROUTINE :

IO_COMPLETION_ROUTINE myCompletionRoutine;

Lorsque vous implémentez myCompletionRoutine, les types de paramètres doivent correspondre à ceux utilisés par IO_COMPLETION_ROUTINE, à savoir PDEVICE_OBJECT, PIRP et PVOID (voir routine IoCompletion pour la syntaxe).

NTSTATUS
myCompletionRoutine(
 PDEVICE_OBJECT  DeviceObject,
 PIRP  Irp,
 PVOID  Context
 )
{
}

Exécution de l’analyse du code pour les pilotes pour vérifier les déclarations de fonction

Pour vous aider à déterminer si le code source est préparé, exécutez Analyse du code pour les pilotes. L’analyse du code pour les pilotes vérifie les déclarations de type de rôle de fonction et peut vous aider à identifier les déclarations de fonction qui peuvent avoir été manquées ou vous avertir lorsque les paramètres de la définition de fonction ne correspondent pas à ceux du type de rôle de fonction.