struttura DRIVER_OBJECT (wdm.h)

Articolo
03/08/2023

Ogni oggetto driver rappresenta l'immagine di un driver in modalità kernel caricato. Un puntatore all'oggetto driver è un parametro di input per DriverEntry, AddDevice e reinizializzare le routine facoltative e per la routine di scaricamento , se presente.

Un oggetto driver è parzialmente opaco. I writer di driver devono conoscere alcuni membri di un oggetto driver per inizializzare un driver e scaricarlo se il driver non è scaricabile. I membri seguenti dell'oggetto driver sono accessibili ai driver.

Sintassi

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;

Members

Type

Definisce il tipo di membro CSHORT.

Size

Definisce le dimensioni del membro CSHORT.

DeviceObject

Puntatore agli oggetti dispositivo creati dal driver. Questo membro viene aggiornato automaticamente quando il driver chiama correttamente IoCreateDevice . Un driver può usare questo membro e il membro NextDevice di DEVICE_OBJECT per eseguire un elenco di tutti gli oggetti dispositivo creati dal driver.

Flags

Definisce i flag dei membri ULONG.

DriverStart

Definisce il driver del membro PVOIDStart.

DriverSize

Definisce il membro ULONGDriverSize.

DriverSection

Definisce il driver del membro PVOIDSection.

DriverExtension

Puntatore all'estensione del driver. L'unico membro accessibile dell'estensione driver è DriverExtension-AddDevice>, in cui la routine DriverEntry di un driver archivia la routine AddDevice del driver.

DriverName

Definisce il driver delmembro UNICODE_STRING.

HardwareDatabase

Puntatore al percorso \Registry\Machine\Hardware alle informazioni di configurazione hardware nel Registro di sistema.

FastIoDispatch

Puntatore a una struttura che definisce i punti di ingresso di I/O rapidi del driver. Questo membro viene usato solo dagli FSD e dai driver di trasporto di rete.

DriverInit

Punto di ingresso per la routine DriverEntry , configurata dal gestore di I/O.

DriverStartIo

Punto di ingresso per la routine StartIo del driver, se presente, impostato dalla routine DriverEntry quando il driver inizializza. Se un driver non ha una routine StartIo , questo membro è NULL.

DriverUnload

Punto di ingresso per la routine di scaricamento del driver, se presente, impostato dalla routine DriverEntry quando il driver inizializza. Se un driver non ha una routine di scaricamento , questo membro è NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Tabella di invio costituita da una matrice di punti di ingresso per le routine DispatchXxx del driver. I valori di indice della matrice sono i valori IRP_MJ_XXX che rappresentano ogni codice di funzione principale IRP. Ogni driver deve impostare punti di ingresso in questa matrice per le richieste IRP_MJ_XXX gestite dal driver. Per altre informazioni, vedere Scrittura di routine di invio.

Per facilitare l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica, ogni routine DispatchXxx viene dichiarata usando il tipo di DRIVER_DISPATCH, come illustrato nell'esempio di codice seguente:

DRIVER_DISPATCH DispatchXxx;

La routine di callback viene quindi implementata come segue:

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

Il tipo di funzione DRIVER_DISPATCH viene definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione _Use_decl_annotations_ alla definizione della funzione. L'annotazione _Use_decl_annotations_ garantisce che vengano usate le annotazioni applicate al tipo di funzione DRIVER_DISPATCH nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver WDM. Per informazioni su _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.

Commenti

Ogni routine di inizializzazione in modalità kernel deve essere denominata DriverEntry in modo che il sistema caricherà automaticamente il driver. Se il nome di questa routine è un altro, il writer del driver deve definire il nome della routine di inizializzazione per il linker; in caso contrario, il caricatore di sistema o gestione I/O non riesce a trovare l'indirizzo di trasferimento del driver. I nomi di altre routine di driver standard possono essere scelti a discrezione del writer del driver.

Un driver deve impostare i punti di ingresso DispatchXxx nell'oggetto driver passato alla routine DriverEntry quando il driver viene caricato. Un driver di dispositivo deve impostare uno o più punti di ingresso DispatchXxx per il IRP_MJ_XXX necessario per gestire qualsiasi driver dello stesso tipo di dispositivo. Un driver di livello superiore deve impostare uno o più punti di ingresso DispatchXxx per tutti i IRP_MJ_XXX che deve passare al driver di dispositivo sottostante. In caso contrario, un driver non invia IRP per qualsiasi IRP_MJ_XXX per cui non configura una routine DispatchXxx nell'oggetto driver. Per altre informazioni sul set di IRP_MJ_XXX che i driver per diversi tipi di dispositivi sottostanti sono necessari per gestire, vedere Codici di funzione principali IRP.

La routine DriverEntry imposta anche i punti di ingresso AddDevice del driver, StartIo e/o Scarica punti di ingresso, se presenti, nell'oggetto driver.

La stringa HardwareDatabase può essere usata dai driver di dispositivo per ottenere informazioni di configurazione hardware dal Registro di sistema quando il driver viene caricato. Un driver ha accesso di sola lettura a questa stringa.

L'input di RegistryPath alla routine DriverEntry punta alla chiave \Registry\Machine\System\CurrentControlSet\Services\DriverName , dove la voce valore di DriverName identifica il driver. Come per HardwareDatabase nell'oggetto driver di input, viene assegnato un driver di sola lettura a questa stringa.

I membri non documentati all'interno di un oggetto driver devono essere considerati inaccessibili. I driver con dipendenze sulle posizioni dei membri dell'oggetto o sull'accesso ai membri non documentati potrebbero non rimanere portabili e interoperabili con altri driver nel tempo.