WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构 (wdfdevice.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS结构包含驱动程序提供的有关设备自身和系统（当两者都处于低功耗状态时）唤醒自身和系统的能力的信息。

语法

typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
  ULONG                                 Size;
  DEVICE_POWER_STATE                    DxState;
  WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
  WDF_TRI_STATE                         Enabled;
  BOOLEAN                               ArmForWakeIfChildrenAreArmedForWake;
  BOOLEAN                               IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;

成员

Size

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

DxState

一个DEVICE_POWER_STATE类型的枚举器，用于标识当系统电源状态降至可唤醒的低功耗状态时设备将进入的低设备电源状态。 DxState 的值不能为 PowerDeviceD0。 DEVICE_POWER_STATE 值在 wdm.h 中定义。

UserControlOfWakeSettings

一个WDF_POWER_POLICY_SX_WAKE_USER_CONTROL类型的枚举器，指示用户是否能够修改设备的唤醒设置。

Enabled

一个WDF_TRI_STATE类型的枚举器，指示设备是否可以唤醒系统 (即，在系统处于低功耗状态时将系统还原到 S0) 。此成员可以具有以下值之一：

WdfTrue - 唤醒系统已启用。

WdfFalse - 唤醒系统已禁用。

WdfUseDefault - 最初默认启用系统;但如果 UserControlOfWakeSettings 成员设置为 WakeAllowUserControl，则用户的设置或驱动程序的 INF 文件将替代初始值。

如果唤醒系统且系统即将进入低功耗状态，框架会在设备进入低功耗状态之前调用驱动程序的 EvtDeviceArmWakeFromSx 或 EvtDeviceArmWakeFromSxWithReason 回调函数。

ArmForWakeIfChildrenAreArmedForWake

一个布尔值，如果设置为 TRUE，则指示父设备在为设备的子设备启用此功能时，应启用自身和系统的能力。有关更多信息，请参见下面的“备注”部分。此成员在 1.7 版及更高版本的 KMDF 中可用。

IndicateChildWakeOnParentWake

如果设置为 TRUE，则表示如果父设备检测到唤醒信号，框架将为子设备提供唤醒状态。有关更多信息，请参见下面的“备注”部分。此成员在 1.7 版及更高版本的 KMDF 中可用。

注解

WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构用作 WdfDeviceAssignSxWakeSettings 的输入。

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

驱动程序首次调用 WdfDeviceAssignSxWakeSettings 时，将执行以下操作：

框架存储所有 WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构成员的值。
如果 UserControlOfWakeSettings 成员设置为 WakeAllowUserControl ，并且 Enabled 成员设置为 WdfUseDefault，框架将读取注册表，以确定用户是否已启用唤醒系统。

在后续调用 WdfDeviceAssignSxWakeSettings 期间，框架不存储 UserControlOfWakeSettings 成员的值。换句话说，框架在驱动程序首次调用 WdfDeviceAssignSxWakeSettings 时执行以下步骤，但在后续调用期间则不执行：

存储 UserControlOfWakeSettings 成员的值。
如果 Enabled 成员的值为 WdfUseDefault，请在注册表中查找用户设置。

以下规则适用于为 DxState 成员指定的值：

该值不能为 PowerDeviceD0。
如果指定 PowerDeviceMaximum，框架将使用设备总线驱动程序在其WDF_DEVICE_POWER_CAPABILITIES结构的 DeviceWake 成员中提供的值。
不能在总线驱动程序WDF_DEVICE_POWER_CAPABILITIES结构的DeviceWake 成员中指定低于设备电源状态的设备电源状态。 (换句话说，如果总线驱动程序的 DeviceWake 值为 PowerDeviceD2，则函数驱动程序的 DxState 值不能为 PowerDeviceD3.)

有关控制设备唤醒功能的注册表项的信息，请参阅用户控制设备空闲和唤醒行为。

如果 WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构描述的设备是父设备，则父设备的驱动程序可以使用 ArmForWakeIfChildrenAreArmedForWake 和 IndicateChildWakeOnParentWake 成员，如下所示：

如果驱动程序将 ArmForWakeIfChildrenAreArmedForWake 成员设置为 TRUE，框架会在启用子设备的唤醒功能时调用驱动程序的 EvtDeviceArmWakeFromSx 或 EvtDeviceArmWakeFromSxWithReason 回调函数，即使父设备的唤醒功能未启用也是如此。
为了降低能耗，你可能不希望启用设备的唤醒功能，除非插入了也支持唤醒功能的子设备。如果驱动程序将 ArmForWakeIfChildrenAreArmedForWake 成员设置为 TRUE， 则 Enabled 成员的值具有以下含义：
- 如果 Enabled 为 WdfFalse，则框架仅在启用子设备的唤醒功能时启用驱动程序的唤醒功能。
- 如果 Enabled 为 WdfTrue，则无论设备是否具有启用唤醒的子设备，框架始终启用驱动程序的唤醒功能。
- 如果 Enabled 为 WdfUseDefault 且 UserControlOfWakeSettings 为 WakeAllowUserControl，则用户可以控制设备是否始终启用唤醒，或者仅当设备具有启用了唤醒的子设备时，才能控制设备是否始终已启用唤醒。
如果驱动程序将 IndicateChildWakeOnParentWake 成员设置为 TRUE，框架会在父设备的驱动程序和每个启用唤醒的子设备的驱动程序中调用 EvtDeviceWakeFromSxTriggered 回调函数。如果驱动程序将此成员设置为 FALSE，则框架仅在父设备的驱动程序中调用 EvtDeviceWakeFromSxTriggered 回调函数。如果设备子级的驱动程序必须检查硬件以确定系统唤醒的原因，则驱动程序应将 IndicateChildWakeOnParentWake 设置为 TRUE 。