GET_IDLE_WAKE_INFO Rückruffunktion (wdm.h)
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
[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-
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.
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.
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.
Anforderungen
Anforderung | Wert |
---|---|
mindestens unterstützte Client- | Verfügbar ab Windows 8. |
Zielplattform- | Desktop |
Header- | wdm.h (include Wdm.h) |
IRQL- | PASSIVE_LEVEL |