WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 结构 (wdfdevice.h)

  • 项目

[适用于 KMDF 和 UMDF]

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 结构包含驱动程序提供的信息，当设备空闲且系统处于系统工作状态时，框架将使用这些信息， (S0) 。

语法

typedef struct _WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS {
  ULONG                                 Size;
  WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps;
  DEVICE_POWER_STATE                    DxState;
  ULONG                                 IdleTimeout;
  WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings;
  WDF_TRI_STATE                         Enabled;
  WDF_TRI_STATE                         PowerUpIdleDeviceOnSystemWake;
  WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE    IdleTimeoutType;
  WDF_TRI_STATE                         ExcludeD3Cold;
} WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS;

成员

Size

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

IdleCaps

一个WDF_POWER_POLICY_S0_IDLE_CAPABILITIES类型的枚举器，用于标识设备在设置为低功耗状态后自行唤醒的能力，同时系统保持其工作 (S0) 状态。

DxState

一个DEVICE_POWER_STATE类型的枚举器，用于标识设备在空闲超时期限结束后将进入的低设备电源状态。 DEVICE_POWER_STATE 值在 wdm.h 中定义。

IdleTimeout

在框架将设备置于 DxState 提供的低功耗状态之前，设备将保持空闲状态的时间（以毫秒为单位）。 若要使用框架的默认空闲超时值，请指定 IdleTimeoutDefaultValue。 有关框架何时认为设备处于空闲状态的详细信息，请参阅 支持空闲关机。

UserControlOfIdleSettings

一个WDF_POWER_POLICY_S0_IDLE_USER_CONTROL类型的枚举器，指示用户是否能够修改设备的空闲设置。

Enabled

一个WDF_TRI_STATE类型的枚举器，指示设备在处于空闲状态且系统电源处于 S0 时是否关闭。 此成员可以具有以下值之一：

WdfTrue - 已启用关机。

WdfFalse - 已禁用关机。

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

如果启用关机，设备具有唤醒功能，并且空闲超时值过期，框架将在设备进入低功耗状态之前调用驱动程序的 EvtDeviceArmWakeFromS0 回调函数。

PowerUpIdleDeviceOnSystemWake

一个 WDF_TRI_STATE类型的枚举器，指示当系统返回到其工作 (S0) 状态时，设备是否将返回到其工作 (D0) 状态。 仅当驱动程序将 IdleCaps 成员设置为 IdleCannotWakeFromS0 时，此成员才有效。 PowerUpIdleDeviceOnSystemWake 成员可以具有以下值之一：

WdfTrue - 如果设备和系统都处于低功耗状态，则当系统返回到其工作状态时，设备将返回到其工作状态。

WdfFalse - 如果设备和系统都处于低功耗状态，则当系统返回到其工作状态时，设备将保持低功耗状态。

WdfUseDefault - 驱动程序未设置其他值时框架使用的默认值。 此值与 WdfFalse 具有相同的含义。

如果 PowerUpIdleDeviceOnSystemWake 成员设置为 WdfFalse 或 WdfUseDefault，则仅当软件访问设备时（例如应用程序向设备发送 I/O 请求时），设备才会返回到其工作状态。 有关详细信息，请参阅 设备返回到其工作状态。

PowerUpIdleDeviceOnSystemWake 成员在 KMDF 版本 1.9 及更高版本中可用，以及从 UMDF 版本 2.0 开始。

IdleTimeoutType

一个WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE类型的枚举器，指示如何使用 IdleTimeout 成员。

IdleTimeoutType 成员在 KMDF 版本 1.11 及更高版本中可用，以及从 UMDF 2.0 版开始提供。 请参阅备注中的其他信息。

ExcludeD3Cold

一个WDF_TRI_STATE类型的枚举器，指示 D3cold 电源状态是否应是设备在空闲超时期限到期时将进入的低功耗状态的允许选择。 ExcludeD3Cold 成员可以具有以下值之一：

WdfTrue - 当空闲超时期限到期时，框架会将设备移动到低功率 D 状态。 如果该 D 状态为 D3，则设备将移动到 D3hot。 如果 ExcludeD3Cold 设置为 WdfTrue，则不允许进一步从 D3hot 转换为 D3cold。

WdfFalse - 如果满足以下所有条件，设备可能会在空闲超时期限到期时进入 D3cold 电源状态：

  • 此结构的 DxState 成员指定 PowerDeviceD3 或 PowerDeviceMaximum。
  • ACPI 固件指示设备支持 D3cold 电源状态。
  • 如果驱动程序在此结构的 IdleCaps 成员中指定了 IdleCanWakeFromS0 或 IdleUsbSelectiveSuspend，则设备可以在处于 D3cold 电源状态时响应外部唤醒事件。 否则，此要求不适用。
WdfUseDefault - 框架检查 DDInstall。 驱动程序 INF 文件的 HW 部分。 如果存在以下行，则此值与 WdfFalse 具有相同的含义：
Include = machine.inf
Needs = PciD3ColdSupported
否则，此值与 WdfTrue 具有相同的含义。

ExcludeD3Cold 成员从 KMDF 版本 1.11 开始可用，从 UMDF 版本 2.0 开始可用，在早于 Windows 8 的操作系统中将被忽略。 请参阅备注中的其他信息。

注解

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 结构用作 WdfDeviceAssignS0IdleSettings 的输入。

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

  • 框架存储所有 WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 结构成员的值。
  • 如果 UserControlOfIdleSettings 成员设置为 IdleAllowUserControl ，并且 Enabled 成员设置为 WdfUseDefault，框架将读取注册表，以确定用户是否已启用在空闲时关闭设备。
在后续调用 WdfDeviceAssignS0IdleSettings 期间，框架仅存储 DxState、 IdleTimeout 和 Enabled 成员的值。 此外，在 KMDF 1.9 及更早版本中，框架存储 IdleCaps 成员的值， 除非 值为 IdleUsbSelectiveSuspend。 因此，驱动程序必须使用以下规则：
  • 如果驱动程序为 IdleCaps 成员的值指定 IdleUsbSelectiveSuspend，则它必须在首次调用 WdfDeviceAssignS0IdleSettings 时执行此操作，并且随后无法更改该值。
  • 如果驱动程序在首次调用 WdfDeviceAssignS0IdleSettings 时指定 IdleCanWakeFromS0 或 IdleCannotWakeFromS0，则可以随后再次调用 WdfDeviceAssignS0IdleSettings 以将该值更改为 (但无法将该值更改为 IdleUsbSelectiveSuspend) 。

从 KMDF 1.11 和 UMDF 2.0 开始，KMDF 驱动程序可以随时在 IdleUsbSelectiveSuspend 和 IdleCannotWakeFromS0 之间切换。

从 Windows 8 开始，将 IdleTimeoutType 成员设置为 SystemManagedIdleTimeout 或 SystemManagedIdleTimeoutWithHint 会导致框架注册到电源管理框架 (PoFx) 。

如果驱动程序为多组件设备实现功能电源状态支持，则驱动程序必须将 IdleTimeoutType 设置为 DriverManagedIdleTimeout ，或者根本不调用 WdfDeviceAssignS0IdleSettings 。

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

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

  • 该值不能为 PowerDeviceD0。
  • 对于 USB 设备，该值不能为 PowerDeviceD0 或 PowerDeviceD3。
  • 如果指定 PowerDeviceMaximum，框架将使用设备总线驱动程序在其WDF_DEVICE_POWER_CAPABILITIES结构的 DeviceWake 成员中提供的值。
  • 如果 IdleCaps 成员的值为 IdleCanWakeFromS0，则无法在总线驱动程序WDF_DEVICE_POWER_CAPABILITIES结构的 DeviceWake 成员中指定低于设备电源状态的设备电源状态。 (换言之，如果总线驱动程序的 DeviceWake 值为 PowerDeviceD2，则函数驱动程序的 DxState 值不能为 PowerDeviceD3.)
在早于 Windows 8 的操作系统中，D3 电源状态表示设备处于低功耗状态，但仍会保持总线的一些电源。 从 Windows 8 开始，以前的 D3 电源状态称为 D3hot，并且可以使用新的电源状态 (D3cold) 。 当系统处于工作 (S0) 状态或处于低功耗状态时，设备可以进入 D3cold 状态。 当设备处于 D3cold 电源状态时，总线处于非活动状态，当外部操作 (例如插入网线) 导致硬件事件时，设备必须触发自己的唤醒信号。

从 KMDF 1.11 和 UMDF 2.0 开始， 支持空闲断电 的设备可以使用此结构的 ExcludeD3Cold 成员来指定 D3cold 电源状态是否应是设备在空闲超时期限结束后将进入的低 设备电源状态 的允许选择。

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

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

要求

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