estrutura DRIVER_OBJECT (wdm.h)

Artigo
02/27/2024

Cada objeto driver representa a imagem de um driver de modo kernel carregado. Um ponteiro para o objeto driver é um parâmetro de entrada para driverEntry, AddDevice e rotinas opcionais de Reinicialização e para sua rotina de descarregamento , se houver.

Um objeto driver é parcialmente opaco. Os gravadores de driver devem saber sobre determinados membros de um objeto de driver para inicializar um driver e descarregá-lo se o driver for descarregado. Os membros a seguir do objeto driver são acessíveis aos drivers.

Sintaxe

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;

Membros

Type

Define o tipo de membro CSHORT.

Size

Define o tamanho do membro CSHORT.

DeviceObject

Ponteiro para os objetos de dispositivo criados pelo driver. Esse membro é atualizado automaticamente quando o driver chama IoCreateDevice com êxito . Um driver pode usar esse membro e o membro NextDevice do DEVICE_OBJECT para percorrer uma lista de todos os objetos de dispositivo que o driver criou.

Flags

Define os Sinalizadores de membro ULONG.

DriverStart

Define o DriverStart membro PVOID.

DriverSize

Define o membro ULONGDriverSize.

DriverSection

Define o membro PVOIDDriverSection.

DriverExtension

Ponteiro para a extensão do driver. O único membro acessível da extensão de driver é DriverExtension-AddDevice>, no qual a rotina DriverEntry de um driver armazena a rotina AddDevice do driver.

DriverName

Define o UNICODE_STRING membro DriverName.

HardwareDatabase

Ponteiro para o caminho \Registry\Machine\Hardware para as informações de configuração de hardware no Registro.

FastIoDispatch

Ponteiro para uma estrutura que define os pontos de entrada de E/S rápidos do driver. Esse membro é usado apenas por FSDs e drivers de transporte de rede.

DriverInit

O ponto de entrada para a rotina DriverEntry , que é configurada pelo gerente de E/S.

DriverStartIo

O ponto de entrada para a rotina StartIo do driver, se houver, que é definido pela rotina DriverEntry quando o driver é inicializado. Se um driver não tiver rotina StartIo , esse membro será NULL.

DriverUnload

O ponto de entrada para a rotina de descarregamento do driver, se houver, que é definido pela rotina DriverEntry quando o driver é inicializado. Se um driver não tiver rotina de descarregamento , esse membro será NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Uma tabela de expedição que consiste em uma matriz de pontos de entrada para as rotinas DispatchXxx do driver. Os valores de índice da matriz são os valores IRP_MJ_XXX que representam cada código de função principal IRP. Cada driver deve definir pontos de entrada nessa matriz para as solicitações IRP_MJ_XXX que o driver manipula. Para obter mais informações, consulte Escrevendo rotinas de expedição.

Para ajudar a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação, cada rotina DispatchXxx é declarada usando o tipo DRIVER_DISPATCH, conforme mostrado neste exemplo de código:

DRIVER_DISPATCH DispatchXxx;

Em seguida, a rotina de retorno de chamada é implementada da seguinte maneira:

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

O tipo de função DRIVER_DISPATCH é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a _Use_decl_annotationsanotação _ à sua definição de função. A _Use_decl_annotations_ anotação garante que as anotações aplicadas ao tipo de função DRIVER_DISPATCH no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre _Use_decl_annotations_, consulte Anotando o comportamento da função.

Comentários

A rotina de inicialização de cada driver no modo kernel deve ser denominada DriverEntry para que o sistema carregue o driver automaticamente. Se o nome dessa rotina for outra coisa, o gravador de driver deverá definir o nome da rotina de inicialização para o vinculador; caso contrário, o carregador do sistema ou o gerente de E/S não podem encontrar o endereço de transferência do driver. Os nomes de outras rotinas de driver padrão podem ser escolhidos a critério do gravador de driver.

Um driver deve definir seus pontos de entrada DispatchXxx no objeto driver que é passado para a rotina DriverEntry quando o driver é carregado. Um driver de dispositivo deve definir um ou mais pontos de entrada DispatchXxx para o IRP_MJ_XXX que qualquer driver do mesmo tipo de dispositivo é necessário para manipular. Um driver de nível superior deve definir um ou mais pontos de entrada DispatchXxx para todos os IRP_MJ_XXX que ele deve passar para o driver de dispositivo subjacente. Caso contrário, um driver não será enviado a IRPs para nenhum IRP_MJ_XXX para o qual ele não configura uma rotina DispatchXxx no objeto driver. Para obter mais informações sobre o conjunto de IRP_MJ_XXX que os drivers para diferentes tipos de dispositivos subjacentes são necessários para lidar, consulte Códigos de Função Principais do IRP.

A rotina DriverEntry também define os pontos de entrada AddDevice, StartIo e/ou Unload do driver, se houver, no objeto driver.

A cadeia de caracteres HardwareDatabase pode ser usada por drivers de dispositivo para obter informações de configuração de hardware do registro quando o driver é carregado. Um driver recebe acesso somente leitura a essa cadeia de caracteres.

A entrada registryPath para a rotina DriverEntry aponta para a chave \Registry\Machine\System\CurrentControlSet\Services\DriverName , em que a entrada de valor de DriverName identifica o driver. Quanto ao HardwareDatabase no objeto de driver de entrada, um driver recebe acesso somente leitura a essa cadeia de caracteres.

Membros não documentados em um objeto driver devem ser considerados inacessíveis. Drivers com dependências em locais de membro do objeto ou no acesso a membros não documentados podem não permanecer portáteis e interoperáveis com outros drivers ao longo do tempo.