WDF_POWER_FRAMEWORK_SETTINGS结构（wdfdevice.h）

项目
03/22/2025

[适用于 KMDF 和 UMDF]

WDF_POWER_FRAMEWORK_SETTINGS 结构描述单组件设备的电源管理框架（PoFx）设置。

语法

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;

成员

Size

此结构的大小（以字节为单位）。

EvtDeviceWdmPostPoFxRegisterDevice

指向驱动程序 EvtDeviceWdmPostPoFxRegisterDevice 事件回调函数或 NULL 的指针。

EvtDeviceWdmPrePoFxUnregisterDevice

指向驱动程序 EvtDeviceWdmPrePoFxUnregisterDevice 事件回调函数或 NULL 的指针。

Component

指向描述单组件设备中唯一组件或 NULL 的 PO_FX_COMPONENT 结构的指针。如果为 NULL，则 KMDF 默认为 F0 仅支持此组件。此结构指定组件支持的 F 状态的数量和属性，以及组件可以从中唤醒的最深 Fx 状态。

ComponentActiveConditionCallback

指向驱动程序的 ComponentActiveConditionCallback 回调例程或 NULL 的指针。当组件处于活动状态时，电源管理框架（PoFx）将调用此回调函数。在活动条件下，组件保证在 F0 中。

ComponentIdleConditionCallback

指向驱动程序的 ComponentIdleConditionCallback 回调函数或 NULL 的指针。 PoFx 在组件空闲时调用此回调函数。处于空闲状态时，组件可能处于任何 F 状态，包括 F0。

ComponentIdleStateCallback

指向驱动程序的 ComponentIdleStateCallback 回调函数或 NULL 的指针。 PoFx 在组件 F 状态更改时调用此回调函数。

PowerControlCallback

指向客户端驱动程序 PowerControlCallback 回调函数或 NULL 的指针。 PoFx 调用此例程，将电源控制作的请求直接传递给驱动程序。如果驱动程序不支持任何电源控制代码，请将此参数设置为 NULL。

PoFxDeviceContext

框架提供给 ComponentActiveConditionCallback、ComponentIdleConditionCallback、ComponentIdleStateCallback和 PowerControlCallback的上下文指针。

PoFxDeviceFlags

ULONGLONG 类型的值，其中包含与定向电源管理框架相关的以下值的按位 OR。此字段从 KMDF 版本 1.33 和 UMDF 2.33 开始可用。

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

在设备上启用定向 Power Framework（“DFx”）时，通常子设备也会启用 DFx。但是，在某些情况下（例如纯软件设备），子设备不实现电源管理。设置此标志以允许此类子设备跳过 DFx。

若要代表子设备设置此标志，父 WDF 驱动程序必须：

选择加入 DFx
不是总线驱动程序
至少有一个虚拟子设备通过侧带通道创建（例如，通过调用 SwDeviceCreate 创建的上部筛选器或设备）

对于面向 v33 WDF 的驱动程序，请改为指定 INF 指令：WdfDirectedPowerTransitionChildrenOptional，从 Windows 10 版本 1903 开始提供。如果驱动程序指定 INF 指令并设置此标志，则 INF 指令优先。

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

这需要在两台设备之间实现 IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations。

默认情况下，WDF 实现快速恢复，这意味着在系统唤醒期间，设备堆栈中的电源策略所有者无需等待请求并完成 D0-IRP 即可完成 S0-IRP。这不适用于 PowerRelations。

若要使 PowerRelations 正常工作，如果设备依赖于另一台设备先输入 D0，则第二台设备应设置此标志以选择退出快速恢复。

在某些情况下，即使未设置此标志，全局策略也可能全局禁用快速恢复。

DirectedPoFxEnabled

一个WDF_TRI_STATE类型的枚举器，指示设备是否启用定向电源管理框架（DFx）。从 KMDF 版本 1.33 和 UMDF 2.33 开始可用。

WdfTrue - 已启用 DFx。 WdfFalse – 禁用 DFx。 WdfUseDefault - 如果驱动程序未设置默认值。此值的含义与 WdfTrue相同。

从 Windows 10 版本 1903 开始，定向 PoFx（DFx）作为使用 SystemManagedIdleTimeout 或 SystemManagedIdleTimeoutWithHint的驱动程序的选项可用。

对于面向 v31 WDF 的驱动程序，请将 INF 指令 WdfDirectedPowerTransitionEnable 设置为 1 以选择加入 DFx。
对于面向 v31+ WDF 的驱动程序，默认启用 DFx。驱动程序可以将 WdfDirectedPowerTransitionEnable 设置为零，以选择退出 DFx。
对于面向 v33+ WDF 的驱动程序，默认情况下还会启用 DFx。驱动程序可以将 WdfDirectedPowerTransitionEnable 设置为零，或者将此字段设置为 WdfFalse（建议）选择退出 DFx。如果两者都已设置，则 INF 指令优先。