WDF_POWER_FRAMEWORK_SETTINGS 结构 (wdfdevice.h)

  • 项目

[适用于 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

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

ComponentActiveConditionCallback

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

ComponentIdleConditionCallback

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

ComponentIdleStateCallback

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

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 驱动程序必须：

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

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

这是在两个设备之间实现 IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations 所必需的。

默认情况下，WDF 实现快速恢复，这意味着在系统唤醒期间，设备堆栈中的电源策略所有者完成 S0-IRP，而无需等待请求并完成 D0-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 指令优先。

注解

WDF_POWER_FRAMEWORK_SETTINGS 结构用于 WdfDeviceWdmAssignPowerFrameworkSettings 的输入。

若要初始化其 WDF_POWER_FRAMEWORK_SETTINGS 结构，驱动程序应调用 WDF_POWER_FRAMEWORK_SETTINGS_INIT。

对于 UMDF，仅使用 Size、 PoFxDeviceFlags 和 DirectedPoFxEnabled 。 其他字段将被忽略，并且必须设置为零。 当 UMDF 驱动程序调用 WDF_POWER_FRAMEWORK_SETTINGS_INIT 时，框架会自动执行此操作。

有关详细信息，请参阅 支持功能电源状态 和 电源管理框架概述。

此结构不适用于多组件设备的 KMDF 客户端驱动程序。

要求

要求 值
最低 KMDF 版本 1.11
最低 UMDF 版本 2.33
标头 wdfdevice.h (包括 Wdf.h)

另请参阅

EvtDeviceWdmPostPoFxRegisterDevice

EvtDeviceWdmPrePoFxUnregisterDevice

WDF_POWER_FRAMEWORK_SETTINGS_INIT

WdfDeviceWdmAssignPowerFrameworkSettings