SET_D3COLD_SUPPORT回调函数 (wdm.h)

  • 项目

SetD3ColdSupport 回调例程启用或禁用到 D3cold 设备电源状态的转换。

语法

SET_D3COLD_SUPPORT SetD3coldSupport;

void SetD3coldSupport(
  [in, optional] PVOID Context,
  [in]           BOOLEAN D3ColdSupport
)
{...}

参数

[in, optional] Context

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

[in] D3ColdSupport

是否允许从 D3hot 转换到 D3cold。 设置为 TRUE 以启用这些转换。 否则，设置为 FALSE。 有关详细信息，请参阅备注。

返回值

无

备注

作为设备的电源策略所有者 (PPO) 的驱动程序可以调用此例程来启用或禁用对 D3cold 子状态的转换，当计算机处于 S0 (工作) 系统电源状态且未准备退出 S0 时可能发生。

如果设备必须能够从它进入的任何低功耗 Dx 状态发出唤醒事件信号，则此设备的驱动程序不应启用到 D3cold 子状态的转换，除非设备可以从此子状态发出唤醒事件信号。 否则，在进入 D3cold 后，设备将不可用，直到计算机重新启动或从睡眠状态唤醒。

设备的驱动程序可以调用 GetIdleWakeInfo 例程，以确定设备是否可以发出来自 D3cold 的唤醒事件的信号。

如有必要，设备的驱动程序可以发出一系列 SetD3ColdSupport 调用，以交替启用和禁用 D3cold 转换以响应动态变化的条件。

例如，从 D3cold 转换到 D0 后，图形设备可能具有要还原的大型硬件上下文。 还原此上下文所需的时间可能是可以接受的，也可能是不能接受的，具体取决于用户当前正在执行的任务集。 此外，还原时间可能因此任务组合而异。 当任务组合发生变化时，驱动程序可能需要动态启用和禁用到 D3cold 的转换。

设备只能从 D3hot 子状态进入 D3cold 子状态。 如果驱动程序调用 SetD3ColdSupport 以启用从 D3hot 到 D3cold 的转换，则设备在进入 D3hot 后可能进入 D3cold，也可能不进入 D3cold。 为了响应唤醒事件，设备可能直接从 D3hot 进入 D0，而无需通过 D3cold。

当设备从 D3hot 移动到 D3cold 时，它可能会这样做，因为它与某些其他设备共享的电源已关闭。 在这些设备进入 D3cold 一段时间后，其中一个设备的驱动程序可能会请求转换到 D0。 为了响应此请求，父总线驱动程序或 ACPI 筛选器驱动程序将打开电源，共享电源的所有设备都进入其默认的开机状态。

唯一需要此电源状态更改的设备驱动程序是请求更改的驱动程序。 其他设备的驱动程序必须收到有关此更改的通知，以便它们能够正确初始化其设备以在 D0 中运行。 只有能够接收此通知的驱动程序才应允许其设备进入 D3cold。 否则，驱动程序将不知道设备何时进入 D0。

从Windows 8开始，WDM 驱动程序可以将设备注册到 Power Framework (PoFx) ，并在设备进入 D0 时收到 DevicePowerRequiredCallback 例程的通知。 同样，KMDF 驱动程序可以将设备注册到 PoFx，并通过 EvtDeviceD0Entry 事件回调通知。

如果设备已准备好唤醒，则未将其设备注册到 PoFx 的驱动程序仍会收到转换为 D0 的通知。 当总线驱动程序打开设备的电源时，它们将完成驱动程序的 IRP_MN_WAIT_WAKE 请求。 作为响应，驱动程序初始化其设备以在 D0 中运行。

在多个设备共享的电源打开后，驱动程序请求转换到 D0 的设备可能是这些设备中唯一有工作要做的设备。 其他设备可能处于空闲状态，在这种情况下，其驱动程序会在一段时间后将这些设备移动到 D3hot。

如果驱动程序调用 SetD3ColdSupport 来禁用到 D3cold 的转换，则 D0 是设备可以从 D3hot 进入的唯一设备电源状态。

如果驱动程序调用 SetD3ColdSupport 以启用到 D3cold 的转换，则这些转换可能出于其他原因而禁用。 驱动程序可以调用 GetD3ColdCapability 例程，以确定设备是否能够进入 D3cold 子状态。 但是，驱动程序可能不需要此信息。 如果设备无法进入 D3cold，则调用 SetD3ColdSupport 不起作用，但无害。

SetD3ColdSupport 例程仅影响当计算机处于 (且未准备退出 S0 状态) 时可能发生的 D3hot 到 D3cold 转换。 此例程对计算机准备退出 S0 并进入低功耗系统状态的情况没有影响。 在计算机进入系统低功耗状态之前，D3hot 子状态中的设备可能始终进入 D3cold 子状态。

默认情况下，在首次调用 SetD3ColdSupport 例程之前，将禁用 D3hot 到 D3cold 转换。 若要更改此默认值，以便在第一次 SetD3ColdSupport 调用之前启用 D3hot 到 D3cold 转换，设备的驱动程序包可以在安装驱动程序的 INF 文件的 DDInstall.HW 节中包含以下两行：

Include = machine.inf
Needs = PciD3ColdSupported

Windows 8是 Windows 的第一个版本，支持可在计算机保持 S0 状态时进入和退出 D3cold 子状态的设备。 有关详细信息，请参阅 设备 Low-Power 状态。

要求

要求 值
最低受支持的客户端 从Windows 8开始可用。
目标平台 桌面
标头 wdm.h (包括 Wdm.h)
IRQL PASSIVE_LEVEL

另请参阅

D3COLD_SUPPORT_INTERFACE

DevicePowerRequiredCallback

EvtDeviceD0Entry

GetD3ColdCapability

IRP_MN_WAIT_WAKE