WDF_POWER_FRAMEWORK_SETTINGS structure (wdfdevice.h)

Article
02/29/2024

[S’applique à KMDF et UMDF]

La structure WDF_POWER_FRAMEWORK_SETTINGS décrit les paramètres de l’infrastructure de gestion de l’alimentation (PoFx) pour les appareils à composant unique.

Syntaxe

typedef struct _WDF_POWER_FRAMEWORK_SETTINGS {
  ULONG                                         Size;
  PFN_WDFDEVICE_WDM_POST_PO_FX_REGISTER_DEVICE  EvtDeviceWdmPostPoFxRegisterDevice;
  PFN_WDFDEVICE_WDM_PRE_PO_FX_UNREGISTER_DEVICE EvtDeviceWdmPrePoFxUnregisterDevice;
  PPO_FX_COMPONENT                              Component;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK    ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK      ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK          ComponentIdleStateCallback;
  PPO_FX_POWER_CONTROL_CALLBACK                 PowerControlCallback;
  PVOID                                         PoFxDeviceContext;
  ULONGLONG                                     PoFxDeviceFlags;
  WDF_TRI_STATE                                 DirectedPoFxEnabled;
} WDF_POWER_FRAMEWORK_SETTINGS, *PWDF_POWER_FRAMEWORK_SETTINGS;

Membres

Size

Taille, en octets, de cette structure.

EvtDeviceWdmPostPoFxRegisterDevice

Pointeur vers la fonction de rappel d’événement EvtDeviceWdmPostPoFxRegisterDevice du pilote, ou NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Pointeur vers la fonction de rappel d’événement EvtDeviceWdmPrePoFxUnregisterDevice du pilote, ou NULL.

Component

Pointeur vers une structure PO_FX_COMPONENT qui décrit le seul composant de l’appareil à composant unique, ou NULL. Si la valeur est NULL, KMDF prend par défaut en charge F0 uniquement pour ce composant. Cette structure spécifie le nombre et les attributs des états F pris en charge par le composant, ainsi que l’état Fx le plus profond à partir duquel le composant peut se réveiller.

ComponentActiveConditionCallback

Pointeur vers la routine de rappel ComponentActiveConditionCallback du pilote, ou NULL. L’infrastructure de gestion de l’alimentation (PoFx) appelle cette fonction de rappel lorsqu’un composant devient actif. Dans la condition Active, le composant est garanti en F0.

ComponentIdleConditionCallback

Pointeur vers la fonction de rappel ComponentIdleConditionCallback du pilote, ou NULL. PoFx appelle cette fonction de rappel lorsqu’un composant devient inactif. Dans la condition d’inactivité, le composant peut se trouver dans n’importe quel état F, y compris F0.

ComponentIdleStateCallback

Pointeur vers la fonction de rappel ComponentIdleStateCallback du pilote, ou NULL. PoFx appelle cette fonction de rappel lorsque l’état F du composant change.

PowerControlCallback

Pointeur vers la fonction de rappel PowerControlCallback du pilote client, ou NULL. PoFx appelle cette routine pour transmettre une demande d’opération de contrôle d’alimentation directement au pilote. Si votre pilote ne prend pas en charge les codes de contrôle d’alimentation, définissez ce paramètre sur NULL.

PoFxDeviceContext

Pointeur de contexte que l’infrastructure fournit à ComponentActiveConditionCallback, ComponentIdleConditionCallback, ComponentIdleStateCallback et PowerControlCallback.

PoFxDeviceFlags

Valeur de type ULONGLONG contenant le ou au niveau du bit des valeurs suivantes liées à Directed Power Management Framework. Ce champ est disponible à partir de KMDF version 1.33 et UMDF 2.33.

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

Lorsque l’infrastructure Power Framework dirigée (« DFx ») est activée sur un appareil, les appareils enfants activent également DFx. Toutefois, dans certains cas (par exemple un appareil logiciel pur), un appareil enfant n’implémente pas la gestion de l’alimentation. Définissez cet indicateur pour permettre à un appareil enfant d’ignorer DFx.

Pour définir cet indicateur pour le compte d’appareils enfants, le pilote WDF parent doit :

Accepter DFx
Ne pas être un chauffeur d’autobus
Avoir au moins un appareil enfant virtuel créé via un canal de bande latérale (par exemple un filtre supérieur ou un appareil créé en appelant SwDeviceCreate

Pour les pilotes ciblant WDF pré-v33, spécifiez plutôt la directive INF : WdfDirectedPowerTransitionChildrenOptional, qui est disponible à partir de Windows 10, version 1903. Si le pilote spécifie la directive INF et définit cet indicateur, la directive INF est prioritaire.

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

Cela est nécessaire pour implémenter des IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations entre deux appareils.

Par défaut, WDF implémente une reprise rapide, ce qui signifie que pendant la mise en éveil du système, le propriétaire de la stratégie d’alimentation dans une pile d’appareils effectue un S0-IRP sans attendre de demander et de terminer un D0-IRP. Cela ne fonctionne pas correctement avec PowerRelations.

Pour que PowerRelations fonctionne correctement, si un appareil dépend d’un autre appareil pour entrer D0 en premier, le deuxième appareil doit définir cet indicateur pour refuser la reprise rapide.

Dans certains cas, la stratégie globale peut désactiver la reprise rapide à l’échelle mondiale, même si cet indicateur n’est pas défini.

DirectedPoFxEnabled

Énumérateur WDF_TRI_STATE qui indique si l’appareil active L’infrastructure de gestion de l’alimentation dirigée (DFx). Disponible à partir de KMDF version 1.33 et UMDF 2.33.

WdfTrue : DFx est activé. WdfFalse : DFx est désactivé. WdfUseDefault : valeur par défaut si le pilote n’en définit pas. Cette valeur a la même signification que WdfTrue.

Directed PoFx (DFx) est disponible à partir de Windows 10, version 1903 en tant qu’option pour les pilotes qui utilisent SystemManagedIdleTimeout ou SystemManagedIdleTimeoutWithHint.

Pour un pilote ciblant WDF pré-v31, définissez la directive INF WdfDirectedPowerTransitionEnable sur 1 pour choisir DFx.
Pour un pilote ciblant v31+ WDF, DFx est activé par défaut. Le pilote peut définir WdfDirectedPowerTransitionEnable sur zéro pour refuser DFx.
Pour un pilote ciblant v33+ WDF, DFx est également activé par défaut. Le pilote peut définir WdfDirectedPowerTransitionEnable sur zéro ou définir ce champ sur WdfFalse (recommandé) pour désactiver DFx. Si les deux sont définis, la directive INF est prioritaire.

Remarques

La structure WDF_POWER_FRAMEWORK_SETTINGS est utilisée comme entrée pour WdfDeviceWdmAssignPowerFrameworkSettings.

Pour initialiser sa structure WDF_POWER_FRAMEWORK_SETTINGS , votre pilote doit appeler WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Pour UMDF, seuls Size, PoFxDeviceFlags et DirectedPoFxEnabled sont utilisés. Les autres champs sont ignorés et doivent être définis sur zéro. L’infrastructure effectue cette opération automatiquement lorsqu’un pilote UMDF appelle WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Pour plus d’informations, consultez Prise en charge des états d’alimentation fonctionnels et Vue d’ensemble de l’infrastructure de gestion de l’alimentation.

Cette structure ne s’applique pas aux pilotes clients KMDF pour les appareils à plusieurs composants.