WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure (wdfdevice.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La structure WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS contient des informations fournies par le pilote sur la capacité d’un appareil à se réveiller lui-même et le système, lorsque les deux sont dans un état de faible consommation.

Syntaxe

typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
  ULONG                                 Size;
  DEVICE_POWER_STATE                    DxState;
  WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
  WDF_TRI_STATE                         Enabled;
  BOOLEAN                               ArmForWakeIfChildrenAreArmedForWake;
  BOOLEAN                               IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;

Membres

Size

Taille, en octets, de cette structure.

DxState

Énumérateur de type DEVICE_POWER_STATE qui identifie l’état d’alimentation faible de l’appareil que l’appareil entre lorsque l’état d’alimentation du système passe à un état de faible consommation en éveil. La valeur de DxState ne peut pas être PowerDeviceD0. DEVICE_POWER_STATE valeurs sont définies dans wdm.h.

UserControlOfWakeSettings

Énumérateur WDF_POWER_POLICY_SX_WAKE_USER_CONTROL qui indique si les utilisateurs ont la possibilité de modifier les paramètres de veille de l’appareil.

Enabled

Énumérateur de type WDF_TRI_STATE qui indique si l’appareil peut sortir le système (autrement dit, restaurer le système sur S0) lorsque le système est dans un état de faible consommation. Ce membre peut avoir l’une des valeurs suivantes :

WdfTrue : l’éveil du système est activé.

WdfFalse : l’éveil du système est désactivé.

WdfUseDefault : l’éveil du système est initialement activé par défaut ; mais si le membre UserControlOfWakeSettings est défini sur WakeAllowUserControl, le paramètre de l’utilisateur ou le fichier INF du pilote remplace la valeur initiale.

Si le système est activé et que le système est sur le point de passer à un état de faible consommation, le framework appelle la fonction de rappel EvtDeviceArmWakeFromSx ou EvtDeviceArmWakeFromSxWithReason du pilote avant que l’appareil ne passe à un état de faible consommation.

ArmForWakeIfChildrenAreArmedForWake

Valeur booléenne qui, si elle est définie sur TRUE, indique que la capacité d’un appareil parent à se réveiller lui-même et le système doivent être activés lorsque cette fonctionnalité est activée pour les appareils enfants de l’appareil. Pour plus d'informations, consultez la section Notes qui suit. Ce membre est disponible dans la version 1.7 et les versions ultérieures de KMDF.

IndicateChildWakeOnParentWake

Valeur booléenne qui, si elle est définie sur TRUE, indique que l’infrastructure fournira des status de mise en éveil aux appareils enfants si un appareil parent détecte un signal de mise en éveil. Pour plus d'informations, consultez la section Notes qui suit. Ce membre est disponible dans la version 1.7 et les versions ultérieures de KMDF.

Remarques

La structure WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS est utilisée comme entrée dans WdfDeviceAssignSxWakeSettings.

Pour initialiser sa structure WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS , votre pilote doit appeler WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT.

La première fois qu’un pilote appelle WdfDeviceAssignSxWakeSettings, les actions suivantes se produisent :

L’infrastructure stocke les valeurs de tous les membres de la structure WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS .
Si le membre UserControlOfWakeSettings est défini sur WakeAllowUserControl et si le membre Enabled est défini sur WdfUseDefault, l’infrastructure lit le Registre pour déterminer si l’utilisateur a activé la veille du système.

Lors des appels suivants à WdfDeviceAssignSxWakeSettings, l’infrastructure ne stocke pas la valeur du membre UserControlOfWakeSettings . En d’autres termes, le framework effectue les étapes suivantes la première fois que le pilote appelle WdfDeviceAssignSxWakeSettings , mais pas lors des appels ultérieurs :

Stocke la valeur du membre UserControlOfWakeSettings .
Recherche un paramètre utilisateur dans le Registre, si la valeur du membre Enabled est WdfUseDefault.

Les règles suivantes s’appliquent à la valeur que vous spécifiez pour le membre DxState :

La valeur ne peut pas être PowerDeviceD0.
Si vous spécifiez PowerDeviceMaximum, l’infrastructure utilise la valeur que le pilote du bus de l’appareil a fournie dans le membre DeviceWake de sa structure WDF_DEVICE_POWER_CAPABILITIES .
Vous ne pouvez pas spécifier un état d’alimentation du périphérique inférieur à l’état d’alimentation du périphérique dans le membre DeviceWake de la structure WDF_DEVICE_POWER_CAPABILITIES du pilote de bus. (En d’autres termes, si la valeur DeviceWake du pilote de bus est PowerDeviceD2, la valeur DxState de votre pilote de fonction ne peut pas être PowerDeviceD3.)

Pour plus d’informations sur les entrées de Registre qui contrôlent les fonctionnalités de veille d’un appareil, consultez Contrôle utilisateur du comportement d’inactivité et de veille de l’appareil.

Si l’appareil décrit par la structure WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS est un périphérique parent, le pilote de l’appareil parent peut utiliser les membres ArmForWakeIfChildrenAreArmedForWake et IndicateChildWakeOnParentWake comme suit :

Si le pilote définit le membre ArmForWakeIfChildrenAreArmedForWake sur TRUE, le framework appelle la fonction de rappel EvtDeviceArmWakeFromSx ou EvtDeviceArmWakeFromSxWithReason du pilote lorsque la capacité de éveil d’un appareil enfant est activée, même si la capacité de éveil du périphérique parent n’est pas activée.
Pour réduire la consommation d’énergie, vous ne souhaiterez peut-être pas activer la capacité de veille de votre appareil, sauf si un appareil enfant qui prend également en charge une capacité de veille est branché. Si votre pilote définit le membre ArmForWakeIfChildrenAreArmedForWake sur TRUE, les valeurs du membre Enabled ont les significations suivantes :
- Si Activé est WdfFalse, l’infrastructure active la capacité de sortie de veille de votre pilote uniquement si la capacité de veille d’un appareil enfant est activée.
- Si Activé est WdfTrue, l’infrastructure active toujours la capacité de sortie de veille de votre pilote, que votre appareil dispose d’appareils enfants activés ou non.
- Si Enabled est WdfUseDefault et Que UserControlOfWakeSettings a la valeur WakeAllowUserControl, les utilisateurs peuvent contrôler si votre appareil est toujours activé pour la veille ou s’il est activé uniquement lorsque votre appareil a des appareils enfants qui sont activés pour la veille.
Si le pilote définit le membre IndicateChildWakeOnParentWake sur TRUE, l’infrastructure appelle la fonction de rappel EvtDeviceWakeFromSxTriggered dans le pilote de l’appareil parent et dans le pilote pour chaque appareil enfant activé pour la veille. Si le pilote définit ce membre sur FALSE, le framework appelle la fonction de rappel EvtDeviceWakeFromSxTriggered uniquement dans le pilote de l’appareil parent. Votre pilote doit définir IndicateChildWakeOnParentWake sur TRUE si les pilotes des enfants de votre appareil doivent examiner le matériel pour déterminer pourquoi le système a été réveillé.