fonction de rappel GET_IDLE_WAKE_INFO (wdm.h)

Article
02/07/2025

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 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 de 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) via S4. Pour l'SystemPowerState valeur fournie par l’appelant, la routine détermine l’état d’alimentation de l’appareil le plus profond à partir duquel l’appareil peut émettre un signal de veille.

[out] DeepestWakeableDstate

État Dx wakeable 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 de la plage DeviceWakeDepthD0 à DeviceWakeDepthD3cold indique l’état Dx le plus bas à partir duquel l’appareil peut envoyer un signal de veille lorsque l’ordinateur est 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 veille lorsque l’ordinateur est dans l’état d’alimentation du système spécifié par SystemPowerState.

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

Valeur de retour

La routine GetIdleWakeInfo retourne STATUS_SUCCESS si elle récupère correctement l’état d’appareil wakeable le plus profond. Sinon, elle retourne un code d’état d’erreur approprié.

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 bas à partir duquel l’appareil peut signaler un événement de veille au processeur. Si elle réussit, la routine écrit l’état de l’alimentation de l’appareil à l’emplacement vers lequel pointe 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 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 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 (opérationnel) diffère de ceux que l’appareil doit envoyer lorsque l’ordinateur semble être désactivé.

Par exemple, lorsqu’une carte est insérée dans un emplacement de carte PCI Express et que l’appareil de contrôleur de plug-à-chaud PCI Express pour l’emplacement est dans l’état d’alimentation de l’appareil D0, cet appareil signale une interruption au processeur. Toutefois, si l’appareil du contrôleur est dans un état Dx à faible alimentation lorsque la carte est insérée, l’état d’alimentation du système de l’ordinateur peut déterminer si cet appareil doit signaler un événement de veille au processeur. Dans l’idéal, l’appareil du contrôleur doit se comporter comme suit :

Si l’ordinateur est à l’état d’alimentation du système S0 (opérationnel), l’appareil doit signaler un événement de veille au processeur.
Si l’ordinateur est en veille (dans un état Sx à faible alimentation), l’appareil ne doit pas signaler un événement 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 plug-à-chaud PCI Express dans cet exemple peut signaler un événement de veille uniquement lorsque l’ordinateur est dans l’état S3, le pilote (qui, dans ce cas, est la boîte de réception Pci.sys pilote) pour le contrôleur doit conserver le contrôleur en D0 lorsque l’ordinateur est dans S0 (et ne se prépare pas à entrer dans un état de veille).

Le pilote de cet exemple peut appeler la routine GetIdleWakeInfo pour déterminer si l’appareil de contrôleur à chaud doit quitter l’état D0 pendant que l’ordinateur est dans S0. Pour cet appel, le pilote définit SystemPowerState = PowerSystemWorking. Cet appareil ne doit pas laisser l’état D0 (lorsque l’ordinateur est dans 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 un code d’état d’erreur.

Le pilote doit interpréter l’un de ces résultats pour signifier que l’appareil ne peut pas signaler un événement de veille lorsque l’ordinateur se trouve dans S0. En fonction de ces informations, le pilote doit conserver l’appareil en D0 jusqu’à ce que l’ordinateur se prépare à quitter S0.

Les pilotes pour la plupart des appareils peuvent traiter une valeur de sortie de DeviceWakeDepthD0 identiques à 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 de sortie de veille, que les appareils soient dans des états D0 ou À faible alimentation. Un exemple de tel appareil est un bouton d’alimentation ou un bouton de veille sur un ordinateur.

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

La structure DEVICE_CAPABILITIES comprend un membre DeviceWake qui fournit des informations similaires à celles disponibles à partir de la routine GetIdleWakeInfo. Toutefois, les informations contenues dans le membre DeviceWake s’appliquent uniquement aux états de faible puissance système S1 à S4. Pour certains appareils, les informations du 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. Seul le GetIdleWakeInfo routine signale de manière fiable la capacité d’un appareil à signaler un événement de veille si l’ordinateur se trouve dans S0.

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