如何从 USB 管道错误中恢复

  • 项目

注意

本文面向设备驱动程序开发人员。 如果在使用 USB 设备时遇到问题，请参阅 排查常见的 USB 问题

本文提供有关在数据传输到 USB 管道失败时可以尝试的步骤的信息。 本文中所述的机制涵盖批量、中断和常时常量管道上的中止、重置和循环端口操作。

USB 客户端驱动程序通过将控制传输发送到默认终结点来与其设备通信;数据传输到设备的批量、中断和常时等量终结点。 有时，这些传输可能会由于各种原因（例如终结点中的停止条件）而失败。 如果传输失败，则在清除错误条件之前，关联的管道无法处理请求。

对于控制传输，USB 驱动程序堆栈会自动清除错误条件。 对于数据传输，客户端必须采取适当的步骤从错误条件中恢复。 数据传输失败时，USB 驱动程序堆栈会通过失败的 USBD 状态代码向客户端驱动程序报告错误。 然后，驱动程序可以根据状态代码提供错误恢复机制。

本文提供有关通过这些操作进行错误恢复的准则。

  • 重置 USB 管道
  • 重置设备连接到的 USB 端口
  • 循环 USB 端口以重新枚举客户端驱动程序的设备堆栈

若要清除错误条件，请从重置管道操作开始，并仅在必要时执行更复杂的操作，例如 reset-port 和 cycle-port。

关于协调各种恢复机制：

客户端驱动程序必须协调不同的恢复操作，并确保在给定时间仅使用一种方法。 例如，假设某个设备有两个终结点：批量和中断。 向设备发送一些数据传输请求后，驱动程序会注意到请求在批量管道上失败。 若要从这些错误中恢复，驱动程序会重置批量管道。 但是，该操作无法解决传输错误，并且批量传输将继续失败。 因此，驱动程序发出重置 USB 端口的请求。 同时，传输开始在中断管道上失败，然后重置设备请求。 若要从中断传输失败中恢复，驱动程序将在中断管道上发出重置管道请求。 如果这两个操作未协调，驱动程序可以同时启动两个重置设备操作，因为两个管道都失败。 这些同时操作可能会出现问题。

客户端驱动程序必须确保在给定的时间，驱动程序只执行一个重置端口或周期端口操作。 在这些操作期间，不应在任何管道上进行重置管道操作，并且驱动程序不得发出新的重置管道请求。

需要了解的事项

本文使用 内核模式驱动程序框架 (KMDF) 。

先决条件

  • 客户端驱动程序必须已创建框架 USB 目标设备对象。

    如果使用 Microsoft Visual Studio Professional 2012 随附的 USB 模板，则模板代码将执行这些任务。 模板代码会获取目标设备对象的句柄并将其存储在设备上下文中。

    KMDF 客户端驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters 方法来获取 WDFUSBDEVICE 句柄。 有关详细信息，请参阅了解 USB 客户端驱动程序代码结构 (KMDF) 中的“设备源代码”。

  • 客户端驱动程序必须具有框架目标管道对象的句柄。 有关详细信息，请参阅 如何枚举 USB 管道。

步骤 1：确定错误条件的原因

客户端驱动程序使用 USB 请求块 (URB) 启动数据传输。 请求完成后，USB 驱动程序堆栈将返回 USBD 状态代码，指示传输是成功还是失败。 在失败时，USBD 代码指示失败的原因。

传输失败可能是由设备错误引起的，例如USBD_STATUS_STALL_PID或USBD_STATUS_BABBLE_DETECTED。 它们也可能是由于主机控制器报告的错误（例如USBD_STATUS_XACT_ERROR）导致的。

步骤 2：确定设备是否已连接到端口

在发出重置管道或设备的任何请求之前，请确保设备已连接。 可以通过调用 WdfUsbTargetDeviceIsConnectedSynchronous 方法来确定设备的连接状态。

步骤 3：取消到管道的所有挂起传输

在发送任何重置管道或端口的请求之前，请取消对管道的所有挂起的传输请求，USB 驱动程序堆栈尚未完成这些请求。 可以通过以下方式之一取消请求：

步骤 4：重置 USB 管道

通过重置管道启动错误恢复。 可以通过调用以下方法之一来发送重置管道请求：

注意

在重置管道操作完成之前，不要发送任何新的传输请求。

重置管道请求清除设备和主机控制器硬件中的错误条件。 为了清除设备错误，USB 驱动程序堆栈使用ENDPOINT_HALT功能选择器向设备发送CLEAR_FEATURE控制请求。 请求的接收方是与管道关联的终结点。 如果错误条件发生在常时常量管道上，则驱动程序堆栈不会执行任何操作来清除设备，因为发生错误时，会自动清除常量终结点。

为了清除主机控制器错误，驱动程序堆栈会清除管道的 HALT 状态，并将管道的数据开关重置为 0。

步骤 5：重置 USB 端口

如果重置管道操作未清除错误条件，并且数据传输继续失败，请发送重置端口请求。

  1. 取消到设备的所有传输。 为此，请枚举当前配置中的所有管道，并取消为每个管道计划的挂起请求。

  2. 停止设备的 I/O 目标。

    调用 WdfUsbTargetDeviceGetIoTarget 方法以获取与框架目标设备对象关联的 WDFIOTARGET 句柄。 然后，调用 WdfIoTargetStop 并指定 WDFIOTARGET 句柄。 在调用中，将操作设置为 WdfIoTargetCancelSentIo (WDF_IO_TARGET_SENT_IO_ACTION) 。

  3. 通过调用 WdfUsbTargetDeviceResetPortSynchronously 方法发送重置端口请求。

重置端口操作会导致设备在 USB 总线上重新枚举。 USB 驱动程序堆栈在 枚举后保留设备配置。 客户端驱动程序可以使用以前获取的管道句柄，因为驱动程序堆栈可确保现有管道句柄保持有效。

无法重置复合设备的单个功能。 对于复合设备，当特定函数的客户端驱动程序发送重置端口请求时，将重置整个设备。 如果 USB 设备保持状态，该重置端口请求可能会影响其他功能的客户端驱动程序。 因此，客户端驱动程序必须在重置端口之前尝试重置管道。

步骤 6：循环使用 USB 端口

循环端口操作类似于拔出电源并插回端口的设备，不同之处在于设备未以电气方式断开连接。 设备在软件中断开连接并重新连接。 此操作会导致设备重置和枚举。 因此，PnP 管理器会重新生成设备节点。

如果重置端口操作未清除错误条件，并且数据传输继续失败，请发送周期端口请求。

  1. 取消到设备的所有传输。 请确保取消针对当前配置中每个管道计划的挂起请求 (请参阅步骤 3) 。

  2. 停止设备的 I/O 目标。

    调用 WdfUsbTargetDeviceGetIoTarget 方法以获取与框架目标设备对象关联的 WDFIOTARGET 句柄。 然后，调用 WdfIoTargetStop 并指定 WDFIOTARGET 句柄。 在调用中，将操作设置为 WdfIoTargetCancelSentIo (WDF_IO_TARGET_SENT_IO_ACTION) 。

  3. 通过调用以下方法之一发送循环端口请求：

客户端驱动程序只能在周期端口请求完成后向设备发送传输请求。 这是因为在 USB 驱动程序堆栈处理周期端口请求时删除了设备节点。

循环端口请求会导致设备重新枚举。 USB 驱动程序堆栈通知 PnP 管理器设备已断开连接。 PnP 管理器会拆掉与客户端驱动程序关联的设备堆栈。 驱动程序堆栈重置设备，在 USB 总线上重新枚举该设备，并通知 PnP 管理器设备已连接。 然后，PnP 管理器为 USB 设备重新生成设备堆栈。

由于循环端口操作，如果应用程序注册了此类通知) ，则任何对设备打开句柄的应用程序都会获得设备删除通知 (。 作为响应，应用程序可能会向用户报告设备断开连接的消息。 因为它会影响用户体验，因此仅当其他恢复机制无法解决错误条件时，客户端驱动程序才应选择周期端口请求。

与步骤 6) 中所述的重置端口操作 (类似，对于复合设备，循环端口操作会影响整个设备，而不是设备的各个功能。