Rotina driverEntry para drivers WDF

[Aplica-se a KMDF e UMDF]

DriverEntry é a primeira rotina fornecida pelo driver 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 [in]
Um ponteiro para uma estrutura DRIVER_OBJECT que representa o objeto de driver WDM do driver.

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

Retornar valor

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

Comentários

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

• Ativar o rastreamento de software WPP.

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

• Chame 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 todos os recursos do sistema não específicos do dispositivo e as 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 chamada EvtDriverDeviceAdd , que é chamado quando dispositivos individuais são detectados.

  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 retornado de DriverEntry.

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

• A estrutura pode chamar a rotina DriverEntry de um driver UMDF várias vezes se carregar instâncias do driver em processos de host diferentes. Por outro lado, a estrutura chama uma rotina driverEntry do driver KMDF apenas uma vez.
• Se um driver UMDF criar uma variável global em sua rotina DriverEntry, a variável poderá 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 DriverEntry de um driver baseado em estrutura é chamada, consulte Compilando e carregando um driver WDF.

A rotina DriverEntry não é declarada em cabeçalhos do WDK. O SDV (Verificador de Driver Estático) 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 driverEntry do driver de exemplo (KMDF) serial.

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;
}

Confira também

WdfDriverCreate

EvtDriverDeviceAdd