GET_IDLE_WAKE_INFO fonction de rappel (wdm.h)

Article
02/27/2024

La routine GetIdleWakeInfo permet au pilote d’un appareil de découvrir les états d’alimentation de l’appareil à partir desquels l’appareil peut signaler un événement de sortie de veille.

Syntaxe

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

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

Paramètres

[in, optional] Context

Pointeur vers des informations de contexte spécifiques à l’interface. L’appelant définit ce paramètre sur la valeur du membre Context de la structure D3COLD_SUPPORT_INTERFACE pour l’interface.

[in] SystemPowerState

État de l’alimentation du système. Définissez ce paramètre sur l’une des valeurs d’énumération SYSTEM_POWER_STATE suivantes :

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

Ces valeurs représentent les états d’alimentation système S0 (état de fonctionnement du système) à S4. Pour la valeur SystemPowerState fournie par l’appelant, la routine détermine l’état d’alimentation le plus profond de l’appareil à partir duquel l’appareil peut émettre un signal de sortie de veille.

[out] DeepestWakeableDstate

État Dx réactivable le plus profond. Ce paramètre est un pointeur vers une variable DEVICE_WAKE_DEPTH . Si l’appel réussit, la routine écrit l’une des valeurs d’énumération suivantes dans cette variable :

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

Une valeur comprise entre DeviceWakeDepthD0 et DeviceWakeDepthD3cold indique l’état Dx le plus faible à partir duquel l’appareil peut envoyer un signal de veille lorsque l’ordinateur se trouve dans l’état d’alimentation du système spécifié par le paramètre SystemPowerState . DeviceWakeDepthNotWakeable indique qu’il n’existe aucun état d’alimentation de l’appareil à partir duquel l’appareil peut envoyer un signal de sortie de veille lorsque l’ordinateur se trouve dans l’état d’alimentation du système spécifié par SystemPowerState.

Si la routine ne peut pas déterminer l’état le plus profond de l’appareil en éveil (peut-être parce que le microprogramme de la plateforme ne contient pas ces informations), l’appel échoue et la routine retourne une erreur status code. Si un appel GetIdleWakeInfo échoue pour une valeur de paramètre SystemPowerState dans la plage PowerSystemWorking à PowerSystemHibernate, il échoue pour toutes ces valeurs.

Valeur retournée

La routine GetIdleWakeInfo retourne STATUS_SUCCESS si elle récupère correctement l’état d’éveil le plus profond de l’appareil. Sinon, elle retourne une erreur appropriée status code.

Remarques

Pour l’état d’alimentation du système spécifié par l’appelant, cette routine tente de déterminer l’état d’alimentation de l’appareil le plus faible à partir duquel l’appareil peut signaler un événement de sortie de veille au processeur. Si elle réussit, la routine écrit l’état d’alimentation de l’appareil à l’emplacement désigné par le paramètre DeepestWakeableDstate et retourne STATUS_SUCCESS. Ou, si la routine détermine que l’appareil ne peut pas signaler un événement de sortie de veille à partir d’un état d’alimentation de l’appareil, la routine écrit la valeur DeviceWakeDepthNotWakeable à cet emplacement et retourne STATUS_SUCCESS.

Le pilote d’un appareil utilise les informations fournies par la routine GetIdleWakeInfo pour déterminer les conditions dans lesquelles l’appareil peut signaler un événement de veille. Un appareil qui doit être en mesure de signaler certains événements de sortie de veille ne doit pas entrer dans un état d’alimentation de l’appareil à partir duquel il ne peut pas signaler ces événements. Pour certains types d’appareils, les signaux de veille que l’appareil doit envoyer lorsque l’ordinateur est dans l’état d’alimentation du système S0 (fonctionnement) diffèrent de ceux que l’appareil doit envoyer lorsque l’ordinateur semble éteint.

Par exemple, lorsqu’un carte est inséré dans un emplacement PCI Express carte et que le périphérique de contrôleur pci Express pour l’emplacement est dans l’état d’alimentation de l’appareil D0, ce périphérique signale une interruption au processeur. Toutefois, si l’appareil du contrôleur est dans un état Dx à faible consommation lors de l’insertion de l’carte, l’état d’alimentation du système de l’ordinateur peut déterminer si cet appareil doit signaler un événement de sortie de veille au processeur. Dans l’idéal, l’appareil de contrôleur doit se comporter comme suit :

Si l’ordinateur est dans l’état d’alimentation du système S0 (fonctionnement), l’appareil doit signaler un événement de sortie de veille au processeur.
Si l’ordinateur est en veille (dans un état Sx à faible consommation), l’appareil ne doit pas signaler un événement de sortie de veille.

Certains appareils plus anciens peuvent ne pas prendre en charge ce comportement idéal. Si le périphérique de contrôleur de branchement à chaud PCI Express dans cet exemple peut signaler un événement de sortie de veille uniquement lorsque l’ordinateur est dans l’état S3, le pilote (qui, dans ce cas, est le pilote de boîte de réception Pci.sys) pour le contrôleur doit conserver le contrôleur en D0 lorsque l’ordinateur est dans S0 (et ne se prépare pas à entrer en état de veille).

Dans cet exemple, le pilote peut appeler la routine GetIdleWakeInfo pour déterminer si le périphérique de contrôleur à chaud doit quitter l’état D0 lorsque l’ordinateur se trouve dans S0. Pour cet appel, le pilote définit SystemPowerState = PowerSystemWorking. Cet appareil ne doit pas laisser l’état D0 (lorsque l’ordinateur est en S0) dans l’un des cas suivants :

L’appel GetIdleWakeInfo définit le paramètre de sortie sur DeviceWakeDepthNotWakeable ou DeviceWakeDepthD0 et retourne STATUS_SUCCESS.
L’appel GetIdleWakeInfo échoue et retourne une erreur status code.

Le pilote doit interpréter l’un de ces résultats comme signifiant que le périphérique ne peut pas signaler un événement de sortie de veille lorsque l’ordinateur est en S0. Sur la base de ces informations, le pilote doit conserver l’appareil dans D0 jusqu’à ce que l’ordinateur se prépare à quitter S0.

Les pilotes de la plupart des appareils peuvent traiter une valeur de sortie DeviceWakeDepthD0 de la même façon que DeviceWakeDepthNotWakeable. Seuls quelques pilotes peuvent avoir une raison d’armer un signal de veille lorsque leurs appareils sont en D0. Il s’agit de pilotes pour les appareils simples qui surveillent les événements externes qui déclenchent des signaux d’éveil, que les appareils soient dans des états D0 ou Dx de faible consommation. Un exemple de ce type d’appareil est un bouton d’alimentation ou un bouton de veille sur un ordinateur.

La routine GetIdleWakeInfo interroge le pilote de bus sous-jacent et le microprogramme système ACPI pour déterminer l’état d’alimentation le plus faible à partir duquel l’appareil peut signaler un événement de sortie de veille. Si le pilote de bus et le microprogramme ne peuvent pas fournir ces informations, la routine échoue et retourne une erreur status code.

La structure DEVICE_CAPABILITIES inclut un membre DeviceWake qui fournit des informations similaires à celles disponibles dans la routine GetIdleWakeInfo . Toutefois, les informations contenues dans le membre DeviceWake s’appliquent uniquement aux états système de faible puissance S1 à S4. Pour certains appareils, les informations contenues dans le membre DeviceWake peuvent également s’appliquer à l’état d’alimentation du système S0, mais les pilotes ne doivent pas s’appuyer sur ce comportement. Seule la routine GetIdleWakeInfo signale de manière fiable la capacité d’un appareil à signaler un événement de veille si l’ordinateur est en S0.

Une fonction d’assistance inline, MapWakeDepthToDstate, est fournie pour convertir la valeur de sortie DEVICE_WAKE_DEPTH de la routine GetIdleWakeInfo en valeur DEVICE_POWER_STATE qui peut être utilisée comme paramètre d’entrée par la routine PoRequestPowerIrp .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (include Wdm.h)
IRQL	PASSIVE_LEVEL