struttura WDF_POWER_FRAMEWORK_SETTINGS (wdfdevice.h)

Articolo
03/22/2025

[Si applica a KMDF e UMDF]

La struttura WDF_POWER_FRAMEWORK_SETTINGS descrive le impostazioni del framework di risparmio energia (PoFx) per i dispositivi a componente singolo.

Sintassi

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;

Membri

Size

Dimensione, in byte, di questa struttura.

EvtDeviceWdmPostPoFxRegisterDevice

Puntatore al evtDeviceWdmPostPoFxRegisterDevice funzione di callback degli eventi o NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Puntatore al del driver EvtDeviceWdmPrePoFxUnregisterDevice funzione di callback degli eventi o NULL.

Component

Puntatore a una struttura PO_FX_COMPONENT che descrive l'unico componente nel dispositivo a componente singolo o NULL. Se NULL, il valore predefinito di KMDF è F0 supportato solo per questo componente. Questa struttura specifica il numero e gli attributi degli stati F supportati dal componente, nonché lo stato fx più profondo da cui il componente può riattivarsi.

ComponentActiveConditionCallback

Puntatore al ComponentActiveConditionCallback del driver routine di callback o NULL. Il framework di risparmio energia (PoFx) chiama questa funzione di callback quando un componente diventa attivo. Mentre nella condizione Attiva, il componente è garantito che sia in F0.

ComponentIdleConditionCallback

Puntatore al ComponentIdleConditionCallback del driver funzione di callback o NULL. PoFx chiama questa funzione di callback quando un componente diventa inattivo. Nella condizione di inattività, il componente può trovarsi in qualsiasi stato F, incluso F0.

ComponentIdleStateCallback

Puntatore al ComponentIdleStateCallback del driver funzione di callback o NULL. PoFx chiama questa funzione di callback quando cambia lo stato F del componente.

PowerControlCallback

Puntatore al driver client PowerControlCallback funzione di callback o NULL. PoFx chiama questa routine per passare una richiesta per un'operazione di controllo alimentazione direttamente al driver. Se il driver non supporta alcun codice di controllo alimentazione, impostare questo parametro su NULL.

PoFxDeviceContext

Puntatore di contesto fornito dal framework a ComponentActiveConditionCallback, ComponentIdleConditionCallback, ComponentIdleStateCallbacke PowerControlCallback.

PoFxDeviceFlags

Valore di tipo ULONGLONG contenente l' OR bit per bit dei valori seguenti correlati al framework di gestione alimentazione diretta . Questo campo è disponibile a partire da KMDF versione 1.33 e UMDF 2.33.

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

Quando power framework diretto ("DFx") è abilitato in un dispositivo, in genere anche i dispositivi figlio abilitano DFx. In alcuni casi, ad esempio un dispositivo software puro, un dispositivo figlio non implementa il risparmio energia. Impostare questo flag per consentire a un dispositivo figlio di ignorare DFx.

Per impostare questo flag per conto dei dispositivi figlio, il driver WDF padre deve:

acconsentire esplicitamente a DFx
Non essere un autista di autobus
Avere almeno un dispositivo figlio virtuale creato tramite un canale side-band (ad esempio un filtro superiore o un dispositivo creato chiamando SwDeviceCreate

Per i driver destinati a WDF pre-v33, specificare invece la direttiva INF: WdfDirectedPowerTransitionChildrenOptional, disponibile a partire da Windows 10 versione 1903. Se il driver specifica la direttiva INF e imposta questo flag, la direttiva INF ha la precedenza.

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

Questa operazione è necessaria per implementare IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations tra due dispositivi.

Per impostazione predefinita, WDF implementa una ripresa rapida, il che significa che durante la riattivazione del sistema, il proprietario dei criteri di alimentazione in uno stack di dispositivi completa un S0-IRP senza attendere la richiesta e completare una richiesta D0-IRP. Questo non funziona correttamente con PowerRelations.

Per fare in modo che PowerRelations funzioni correttamente, se un dispositivo dipende da un altro dispositivo per entrare prima D0, il secondo dispositivo deve impostare questo flag per rifiutare esplicitamente la ripresa rapida.

In alcuni casi, i criteri globali possono disabilitare la ripresa rapida a livello globale anche se questo flag non è impostato.

DirectedPoFxEnabled

Enumeratore WDF_TRI_STATE tipizzato che indica se il dispositivo abilita DFx (Directed Power Management Framework). Disponibile a partire da KMDF versione 1.33 e UMDF 2.33.

WdfTrue : DFx è abilitato. WdfFalse: DFx è disabilitato. WdfUseDefault: valore predefinito se il driver non ne imposta uno. Questo valore ha lo stesso significato di WdfTrue.

PoFx diretto (DFx) è disponibile a partire da Windows 10 versione 1903 come opzione per i driver che usano SystemManagedIdleTimeout o SystemManagedIdleTimeoutWithHint.

Per un driver destinato alla versione precedente alla versione 31 WDF, impostare la direttiva INF WdfDirectedPowerTransitionEnable su 1 per acconsentire esplicitamente a DFx.
Per un driver destinato a V31+ WDF, DFx è abilitato per impostazione predefinita. Il driver può impostare WdfDirectedPowerTransitionEnable su zero per rifiutare esplicitamente DFx.
Per un driver destinato a V33+ WDF, DFx è abilitato anche per impostazione predefinita. Il driver può impostare WdfDirectedPowerTransitionEnable su zero o impostare questo campo su WdfFalse (scelta consigliata) per rifiutare esplicitamente DFx. Se entrambi sono impostati, la direttiva INF ha la precedenza.

Osservazioni:

La struttura WDF_POWER_FRAMEWORK_SETTINGS viene usato un input per WdfDeviceWdmAssignPowerFrameworkSettings.

Per inizializzare la struttura WDF_POWER_FRAMEWORK_SETTINGS, il driver deve chiamare WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Per UMDF, vengono usati solo Size, PoFxDeviceFlagse DirectedPoFxEnabled. Gli altri campi vengono ignorati e devono essere impostati su zero. Il framework esegue questa operazione automaticamente quando un driver UMDF chiama WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Per altre informazioni, vedere Supporto degli stati di risparmio energia funzionale e panoramica di Power Management Framework.

Questa struttura non è applicabile ai driver client KMDF per dispositivi con più componenti.