Routine driverEntry per i driver WDF

  • Articolo

[Si applica a KMDF e UMDF]

DriverEntry è la prima routine fornita dal driver chiamata dopo il caricamento di un driver. È responsabile dell'inizializzazione del driver.

Sintassi

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

Parametri

DriverObject [in]
Puntatore a una struttura DRIVER_OBJECT che rappresenta l'oggetto driver WDM del driver.

RegistryPath [in]
Puntatore a una struttura UNICODE_STRING che specifica il percorso della chiave Parametri del driver nel Registro di sistema.

Valore restituito

Se la routine ha esito positivo, deve restituire STATUS_SUCCESS. In caso contrario, deve restituire uno dei valori di stato dell'errore definiti in ntstatus.h.

Commenti

Come tutti i driver WDM, i driver basati su framework devono avere una routine DriverEntry , chiamata dopo il caricamento del driver. La routine DriverEntry basata su framework deve:

  • Attivare la traccia software WPP.

    DriverEntry deve includere una macro WPP_INIT_TRACING per attivare la traccia software.

  • Chiamare WdfDriverCreate.

    La chiamata a WdfDriverCreate consente al driver di usare interfacce di Windows Driver Framework. Il driver non può chiamare altre routine del framework prima di chiamare WdfDriverCreate.

  • Allocare tutte le risorse di sistema specifiche del dispositivo e le variabili globali necessarie.

    In genere, i driver associano le risorse di sistema ai singoli dispositivi. Pertanto, i driver basati su framework allocano la maggior parte delle risorse in un callback EvtDriverDeviceAdd callback, che viene chiamato quando vengono rilevati singoli dispositivi.

    Poiché più istanze di un driver UMDF potrebbero essere ospitate da istanze separate di Wudfhost, una variabile globale potrebbe non essere disponibile in tutte le istanze di un driver UMDF.

  • Ottenere parametri specifici del driver dal Registro di sistema.

    Alcuni driver ottengono parametri dal Registro di sistema. Questi driver possono chiamare WdfDriverOpenParametersRegistryKey per aprire la chiave del Registro di sistema che contiene questi parametri.

  • Specificare un valore restituito driverEntry.

Nota Un driver UMDF viene eseguito in un processo host in modalità utente, mentre un driver KMDF viene eseguito in modalità kernel in un processo di sistema. Il framework potrebbe caricare più istanze di un driver UMDF in istanze separate del processo host. Di conseguenza:

  • Il framework potrebbe chiamare una routine driver UMDF più volte se carica istanze del driver in processi host diversi. Al contrario, il framework chiama una routine DriverEntry del driver kmDF una sola volta.
  • Se un driver UMDF crea una variabile globale nella routine DriverEntry, la variabile potrebbe non essere disponibile per tutte le istanze del driver. Tuttavia, una variabile globale creata da un driver KMDF nella routine DriverEntry è disponibile per tutte le istanze del driver.

Per altre informazioni su quando viene chiamata una routine driver basata su framework, vedere Compilazione e caricamento di un driver WDF.

La routine DriverEntry non è dichiarata nelle intestazioni WDK. Il verifica driver statico (SDV) e altri strumenti di verifica possono richiedere una dichiarazione, ad esempio quanto segue:

DRIVER_INITIALIZE MyDriverEntry;

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

Esempio

Nell'esempio di codice seguente viene illustrata la routine DriverEntry del driver di esempio Serial (KMDF).

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

Vedi anche

WdfDriverCreate

EvtDriverDeviceAdd