PO_FX_DEVICE_V3 struttura (wdm.h)

Articolo
08/08/2023

La struttura PO_FX_DEVICE_V3 descrive gli attributi di alimentazione di un dispositivo nel framework di gestione energia (PoFx), DFx (Directed PoFx)

Sintassi

typedef struct _PO_FX_DEVICE_V3 {
  ULONG                                      Version;
  ULONGLONG                                  Flags;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK   ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK       ComponentIdleStateCallback;
  PPO_FX_DEVICE_POWER_REQUIRED_CALLBACK      DevicePowerRequiredCallback;
  PPO_FX_DEVICE_POWER_NOT_REQUIRED_CALLBACK  DevicePowerNotRequiredCallback;
  PPO_FX_POWER_CONTROL_CALLBACK              PowerControlCallback;
  PPO_FX_DIRECTED_POWER_UP_CALLBACK          DirectedPowerUpCallback;
  PPO_FX_DIRECTED_POWER_DOWN_CALLBACK        DirectedPowerDownCallback;
  ULONG                                      DirectedFxTimeoutInSeconds;
  PVOID                                      DeviceContext;
  ULONG                                      ComponentCount;
  PO_FX_COMPONENT_V2                         Components[ANYSIZE_ARRAY];
} PO_FX_DEVICE_V3, *PPO_FX_DEVICE_V3;

Members

Version

Numero di versione di questa struttura. Se il driver registrerà il supporto per l'alimentazione diretta con DFx, impostare questo membro su PO_FX_VERSION_V3.

Flags

Controlla se i dispositivi figlio diretti e i dispositivi figlio possono rifiutare esplicitamente l'opzione Direct PoFx.

I valori del flag possibili includono:

Flag	Descrizione
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Consente ai dispositivi figlio diretti di questo dispositivo di supportare facoltativamente Direct PoFx. Se non è impostato, tutti i bambini diretti devono supportare Direct PoFx per questo dispositivo per supportare completamente Direct PoFx.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Consente ai dispositivi figlio di alimentazione di questo dispositivo di supportare facoltativamente Directed PoFx. Se non specificato, tutti i bambini di alimentazione devono supportare Directed PoFx per questo dispositivo per supportare completamente Directed PoFx.
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	Imposta sia PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL che PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	Forza PoFx a impedire che l'IRP S0 venga completato prima del ripristino di D0-IRP da uno stato di sistema, ad esempio Hibernate o Sleep. Si escludono a vicenda con PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Forza PoFx a consentire il completamento di S0-IRP prima del ripristino di D0-IRP da uno stato di sistema, ad esempio Hibernate o Sleep. Si escludono a vicenda con PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.

ComponentActiveConditionCallback

Puntatore alla routine di callback ComponentActiveConditionCallback implementata dal driver del dispositivo.

ComponentIdleConditionCallback

Puntatore alla routine di callback ComponentIdleConditionCallback implementata dal driver del dispositivo.

ComponentIdleStateCallback

Puntatore alla routine di callback ComponentIdleStateCallback implementata dal driver del dispositivo.

DevicePowerRequiredCallback

Puntatore alla routine di callback DevicePowerRequiredCallback implementata dal driver di dispositivo.

DevicePowerNotRequiredCallback

Puntatore alla routine di callback DevicePowerNotRequiredCallback implementata dal driver del dispositivo.

PowerControlCallback

Puntatore alla routine di callback powerControlCallback implementata dal driver del dispositivo.

DirectedPowerUpCallback

Puntatore alla routine di callback PO_FX_DIRECTED_POWER_UP_CALLBACK implementata dal driver del dispositivo. Un dispositivo può fornire solo i callback durante la DirectedPower* registrazione per PoFx. Non è necessario implementare il resto dei callback di PoFx.

DirectedPowerDownCallback

Puntatore alla routine di callback PO_FX_DIRECTED_POWER_DOWN_CALLBACK implementata dal driver del dispositivo.

DirectedFxTimeoutInSeconds

Fornisce un suggerimento al framework che specifica un timeout consigliato in secondi in cui il dispositivo deve essere stato disattivato dopo che l'attività software non è più presente. Il valore predefinito è 2 minuti.

DeviceContext

Puntatore a un contesto di dispositivo allocato dal chiamante. Questo puntatore viene passato come parametro a ogni funzione di callback implementata dal driver a cui punta questa struttura. Il driver del dispositivo usa questo contesto per archiviare informazioni sullo stato corrente del dispositivo. Questo contesto è opaco a PoFx.

ComponentCount

Numero di elementi nella matrice Components . Inoltre, questo membro specifica il numero di componenti nel dispositivo.

Components[ANYSIZE_ARRAY]

Questo membro è il primo elemento in una matrice di uno o più elementi PO_FX_COMPONENT_V2. Se la matrice contiene più elementi, gli elementi aggiuntivi seguono immediatamente la struttura PO_FX_DEVICE_V2 . La matrice contiene un elemento per ogni componente del dispositivo. Lo stato di alimentazione Fx di ogni componente può essere controllato indipendentemente dagli stati di alimentazione Fx degli altri componenti nel dispositivo. La costante ANYSIZE_ARRAY è definita come 1 nel file di intestazione Ntdef.h.

Commenti

Per registrare un dispositivo con PoFx, un driver chiama la routine PoFxRegisterDevice e fornisce, come parametro, un puntatore a una struttura PO_FX_DEVICE che descrive il dispositivo. Per usare PoFx ma non DFx, registrare con PoFx usando PO_FX_DEVICE_V2 struttura o PO_FX_DEVICE_V3 struttura.

Ogni elemento nella matrice Components descrive gli attributi dello stato di alimentazione di un componente nel dispositivo. Ogni componente nel dispositivo viene identificato dall'indice matrice Components . Routine come PoFxActivateComponent e PoFxCompleteIdleCondition usano l'indice della matrice di un componente per identificare il componente.

Un driver di dispositivo non è necessario per implementare tutte e otto le routine di callback. Il driver può impostare un puntatore alla funzione nella struttura PO_FX_DEVICE su NULL se il driver non implementa la routine di callback corrispondente. Tuttavia, alcune routine di callback devono essere implementate. In particolare, se uno o più componenti in un dispositivo ha più di uno stato Fx, il driver deve implementare le routine ComponentIdleStateCallback, ComponentActiveConditionCallback e ComponentIdleConditionCallback . In caso contrario, la registrazione del dispositivo ha esito negativo e PoFxRegisterDevice restituisce STATUS_INVALID_PARAMETER.

Se un driver non fornisce uno dei PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME o PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME il sistema eseguirà il fallback alla configurazione predefinita della piattaforma. La configurazione predefinita è PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME per le piattaforme x86/x64 e PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME per le piattaforme ARM32/ARM64. Questi flag sono onorati solo per Win11 22000+ e vengono ignorati in modo silenzioso per le versioni precedenti. Per i driver WDF è possibile specificare questi flag usando il campo PoFxDeviceFlags di WDF_POWER_FRAMEWORK_SETTINGS.