windows USB 设备驱动开发-USB电源管理(一)

符合通用串行总线 (USB) 规范的 USB 设备的电源管理功能具有一组丰富而复杂的电源管理功能。 请务必了解这些功能如何与 Windows 驱动程序模型 (WDM) 交互，特别是 Microsoft Windows 如何调整标准 USB 功能以支持系统唤醒体系结构。

基于内核模式驱动程序框架的 USB 客户端驱动程序 (KMDF) 和用户模式驱动程序框架 (UMDF) 应使用基本技术和相应框架支持的机制来管理 USB 设备的电源。 

USB 设备电源状态

下面介绍用于通用串行总线 2.0 规范第 9.1 节规定的 USB 设备电源状态的 WDM 设备状态。

USB 设备电源状态（如通用串行总线 2.0 规范第 9.1 节所述）可分为三大类：

• 初始：设备已连接，但未完全通电；
• 通电：设备处于其中一种完全通电状态：默认、地址或配置；
• 暂停：设备处于闲置状态，以低功耗运行；

WDM 功率模型中定义的设备功率状态与 USB 标准中定义的设备功率状态之间没有直接关联。 例如，在 USB 规范中，术语 suspended 和 idle 具有非常明确的含义；但在 WDM 功率模型中，这些术语的用法往往不同。 Windows 客户端驱动程序可以将 USB 设备置于挂起状态。 客户机驱动程序准备挂起设备时，会指示总线驱动程序将其空闲。

WDM 模型中的设备功率状态可概括如下：

• D0 - 工作状态。 设备已完全通电；
• D1/D2 - 中间睡眠状态。 这些状态允许设备布防以进行远程唤醒；
• D3 - 最深的睡眠状态。 处于 D3 状态的设备无法为远程唤醒布防；

WDM 功率模型使用设备防护一词来实现远程唤醒。 防护是一项软件操作，通常（但不总是）会导致启用 USB 设备远程唤醒功能的硬件操作。 等待唤醒 IRP (IRP_MN_WAIT_WAKE) 是 WDM 软件对设备进行的远程唤醒操作。

更改非复合设备的电源状态

USB 设备的电源策略管理器负责设置设备的电源状态。 电源策略管理器通过发出 WDM 电源 (IRP_MN_SET_POWER) IRP 来设置电源状态。总线驱动程序采取的行动取决于电源策略管理器要求的设备功率级别。 下面列出了总线驱动程序针对各级设置功率请求所采取的操作：

• D0

总线驱动程序执行以下任务

确保所有上游 USB 集线器都已通电并准备好接收请求。
如果设备的 USB 端口处于暂停状态，则通过清除 PORT_SUSPEND 功能恢复端口。
以 STATUS_SUCCESS 完成设备的空闲 IRP（如果有的话）。
如果设备已布防，则解除布防以便远程唤醒。

• D1/D2

总线驱动程序执行以下任务

如果等待唤醒 IRP (IRP_MN_WAIT_WAKE) 待定，则启动设备进行远程唤醒。
通过设置 PORT_SUSPEND 功能暂停设备的 USB 端口。

• D3

总线驱动程序执行以下任务

1. 通过设置 PORT_SUSPEND 功能暂停设备的 USB 端口。
2. 完成设备的等待唤醒 IRP，如果有 STATUS_POWER_STATE_INVALID（等待唤醒）的话。
3. 完成设备的空闲 IRP (IOCTL_INTERNAL_USB_SUBMIT_IDLE_NOTIFICATION)，如果正在等待 STATUS_POWER_STATE_INVALID。

更改复合设备的电源状态

复合设备上接口的客户端驱动程序必须与设备上其他接口的客户端驱动程序共享复合设备的电源状态。 因此，接口的客户端驱动程序无法在不影响设备上其他接口的情况下，将复合设备置于低功耗状态。 当接口的客户端驱动程序发送 IRP_MN_SET_POWER 请求时，USB 通用父驱动程序 (Usbccgp.sys) 会采取以下操作。

• D0

总线驱动程序执行以下任务

确保所有上游 USB 集线器都已通电并准备好接收请求。
如果设备的 USB 端口处于暂停状态，则通过清除 PORT_SUSPEND 功能恢复端口。
完成客户端驱动程序的空闲 IRP（如果有），并显示 STATUS_SUCCESS。

• D1/D2

总线驱动程序没有采取任何行动。

• D3

总线驱动程序执行以下任务

1. 完成客户端驱动程序的等待唤醒 IRP (IRP_MN_WAIT_WAKE)，如果有 STATUS_POWER_STATE_INVALID 待执行。
2. 完成客户端驱动程序的空闲 IRP（IOCTL_INTERNAL_USB_SUBMIT_IDLE_NOTIFICATION），如果正在等待 STATUS_POWER_STATE_INVALID。

当以下条件之一为真时，通用父驱动程序会暂停设备的 USB 端口：

• 系统正在向低功耗状态过渡。
• 复合设备上所有功能的客户端驱动程序已启动选择性挂起。

USB 驱动程序 (WDF) 中的选择性挂起

USB 函数驱动程序通过实现 USB 选择性挂起支持运行时空闲检测。 下面是面向驱动程序开发人员的内容，介绍如何在基于 Windows® Driver Foundation (WDF) 的 USB 驱动程序中实现选择性挂起。

关于选择性挂起

选择性挂起是能够关闭并稍后恢复空闲 USB 设备，而连接到该设备的计算机保持工作状态 (S0) 。 对于节能操作（尤其是在移动电脑上），所有 USB 设备和驱动程序都应支持选择性挂起。 在设备处于空闲状态时关闭设备，但当系统保持 S0 状态时，具有以下显著优势：

• 选择性挂起可节省电量。
• 选择性暂停有助于减少环境因素，如热负载和噪音。
• 如果设备硬件在空闲时可以关机，驱动程序应支持此功能。 基于 Windows® Driver Foundation (WDF) 的 USB 驱动程序中的选择性挂起支持最多需要一些额外的回调，而不需要基本即插即用支持所需的回调。

USB 设备的每个功能驱动程序都应实现积极的电源管理，以便在系统运行时挂起空闲设备。

USB 设备支持通过 USB 选择性挂起进行运行时空闲检测。 选择性挂起允许将空闲设备置于挂起状态，而不会影响连接到同一集线器的其他设备（如果是多功能设备），而不会影响设备中的其他功能。 当所有设备或功能都已挂起时，整个集线器或多功能设备可以关闭电源。

从硬件的角度来看，选择性挂起是 USB 端口上的一种物理状态。 当附加到端口的所有函数都空闲时，该端口可以进入选择性挂起。

为了符合 USB 规范，所有 USB 设备都必须支持选择性挂起。 当 USB 总线空闲时，设备必须能够关闭电源。 Microsoft 提供的 USB 集线器驱动程序在硬件级别实现选择性挂起。

USB 功能驱动程序应通过 WDF 为其各个设备功能实现选择性挂起，WDF 与总线驱动程序通信，并管理暂停和恢复设备功能的设备 I/O 控制请求。 WDF 使内核模式和用户模式驱动程序都支持选择性挂起。

函数驱动程序的 USB 选择性挂起代码的详细信息取决于驱动程序是在用户模式还是内核模式下运行。 请考虑以下准则：

• 尽可能使用用户模式驱动程序框架 (UMDF) 来实现 USB 驱动程序。 用户模式驱动程序损坏系统数据的可能性较小，并且比内核模式驱动程序更易于调试；
• 仅当驱动程序通过常时等量端点流式传输数据或需要仅在内核模式下可用的其他功能或资源时，才使用内核模式驱动程序框架 (KMDF) ；

电源策略所有权、I/O 队列和选择性挂起

设备堆栈的电源策略所有者 (PPO) 是确定设备在任何给定时间应处于哪个电源状态的驱动程序。 每个设备堆栈中只有一个驱动程序可以是 PPO。 函数驱动程序通常是其设备的 PPO。

如果 USB 驱动程序支持选择性挂起，并且其设备堆栈中的 PPO 之上分层，则驱动程序不得使用电源管理的队列。 这适用于 UMDF 和 KMDF 驱动程序。 如果在设备挂起时收到电源管理队列的请求，整个设备堆栈可能会停止。

图 1 显示了通过 USB 驱动程序的 I/O 队列向 USB 驱动程序发出的 I/O 请求流。

在图中，针对 USB 驱动程序的请求到达。 框架将请求添加到相应的队列。

如果队列不受电源管理，框架将根据驱动程序为队列配置的调度类型向驱动程序提供请求，该调度类型 (顺序、并行或手动) 。 然后，驱动程序处理请求。

如果队列受电源管理且设备未挂起，则框架会根据配置的调度类型向驱动程序提供请求。

但是，如果设备挂起，框架的操作取决于驱动程序是否是设备堆栈的 PPO。 如果驱动程序是 PPO，则框架将与 USB 父驱动程序通信以启动设备。 设备恢复后，框架向驱动程序提供请求。

如果驱动程序不是 PPO，则框架不会执行进一步的操作，因为只有 PPO 可以恢复设备。 请求保留在队列中。 如果 PPO 未收到导致它恢复设备的任何请求，则设备堆栈将停止。

USB UMDF 驱动程序中的选择性挂起

重要的 API

• IWDFUsbTargetDevice：：SetPowerPolicy
• IWDFDevice2：：AssignSxWakeSettings
• IWDFDevice2：：AssignS0IdleSettings

UMDF 函数驱动程序可以通过以下两种方式之一支持 USB 选择性挂起：

• 通过声明电源策略所有权并处理设备空闲关闭和恢复；
• 依靠 Microsoft 提供的 WinUSB.sys 驱动程序来处理选择性挂起。 安装 UMDF USB 驱动程序期间，WinUSB.sys 作为内核模式设备堆栈的一部分进行安装。 WinUSB.sys 实现用于暂停和恢复 USB 设备操作的基础机制；

这两种方法只需要少量代码。 WDK 中提供的 IdleWake 示例演示如何在 UMDF USB 驱动程序中支持选择性挂起。 可以在 %WinDDK%\BuildNumber\Src\Usb\OsrUsbFx2\ UMDF\Fx2_Driver\IdleWake 中找到此示例，文件夹包含示例的 PPO 和非 PPO 版本。

支持选择性挂起的 UMDF 驱动程序必须遵循以下准则：

• UMDF 驱动程序可以声明其设备堆栈的电源策略所有权，但不需要这样做。 默认情况下，基础 WinUSB.sys 驱动程序拥有电源策略。
• 支持选择性挂起且是 PPO 的 UMDF 驱动程序可以使用电源管理的队列或非电源管理的队列。 支持选择性挂起但不是 PPO 的 UMDF 驱动程序不得使用电源管理的队列。

UMDF USB 驱动程序中的电源策略所有权

默认情况下，WinUSB.sys 是包含 UMDF USB 驱动程序的设备堆栈的 PPO。 从 WDF 1.9 开始，基于 UMDF 的 USB 驱动程序可以声明电源策略所有权。 由于每个设备堆栈中只有一个驱动程序可以是 PPO，因此作为 PPO 的 UMDF USB 驱动程序必须在 WinUSB.sys 中显式禁用电源策略所有权。

在 UMDF USB 驱动程序中声明电源策略所有权

1.调用 IWDFDeviceInitialize：：SetPowerPolicyOwnership 并传递 TRUE，通常是从驱动程序回调对象上的 IDriverEntry：：OnDeviceAdd 方法传递。 例如：

FxDeviceInit->SetPowerPolicyOwnership(TRUE);

2.在 WinUSB 中禁用电源策略所有权。 在驱动程序的 INF 文件中，包含 AddReg 指令，该指令将注册表中的 WinUsbPowerPolicyOwnershipDisabled 值设置为非零值。 AddReg 指令必须出现在 DDInstall.HW 节中。 例如：

[MyDriver_Install.NT.hw]
AddReg=MyDriver_AddReg
 
[MyDriver_AddReg]
HKR,,"WinUsbPowerPolicyOwnershipDisabled",0x00010001,1

UMDF USB 驱动程序中的 I/O 队列

对于支持选择性挂起的 UMDF 驱动程序，UMDF 驱动程序是否为其设备拥有电源策略决定了它可以使用的 I/O 队列的类型。 支持选择性挂起和 PDO 的 UMDF 驱动程序可以使用电源托管或非电源管理的队列。 支持选择性挂起但不是 PPO 的 UMDF USB 驱动程序不应使用任何电源管理的 I/O 队列。

如果在设备挂起时，电源管理队列的 I/O 请求到达，则框架不会显示该请求，除非驱动程序为 PPO，如 USB 驱动程序中的选择性挂起图像中所示。 如果 UMDF 驱动程序不是设备的 PPO，则框架无法代表设备启动。 因此，请求仍停滞在电源管理的队列中。 请求永远不会到达 WinUSB，因此 WinUSB 无法启动设备。 因此，设备堆栈可能会停止。

如果队列不受电源管理，则框架会向 UMDF 驱动程序提供 I/O 请求，即使设备关闭也是如此。 UMDF 驱动程序格式化请求，并按照通常的方式将请求在设备堆栈中向下转发到默认 I/O 目标。 不需要特殊代码。 当请求到达 PPO (WinUSB.sys) 时，WinUSB.sys 启动设备并执行所需的 I/O 操作。

%WinDDK%\BuildNumber\Src\Usb\OsrUsbFx2\umdf\Fx2_Driver\IdleWake 中的示例驱动程序定义在生成非 PPO 版本的驱动程序时_NOT_POWER_POLICY_OWNER_常量。 当驱动程序为读取和写入请求创建队列时，它会确定是否通过检查常量来创建电源管理的队列。

为了创建队列，驱动程序调用驱动程序定义的 CMyQueue：：Initialize 方法，该方法采用以下三个参数：

• DispatchType，一个WDF_IO_QUEUE_DISPATCH_TYPE枚举值，指示队列如何调度请求。
• 默认值，指示队列是否为默认队列的布尔值。
• PowerManaged，一个布尔值，指示队列是否受电源管理。

以下代码片段演示驱动程序在创建读写队列过程中对 CMyQueue：：Initialize 方法的调用：

#if defined(_NOT_POWER_POLICY_OWNER_)
    powerManaged = false;
#else
    powerManaged = true;
#endif  
hr = __super::Initialize(WdfIoQueueDispatchParallel,
                         true,
                         powerManaged,
                         );

CMyQueue：：Initialize 然后调用 IWDFDevice：：CreateIoQueue 来创建队列，如下所示：

hr = m_FxDevice->CreateIoQueue(
                               callback,
                               Default,
                               DispatchType,
                               PowerManaged,
                               FALSE,
                               &fxQueue
                               );

此代码序列生成一个并行调度请求的默认队列。 如果驱动程序是 PPO，则队列受电源管理，如果驱动程序不是 PPO，则队列不受电源管理。

支持 UMDF PPO 中的 USB 选择性挂起

若要支持选择性挂起，作为其设备堆栈的 PPO 的 UMDF USB 驱动程序必须执行以下操作：

声明设备堆栈的电源策略所有权，通常在其驱动程序回调对象上的 IDriverEntry：：OnDeviceAdd 方法中，如前所述。通过在框架设备对象上调用 IWDFDevice2：：AssignS0IdleSettings 方法来启用选择性挂起。

从 PPO 启用 USB 选择性挂起

通常从设备回调对象的 OnPrepareHardware 方法调用 IWDFDevice2：：AssignS0IdleSettings。 将参数设置为 AssignS0IdleSettings，如下所示：

IdleCaps 到 IdleUsbSelectiveSuspend。

DxState 到框架将空闲设备转换到的设备睡眠状态。 对于 USB 选择性挂起，请指定 PowerDeviceMaximum，指示框架应使用总线驱动程序指定的值。

IdleTimeout 为在框架将其转换为 DxState 之前设备必须处于空闲状态的毫秒数。

UserControlOfIdleSettings 为 IdleAllowUserControl （如果驱动程序允许用户管理空闲设置），否则为 IdleDoNotAllowUserControl。

已启用WdfUseDefault 以默认启用选择性挂起，但允许用户设置替代默认值。

以下示例演示IdleWake_PPO驱动程序如何在其内部 CMyDevice：：SetPowerManagement 方法中调用此方法：

hr = m_FxDevice->CreateIoQueue(
                               callback,
                               Default,
                               DispatchType,
                               PowerManaged,
                               FALSE,
                               &fxQueue
                               );

如果设备硬件可以生成唤醒信号，则 UMDF 驱动程序还可以支持来自 S1、S2 或 S3 的系统唤醒。 

支持非 PPO UMDF 驱动程序中的 USB 选择性挂起

非 PPO 的 UMDF 函数驱动程序可以使用基础 WinUSB.sys 驱动程序的功能支持选择性挂起。 UMDF 驱动程序必须通知 WinUSB 设备和驱动程序支持选择性挂起，并且必须在 INF 文件中或通过在 USB 目标设备对象上设置电源策略来启用选择性挂起。

如果 UMDF 函数驱动程序启用选择性挂起，则基础 WinUSB.sys 驱动程序将确定设备何时处于空闲状态。 WinUSB 在没有挂起的传输或中断或批量端点上唯一挂起的传输为 IN 传输时，WinUSB 会启动空闲超时计数器。 默认情况下，空闲超时为 5 秒，但 UMDF 驱动程序可以更改此默认值。

当 WinUSB.sys 确定设备处于空闲状态时，它会发送请求，将设备挂起内核模式设备堆栈。 总线驱动程序会根据需要更改硬件的状态。 如果端口上的所有设备功能都已挂起，该端口将进入 USB 选择性挂起状态。

如果 I/O 请求在设备挂起时到达 WinUSB.sys，WinUSB.sys 恢复设备操作（如果设备必须通电才能为请求提供服务）。 当系统保留在 S0 中时，UMDF 驱动程序不需要任何代码即可恢复设备。 如果设备硬件可以生成唤醒信号，则 UMDF 驱动程序还可以支持来自 S1、S2 或 S3 的系统唤醒。 

非 PPO 的 UMDF 驱动程序可以通过执行以下两个步骤来支持选择性挂起：

• 通知 WinUSB.sys 设备和驱动程序支持选择性挂起；
• 启用 USB 选择性挂起；

此外，驱动程序还可以选择：

• 设置设备的超时值；
• 允许用户启用或禁用选择性挂起；

有关如何在非 PPO 的 UMDF USB 函数驱动程序中实现 USB 选择性挂起的示例，请参阅 WDK 中的 Fx2_Driver 示例。 此示例位于 %WinDDK%\BuildNumber\Src\Usb\OsrUsbFx2\Umdf\Fx2_Driver\ IdleWake_Non-PPO。

通知 WinUSB 选择性挂起支持

若要通知 WinUSB.sys 设备可以支持 USB 选择性挂起，设备 INF 必须将 DeviceIdleEnabled 值添加到设备的硬件密钥，并将该值设置为 1。 以下示例演示Fx2_Driver示例如何在 WUDFOsrUsbFx2_IdleWakeNon-PPO.Inx 文件中添加和设置此值：

[OsrUsb_Device_AddReg]
...
HKR,,"DeviceIdleEnabled",0x00010001,1

启用 USB 选择性挂起

UMDF USB 驱动程序可以在运行时或在 INF 中安装期间启用 USB 选择性挂起。

• 为了在运行时启用支持，函数驱动程序调用 IWDFUsbTargetDevice：：SetPowerPolicy 并将 PolicyType 参数设置为 AUTO_SUSPEND，Value 参数设置为 TRUE 或 1。 以下示例演示 Fx2_Driver 示例如何在 DeviceNonPpo.cpp 文件中启用选择性挂起：

  BOOL AutoSuspend = TRUE;
  hr = m_pIUsbTargetDevice->SetPowerPolicy( AUTO_SUSPEND,
                                            sizeof(BOOL),
                                           (PVOID) &AutoSuspend );
  

• 为了在安装过程中启用支持，INF 包含一个 AddReg 指令，该指令将 DefaultIdleState 值添加到设备的硬件密钥，并将值设置为 1。 例如：

  HKR,,"DefaultIdleState",0x00010001,1
  

设置空闲超时值

默认情况下，如果没有任何传输挂起，或者唯一挂起的传输是中断或批量终结点上的 IN 传输，WinUSB 会在 5 秒后暂停设备。 UMDF 驱动程序可以在安装 INF 时或在运行时更改此空闲超时值。

• 为了在安装时设置空闲超时，INF 包含一个 AddReg 指令，该指令将 DefaultIdleTimeout 值添加到设备的硬件密钥，并将该值设置为超时间隔（以毫秒为单位）。 以下示例将超时设置为 7 秒：

  HKR,,"DefaultIdleTimeout",0x00010001,7000
  

• 若要在运行时设置空闲超时，驱动程序调用 IWDFUsbTargetDevice：：SetPowerPolicy，PolicyType 设置为 SUSPEND_DELAY，Value 设置为空闲超时值（以毫秒为单位）。 在 Device.cpp 文件的以下示例中，Fx2_Driver示例将超时设置为 10 秒：

  HRESULT hr;
  ULONG value;
  value = 10 * 1000;
  hr = m_pIUsbTargetDevice->SetPowerPolicy( SUSPEND_DELAY,
                                            sizeof(ULONG),
                                           (PVOID) &value );
  

提供 USB 选择性挂起的用户控制

使用 WinUSB 选择性挂起支持的 UMDF USB 驱动程序可以选择性地允许用户启用或禁用选择性挂起。 为此，请在 INF 中包含 AddReg 指令，该指令将 UserSetDeviceIdleEnabled 值添加到设备的硬件密钥，并将值设置为 1。 下面显示了要用于 AddReg 指令的字符串：

HKR,,"UserSetDeviceIdleEnabled",0x00010001,1

如果设置了 UserSetDeviceIdleEnabled，则设备的“属性”对话框包含一个“电源管理”选项卡，允许用户启用或禁用 USB 选择性挂起。

UMDF 驱动程序中的系统唤醒

在 UMDF 驱动程序中，对系统唤醒的支持独立于对选择性挂起的支持。 UMDF USB 驱动程序可以同时支持系统唤醒和选择性挂起、系统唤醒和选择性挂起，或者系统唤醒或选择性挂起。 支持系统唤醒的设备可以将系统从睡眠状态唤醒 (S1、S2 或 S3) 。

UMDF USB PPO 驱动程序可以通过为框架的驱动程序对象提供唤醒信息来支持系统唤醒。 当外部事件触发系统唤醒时，框架会将设备返回到工作状态。

USB 非 PPO 驱动程序可以使用 WinUSB.sys 驱动程序实现的系统唤醒支持。

在作为 PPO 的 UMDF USB 驱动程序中支持系统唤醒

使用以下参数在框架的设备对象上调用 IWDFDevice2：：AssignSxWakeSettings 方法：

• DxState 为系统进入可唤醒 Sx 状态时设备转换到的电源状态。 对于 USB 设备，请指定 PowerDeviceMaximum 以使用总线驱动程序指定的值。
• 如果驱动程序允许用户管理唤醒设置，则 UserControlOfWakeSettings 到 WakeAllowUserControl;如果驱动程序允许用户管理唤醒设置，则为 WakeDoNotAllowUserControl。
• 启用WdfUseDefault 以默认启用唤醒，但允许用户的设置替代默认值。

以下示例演示IdleWake_PPO驱动程序如何在其内部 CMyDevice：：SetPowerManagement 方法中调用此方法：

hr = m_FxDevice->AssignSxWakeSettings( PowerDeviceMaximum,
                                       WakeAllowUserControl,
                                       WdfUseDefault);

在非 PPO 驱动程序中通过 WinUSB 启用系统唤醒

若要通过 WinUSB 启用系统唤醒，驱动程序的 INF 会将注册表值 SystemWakeEnabled 添加到设备的硬件密钥，并将其设置为 1。 IdleWake_Non-PPO 示例启用系统唤醒，如下所示：

[OsrUsb_Device_AddReg]
...
HKR,,"SystemWakeEnabled",0x00010001,1

通过设置此值，驱动程序将启用系统唤醒并允许用户控制设备唤醒系统的能力。 在 设备管理器 中，设备的电源管理设置属性页包括一个检查框，用户可以使用该框启用或禁用系统唤醒。