WdfDeviceStopIdle 宏 (wdfdevice.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfDeviceStopIdle 方法通知框架，指定的设备必须置于其工作 (D0) 电源状态中。

语法

NTSTATUS WdfDeviceStopIdle(
   _In_ WDFDEVICE Device,
   _In_ BOOLEAN WaitForD0
);

参数

[in] Device

框架设备对象的句柄。

[in] WaitForD0

一个布尔值，指示 何时返回 WdfDeviceStopIdle 。 如果 为 TRUE，则仅在指定设备进入 D0 设备电源状态后返回。 如果 为 FALSE，该方法将立即返回。

返回值

无

备注

此宏可以返回以下值：

返回值 含义
STATUS_PENDING 设备正在异步启动。
STATUS_INVALID_DEVICE_STATE 驱动程序不是设备的电源策略所有者。
STATUS_POWER_STATE_INVALID 发生设备故障，设备无法进入其 D0 电源状态。

该方法可能会返回其他 NTSTATUS 值。

注意

对于在 WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE 枚举中指定 SystemManagedIdleTimeout 或 SystemManagedIdleTimeoutWithHint 的设备， 调用 WdfDeviceStopIdle 且 WaitForD0 设置为 FALSE 时，如果设备仍在 D0 中，并且空闲超时期限尚未过，则从 WDF 版本 1.33/2.33 开始，WdfDeviceStopIdle 在早期版本中返回STATUS_SUCCESS (，这会导致返回值STATUS_PENDING) 。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

如果设备在空闲时可以进入低功耗状态，驱动程序可能需要偶尔调用 WdfDeviceStopIdle ，使设备恢复工作 (D0) 状态或阻止其进入低功耗状态。

当系统更改为 Sx 睡眠状态时，WdfDeviceStopIdle 不会阻止框架将设备转换为睡眠状态。 它的唯一效果是在系统处于 S0 工作状态时防止转换为 Dx 睡眠状态。 同样，如果设备支持 定向电源管理， 则 WdfDeviceStopIdle 不会阻止设备进入定向断电。

警告

在关机期间，请勿直接或间接调用具有 WaitForD0 = TRUE 的 WdfDeviceStopIdle。 例如，如果 EvtDeviceArmWakeFromS0 回调在另一个调用 WdfDeviceStopIdle(TRUE)的线程上等待，则会阻止电源转换，并且系统崩溃。

当设备处于空闲状态并且框架将 I/O 请求置于设备的电源托管 I/O 队列中时，驱动程序 不必 调用 WdfDeviceStopIdle 。 此外，当设备处于空闲状态并且检测到唤醒信号时，驱动程序 不必 调用 WdfDeviceStopIdle 。 在这两种情况下，框架都请求总线驱动程序将设备的电源状态还原为 D0。

尽管驱动程序在处理从电源管理的 I/O 队列获取的 I/O 请求时通常不需要调用 WdfDeviceStopIdle ，但允许调用。 但是，驱动程序在处理来自电源管理的 I/O 队列的 I/O 请求时，不得将 WaitForD0 参数设置为 TRUE 。

如果 驱动程序必须 访问设备，则驱动程序必须调用 WdfDeviceStopIdle ，因为驱动程序已在电源管理的 I/O 队列之外收到请求。 例如，驱动程序可能支持驱动程序定义的接口或需要访问设备的 WMI 请求。 在这种情况下，必须确保设备在驱动程序访问设备之前处于其工作状态，并且设备在驱动程序完成访问设备之前保持其工作状态。

如果系统处于工作 (S0) 状态，则调用 WdfDeviceStopIdle 会强制设备进入其工作 (D0) 状态。 设备将保持工作状态，直到驱动程序调用 WdfDeviceResumeIdle，此时，如果设备保持空闲状态，框架可以将设备置于低功耗状态。

在框架首次调用驱动程序的 EvtDeviceD0Entry 回调函数之前，请勿调用 WdfDeviceStopIdle。

仅当系统处于工作 (S0) 状态时，对 WdfDeviceStopIdle 的调用才能将空闲设备还原到其工作状态。 如果系统正在转换为低功耗状态，或者设备已关闭电源以响应 Sx (其中 x > 0) 当驱动程序调用 WdfDeviceStopIdle 并将 WaitForD0 参数设置为 TRUE 时，函数不会返回，直到系统返回到其 S0 状态。

每次成功调用 WdfDeviceStopIdle 后，最终都必须调用 WdfDeviceResumeIdle，否则设备在再次变为空闲状态时永远不会返回到低功耗状态。 对 WdfDeviceStopIdle 的调用可以嵌套，因此对 WdfDeviceResumeIdle 的调用次数必须等于对 WdfDeviceStopIdle 的调用数。 如果对 WdfDeviceStopIdle 的调用失败，请不要调用 WdfDeviceResumeIdle 。

如果系统在 WdfDeviceStopIdle 返回后进入低功耗状态，则设备也会进入低功耗状态。 当系统返回到其工作 (S0) 状态时，设备也会返回到其工作 (D0) 状态。 调用 WdfDeviceStopIdle 的电源参考将保持活动状态，并阻止设备进入低功耗状态，直到对 WdfDeviceResumeIdle 进行匹配调用。

有关详细信息，请参阅 支持空闲关机。

如果 WaitForD0 为 TRUE，则必须在 IRQL = PASSIVE_LEVEL调用 WdfDeviceStopIdle 。 如果 WaitForD0 为 FALSE，则必须在 IRQL <= DISPATCH_LEVEL 调用此方法。

调用 WdfDeviceStopIdleWithTag 而不是 WdfDeviceStopIdle 可提供可在 Microsoft 调试器中查看 (标记值、行号和文件名) 的其他信息。

示例

在下面的代码示例中， WdfDeviceStopIdle 在指定设备进入 D0 设备电源状态后返回。

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfdevice.h (包括 Wdf.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL 请参见“备注”部分。
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅