通过

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）状态，或阻止设备进入低功率状态。

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

警告

在关闭电源期间，请勿使用 WaitForD0 = TRUE（直接或间接）调用 WdfDeviceStopIdle。 例如，如果 EvtDeviceArmWakeFromS0 回调等待另一个调用 WdfDeviceStopIdle(TRUE)线程，则会阻止电源转换，系统崩溃。

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

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

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

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

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

调用 WdfDeviceStopIdle 仅当系统处于工作状态（S0）状态时，才能将空闲设备还原到其工作状态。 如果系统正在转换为低功率状态或设备已关闭，以响应 Sx（其中 x > 0），当驱动程序调用 WdfDeviceStopIdle 时，WaitForD0 参数设置为 TRUE，函数不会返回，直到系统返回到其 S0 状态。 同样，如果设备支持 定向电源管理，并且电源子系统已启动定向停电，则调用 WdfDeviceStopIdle，WaitForD0 参数设置为 TRUE，直到电源子系统指示设备电源备份后才会返回。

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

如果系统在 WdfDeviceStopIdle 返回后进入低功率状态，设备也会进入低功率状态。 当系统返回到其工作状态（S0）时，设备也会返回到其工作状态（D0）。 从调用 WdfDeviceStopIdle 的电源引用保持活动状态，并阻止设备进入低功率状态，直到有匹配调用 WdfDeviceResumeIdle。

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

如果 WaitForD0TRUE，则必须在 IRQL = PASSIVE_LEVEL 调用 WdfDeviceStopIdle。 如果 WaitForD0FALSE，则必须在 IRQL <= DISPATCH_LEVEL调用此方法。

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

例子

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

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

要求

要求 价值
目标平台 普遍
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfdevice.h （包括 Wdf.h）
图书馆 Wdf01000.sys（KMDF）：WUDFx02000.dll （UMDF）
IRQL 请参阅“备注”部分。
DDI 符合性规则 DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）

另请参阅