structure DRIVER_OBJECT (wdm.h)

Chaque objet de pilote représente l’image d’un pilote en mode noyau chargé. Le gestionnaire d’E/S alloue la structure DRIVER_OBJECT et la transmet en tant que paramètre d’entrée aux routines DriverEntry, AddDevice et Réinitialisation facultatives et à sa routine de déchargement , le cas échéant.

Un objet de 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 de pilote 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

Spécifie l’identificateur de type d’objet de l’objet pilote. Le gestionnaire d’E/S définit ce champ lorsqu’il alloue l’objet de pilote. Les pilotes ne doivent pas utiliser ou modifier ce champ.

Size

Spécifie la taille, en octets, de la structure d’objets du pilote. Le gestionnaire d’E/S définit ce champ lorsqu’il alloue l’objet de pilote. Les pilotes ne doivent pas utiliser ou modifier ce champ.

DeviceObject

Pointeur vers le premier objet d’appareil dans une liste liée d’objets d’appareil créés par le pilote. Ce champ lie tous les appareils créés par un seul pilote dans une liste. Ce membre est automatiquement mis à jour par le gestionnaire d’E/S lorsque le pilote appelle IoCreateDevice avec succès. Un pilote peut utiliser ce membre et le membre NextDevice de DEVICE_OBJECT pour parcourir la liste complète de tous les objets de périphérique créés par le pilote. Cela est particulièrement utile pendant le déchargement du pilote pour vous assurer que tous les objets d’appareil sont correctement nettoyés.

Flags

Contient des indicateurs définis par le système qui décrivent différents attributs et états du pilote. Ce champ fournit un emplacement d’indicateur extensible pour les objets de pilote. Ces indicateurs sont définis et gérés par le gestionnaire d’E/S et d’autres composants système. Les pilotes ne doivent pas modifier directement ce champ.

DriverStart

Pointe vers l’adresse virtuelle de base où l’image du pilote est chargée dans la mémoire système. Cette adresse représente le début de la section de code du pilote dans l’espace d’adressage du noyau. Le gestionnaire d’E/S définit cette valeur lorsque le pilote est chargé.

DriverSize

Spécifie la taille, en octets, de l’image du pilote en mémoire. Cette valeur représente l’empreinte mémoire totale du pilote chargé, y compris le code, les données et d’autres sections. Le gestionnaire d’E/S définit cette valeur lorsque le pilote est chargé.

DriverSection

Pointe vers l’objet de section du pilote, qui représente l’image du pilote dans le gestionnaire de mémoire. Il s’agit d’une structure système opaque utilisée en interne par le gestionnaire de mémoire et le chargeur. Les pilotes ne doivent pas accéder ou modifier ce membre.

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

Contient le nom de chaîne Unicode du pilote. Ce champ est utilisé par le thread du journal des erreurs pour déterminer le nom du pilote auquel une requête d’E/S est liée ou auquel elle a été liée. Il s’agit généralement de la forme \Driver\DriverName, où DriverName correspond au nom du service du pilote dans le Registre. Le gestionnaire d’E/S définit cette valeur en fonction de la configuration du Registre du pilote.

HardwareDatabase

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

FastIoDispatch

Pointeur vers une structure FAST_IO_DISPATCH définissant les points d’entrée d’E/S rapides du pilote. Ce pointeur facultatif pointe vers un tableau de points d’entrée alternatifs vers un pilote pour la prise en charge des E/S rapides. Les E/S rapides sont effectuées en appelant la routine de pilote directement avec des paramètres distincts, plutôt que d’utiliser le mécanisme d’appel IRP standard. Notez que ces fonctions peuvent uniquement être utilisées pour les E/S synchrones et lorsque le fichier est mis en cache. Ce membre est utilisé uniquement par les pilotes de système de fichiers (FSD) et les pilotes de transport réseau.

DriverInit

Adresse du point d’entrée de la routine DriverEntry du pilote. Le gestionnaire d’E/S définit ce champ pour qu’il pointe vers la fonction d’initialisation du pilote lorsque le pilote est chargé. Il s’agit de la première fonction appelée dans le pilote lorsqu’elle est chargée en mémoire, et elle est chargée d’initialiser l’objet du pilote et de configurer des routines de répartition.

DriverStartIo

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

DriverUnload

Point d’entrée de la routine Décharger du pilote, le cas échéant, défini par la routine DriverEntry lors de l’initialisation du pilote. Si un pilote n’a pas de routine décharger, ce membre est 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 principal IRP . Cette table de répartition de fonction principale doit être le dernier champ de l’objet afin qu’elle reste extensible. Chaque pilote doit définir des points d’entrée dans ce tableau pour le IRP_MJ_XXX demandes que le pilote gère. Pour plus d’informations, consultez Écriture de routines de répartition.

Pour aider 'analyse du code pour les pilotes, le vérificateur de pilotes statiques (SDV) et d’autres outils de vérification, chaque routine DispatchXxx est déclarée à l’aide du type DRIVER_DISPATCH, comme illustré 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 lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l'_Use_decl_annotations_ annotation à 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 les exigences relatives aux 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 annoter le comportement de la fonction.

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 trouve pas 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 son DispatchXxx points d’entrée dans l’objet pilote transmis à la routine DriverEntry lors du chargement du pilote. Un pilote de périphérique doit définir un ou plusieurs DispatchXxx points d’entrée pour le IRP_MJ_XXX que tout pilote du même type d’appareil est requis pour gérer. Un pilote de niveau supérieur doit définir un ou plusieurs DispatchXxx points d’entrée pour tous les IRP_MJ_XXX qu’il doit transmettre au pilote de périphérique sous-jacent. Sinon, un pilote n’est pas envoyé d’IRPs pour une IRP_MJ_XXX pour laquelle il ne configure pas de routine DispatchXxx dans l’objet du pilote. Pour plus d’informations sur l’ensemble de IRP_MJ_XXX que les pilotes pour différents types d’appareils sous-jacents doivent être gérés, consultez codes de fonction principaux IRP.

La routine DriverEntry définit également les AddDevicedu pilote, StartIo et/ou Décharger points d’entrée, le cas échéant, dans l’objet pilote.

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 lorsque le pilote est chargé. Un pilote reçoit un accès en lecture seule à cette chaîne.

L’entrée RegistryPath à la routine DriverEnt ry pointe vers la routine \Registry\Machine\System\CurrentControlSet\Services\DriverName, où l’entrée de valeur de DriverName identifie le pilote. Cette clé de Registre contient la configuration du service du pilote, notamment les valeurs suivantes :

• Démarrage : Lorsque le pilote doit être chargé (démarrage, système, automatique, demande ou désactivé)
• Type : type de service (pilote de noyau, pilote de système de fichiers, etc.)
• ErrorControl : Comment le système doit répondre si le pilote ne parvient pas à charger
• ImagePath : chemin d’accès au fichier binaire du pilote

Les pilotes peuvent stocker des données de configuration supplémentaires sous la sous-clé Parameters de leur clé de service. Comme pour l'HardwareDatabase dans l’objet du pilote d’entrée, un pilote reçoit un accès en lecture seule à cette chaîne.

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

Exigences

Voir aussi

DriverEntry

IoCreateDevice

IoDeleteDevice

startIo

décharger