structure WDF_POWER_FRAMEWORK_SETTINGS (wdfdevice.h)

2025-03-22

[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 fonction de rappel d’événement ou NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Pointeur vers la fonction de rappel d’événement EvtDeviceWdmPrePoFxUnregisterDevice fonction de rappel d’événement 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 le ComponentActiveConditionCallback du pilote routine de rappel ou NULL. PoFx appelle cette fonction de rappel lorsqu’un composant devient actif. Dans la condition Active, le composant est garanti en F0.

ComponentIdleConditionCallback

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

ComponentIdleStateCallback

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

PowerControlCallback

Pointeur vers le PowerControlCallback du pilote client fonction de rappel 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, ComponentIdleStateCallbacket PowerControlCallback.

PoFxDeviceFlags

Valeur de type ULONGLONG contenant le bit OR des valeurs suivantes liées au 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 généralement 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 autoriser un tel appareil enfant à ignorer DFx.

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

Opt into DFx
Ne pas être un chauffeur de bus
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 la fonction 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 IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations entre deux appareils.

Par défaut, WDF implémente une reprise rapide, ce qui signifie que pendant le réveil du système, le propriétaire de la stratégie d’alimentation dans une pile d’appareils termine une S0-IRP sans attendre de demander et 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 d’abord D0, le deuxième appareil doit définir cet indicateur pour désactiver la reprise rapide.

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

DirectedPoFxEnabled

Énumérateur WDF_TRI_STATE typé 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 un. Cette valeur a la même signification que WdfTrue.

L’instruction PoFx (DFx) dirigée 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 pour WdfDeviceWdmAssignPowerFrameworkSettings.

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

Pour UMDF, seules Taille, PoFxDeviceFlagset DirectedPoFxEnabled sont utilisées. 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 fonctionnels et Vue d’ensemble duPower Management Framework.

Cette structure n’est pas applicable aux pilotes clients KMDF pour les appareils à plusieurs composants.