struttura WDF_POWER_FRAMEWORK_SETTINGS (wdfdevice.h)

Articolo
08/08/2023

[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 singolo componente.

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;

Members

Size

Dimensione, in byte, della struttura.

EvtDeviceWdmPostPoFxRegisterDevice

Puntatore alla funzione di callback dell'evento EvtDeviceWdmPostPoFxRegisterDevice del driver o NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Puntatore alla funzione di callback dell'evento EvtDeviceWdmPrePoFxUnregisterDevice del driver o NULL.

Component

Puntatore a una struttura PO_FX_COMPONENT che descrive l'unico componente nel dispositivo a singolo componente 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ò risvegliarsi.

ComponentActiveConditionCallback

Puntatore alla routine di callback ComponentActiveConditionCallback del driver 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 alla funzione di callback ComponentIdleConditionCallback del driver 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 alla funzione di callback ComponentIdleStateCallback del driver o NULL. PoFx chiama questa funzione di callback quando cambia lo stato F del componente.

PowerControlCallback

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

PoFxDeviceContext

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

PoFxDeviceFlags

Valore di tipo ULONGLONG contenente l'OR bit per bit dei valori seguenti correlati a Directed Power Management Framework. 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 i dispositivi figlio abilitano anche 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 di banda laterale ,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 provider di risorse S0 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 immettere 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 tipizzato WDF_TRI_STATE che indica se il dispositivo abilita Directed Power Management Framework (DFx). Disponibile a partire dalla versione 1.33 e UMDF 2.33 di KMDF.

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

Directed PoFx (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.

Commenti

La struttura WDF_POWER_FRAMEWORK_SETTINGS viene usata 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, PoFxDeviceFlags e 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 a più componenti.