PoFxRegisterDevice-Funktion (wdm.h)

Artikel
03/01/2024

Die PoFxRegisterDevice-Routine registriert ein Gerät mit dem Power Management Framework (PoFx).

Syntax

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

Parameter

[in] Pdo

Ein Zeiger auf ein physisches Geräteobjekt (PDO ). Dieser Parameter verweist auf eine DEVICE_OBJECT Struktur, die das physische Gerät darstellt, das registriert wird. Der Aufrufer ist der Besitzer der Energierichtlinie für das Gerät, das in der Regel der Funktionstreiber des Geräts ist.

[in] Device

Ein Zeiger auf eine vom Aufrufer zugewiesene PO_FX_DEVICE Struktur, die die Registrierungsinformationen für das Gerät enthält. Diese Struktur enthält Zeiger auf eine Reihe von Rückrufroutinen, die vom Gerätetreiber implementiert werden. PoFx ruft diese Routinen auf, um mit dem Treiber zu kommunizieren.

[out] Handle

Ein Zeiger auf einen Ort, an dem die Routine ein Handle schreibt, das die Registrierung des Geräts mit PoFx darstellt. Der Gerätetreiber übergibt dieses Handle als Eingabeparameter an die anderen PoFxXxx-Routinen , die er aufruft. Der Treiber muss zuerst PoFxRegisterDevice aufrufen, um das Gerät zu registrieren, bevor der Treiber andere PoFxXxx-Routinen aufruft, um das Gerät mit Energie zu verwalten.

Rückgabewert

PoFxRegisterDevice gibt STATUS_SUCCESS zurück, wenn die Routine das Gerät erfolgreich registriert. Mögliche Fehlerrückgabewerte umfassen die folgenden status-Codes.

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Pdo ist NULL; oder die PPO_FX_DEVICE Struktur hat eine ungültige Versionsnummer oder eine Komponentenanzahl von 0; oder die Anzahl der für eine Komponente angegebenen Leerlaufzustände ist 0; oder die Beschreibung eines Leerlaufzustands ist ungültig.
STATUS_DEVICE_NOT_READY	Das Gerät ist nicht bereit.
STATUS_INSUFFICIENT_RESOURCES	Für die Registrierung stehen nicht genügend Ressourcen zur Verfügung.

Hinweise

Ein Gerätetreiber ruft diese Routine in der Regel vom IRP_MN_START_DEVICE Anforderungshandler des Treibers auf. Der Treiber darf diese Routine nicht aufrufen, bevor das Gerät eine IRP_MN_START_DEVICE-Anforderung empfängt. Das Gerät empfängt die erste IRP_MN_START_DEVICE Anforderung, wenn das Gerät zum ersten Mal gestartet wird. Das Gerät empfängt jedes Mal, wenn das Gerät nach dem Beenden des Ressourcenausgleichs neu gestartet wird, eine zusätzliche IRP_MN_START_DEVICE Anforderung. Ein PoFxRegisterDevice-Aufruf zum Registrieren eines bereits registrierten Geräts ist ein schwerwiegender Fehler und verursacht eine Fehlerüberprüfung. Beachten Sie, dass PoFx eine tiefgehende Kopie der Gerätestrukturen in den Arbeitsspeicher durchführt.

Bevor der Treiber PoFxRegisterDevice aufruft, muss das Gerät die folgenden Bedingungen erfüllen:

Das Gerät (d. h. das PDO) ist noch nicht bei PoFx registriert.
Das Gerät befindet sich im D0-Betriebszustand (vollständig eingeschaltet).
Das Gerät befindet sich in der Ausführungsbedingung.
Jede Komponente im Gerät befindet sich im Betriebszustand F0 (vollständig eingeschaltet).
Jede Komponente befindet sich in der aktiven Bedingung.

Durch die Registrierung des Geräts bei PoFx übernimmt der Treiber die Verantwortung, PoFx zu informieren, wenn eine Komponente aktiv verwendet wird und sich die Komponente im Leerlauf befindet. Während das Gerät registriert ist, muss der Treiber die PoFxActivateComponent-Routine aufrufen, um Zugriff auf die Hardwareregister einer Komponente zu erhalten, und der Treiber muss die PoFxIdleComponent-Routine aufrufen, um PoFx zu benachrichtigen, wenn der Treiber keinen Zugriff mehr auf die Komponente benötigt.

Nachdem ein Treiber PoFxRegisterDevice aufgerufen hat , um ein Gerät bei PoFx zu registrieren, sind alle Komponenten im Gerät vollständig aktiviert und im aktiven Zustand, sodass der Treiber die Initialisierung der Hardware beenden kann. Um die aktive Energieverwaltung zu starten, muss der Treiber die PoFxStartDevicePowerManagement-Routine aufrufen.

Standardmäßig wechselt PoFxStartDevicePowerManagement alle Komponenten in die Leerlaufbedingung. Wenn der Treiber erfordert, dass sich eine Komponente unmittelbar nach dem Start der Energieverwaltung im aktiven Zustand befindet, muss der Treiber die Komponente explizit aktivieren, indem er die PoFxActivateComponent-Routine aufruft. Dieser Aufruf muss nach dem PoFxRegisterDevice-Aufruf , aber vor dem PoFxStartDevicePowerManagement-Aufruf erfolgen.

In der Regel ruft der kmDF-Treiber (Kernel-Mode Driver Framework) für ein Gerät mit nur einer Komponente PoFxRegisterDevice nicht auf, um das Gerät bei PoFx zu registrieren. Stattdessen erhält dieser Treiber ein PoFx-Registrierungshandle, wenn KMDF die Rückruffunktion EvtDeviceWdmPostPoFxRegisterDevice des Treibers aufruft. Weitere Informationen finden Sie unter Unterstützung mehrerer funktionsbezogener Energiezustände für Single-Component Geräte.

Informationen dazu, wie der KMDF-Treiber für ein Gerät mit mehreren Komponenten bei PoFx registriert wird, finden Sie unter Unterstützung mehrerer Funktionszustände für Multiple-Component-Geräte.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Universell
Header	wdm.h
Bibliothek	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL