DRIVER_OBJECT structure (wdm.h)

Article
03/01/2024

Chaque objet pilote représente l’image d’un pilote en mode noyau chargé. Un pointeur vers l’objet pilote est un paramètre d’entrée vers les routines DriverEntry, AddDevice et facultatives Reinitialize d’un pilote, et vers sa routine Deload , le cas échéant.

Un objet pilote est partiellement opaque. Les enregistreurs de pilotes doivent connaître certains membres d’un objet pilote pour initialiser un pilote et le décharger si le pilote est déchargé. Les membres suivants de l’objet driver sont accessibles aux pilotes.

Syntaxe

typedef struct _DRIVER_OBJECT {
  CSHORT             Type;
  CSHORT             Size;
  PDEVICE_OBJECT     DeviceObject;
  ULONG              Flags;
  PVOID              DriverStart;
  ULONG              DriverSize;
  PVOID              DriverSection;
  PDRIVER_EXTENSION  DriverExtension;
  UNICODE_STRING     DriverName;
  PUNICODE_STRING    HardwareDatabase;
  PFAST_IO_DISPATCH  FastIoDispatch;
  PDRIVER_INITIALIZE DriverInit;
  PDRIVER_STARTIO    DriverStartIo;
  PDRIVER_UNLOAD     DriverUnload;
  PDRIVER_DISPATCH   MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1];
} DRIVER_OBJECT, *PDRIVER_OBJECT;

Membres

Type

Définit le type de membre CSHORT.

Size

Définit la taille du membre CSHORT.

DeviceObject

Pointeur vers les objets de périphérique créés par le pilote. Ce membre est automatiquement mis à jour lorsque le pilote appelle IoCreateDevice avec succès. Un pilote peut utiliser ce membre et le membre NextDevice de DEVICE_OBJECT pour parcourir une liste de tous les objets de périphérique créés par le pilote.

Flags

Définit les indicateurs de membre ULONG.

DriverStart

Définit le membre PVOIDDriverStart.

DriverSize

Définit le membre ULONGDriverSize.

DriverSection

Définit le membre PVOIDDriverSection.

DriverExtension

Pointeur vers l’extension du pilote. Le seul membre accessible de l’extension de pilote est DriverExtension-AddDevice>, dans lequel la routine DriverEntry d’un pilote stocke la routine AddDevice du pilote.

DriverName

Définit le UNICODE_STRING membre DriverName.

HardwareDatabase

Pointeur vers le chemin \Registry\Machine\Hardware vers les informations de configuration matérielle dans le Registre.

FastIoDispatch

Pointeur vers une structure définissant les points d’entrée d’E/S rapides du pilote. Ce membre est utilisé uniquement par les FSD et les pilotes de transport réseau.

DriverInit

Point d’entrée de la routine DriverEntry , qui est configurée par le gestionnaire d’E/S.

DriverStartIo

Point d’entrée de la routine StartIo du pilote, le cas échéant, qui est défini par la routine DriverEntry lors de l’initialisation du pilote. Si un pilote n’a pas de routine StartIo , ce membre est NULL.

DriverUnload

Point d’entrée de la routine de déchargement du pilote, le cas échéant, qui est défini par la routine DriverEntry lors de l’initialisation du pilote. Si un pilote n’a pas de routine Deload , ce membre a la valeur NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Table de répartition composée d’un tableau de points d’entrée pour les routines DispatchXxx du pilote. Les valeurs d’index du tableau sont les valeurs IRP_MJ_XXX représentant chaque code de fonction principale IRP. Chaque pilote doit définir des points d’entrée dans ce tableau pour les requêtes IRP_MJ_XXX qu’il gère. Pour plus d’informations, consultez Écriture de routines de dispatch.

Pour faciliter l’analyse du code pour les pilotes, le vérificateur de pilote statique (SDV) et d’autres outils de vérification, chaque routine DispatchXxx est déclarée à l’aide du type DRIVER_DISPATCH, comme indiqué dans cet exemple de code :

DRIVER_DISPATCH DispatchXxx;

Ensuite, la routine de rappel est implémentée comme suit :

_Use_decl_annotations_
NTSTATUS
  DispatchXxx(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Le type de fonction DRIVER_DISPATCH est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation _Use_decl_annotations_ à votre définition de fonction. L’annotation _Use_decl_annotations_ garantit que les annotations appliquées au type de fonction DRIVER_DISPATCH dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur _Use_decl_annotations_, consultez Annotating Function Behavior.

Remarques

La routine d’initialisation de chaque pilote en mode noyau doit être nommée DriverEntry afin que le système charge automatiquement le pilote. Si le nom de cette routine est autre chose, l’enregistreur de pilotes doit définir le nom de la routine d’initialisation pour l’éditeur de liens ; sinon, le chargeur système ou le gestionnaire d’E/S ne peut pas trouver l’adresse de transfert du pilote. Les noms d’autres routines de pilotes standard peuvent être choisis à la discrétion de l’enregistreur de pilotes.

Un pilote doit définir ses points d’entrée DispatchXxx dans l’objet driver qui est transmis à la routine DriverEntry lors du chargement du pilote. Un pilote de périphérique doit définir un ou plusieurs points d’entrée DispatchXxx pour le IRP_MJ_XXX que tout pilote du même type de périphérique doit gérer. Un pilote de niveau supérieur doit définir un ou plusieurs points d’entrée DispatchXxx pour tous les IRP_MJ_XXX qu’il doit transmettre au pilote de périphérique sous-jacent. Dans le cas contraire, un pilote n’est pas envoyé de runtimes d’intégration pour les IRP_MJ_XXX pour lesquels il ne configure pas de routine DispatchXxx dans l’objet pilote. Pour plus d’informations sur l’ensemble de IRP_MJ_XXX que les pilotes de différents types d’appareils sous-jacents doivent gérer, consultez Codes de fonction principaux IRP.

La routine DriverEntry définit également les points d’entrée AddDevice, StartIo et/ou Unload du pilote, le cas échéant, dans l’objet driver.

La chaîne HardwareDatabase peut être utilisée par les pilotes de périphérique pour obtenir des informations de configuration matérielle à partir du Registre lors du chargement du pilote. Un pilote a accès en lecture seule à cette chaîne.

L’entrée RegistryPath de la routine DriverEntry pointe vers la clé \Registry\Machine\System\CurrentControlSet\Services\DriverName , où l’entrée de valeur de DriverName identifie le pilote. Comme pour hardwareDatabase dans l’objet pilote d’entrée, un pilote a accès en lecture seule à cette chaîne.

Les membres non documentés au sein d’un objet pilote doivent être considérés comme inaccessibles. Les pilotes ayant des dépendances sur les emplacements des membres de l’objet ou sur l’accès à des membres non documentés peuvent ne pas rester portables et interopérables avec d’autres pilotes au fil du temps.