DriverEntry para WDF Drivers rotina

[Aplica-se a KMDF e UMDF]

DriverEntry é a primeira rotina fornecida pelo motorista que é chamada depois que um driver é carregado. Ele é responsável por inicializar o driver.

Sintaxe

NTSTATUS DriverEntry(
  _In_ PDRIVER_OBJECT  DriverObject,
  _In_ PUNICODE_STRING RegistryPath
);

Parâmetros

DriverObject [em]
Um ponteiro para uma estrutura DRIVER_OBJECT que representa o objeto de driver WDM do driver.

RegistryPath [em]
Um ponteiro para uma estrutura de UNICODE_STRING que especifica o caminho para a chave Parâmetros de do driver no Registro.

Valor de retorno

Se a rotina for bem-sucedida, ela deve voltar STATUS_SUCCESS. Caso contrário, ele deve retornar um dos valores de status de erro definidos em ntstatus.h.

Observações

Como todos os drivers WDM, os drivers baseados em estrutura devem ter uma rotina DriverEntry, que é chamada depois que o driver é carregado. A rotina de DriverEntry do motorista baseada em estrutura deve:

• Ative de rastreamento de software WPP.

  DriverEntry deve incluir uma macro WPP_INIT_TRACING para ativar o rastreamento de software.

• Ligue WdfDriverCreate.

  A chamada para WdfDriverCreate permite que o driver use interfaces do Windows Driver Framework. (O driver não pode chamar outras rotinas de estrutura antes de chamar WdfDriverCreate.)

• Aloque quaisquer recursos de sistema não específicos do dispositivo e variáveis globais que ele possa precisar.

  Normalmente, os drivers associam recursos do sistema a dispositivos individuais. Portanto, os drivers baseados em estrutura alocam a maioria dos recursos em um retorno de chamadaEvtDriverDeviceAdd, que é chamado quando dispositivos individuais são detetados.

  Como várias instâncias de um driver UMDF podem ser hospedadas por instâncias separadas do Wudfhost, uma variável global pode não estar disponível em todas as instâncias de um driver UMDF.

• Obtenha parâmetros específicos do driver do registro.

  Alguns drivers obtêm parâmetros do registro. Esses drivers podem chamar WdfDriverOpenParametersRegistryKey para abrir a chave do Registro que contém esses parâmetros.

• Forneça um valor de retorno DriverEntry.

Observação Um driver UMDF é executado em um processo de host de modo de usuário, enquanto um driver KMDF é executado no modo kernel em um processo de sistema. A estrutura pode carregar várias instâncias de um driver UMDF em instâncias separadas do processo do host. Como resultado:

• A estrutura pode chamar a rotina DriverEntry de um driver UMDF várias vezes se carregar instâncias do driver em diferentes processos de host. Por outro lado, a estrutura chama a rotina DriverEntry de um driver KMDF apenas uma vez.
• Se um driver UMDF cria uma variável global em sua rotina DriverEntry, a variável pode não estar disponível para todas as instâncias do driver. No entanto, uma variável global que um driver KMDF cria em sua rotina DriverEntry está disponível para todas as instâncias do driver.

Para obter mais informações sobre quando a rotina de DriverEntry de um driver baseado em estrutura é chamada, consulte Criando e carregando um driver WDF.

A rotina DriverEntry não é declarada nos cabeçalhos WDK. O Verificador de Driver Estático (SDV) e outras ferramentas de verificação podem exigir uma declaração como a seguinte:

DRIVER_INITIALIZE MyDriverEntry;

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
// Function body
}

Exemplos

O exemplo de código a seguir mostra a rotina de DriverEntry do driver de exemplo Serial (KMDF) DriverEntry.

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    WDFDRIVER  hDriver;
    NTSTATUS  status;
    WDF_OBJECT_ATTRIBUTES  attributes;
    SERIAL_FIRMWARE_DATA driverDefaults;

    //
    // Initialize WPP tracing.
    //
    WPP_INIT_TRACING(
                     DriverObject,
                     RegistryPath
                     );

    SerialDbgPrintEx(
                     TRACE_LEVEL_INFORMATION,
                     DBG_INIT,
                     "Serial Sample (WDF Version) - Built %s %s\n",
                     __DATE__, __TIME__
                     );
    //
    // Register a cleanup callback function (which calls WPP_CLEANUP)
    // for the framework driver object. The framework will call
    // the cleanup callback function when it deletes the driver object,
    // before the driver is unloaded.
    //
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    attributes.EvtCleanupCallback = SerialEvtDriverContextCleanup;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           SerialEvtDeviceAdd
                           );

    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             &attributes,
                             &config,
                             &hDriver
                             );
    if (!NT_SUCCESS(status)) {
        SerialDbgPrintEx(
                         TRACE_LEVEL_ERROR,
                         DBG_INIT,
                         "WdfDriverCreate failed with status 0x%x\n",
                         status
                         );
        //
        // Clean up tracing here because WdfDriverCreate failed.
        //
        WPP_CLEANUP(DriverObject);
        return status;
    }

    //
    // Call an internal routine to obtain registry values
    // to use for all the devices that the driver 
    // controls, including whether or not to break on entry.
    //
    SerialGetConfigDefaults(
                            &driverDefaults,
                            hDriver
                            );

    //
    // Break on entry if requested bt registry value.
    //
    if (driverDefaults.ShouldBreakOnEntry) {
        DbgBreakPoint();
    }

    return status;
}

Ver também

WdfDriverCreate

EvtDriverDeviceAdicionar