PO_FX_DEVICE_V3-Struktur (wdm.h)

Artikel
02/29/2024

Die PO_FX_DEVICE_V3-Struktur beschreibt die Energieattribute eines Geräts für das Energieverwaltungsframework (PoFx), DFx (Directed PoFx)

Syntax

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;

Member

Version

Die Versionsnummer dieser Struktur. Wenn sich der Treiber für die gesteuerte Energieunterstützung bei DFx registriert, legen Sie dieses Element auf PO_FX_VERSION_V3 fest.

Flags

Steuert, ob direkte untergeordnete Geräte und power child-Geräte directed poFx deaktivieren können.

Mögliche Flagwerte sind:

Flag	Beschreibung
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Ermöglicht es direkten untergeordneten Geräten dieses Geräts, direct PoFx optional zu unterstützen. Wenn nicht festgelegt, müssen alle direkten untergeordneten Elemente Directed PoFx unterstützen, damit dieses Gerät Directed PoFx vollständig unterstützt.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Ermöglicht power child devices of this device to optional support Directed PoFx. Wenn nicht bereitgestellt, müssen alle Power Children Directed PoFx unterstützen, damit dieses Gerät Directed PoFx vollständig unterstützt.
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	Legt sowohl PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL als auch PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL fest
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	PoFx erzwingt, zu verhindern, dass das S0-IRP vor dem D0-IRP beim Fortsetzen aus einem Systemzustand wie Ruhezustand oder Ruhezustand abgeschlossen wird. Schließen Sie sich mit PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME gegenseitig aus.
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Erzwingt, dass PoFx das Abschließen des S0-IRP vor dem D0-IRP beim Fortsetzen aus einem Systemzustand wie Ruhezustand oder Ruhezustand zulässt. Schließen Sie sich mit PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME gegenseitig aus.

ComponentActiveConditionCallback

Ein Zeiger auf die Rückrufroutine ComponentActiveConditionCallback , die vom Gerätetreiber implementiert wird.

ComponentIdleConditionCallback

Ein Zeiger auf die Rückrufroutine ComponentIdleConditionCallback , die vom Gerätetreiber implementiert wird.

ComponentIdleStateCallback

Ein Zeiger auf die Rückrufroutine ComponentIdleStateCallback , die vom Gerätetreiber implementiert wird.

DevicePowerRequiredCallback

Ein Zeiger auf die Rückrufroutine DevicePowerRequiredCallback , die vom Gerätetreiber implementiert wird.

DevicePowerNotRequiredCallback

Ein Zeiger auf die Rückrufroutine DevicePowerNotRequiredCallback , die vom Gerätetreiber implementiert wird.

PowerControlCallback

Ein Zeiger auf die PowerControlCallback-Rückrufroutine , die vom Gerätetreiber implementiert wird.

DirectedPowerUpCallback

Ein Zeiger auf die PO_FX_DIRECTED_POWER_UP_CALLBACK Rückrufroutine, die vom Gerätetreiber implementiert wird. Ein Gerät kann bei der Registrierung für PoFx nur die DirectedPower* Rückrufe bereitstellen. Der Rest der PoFx-Rückrufe muss nicht implementiert werden.

DirectedPowerDownCallback

Ein Zeiger auf die PO_FX_DIRECTED_POWER_DOWN_CALLBACK Rückrufroutine, die vom Gerätetreiber implementiert wird.

DirectedFxTimeoutInSeconds

Stellt einen Hinweis an das Framework bereit, der ein empfohlenes Timeout in Sekunden angibt, in dem das Gerät inaktiv sein sollte, nachdem die Softwareaktivität nicht mehr vorhanden ist. Der Standardwert beträgt 2 Minuten.

DeviceContext

Ein Zeiger auf einen vom Aufrufer zugeordneten Gerätekontext. Dieser Zeiger wird als Parameter an jede vom Treiber implementierte Rückruffunktion übergeben, auf die von dieser Struktur verwiesen wird. Der Gerätetreiber verwendet diesen Kontext, um Informationen zum aktuellen Energiezustand des Geräts zu speichern. Dieser Kontext ist für PoFx undurchsichtig.

ComponentCount

Die Anzahl der Elemente im Komponentenarray . Darüber hinaus gibt dieser Member die Anzahl der Komponenten im Gerät an.

Components[ANYSIZE_ARRAY]

Dieses Element ist das erste Element in einem Array von mindestens einem PO_FX_COMPONENT_V2-Elementen. Wenn das Array mehr als ein Element enthält, folgen die zusätzlichen Elemente sofort der PO_FX_DEVICE_V2-Struktur . Das Array enthält ein Element für jede Komponente im Gerät. Der Fx-Energiezustand jeder Komponente kann unabhängig von den Fx-Leistungszuständen der anderen Komponenten im Gerät gesteuert werden. Die ANYSIZE_ARRAY Konstante ist in der Ntdef.h-Headerdatei als 1 definiert.

Hinweise

Um ein Gerät bei PoFx zu registrieren, ruft ein Treiber die PoFxRegisterDevice-Routine auf und stellt als Parameter einen Zeiger auf eine PO_FX_DEVICE Struktur bereit, die das Gerät beschreibt. Um PoFx, aber nicht DFx zu verwenden, registrieren Sie sich bei PoFx, indem Sie entweder PO_FX_DEVICE_V2-Struktur oder PO_FX_DEVICE_V3 Struktur verwenden.

Jedes Element im Komponentenarray beschreibt die Energiezustandsattribute einer Komponente im Gerät. Jede Komponente im Gerät wird durch ihren Komponentenarrayindex identifiziert. Routinen wie PoFxActivateComponent und PoFxCompleteIdleCondition verwenden den Arrayindex einer Komponente, um die Komponente zu identifizieren.

Ein Gerätetreiber ist nicht erforderlich, um alle acht Rückrufroutinen zu implementieren. Der Treiber kann einen Funktionszeiger in der PO_FX_DEVICE-Struktur auf NULL festlegen, wenn der Treiber die entsprechende Rückrufroutine nicht implementiert. Allerdings müssen bestimmte Rückrufroutinen implementiert werden. Insbesondere wenn eine oder mehrere Komponenten in einem Gerät über mehr als einen Fx-Zustand verfügen, muss der Treiber die Routinen ComponentIdleStateCallback, ComponentActiveConditionCallback und ComponentIdleConditionCallback implementieren. Andernfalls schlägt die Geräteregistrierung fehl, und PoFxRegisterDevice gibt STATUS_INVALID_PARAMETER zurück.

Wenn ein Treiber keines der PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME oder PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME führt das System ein Fallback auf die Standardkonfiguration der Plattform aus. Die Standardkonfiguration ist PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME für x86/x64-Plattformen und PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME für ARM32-/ARM64-Plattformen. Diese Flags werden nur für Win11 22000+ berücksichtigt und werden für frühere Versionen automatisch ignoriert. Für WDF-Treiber können diese Flags mithilfe des PoFxDeviceFlags-Feldsvon WDF_POWER_FRAMEWORK_SETTINGS bereitgestellt werden.