estructura DRIVER_OBJECT (wdm.h)

Artículo
03/08/2023

Cada objeto de controlador representa la imagen de un controlador en modo kernel cargado. Un puntero al objeto de controlador es un parámetro de entrada para driver's DriverEntry, AddDevice y opcional Reinitialize routines y a su rutina Unload , si existe.

Un objeto de controlador es parcialmente opaco. Los escritores de controladores deben conocer determinados miembros de un objeto de controlador para inicializar un controlador y descargarlo si el controlador es descargable. Los siguientes miembros del objeto driver son accesibles para los controladores.

Sintaxis

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;

Miembros

Type

Define el tipo de miembro de CSHORT.

Size

Define el tamaño del miembro de CSHORT.

DeviceObject

Puntero a los objetos de dispositivo creados por el controlador. Este miembro se actualiza automáticamente cuando el controlador llama a IoCreateDevice correctamente. Un controlador puede usar este miembro y el miembro NextDevice de DEVICE_OBJECT para recorrer una lista de todos los objetos de dispositivo creados por el controlador.

Flags

Define las marcas de miembro de ULONG.

DriverStart

Define el miembro PVOIDDriverStart.

DriverSize

Define el driverSize miembro de ULONG.

DriverSection

Define el elemento miembro PVOIDDriverSection.

DriverExtension

Puntero a la extensión del controlador. El único miembro accesible de la extensión del controlador es DriverExtension-AddDevice>, en el que la rutina DriverEntry de un controlador almacena la rutina AddDevice del controlador.

DriverName

Define el UNICODE_STRING miembro DriverName.

HardwareDatabase

Puntero a la ruta de acceso \Registry\Machine\Hardware a la información de configuración de hardware del Registro.

FastIoDispatch

Puntero a una estructura que define los puntos de entrada de E/S rápidos del controlador. Este miembro solo lo usan FSD y controladores de transporte de red.

DriverInit

El punto de entrada de la rutina DriverEntry , que el administrador de E/S configura.

DriverStartIo

Punto de entrada de la rutina StartIo del controlador, si existe, que establece la rutina DriverEntry cuando se inicializa el controlador. Si un controlador no tiene ninguna rutina StartIo , este miembro es NULL.

DriverUnload

El punto de entrada de la rutina Unload del controlador, si existe, que establece la rutina DriverEntry cuando se inicializa el controlador. Si un controlador no tiene ninguna rutina Unload , este miembro es NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Tabla de distribución que consta de una matriz de puntos de entrada para las rutinas DispatchXxx del controlador. Los valores de índice de la matriz son los valores IRP_MJ_XXX que representan cada código de función principal de IRP. Cada controlador debe establecer puntos de entrada en esta matriz para las solicitudes IRP_MJ_XXX que controla el controlador. Para obtener más información, vea Escribir rutinas de distribución.

Para ayudar a análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación, cada rutina DispatchXxx se declara mediante el tipo DRIVER_DISPATCH, como se muestra en este ejemplo de código:

DRIVER_DISPATCH DispatchXxx;

A continuación, la rutina de devolución de llamada se implementa de la siguiente manera:

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

El tipo de función DRIVER_DISPATCH se define en el archivo de encabezado Wdm.h. Para identificar con mayor precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación _ a la _Use_decl_annotationsdefinición de la función. La _Use_decl_annotations_ anotación garantiza que se usen las anotaciones que se aplican al tipo de función DRIVER_DISPATCH en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de rol de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, vea Anotación del comportamiento de la función.

Comentarios

Cada rutina de inicialización del controlador en modo kernel debe denominarse DriverEntry , por lo que el sistema cargará el controlador automáticamente. Si el nombre de esta rutina es algo más, el escritor del controlador debe definir el nombre de la rutina de inicialización para el enlazador; de lo contrario, el cargador del sistema o el administrador de E/S no pueden encontrar la dirección de transferencia del controlador. Los nombres de otras rutinas de controlador estándar se pueden elegir a discreción del escritor de controladores.

Un controlador debe establecer sus puntos de entrada DispatchXxx en el objeto de controlador que se pasa a la rutina DriverEntry cuando se carga el controlador. Un controlador de dispositivo debe establecer uno o varios puntos de entrada DispatchXxx para el IRP_MJ_XXX que cualquier controlador del mismo tipo de dispositivo debe controlar. Un controlador de nivel superior debe establecer uno o varios puntos de entrada DispatchXxx para todos los IRP_MJ_XXX que debe pasar al controlador de dispositivo subyacente. De lo contrario, un controlador no se envía IRP para ninguna IRP_MJ_XXX para la que no configura una rutina DispatchXxx en el objeto de controlador. Para obtener más información sobre el conjunto de IRP_MJ_XXX que los controladores para distintos tipos de dispositivos subyacentes son necesarios para controlar, consulte IrP Major Function Codes(Códigos de función principales de IRP).

La rutina DriverEntry también establece los puntos de entrada AddDevice, StartIo o Unload del controlador, si los hay, en el objeto del controlador.

Los controladores de dispositivo pueden usar la cadena HardwareDatabase para obtener información de configuración de hardware del Registro cuando se carga el controlador. A un controlador se le concede acceso de solo lectura a esta cadena.

La entrada RegistryPath de la rutina DriverEntry apunta a la clave \Registry\Machine\System\CurrentControlSet\Services\DriverName , donde la entrada de valor driverName identifica el controlador. En cuanto a HardwareDatabase en el objeto de controlador de entrada, se concede acceso de solo lectura a esta cadena.

Los miembros no documentados de un objeto de controlador deben considerarse inaccesibles. Es posible que los controladores con dependencias en ubicaciones de miembros de objeto o en el acceso a miembros no documentados no permanezcan portátiles e interoperables con otros controladores a lo largo del tiempo.