структура DRIVER_OBJECT (wdm.h)

Статья
03/08/2023

Каждый объект драйвера представляет образ загруженного драйвера в режиме ядра. Указатель на объект driver — это входной параметр для процедур DriverEntry, AddDevice и необязательных подпрограмм Повторной инициализации драйвера, а также на его подпрограмму Unload , если таковые есть.

Объект драйвера является частично непрозрачным. Средства записи драйверов должны знать об определенных членах объекта драйвера для инициализации драйвера и его выгрузки, если драйвер можно выгрузить. Следующие элементы объекта driver доступны для драйверов.

Синтаксис

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;

Члены

Type

Определяет тип элемента CSHORT.

Size

Определяет размер элемента CSHORT.

DeviceObject

Указатель на объекты устройства, созданные драйвером. Этот элемент автоматически обновляется, когда драйвер успешно вызывает IoCreateDevice . Драйвер может использовать этот элемент и элемент NextDeviceDEVICE_OBJECT для пошагового просмотра списка всех объектов устройств, созданных драйвером.

Flags

Определяет флаги элементов ULONG.

DriverStart

Определяет элемент PVOIDDriverStart.

DriverSize

Определяет элемент ULONGDriverSize.

DriverSection

Определяет член PVOIDDriverSection.

DriverExtension

Указатель на расширение драйвера. Единственным доступным членом расширения драйвера является DriverExtension-AddDevice>, в котором подпрограмма DriverEntry драйвера хранит подпрограмму AddDevice драйвера.

DriverName

Определяет член UNICODE_STRINGDriverName.

HardwareDatabase

Указатель на путь \Registry\Machine\Hardware на сведения о конфигурации оборудования в реестре.

FastIoDispatch

Указатель на структуру, определяющую точки быстрого ввода-вывода драйвера. Этот элемент используется только FSD и драйверами сетевого транспорта.

DriverInit

Точка входа для подпрограммы DriverEntry , которая настраивается диспетчером ввода-вывода.

DriverStartIo

Точка входа для подпрограммы StartIo драйвера , если она имеется, которая задается подпрограммой DriverEntry при инициализации драйвера. Если в драйвере нет подпрограммы StartIo , этот элемент имеет значение NULL.

DriverUnload

Точка входа для подпрограммы выгрузки драйвера , если она имеется, которая задается подпрограммой DriverEntry при инициализации драйвера. Если в драйвере нет подпрограммы выгрузки , этот элемент имеет значение NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Таблица диспетчеризации, состоящая из массива точек входа для подпрограмм DispatchXxx драйвера . Значения индекса массива — это значения IRP_MJ_XXX, представляющие код каждой основной функции IRP. Каждый драйвер должен задавать точки входа в этом массиве для IRP_MJ_XXX запросов , обрабатываемых драйвером. Дополнительные сведения см. в разделе Написание подпрограмм диспетчеризации.

Чтобы упростить анализ кода для драйверов, средства проверки статических драйверов (SDV) и других средств проверки, каждая подпрограмма DispatchXxx объявляется с помощью типа DRIVER_DISPATCH, как показано в следующем примере кода:

DRIVER_DISPATCH DispatchXxx;

Затем подпрограмма обратного вызова реализуется следующим образом:

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

Тип функции DRIVER_DISPATCH определен в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку _Use_decl_annotations_в определение функции. Заметка _Use_decl_annotations_ гарантирует, что будут использоваться заметки, которые применяются к типу функции DRIVER_DISPATCH в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов WDM. Дополнительные сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.

Подпрограмма инициализации каждого драйвера в режиме ядра должна называться DriverEntry , чтобы система загружала драйвер автоматически. Если имя этой подпрограммы другое, модуль записи драйверов должен определить имя подпрограммы инициализации для компоновщика. в противном случае системный загрузчик или диспетчер операций ввода-вывода не могут найти адрес передачи драйвера. Названия других стандартных процедур драйвера можно выбрать по усмотрению модуля записи драйверов.

Драйвер должен задать точки входа DispatchXxx в объекте драйвера, который передается в подпрограмму DriverEntry при загрузке драйвера. Драйвер устройства должен задать одну или несколько точек входа DispatchXxx для IRP_MJ_XXXX , для обработки которыми требуется любой драйвер того же типа устройства. Драйвер более высокого уровня должен задать одну или несколько точек входа DispatchXxx для всех IRP_MJ_XXXX , которые он должен передать базовому драйверу устройства. В противном случае драйвер не отправляет irP для IRP_MJ_XXX, для которых не настроена подпрограмма DispatchXxx в объекте драйвера. Дополнительные сведения о наборе IRP_MJ_XXX, которые должны обрабатывать драйверы для различных типов базовых устройств, см. в разделе Основные коды функций IRP.

Подпрограмма DriverEntry также задает в объекте драйвера точки входа AddDevice, StartIo и (или ) Unload , если таковые есть.

Строка HardwareDatabase может использоваться драйверами устройств для получения сведений о конфигурации оборудования из реестра при загрузке драйвера. Драйверу предоставляется доступ только для чтения к этой строке.

Входные данные RegistryPath для подпрограммы DriverEntry указывают на раздел \Registry\Machine\System\CurrentControlSet\Services\DriverName , где запись значения DriverName идентифицирует драйвер. Что касается HardwareDatabase во входном объекте драйвера, драйверу предоставляется доступ только для чтения к этой строке.

Недокументированные члены в объекте драйвера должны считаться недоступными. Драйверы с зависимостями от расположений элементов объекта или доступа к незарегистрированных членам могут не оставаться переносимыми и совместимыми с другими драйверами с течением времени.