PO_FX_DEVICE_V3 Struktur (wdm.h)

Artikel
02/07/2025

Die PO_FX_DEVICE_V3 Struktur beschreibt die Leistungsattribute eines Geräts an das Power Management Framework (PoFx), DFx (Direkt 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;

Angehörige

Version

Die Versionsnummer dieser Struktur. Wenn sich der Treiber für die gerichtete Energieunterstützung bei DFx registriert, legen Sie dieses Mitglied auf PO_FX_VERSION_V3fest.

Flags

Steuert, ob direkte untergeordnete Geräte und untergeordnete Geräte die Option "Direct PoFx" deaktivieren können.

Mögliche Kennzeichenwerte sind:

Flagge	Beschreibung
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Ermöglicht direkten untergeordneten Geräten dieses Geräts optional die Unterstützung von Direct PoFx. Wenn nicht festgelegt, müssen alle direkten Untergeordneten Direct PoFx für dieses Gerät unterstützen, um Direct PoFx vollständig zu unterstützen.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Ermöglicht untergeordneten Geräten dieses Geräts optional die Unterstützung von "Directed PoFx". Wenn dies nicht der Fall ist, müssen alle Power-Kinder "Directed PoFx" für dieses Gerät unterstützen, um "Directed PoFx" vollständig zu unterstützen.
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
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	Erzwingt PoFx, um zu verhindern, dass die S0-IRP abgeschlossen werden, bevor die D0-IRP beim Fortsetzen aus einem Systemzustand wie "Ruhezustand" oder "Ruhezustand" fortgesetzt wird. Sich gegenseitig ausschließend mit PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Erzwingt PoFx, damit die S0-IRP abgeschlossen werden können, bevor die D0-IRP beim Fortsetzen aus einem Systemzustand wie Ruhezustand oder Ruhezustand fortgesetzt wird. Sich gegenseitig ausschließend mit PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.

ComponentActiveConditionCallback

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

ComponentIdleConditionCallback

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

ComponentIdleStateCallback

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

DevicePowerRequiredCallback

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

DevicePowerNotRequiredCallback

Ein Zeiger auf die DevicePowerNotRequiredCallback Rückrufroutine, 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 beim Registrieren 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 auf das Framework bereit, der ein empfohlenes Timeout in Sekunden angibt, in dem das Gerät nach der Softwareaktivität nicht mehr vorhanden sein sollte. Der Standardwert beträgt 2 Minuten.

DeviceContext

Ein Zeiger auf einen vom Anrufer zugewiesenen 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 undurchsichtig für PoFx.

ComponentCount

Die Anzahl der Elemente im Components Array. Darüber hinaus gibt dieses Element die Anzahl der Komponenten im Gerät an.

Components[ANYSIZE_ARRAY]

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

Bemerkungen

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 dar, die das Gerät beschreibt. Um PoFx, aber nicht DFx zu verwenden, registrieren Sie sich bei PoFx mit PO_FX_DEVICE_V2 Struktur oder PO_FX_DEVICE_V3 Struktur.

Jedes Element im Components Array beschreibt die Energiezustandsattribute einer Komponente im Gerät. Jede Komponente im Gerät wird durch ihre Komponenten Arrayindex 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. Bestimmte Rückrufroutinen müssen jedoch implementiert werden. Wenn eine oder mehrere Komponenten eines Geräts mehr als einen Fx-Zustand aufweisen, muss der Treiber ComponentIdleStateCallback, ComponentActiveConditionCallbackund ComponentIdleConditionCallback Routinen implementieren. Andernfalls schlägt die Geräteregistrierung fehl und PoFxRegisterDevice gibt STATUS_INVALID_PARAMETERzurück.

Wenn ein Treiber keinen von PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME oder PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME bereitstellt, wird das System auf die Standardkonfiguration der Plattform zurückfallen. 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 Feld von WDF_POWER_FRAMEWORK_SETTINGSbereitgestellt werden.