PO_FX_DEVICE_V3结构（wdm.h）

项目
02/07/2025

PO_FX_DEVICE_V3 结构描述设备电源管理框架（PoFx）、DFx（定向 PoFx）

语法

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;

成员

Version

此结构的版本号。如果驱动程序将注册 DFx 的定向电源支持，请将此成员设置为 PO_FX_VERSION_V3。

Flags

控制直接子设备和电源子设备是否可以选择退出定向 PoFx。

可能的标志值包括：

旗	描述
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	允许此设备的直接子设备（可选）支持定向 PoFx。如果未设置，则所有直接子级必须支持此设备的定向 PoFx 才能完全支持 Direct PoFx。
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	允许此设备的电源子设备（可选）支持定向 PoFx。如果未提供，则所有电源子级必须支持此设备的定向 PoFx，才能完全支持定向 PoFx。
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	设置 PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL 和 PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	强制 PoFx 防止在从系统状态（如休眠或睡眠）恢复 D0-IRP 之前完成 S0-IRP。与 PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME互斥。
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	强制 PoFx 允许在从系统状态（如休眠或睡眠）恢复 D0-IRP 之前完成 S0-IRP。与 PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME互斥。

ComponentActiveConditionCallback

指向由设备驱动程序实现的 ComponentActiveConditionCallback 回调例程的指针。

ComponentIdleConditionCallback

指向由设备驱动程序实现的 ComponentIdleConditionCallback 回调例程的指针。

ComponentIdleStateCallback

指向由设备驱动程序实现的 ComponentIdleStateCallback 回调例程的指针。

DevicePowerRequiredCallback

指向由设备驱动程序实现的 DevicePowerRequiredCallback 回调例程的指针。

DevicePowerNotRequiredCallback

指向由设备驱动程序实现的 DevicePowerNotRequiredCallback 回调例程的指针。

PowerControlCallback

指向由设备驱动程序实现的 PowerControlCallback 回调例程的指针。

DirectedPowerUpCallback

指向由设备驱动程序实现的 PO_FX_DIRECTED_POWER_UP_CALLBACK 回调例程的指针。设备只能在注册 PoFx 时提供 DirectedPower* 回调。它不需要实现 PoFx 回调的其余部分。

DirectedPowerDownCallback

指向由设备驱动程序实现的 PO_FX_DIRECTED_POWER_DOWN_CALLBACK 回调例程的指针。

DirectedFxTimeoutInSeconds

为框架提供一个提示，该框架指定建议的超时时间（以秒为单位），即设备在软件活动不再存在后应处于空闲状态。默认值为 2 分钟。

DeviceContext

指向调用方分配的设备上下文的指针。此指针作为参数传递给此结构指向的每个驱动程序实现的回调函数。设备驱动程序使用此上下文来存储有关设备的当前电源状态的信息。此上下文对 PoFx 不透明。

ComponentCount

组件数组中的元素数。此外，此成员指定设备中的组件数。

Components[ANYSIZE_ARRAY]

此成员是一个或多个PO_FX_COMPONENT_V2元素数组中的第一个元素。如果数组包含多个元素，则附加元素紧跟 PO_FX_DEVICE_V2 结构。该数组包含设备中每个组件的一个元素。每个组件的 Fx 电源状态可以独立于设备中其他组件的 Fx 电源状态进行控制。 ANYSIZE_ARRAY 常量定义为 Ntdef.h 头文件中的 1。

言论

若要向 PoFx 注册设备，驱动程序调用 PoFxRegisterDevice 例程并提供，作为参数，指向描述设备的 PO_FX_DEVICE 结构的指针。若要使用 PoFx 而不是 DFx，请使用 PO_FX_DEVICE_V2 结构或PO_FX_DEVICE_V3结构向 PoFx 注册。

组件数组中的每个元素都描述了设备中一个组件的电源状态属性。设备中的每个组件都由其组件数组索引标识。 PoFxActivateComponent 和 PoFxCompleteIdleCondition 等例程使用组件的数组索引来标识组件。

实现所有八个回调例程不需要设备驱动程序。如果驱动程序未实现相应的回调例程，驱动程序可以在 PO_FX_DEVICE 结构中将函数指针设置为 NULL。但是，必须实现某些回调例程。具体而言，如果设备中的一个或多个组件具有多个 Fx 状态，驱动程序必须实现 ComponentIdleStateCallback、ComponentActiveConditionCallback，以及 ComponentIdleConditionCallback 例程。否则，设备注册失败，PoFxRegisterDevice 返回 STATUS_INVALID_PARAMETER。

如果驱动程序不提供 PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME 或 PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME 系统将回退到平台的默认配置。对于 x86/x64 平台，默认配置为 PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME，对于 ARM32/ARM64 平台 PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME。这些标志仅适用于 Win11 22000+ 版本，并且对于以前的版本，这些标志会被无提示忽略。对于 WDF 驱动程序，可以使用 WDF_POWER_FRAMEWORK_SETTINGSPoFxDeviceFlags 字段提供这些标志。