PO_FX_DEVICE_V3 结构 (wdm.h)

项目
08/08/2023

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，才能完全支持定向 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 防止 S0-IRP 在从系统状态（如休眠或睡眠）恢复 D0-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 数组中的元素数。此外，此成员指定设备中的组件数。

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 注册。

Components 数组中的每个元素描述设备中一个组件的电源状态属性。设备中的每个组件都由其 Components 数组索引标识。 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_SETTINGS 的 PoFxDeviceFlags 字段提供这些标志。