GET_IDLE_WAKE_INFO Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die GetIdleWakeInfo Routine ermöglicht es dem Treiber für ein Gerät, die Energiezustände des Geräts zu ermitteln, aus denen das Gerät ein Wake-Ereignis signalisieren kann.

Syntax

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

Parameter

[in, optional] Context

Ein Zeiger auf schnittstellenspezifische Kontextinformationen. Der Aufrufer legt diesen Parameter auf den Wert des Context Member der D3COLD_SUPPORT_INTERFACE Struktur für die Schnittstelle fest.

[in] SystemPowerState

Systemleistungszustand. Legen Sie diesen Parameter auf einen der folgenden SYSTEM_POWER_STATE Enumerationswerte fest:

PowerSystemWorking-
PowerSystemSleeping1
PowerSystemSleeping2-
PowerSystemSleeping3-
PowerSystemHibernate

Diese Werte stellen Systemleistungszustände S0 (Systemarbeitszustand) bis S4 dar. Für den vom Aufrufer bereitgestellten SystemPowerState Wert bestimmt die Routine den tiefsten Gerätestromzustand, aus dem das Gerät ein Wakesignal ausgeben kann.

[out] DeepestWakeableDstate

Deepest wakeable Dx state. Dieser Parameter ist ein Zeiger auf eine DEVICE_WAKE_DEPTH Variable. Wenn der Aufruf erfolgreich ist, schreibt die Routine einen der folgenden Enumerationswerte in diese Variable:

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1-
DeviceWakeDepthD2-
DeviceWakeDepthD3hot-
DeviceWakeDepthD3cold-

Ein Wert im Bereich DeviceWakeDepthD0DeviceWakeDepthD3cold gibt den niedrigsten Dx-Zustand an, aus dem das Gerät ein Wakesignal senden kann, wenn sich der Computer im vom SystemPowerState Parameter angegebenen Systemstromzustand befindet. DeviceWakethNotWakeable gibt an, dass kein Gerätestromzustand vorhanden ist, aus dem das Gerät ein Wakesignal senden kann, wenn sich der Computer im durch SystemPowerStateangegebenen Systemstromzustand befindet.

Wenn die Routine den tiefsten Zustand des reaktivierbaren Geräts nicht ermitteln kann (möglicherweise weil die Plattformfirmware diese Informationen nicht enthält), schlägt der Aufruf fehl, und die Routine gibt einen Fehlerstatuscode zurück. Wenn ein GetIdleWakeInfo- Aufruf für einen SystemPowerState Parameterwert im Bereich PowerSystemWorkingPowerSystemHibernatefehlschlägt, tritt für alle diese Werte ein Fehler auf.

Rückgabewert

Die GetIdleWakeInfo Routine gibt STATUS_SUCCESS zurück, wenn sie erfolgreich den tiefsten Zustand des reaktivierbaren Geräts abruft. Andernfalls wird ein entsprechender Fehlerstatuscode zurückgegeben.

Bemerkungen

Für den vom Aufrufer angegebenen Systemstromzustand versucht diese Routine, den Energiezustand des niedrigsten Geräts zu ermitteln, aus dem das Gerät ein Wake-Ereignis an den Prozessor signalisieren kann. Bei erfolgreicher Ausführung schreibt die Routine den Gerätestromzustand an die Position, auf die durch den DeepestWakeableDstate Parameter verwiesen wird, und gibt STATUS_SUCCESS zurück. Oder wenn die Routine feststellt, dass das Gerät kein Wake-Ereignis von einem Gerätestromzustand signalisiert, schreibt die Routine den Wert DeviceWakethNotWakeable an diese Position und gibt STATUS_SUCCESS zurück.

Der Treiber für ein Gerät verwendet die informationen, die vom GetIdleWakeInfo Routine bereitgestellt werden, um die Bedingungen zu bestimmen, unter denen das Gerät ein Wake-Ereignis signalisieren kann. Ein Gerät, das bestimmte Wake-Ereignisse signalisieren muss, sollte keinen Gerätestromzustand eingeben, aus dem diese Ereignisse nicht signalisiert werden können. Bei einigen Gerätetypen unterscheiden sich die Wake-Signale, die das Gerät senden soll, wenn sich der Computer im Netzzustand des S0 (arbeitsfähigen) Systems befindet, von denen abweicht, die das Gerät senden soll, wenn der Computer ausgeschaltet ist.

Wenn z. B. eine Karte in einen PCI Express-Kartensteckplatz eingefügt wird und das PCI Express Hot-Plug-Controller-Gerät für den Steckplatz im D0-Gerätestromzustand liegt, signalisiert dieses Gerät einen Interrupt an den Prozessor. Wenn sich das Controllergerät jedoch in einem Dx-Zustand mit niedriger Leistung befindet, wenn die Karte eingefügt wird, kann der Systemstromzustand des Computers bestimmen, ob dieses Gerät ein Wake-Ereignis an den Prozessor signalisieren soll. Im Idealfall sollte sich das Controllergerät wie folgt verhalten:

Wenn sich der Computer im Netzzustand des S0 -Systems befindet, sollte das Gerät ein Wake-Ereignis an den Prozessor signalisieren.
Wenn der Computer inaktiv ist (in einem Sx-Zustand mit niedriger Leistung), sollte das Gerät kein Wake-Ereignis signalisieren.

Einige ältere Geräte unterstützen dieses ideale Verhalten möglicherweise nicht. Wenn das PCI Express Hot-Plug-Controllergerät in diesem Beispiel nur dann ein Wake-Ereignis signalisieren kann, wenn sich der Computer im S3-Zustand befindet, sollte der Treiber (in diesem Fall der Posteingang Pci.sys Treiber) für den Controller den Controller in D0 beibehalten, wenn sich der Computer in S0 befindet (und sich nicht darauf vorbereitet, in einen Ruhezustand zu wechseln).

Der Treiber in diesem Beispiel kann die GetIdleWakeInfo Routine aufrufen, um zu bestimmen, ob das Hot-Plug-Controllergerät den D0-Zustand verlassen soll, während sich der Computer in S0 befindet. Für diesen Aufruf legt der Treiber SystemPowerState = PowerSystemWorkingfest. Dieses Gerät sollte den D0-Zustand (wenn sich der Computer in S0 befindet) in einem der folgenden Fälle nicht verlassen:

Der GetIdleWakeInfo-aufruf legt den Ausgabeparameter entweder auf DeviceWakeDepthNotWakeable oder DeviceWakeDepthD0- fest und gibt STATUS_SUCCESS zurück.
Der GetIdleWakeInfo Aufruf schlägt fehl und gibt einen Fehlerstatuscode zurück.

Der Treiber sollte eines dieser Ergebnisse interpretieren, um zu bedeuten, dass das Gerät kein Wake-Ereignis signalisieren kann, wenn sich der Computer in S0 befindet. Basierend auf diesen Informationen sollte der Treiber das Gerät in D0 beibehalten, bis sich der Computer auf das Beenden von S0 vorbereitet.

Die Treiber für die meisten Geräte können einen Ausgabewert von DeviceWakeDepthD0 mit DeviceWakethNotWakeablebehandeln. Nur ein paar Treiber haben möglicherweise einen Grund, ein Wake-Signal zu armieren, wenn sich ihre Geräte in D0 befinden. Dies sind Treiber für einfache Geräte, die externe Ereignisse überwachen, die Wake-Signale auslösen, unabhängig davon, ob sich die Geräte in D0- oder Dx-Zuständen mit niedriger Leistung befinden. Ein Beispiel für ein solches Gerät ist ein Netzschalter oder ein Energiesparschalter auf einem Computer.

Die GetIdleWakeInfo Routine fragt den zugrunde liegenden Bustreiber und die ACPI-Systemfirmware ab, um den niedrigsten Gerätestromzustand zu ermitteln, von dem das Gerät ein Wake-Ereignis signalisieren kann. Wenn der Bustreiber und die Firmware diese Informationen nicht angeben können, schlägt die Routine fehl und gibt einen Fehlerstatuscode zurück.

Die DEVICE_CAPABILITIES-Struktur enthält einen DeviceWake- Member, der Informationen bereitstellt, die der GetIdleWakeInfo Routine zur Verfügung stehen. Die Informationen im DeviceWake Mitglied gelten jedoch nur für die System-Low-Power-Zustände S1 bis S4. Bei einigen Geräten gelten die Informationen im DeviceWake Member möglicherweise auch für den S0-Systemstromzustand, treiber sollten sich jedoch nicht auf dieses Verhalten verlassen. Nur die GetIdleWakeInfo Routine meldet zuverlässig die Fähigkeit eines Geräts, ein Wake-Ereignis zu signalisieren, wenn sich der Computer in S0 befindet.

Eine Inlinehilfsfunktion, MapWakeDepthToDstate, wird bereitgestellt, um den DEVICE_WAKE_DEPTH Ausgabewert aus der GetIdleWakeInfo Routine in einen DEVICE_POWER_STATE Wert zu konvertieren, der als Eingabeparameter von der PoRequestPowerIrp Routine verwendet werden kann.