WDF_POWER_FRAMEWORK_SETTINGS Struktur (wdfdevice.h)

2025-03-22

[Gilt für KMDF und UMDF]

In der WDF_POWER_FRAMEWORK_SETTINGS-Struktur werden die Einstellungen des Power Management Frameworks (PoFx) für Einzelkomponentengeräte beschrieben.

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;

Elemente

Size

Die Größe dieser Struktur in Byte.

EvtDeviceWdmPostPoFxRegisterDevice

Ein Zeiger auf die EvtDeviceWdmPostPoFxRegisterDevice Ereignisrückruffunktion oder NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Ein Zeiger auf die EvtDeviceWdmPrePoFxUnregisterDevice Ereignisrückruffunktion oder NULL.

Component

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

ComponentActiveConditionCallback

Ein Zeiger auf die ComponentActiveConditionCallback des Treibers Rückrufroutine oder NULL. Das Power Management Framework (PoFx) ruft diese Rückruffunktion auf, wenn eine Komponente aktiv wird. Während der Aktiven Bedingung ist die Komponente garantiert in F0.

ComponentIdleConditionCallback

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

ComponentIdleStateCallback

Ein Zeiger auf die ComponentIdleStateCallback des Treibers Rückruffunktion oder 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 oder NULL. PoFx ruft diese Routine auf, um eine Anforderung für einen Stromsteuerungsvorgang direkt an den Treiber zu übergeben. Wenn Ihr Treiber keine Leistungssteuerungscodes unterstützt, legen Sie diesen Parameter auf NULL fest.

PoFxDeviceContext

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

PoFxDeviceFlags

Ein Wert vom Typ ULONGLONG, der den bitweisen ODER der folgenden Werte enthält, die sich auf das Directed Power Management Frameworkbeziehen. 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 Kennzeichen fest, damit ein solches untergeordnetes Gerät DFx überspringen kann.

Um dieses Kennzeichen im Auftrag untergeordneter Geräte festzulegen, muss der übergeordnete WDF-Treiber:

DFx-
Kein Busfahrer
Sie verfügen über mindestens ein virtuelles untergeordnetes Gerät, das über einen Querbandkanal erstellt wurde (z. B. einen oberen Filter oder ein Gerät, das durch Aufrufen von SwDeviceCreate

Geben Sie für Treiber für pre-v33 WDF stattdessen die INF-Direktive an: WdfDirectedPowerTransitionChildrenOptional, das ab Windows 10, Version 1903, verfügbar ist. Wenn der Treiber die INF-Direktive angibt und dieses Kennzeichen 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.

WDF implementiert standardmäßig einen schnellen Lebenslauf, was bedeutet, dass der Besitzer der Energierichtlinie in einem Gerätestapel eine S0-IRP abgeschlossen hat, ohne darauf zu warten, eine D0-IRP anzufordern und abzuschließen. Dies funktioniert nicht gut mit PowerRelations.

Damit PowerRelations ordnungsgemäß funktioniert, wenn ein Gerät von einem anderen Gerät abhängig ist, um D0 zuerst einzugeben, sollte das zweite Gerät dieses Kennzeichen festlegen, um den schnellen Lebenslauf zu deaktivieren.

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

DirectedPoFxEnabled

Ein WDF_TRI_STATE typisierter Enumerator, der angibt, ob das Gerät das Directed Power Management Framework (DFx) 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 keins festgelegt hat. Dieser Wert hat dieselbe Bedeutung wie WdfTrue.

Directed PoFx (DFx) ist ab Windows 10, Version 1903 als Option für Treiber verfügbar, die SystemManagedIdleTimeout oder SystemManagedIdleTimeoutWithHintverwenden.

Legen Sie für einen Treiber für pre-v31 WDF die INF-Direktive 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 entweder WdfDirectedPowerTransitionEnable- auf Null festlegen oder dieses Feld auf WdfFalse- (empfohlen) festlegen, um DFx zu deaktivieren. Wenn beides festgelegt ist, hat die INF-Direktive Vorrang.

Bemerkungen

Die WDF_POWER_FRAMEWORK_SETTINGS-Struktur wird eine Eingabe zum WdfDeviceWdmAssignPowerFrameworkSettingsverwendet.

Um die WDF_POWER_FRAMEWORK_SETTINGS Struktur zu initialisieren, sollte ihr Treiber WDF_POWER_FRAMEWORK_SETTINGS_INITaufrufen.

Für UMDF werden nur Size, PoFxDeviceFlagsund DirectedPoFxEnabled- verwendet. Andere Felder werden ignoriert und müssen auf Null festgelegt werden. Das Framework führt dies automatisch aus, wenn ein UMDF-Treiber WDF_POWER_FRAMEWORK_SETTINGS_INITaufruft.

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

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