DriverEntry für WDF-Treiberroutine

[Gilt für KMDF und UMDF]

DriverEntry ist die erste vom Treiber bereitgestellte Routine, die aufgerufen wird, nachdem ein Treiber geladen wurde. Er ist für die Initialisierung des Treibers verantwortlich.

Syntax

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

Parameter

DriverObject [in]
Ein Zeiger auf eine DRIVER_OBJECT Struktur, die das WDM-Treiberobjekt des Treibers darstellt.

RegistryPath [in]
Ein Zeiger auf eine UNICODE_STRING-Struktur , die den Pfad zum Parameterschlüssel des Treibers in der Registrierung angibt.

Rückgabewert

Wenn die Routine erfolgreich ist, muss sie STATUS_SUCCESS zurückgeben. Andernfalls muss einer der Fehlerwerte status zurückgegeben werden, die in ntstatus.h definiert sind.

Hinweise

Wie alle WDM-Treiber müssen frameworkbasierte Treiber über eine DriverEntry-Routine verfügen, die nach dem Laden des Treibers aufgerufen wird. Die DriverEntry-Routine eines frameworkbasierten Treibers muss:

• Aktivieren Sie die WPP-Softwareablaufverfolgung.

  DriverEntry sollte ein WPP_INIT_TRACING Makro zum Aktivieren der Softwareablaufverfolgung enthalten.

• Rufen Sie WdfDriverCreate auf.

  Der Aufruf von WdfDriverCreate ermöglicht dem Treiber die Verwendung von Windows Driver Framework-Schnittstellen. (Der Treiber kann vor dem Aufrufen von WdfDriverCreate keine anderen Frameworkroutinen aufrufen.)

• Ordnen Sie alle nicht gerätespezifischen Systemressourcen und globalen Variablen zu, die möglicherweise benötigt werden.

  In der Regel ordnen Treiber Systemressourcen einzelnen Geräten zu. Daher weisen frameworkbasierte Treiber die meisten Ressourcen in einem EvtDriverDeviceAdd-Rückruf zu, der aufgerufen wird, wenn einzelne Geräte erkannt werden.

  Da mehrere Instanzen eines UMDF-Treibers möglicherweise von separaten Instanzen von Wudfhost gehostet werden, ist eine globale Variable möglicherweise nicht für alle Instanzen eines UMDF-Treibers verfügbar.

• Rufen Sie treiberspezifische Parameter aus der Registrierung ab.

  Einige Treiber erhalten Parameter aus der Registrierung. Diese Treiber können WdfDriverOpenParametersRegistryKey aufrufen, um den Registrierungsschlüssel zu öffnen, der diese Parameter enthält.

• Geben Sie einen DriverEntry-Rückgabewert an.

Hinweis Ein UMDF-Treiber wird in einem Hostprozess im Benutzermodus ausgeführt, während ein KMDF-Treiber im Kernelmodus in einem Systemprozess ausgeführt wird. Das Framework lädt möglicherweise mehrere Instanzen eines UMDF-Treibers in separate Instanzen des Hostprozesses. Infolgedessen:

• Das Framework kann die DriverEntry-Routine eines UMDF-Treibers mehrmals aufrufen, wenn Instanzen des Treibers in verschiedenen Hostprozessen geladen werden. Im Gegensatz dazu ruft das Framework die DriverEntry-Routine eines KMDF-Treibers nur einmal auf.
• Wenn ein UMDF-Treiber eine globale Variable in seiner DriverEntry-Routine erstellt, ist die Variable möglicherweise nicht für alle Instanzen des Treibers verfügbar. Eine globale Variable, die ein KMDF-Treiber in seiner DriverEntry-Routine erstellt, ist jedoch für alle Instanzen des Treibers verfügbar.

Weitere Informationen dazu, wann die DriverEntry-Routine eines frameworkbasierten Treibers aufgerufen wird, finden Sie unter Erstellen und Laden eines WDF-Treibers.

Die DriverEntry-Routine wird in WDK-Headern nicht deklariert. Statische Treiberüberprüfung (Static Driver Verifier, SDV) und andere Überprüfungstools erfordern möglicherweise eine Deklaration wie die folgende:

DRIVER_INITIALIZE MyDriverEntry;

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

Beispiele

Das folgende Codebeispiel zeigt die DriverEntry-Routine des Treibers "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;
}

Weitere Informationen

WdfDriverErstellen

EvtDriverDeviceAdd