GET_IDLE_WAKE_INFO回调函数 (wdm.h)

项目
04/23/2024

GetIdleWakeInfo 例程使设备的驱动程序能够发现设备可从中发出唤醒事件信号的设备电源状态。

语法

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

参数

[in, optional] Context

指向特定于接口的上下文信息的指针。调用方将此参数设置为接口的 D3COLD_SUPPORT_INTERFACE 结构的 Context 成员的值。

[in] SystemPowerState

系统电源状态。将此参数设置为以下 SYSTEM_POWER_STATE 枚举值之一：

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

这些值表示系统电源状态 S0 (系统工作状态，) 到 S4。对于调用方提供的 SystemPowerState 值，例程确定设备可从中发出唤醒信号的最深设备电源状态。

[out] DeepestWakeableDstate

最深的可唤醒 Dx 状态。此参数是指向 DEVICE_WAKE_DEPTH变量的指针。如果调用成功，则例程会将以下枚举值之一写入此变量：

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

DeviceWakeDepthD0 到 DeviceWakeDepthD3cold 范围内的值指示当计算机处于 SystemPowerState 参数指定的系统电源状态时，设备可以从中发送唤醒信号的最低功率 Dx 状态。 DeviceWakeDepthNotWakeable 指示当计算机处于 SystemPowerState 指定的系统电源状态时，设备无法从中发送唤醒信号的设备电源状态。

如果例程无法确定最深的可唤醒设备状态 (可能是因为平台固件不包含此信息) ，则调用将失败，并且例程将返回错误状态代码。如果 PowerSystemWorking 到PowerSystemHibernate 范围内任何 SystemPowerState 参数值的 GetIdleWakeInfo 调用失败，则所有此类值都将失败。

返回值

如果 GetIdleWakeInfo 例程成功检索到最深的可唤醒设备状态，则返回STATUS_SUCCESS。否则，它将返回相应的错误状态代码。

注解

对于调用方指定的系统电源状态，此例程尝试确定设备可从中向处理器发出唤醒事件信号的最低功率设备电源状态。如果成功，例程会将设备电源状态写入 DeepestWakeableDstate 参数指向的位置，并返回STATUS_SUCCESS。或者，如果例程确定设备无法从任何设备电源状态发出唤醒事件信号，则例程会将值 DeviceWakeDepthNotWakeable 写入此位置，并返回STATUS_SUCCESS。

设备的驱动程序使用 GetIdleWakeInfo 例程提供的信息来确定设备可以发出唤醒事件信号的条件。需要能够发出某些唤醒事件信号的设备不应进入设备电源状态，无法从中发出这些事件信号。对于某些类型的设备，当计算机处于 S0 (工作) 系统电源状态时，设备应发送的唤醒信号不同于计算机显示为关闭时设备应发送的唤醒信号。

例如，当卡插入 PCI Express 卡插槽，并且该插槽的 PCI Express 热插拔控制器设备处于 D0 设备电源状态时，此设备会向处理器发出中断信号。但是，如果在插入卡时控制器设备处于低功率 Dx 状态，则计算机的系统电源状态可能会确定此设备是否应向处理器发出唤醒事件信号。理想情况下，控制器设备的行为应如下所示：

如果计算机处于 S0 (工作) 系统电源状态，则设备应向处理器发出唤醒事件信号。
如果计算机在) 处于低功耗 Sx 状态 (睡眠，则设备不应发出唤醒事件信号。

某些较旧的设备可能不支持这种理想行为。如果本示例中的 PCI Express 热插拔控制器设备只能在计算机处于 S3 状态时发出唤醒事件信号，则驱动程序 (在这种情况下，控制器的收件箱 Pci.sys 驱动程序) 应在计算机处于 S0 (且未准备进入睡眠状态) 时将控制器保持在 D0 中。

此示例中的驱动程序可以调用 GetIdleWakeInfo 例程，以确定热插拔控制器设备在计算机处于 S0 时是否应保留 D0 状态。对于此调用，驱动程序设置 SystemPowerState = PowerSystemWorking。在以下任一情况下，当计算机处于 S0) 时，此设备不应将 D0 状态保留 (：

GetIdleWakeInfo 调用将输出参数设置为 DeviceWakeDepthNotWakeable 或 DeviceWakeDepthD0 并返回STATUS_SUCCESS。
GetIdleWakeInfo 调用失败，并返回错误状态代码。

驱动程序应将上述任一结果解释为，表示当计算机处于 S0 中时，设备无法发出唤醒事件信号。根据此信息，驱动程序应将设备保持在 D0 中，直到计算机准备退出 S0。

大多数设备的驱动程序可以将 DeviceWakeDepthD0 的输出值视为 与 DeviceWakeDepthNotWakeable 相同。当设备处于 D0 中时，只有少数驱动程序可能有理由武装唤醒信号。这些驱动程序适用于监视触发唤醒信号的外部事件的简单设备，无论设备处于 D0 还是低功率 Dx 状态。此类设备的示例包括计算机上的电源按钮或睡眠按钮。

GetIdleWakeInfo 例程查询基础总线驱动程序和 ACPI 系统固件，以确定设备可从中发出唤醒事件信号的最低设备电源状态。如果总线驱动程序和固件无法提供此信息，则例程将失败并返回错误状态代码。

DEVICE_CAPABILITIES 结构包括一个 DeviceWake 成员，该成员提供的信息类似于 GetIdleWakeInfo 例程中提供的信息。但是， DeviceWake 成员中的信息仅适用于系统低功耗状态 S1 到 S4。对于某些设备， DeviceWake 成员中的信息可能也适用于 S0 系统电源状态，但驱动程序不应依赖于此类行为。如果计算机处于 S0 中，只有 GetIdleWakeInfo 例程才能可靠地报告设备发出唤醒事件信号的能力。

提供了一个内联帮助程序函数 MapWakeDepthToDstate，用于将 getIdleWakeInfo 例程中的DEVICE_WAKE_DEPTH输出值转换为可由 PoRequestPowerIrp 例程用作输入参数的DEVICE_POWER_STATE值。