EVT_WDF_DEVICE_PREPARE_HARDWARE Rückruffunktion (wdfdevice.h)

  • Artikel

[Gilt für KMDF und UMDF]

Die EvtDevicePrepareHardware-Ereignisrückruffunktion eines Treibers führt alle Vorgänge aus, die erforderlich sind, um ein Gerät für den Treiber zugänglich zu machen.

Syntax

EVT_WDF_DEVICE_PREPARE_HARDWARE EvtWdfDevicePrepareHardware;

NTSTATUS EvtWdfDevicePrepareHardware(
  [in] WDFDEVICE Device,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] ResourcesRaw

Ein Handle für ein Frameworkressourcenlistenobjekt, das die Rohhardwareressourcen identifiziert, die der Plug & Play-Manager dem Gerät zugewiesen hat.

[in] ResourcesTranslated

Ein Handle für ein Frameworkressourcenlistenobjekt, das die übersetzten Hardwareressourcen identifiziert, die der Plug & Play-Manager dem Gerät zugewiesen hat.

Rückgabewert

Wenn für die Rückruffunktion EvtDevicePrepareHardware keine Fehler auftreten, muss sie STATUS_SUCCESS oder einen anderen status-Wert zurückgeben, für den NT_SUCCESS(status) gleich TRUE ist. Andernfalls muss ein status Wert zurückgegeben werden, für den NT_SUCCESS(status) gleich FALSE ist. Geben Sie STATUS_NOT_SUPPORTED nicht zurück.

Wenn NT_SUCCESS(status) gleich FALSE ist, ruft das Framework die Rückruffunktion EvtDeviceReleaseHardware des Treibers auf.

Weitere Informationen zu den Rückgabewerten dieser Rückruffunktion finden Sie unter Melden von Gerätefehlern.

Hinweise

Um eine EvtDevicePrepareHardware-Rückruffunktion zu registrieren, muss ein Treiber WdfDeviceInitSetPnpPowerEventCallbacks aufrufen.

Wenn der Treiber eine EvtDevicePrepareHardware-Rückruffunktion für ein Gerät registriert hat, ruft das Framework die Funktion auf, nachdem der Plug & Play-Manager dem Gerät Hardwareressourcen zugewiesen hat und das Gerät in den nicht initialisierten D0-Zustand versetzt wurde. (Der Plug & Play-Manager startet immer ein übergeordnetes Gerät, bevor er die untergeordneten Geräte dieses Geräts startet.)

Das Framework ruft die EvtDevicePrepareHardware-Rückruffunktion des Treibers auf, bevor die Rückruffunktion EvtDeviceD0Entry des Treibers aufgerufen wird.

Die Rückruffunktion EvtDevicePrepareHardware greift mithilfe der empfangenen Handles ResourcesRaw und ResourcesTranslated auf die rohen und übersetzten Hardwareressourcen des Geräts zu. Die Rückruffunktion kann WdfCmResourceListGetCount und WdfCmResourceListGetDescriptor aufrufen, um die Ressourcenlisten zu durchlaufen. Diese Rückruffunktion kann die Ressourcenlisten nicht ändern.

Weitere Informationen zu Ressourcenlisten und der Reihenfolge, in der die Ressourcen angezeigt werden, finden Sie unter Unformatierte und übersetzte Hardwareressourcen.

In der Regel führt die EvtDevicePrepareHardware-Rückruffunktion Ihres Treibers bei Bedarf Folgendes aus:

  • Ordnet adressen des physischen Arbeitsspeichers virtuellen Adressen zu, damit der Treiber auf den speicher zugreifen kann, der dem Gerät zugewiesen ist.
  • Bestimmt die Revisionsnummer des Geräts.
  • Konfiguriert USB-Geräte
  • Ruft treiberdefinierte Schnittstellen von anderen Treibern ab.
Optional kann die EvtDevicePrepareHardware-Rückruffunktion Ihres Treibers ein Arbeitselement in die Warteschlange stellen, um andere zeitintensive Konfigurationsaufgaben auszuführen. Die Verwendung eines Arbeitselements für solche Vorgänge kann dazu beitragen, sicherzustellen, dass die Startzeit Ihres Geräts die Systemstartzeit nicht erhöht. Weitere Informationen finden Sie unter Verwenden von Framework-Arbeitselementen.

In der Regel sollten alle anderen Hardwareinitialisierungsvorgänge, einschließlich des Ladens der Firmware, bei jedem Wechsel des Geräts in den Betriebszustand (D0) erfolgen und daher in der EvtDeviceD0Entry-Rückruffunktion des Treibers erfolgen.

Die Handles ResourcesRaw und ResourcesTranslated , die die Rückruffunktion EvtDevicePrepareHardware empfängt , bleiben gültig, bis die Rückruffunktion EvtDeviceReleaseHardware des Treibers zurückgibt.

Weitere Informationen zu Hardwareressourcen finden Sie unter Hardwareressourcen für Framework-Based Treiber.

Weitere Informationen dazu, wann das Framework diese Rückruffunktion aufruft, finden Sie unter PnP- und Energieverwaltungsszenarien.

Weitere Informationen zu Treibern, die diese Rückruffunktion bereitstellen, finden Sie unter Unterstützen der PnP- und Energieverwaltung in Funktionstreibern.

Anforderungen

Anforderung Wert
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Kopfzeile wdfdevice.h (einschließen von Wdf.h)
IRQL PASSIVE_LEVEL

Weitere Informationen

EvtDeviceReleaseHardware