DriverEntry für WDF-Treiberroutine
[Gilt für KMDF und UMDF]
DriverEntry ist die erste vom Treiber bereitgestellte Routine, die nach dem Laden eines Treibers aufgerufen wird. Er ist für die Initialisierung des Treibers verantwortlich.
Syntax
NTSTATUS DriverEntry(
_In_ PDRIVER_OBJECT DriverObject,
_In_ PUNICODE_STRING RegistryPath
);
Die 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 angibt, in der Registrierung.
Rückgabewert
Wenn die Routine erfolgreich ist, muss sie STATUS_SUCCESS zurückgeben. Andernfalls muss eine der Fehlerstatuswerte zurückgegeben werden, die in ntstatus.hdefiniert sind.
Bemerkungen
Wie alle WDM-Treiber müssen frameworkbasierte Treiber über eine DriverEntry Routine verfügen, die aufgerufen wird, nachdem der Treiber geladen wurde. Die DriverEntry eines frameworkbasierten Treibers Routine muss:
Aktivieren Sie WPP-Softwareablaufverfolgung.
DriverEntry- sollte ein WPP_INIT_TRACING Makro enthalten, um die Softwareablaufverfolgung zu aktivieren.
Rufen Sie WdfDriverCreateauf.
Der Aufruf von WdfDriverCreate ermöglicht dem Treiber die Verwendung von Windows Driver Framework-Schnittstellen. (Der Treiber kann keine anderen Frameworkroutinen aufrufen, bevor WdfDriverCreateaufgerufen wird.)
Weisen Sie alle nicht gerätespezifischen Systemressourcen und globalen Variablen zu, die sie möglicherweise benötigen.
In der Regel ordnen Treiber Systemressourcen einzelnen Geräten zu. Daher weisen frameworkbasierte Treiber die meisten Ressourcen in einer 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 in allen 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ückgabewertan.
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 kann mehrere Instanzen eines UMDF-Treibers in separate Instanzen des Hostprozesses laden. Ergebnis:
- Das Framework ruft die DriverEntry-Routine eines UMDF-Treibers möglicherweise mehrmals auf, 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 DriverEn try-Routine eines frameworkbasierten Treibers aufgerufen wird, finden Sie unter Building and Loading a WDF Driver.
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 folgenden:
DRIVER_INITIALIZE MyDriverEntry;
NTSTATUS
DriverEntry(
IN PDRIVER_OBJECT DriverObject,
IN PUNICODE_STRING RegistryPath
)
{
// Function body
}
Beispiele
Das folgende Codebeispiel zeigt die DriverEntry Routine des Serial-Beispieltreibers (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;
}