WDF_POWER_FRAMEWORK_SETTINGS-Struktur (wdfdevice.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WDF_POWER_FRAMEWORK_SETTINGS-Struktur beschreibt PoFx-Einstellungen (Power Management Framework) für Einzelkomponentengeräte.

Syntax

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;

Member

Size

Die Größe (in Bytes) dieser Struktur.

EvtDeviceWdmPostPoFxRegisterDevice

Ein Zeiger auf die Ereignisrückruffunktion EvtDeviceWdmPostPoFxRegisterDevice des Treibers oder NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Ein Zeiger auf die EvtDeviceWdmPrePoFxUnregisterDevice-Ereignisrückruffunktion des Treibers oder NULL.

Component

Ein Zeiger auf eine PO_FX_COMPONENT-Struktur , die die einzige Komponente im Einzelkomponentengerät oder NULL beschreibt. Bei NULL wird KMDF standardmäßig nur für diese Komponente auf F0-Unterstützung festgelegt. Diese Struktur gibt die Anzahl und Attribute der von der Komponente unterstützten F-Zustände sowie den tiefsten Fx-Zustand an, aus dem die Komponente erwachen kann.

ComponentActiveConditionCallback

Ein Zeiger auf die ComponentActiveConditionCallback-Rückrufroutine des Treibers (NULL). Das Power Management Framework (PoFx) ruft diese Rückruffunktion auf, wenn eine Komponente aktiv wird. In der Active-Bedingung wird garantiert, dass sich die Komponente in F0 befindet.

ComponentIdleConditionCallback

Ein Zeiger auf die ComponentIdleConditionCallback-Rückruffunktion des Treibers oder NULL. PoFx ruft diese Rückruffunktion auf, wenn eine Komponente im Leerlauf ist. Im Leerlaufzustand kann sich die Komponente in einem beliebigen F-Zustand befinden, einschließlich F0.

ComponentIdleStateCallback

Ein Zeiger auf die Rückruffunktion ComponentIdleStateCallback des Treibers (NULL). PoFx ruft diese Rückruffunktion auf, wenn sich der F-Zustand der Komponente ändert.

PowerControlCallback

Ein Zeiger auf die PowerControlCallback-Rückruffunktion des Clienttreibers (NULL). PoFx ruft diese Routine auf, um eine Anforderung für einen Energiesteuerungsvorgang direkt an den Treiber zu übergeben. Wenn Ihr Treiber keine Stromsteuerungscodes unterstützt, legen Sie diesen Parameter auf NULL fest.

PoFxDeviceContext

Ein Kontextzeiger, den das Framework für ComponentActiveConditionCallback, ComponentIdleConditionCallback, ComponentIdleStateCallback und PowerControlCallback bereitstellt.

PoFxDeviceFlags

Ein Wert vom Typ ULONGLONG, der den bitweisen OR der folgenden Werte im Zusammenhang mit dem Directed Power Management Framework enthält. Dieses Feld ist ab KMDF Version 1.33 und UMDF 2.33 verfügbar.

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

Wenn das Directed Power Framework ("DFx") auf einem Gerät aktiviert ist, aktivieren in der Regel auch untergeordnete Geräte DFx. In einigen Fällen (z. B. ein reines Softwaregerät) implementiert ein untergeordnetes Gerät jedoch keine Energieverwaltung. Legen Sie dieses Flag fest, damit ein solches untergeordnetes Gerät DFx überspringen kann.

Um dieses Flag im Namen untergeordneter Geräte festzulegen, muss der übergeordnete WDF-Treiber Folgendes ausführen:

Wählen Sie DFx aus.
Kein Busfahrer sein
Mindestens ein virtuelles untergeordnetes Gerät über einen Seitenbandkanal erstellt haben (z. B. ein oberer Filter oder ein Gerät, das durch Aufrufen von SwDeviceCreate erstellt wird

Geben Sie für Treiber, die auf pre-v33 WDF abzielen, stattdessen die INF-Direktive an: WdfDirectedPowerTransitionChildrenOptional, die ab Windows 10, Version 1903, verfügbar ist. Wenn der Treiber die INF-Direktive angibt und dieses Flag festlegt, hat die INF-Direktive Vorrang.

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

Dies ist erforderlich, um IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations zwischen zwei Geräten zu implementieren.

Standardmäßig implementiert WDF eine schnelle Fortsetzung, was bedeutet, dass der Besitzer der Energierichtlinie in einem Gerätestapel während der Systemreaktivierung eine S0-IRP abschließt, ohne auf die Anforderung und das Abschließen eines D0-IRP zu warten. Dies funktioniert nicht gut mit PowerRelations.

Damit PowerRelations ordnungsgemäß funktioniert, sollte das zweite Gerät dieses Flag so festlegen, dass die schnelle Fortsetzung deaktiviert wird, wenn ein Gerät von einem anderen Gerät abhängig ist, um zuerst D0 einzugeben.

In einigen Fällen kann die globale Richtlinie den schnellen Fortsetzen global deaktivieren, auch wenn dieses Flag nicht festgelegt ist.

DirectedPoFxEnabled

Ein WDF_TRI_STATE typisiertes Enumerator, der angibt, ob das Gerät DFx (Directed Power Management Framework) aktiviert. Verfügbar ab KMDF Version 1.33 und UMDF 2.33.

WdfTrue : DFx ist aktiviert. WdfFalse : DFx ist deaktiviert. WdfUseDefault : Der Standardwert, wenn der Treiber keinen wert legt. Dieser Wert hat die gleiche Bedeutung wie WdfTrue.

Directed PoFx (DFx) ist ab Windows 10 Version 1903 als Option für Treiber verfügbar, die SystemManagedIdleTimeoutout oderSystemManagedIdleTimeoutWithHint verwenden.

Legen Sie für einen Treiber für pre-v31 WDF die INF-Anweisung WdfDirectedPowerTransitionEnable auf 1 fest, um DFx zu aktivieren.
Für einen Treiber für v31+ WDF ist DFx standardmäßig aktiviert. Der Treiber kann WdfDirectedPowerTransitionEnable auf Null festlegen, um DFx zu deaktivieren.
Für einen Treiber für v33+ WDF ist DFx ebenfalls standardmäßig aktiviert. Der Treiber kann WdfDirectedPowerTransitionEnable entweder auf Null festlegen oder dieses Feld auf WdfFalse (empfohlen) festlegen, um DFx zu deaktivieren. Wenn beide festgelegt sind, hat die INF-Direktive Vorrang.

Hinweise

Die WDF_POWER_FRAMEWORK_SETTINGS-Struktur wird als Eingabe für WdfDeviceWdmAssignPowerFrameworkSettings verwendet.

Um die WDF_POWER_FRAMEWORK_SETTINGS-Struktur zu initialisieren, sollte Ihr Treiber WDF_POWER_FRAMEWORK_SETTINGS_INIT aufrufen.

Für UMDF werden nur Size, PoFxDeviceFlags und DirectedPoFxEnabled verwendet. Andere Felder werden ignoriert und müssen auf 0 festgelegt werden. Das Framework macht dies automatisch, wenn ein UMDF-Treiber WDF_POWER_FRAMEWORK_SETTINGS_INIT aufruft.

Weitere Informationen finden Sie unter Unterstützen von Funktionsenergiezuständen und Übersicht über das Power Management Framework.

Diese Struktur gilt nicht für KMDF-Clienttreiber für Geräte mit mehreren Komponenten.