GET_IDLE_WAKE_INFO Rückruffunktion (wdm.h)

Artikel
03/01/2024

Mit der GetIdleWakeInfo-Routine kann der Treiber für ein Gerät die Gerätestromzustände ermitteln, von denen aus das Gerät ein Aktivierungsereignis 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-Members der D3COLD_SUPPORT_INTERFACE-Struktur für die Schnittstelle fest.

[in] SystemPowerState

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

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

Diese Werte stellen die 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 Aktivierungssignal ausgeben kann.

[out] DeepestWakeableDstate

Tiefster dx-Zustand für reaktivierbar. 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 DeviceWakeDepthD0 bis DeviceWakeDepthD3cold gibt den Dx-Zustand mit der niedrigsten Leistung an, von dem aus das Gerät ein Wakesignal senden kann, wenn sich der Computer in dem vom SystemPowerState-Parameter angegebenen Systemstromzustand befindet. DeviceWakeDepthNotWakeable gibt an, dass es keinen Gerätestromzustand gibt, von dem das Gerät ein Aktivierungssignal senden kann, wenn sich der Computer in dem von SystemPowerState angegebenen 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 Fehler status Code zurück. Wenn ein GetIdleWakeInfo-Aufruf für einen Beliebigen SystemPowerState-Parameterwert im Bereich PowerSystemWorking bis PowerSystemHibernate fehlschlägt, tritt für alle diese Werte ein Fehler auf.

Rückgabewert

Die GetIdleWakeInfo-Routine gibt STATUS_SUCCESS zurück, wenn der geräteaktivste Zustand erfolgreich abgerufen wird. Andernfalls wird ein entsprechender Fehler status Code zurückgegeben.

Hinweise

Für den vom Aufrufer angegebenen Systemleistungszustand versucht diese Routine, den Gerätestromzustand mit der niedrigsten Leistung zu ermitteln, von dem aus das Gerät ein Aktivierungsereignis an den Prozessor signalisieren kann. Bei erfolgreicher Ausführung schreibt die Routine den Gerätestromzustand an den Speicherort, auf den der DeepestWakeableDstate-Parameter verweist, und gibt STATUS_SUCCESS zurück. Wenn die Routine feststellt, dass das Gerät kein Aktivierungsereignis aus einem Gerätestromzustand signalisieren kann, schreibt die Routine den Wert DeviceWakeDepthNotWakeable an diesen Speicherort und gibt STATUS_SUCCESS zurück.

Der Treiber für ein Gerät verwendet die von der GetIdleWakeInfo-Routine bereitgestellten Informationen, um die Bedingungen zu bestimmen, unter denen das Gerät ein Aktivierungsereignis signalisieren kann. Ein Gerät, das in der Lage sein muss, bestimmte Aktivierungsereignisse zu signalisieren, sollte nicht in einen Gerätestromzustand gelangen, von dem es diese Ereignisse nicht signalisieren kann. Bei einigen Gerätetypen unterscheiden sich die Aktivierungssignale, die das Gerät senden soll, wenn sich der Computer im Systemzustand S0 (Arbeitssystem) befindet, von denen, die das Gerät senden soll, wenn der Computer ausgeschaltet zu sein scheint.

Wenn beispielsweise ein Karte in einen PCI Express-Karte-Steckplatz eingefügt wird und sich das PCI Express-Hot-Plug-Controllergerät für den Steckplatz im Gerätestromzustand D0 befindet, signalisiert dieses Gerät einen Interrupt an den Prozessor. Wenn sich das Controllergerät jedoch in einem Dx-Zustand mit geringem Stromverbrauch befindet, wenn das Karte eingefügt wird, kann der Systemleistungszustand des Computers bestimmen, ob dieses Gerät ein Aktivierungsereignis für den Prozessor signalisieren soll. Idealerweise sollte sich das Controllergerät wie folgt verhalten:

Wenn sich der Computer im Betriebszustand des S0-Systems befindet, sollte das Gerät dem Prozessor ein Aktivierungsereignis signalisieren.
Wenn sich der Computer im Ruhezustand befindet (in einem Sx-Zustand mit geringer Leistung), sollte das Gerät kein Aktivierungsereignis 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 Aktivierungsereignis 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 = PowerSystemWorking fest. Dieses Gerät sollte in keinem der folgenden Fälle den D0-Zustand verlassen (wenn sich der Computer in S0 befindet):

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

Der Treiber sollte eines dieser Ergebnisse so interpretieren, dass das Gerät kein Aktivierungsereignis 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 darauf vorbereitet, S0 zu beenden.

Die Treiber für die meisten Geräte können einen Ausgabewert von DeviceWakeDepthD0 genauso behandeln wie DeviceWakeDepthNotWakeable. Nur wenige Treiber haben möglicherweise einen Grund, ein Aktivierungssignal auszurüsten, wenn sich ihre Geräte in D0 befinden. Hierbei handelt es sich um Treiber für einfache Geräte, die externe Ereignisse überwachen, die Aktivierungssignale auslösen, unabhängig davon, ob sich die Geräte in D0- oder Dx-Zuständen mit geringer Leistung befinden. Ein Beispiel für ein solches Gerät ist ein Netzschalter oder ein Ruhemodustaste auf einem Computer.

Die GetIdleWakeInfo-Routine fragt den zugrunde liegenden Bustreiber und die ACPI-Systemfirmware ab, um den niedrigsten Geräteleistungszustand zu ermitteln, von dem aus das Gerät ein Aktivierungsereignis signalisieren kann. Wenn der Bustreiber und die Firmware diese Informationen nicht bereitstellen können, schlägt die Routine fehl und gibt einen Fehler status Code zurück.

Die DEVICE_CAPABILITIES-Struktur enthält ein DeviceWake-Member , das Informationen bereitstellt, die den in der GetIdleWakeInfo-Routine verfügbaren Informationen ähneln. Die Informationen im DeviceWake-Element gelten jedoch nur für die Systemzustände mit geringer Leistung 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 ein solches Verhalten verlassen. Nur die GetIdleWakeInfo-Routine meldet zuverlässig die Fähigkeit eines Geräts, ein Aktivierungsereignis zu signalisieren, wenn sich der Computer in S0 befindet.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Kopfzeile	wdm.h (einschließen von Wdm.h)
IRQL	PASSIVE_LEVEL