windows USB 设备驱动开发-发送MDL和错误恢复

USB 驱动程序可以在堆栈中使用链接式 MDL 功能发送数据，并且USB驱动的客户端可以将传输缓冲区作为 MDL 结构链发送。

大多数 USB 主机控制器要求传输缓冲区几乎是连续的。几乎连续意味着缓冲区可以开始和结束页中的任意位置，但缓冲区的其余部分必须在页面边界上开始和结束。许多 USB 客户端驱动程序都能够满足该要求。但是，对于某些客户端驱动程序，特别是那些需要向缓冲区添加或删除其他数据的客户端驱动程序，为传输缓冲区分配几乎连续的内存是不可取的。

例如，假设网络堆栈包含三个驱动程序、一个网络协议驱动程序、一个中间驱动程序和一个微型端口驱动程序。协议驱动程序启动传输并将数据包发送到堆栈中的下一个驱动程序：中间驱动程序。中间驱动程序希望向数据包添加单独的内存块中包含的自定义标头。中间驱动程序将该标头和收到的数据包发送到堆栈中的下一个驱动程序：微型端口驱动程序。微型端口驱动程序与 USB 驱动程序堆栈接口，因此必须准备几乎连续的传输缓冲区。若要创建此类缓冲区，微型端口驱动程序会分配一个大型缓冲区，添加自定义标头，然后复制有效负载。由于有效负载通常很大，因此复制整个有效负载可能会对性能产生重大影响。

使用链式MDL

客户端驱动程序可以通过将传输缓冲区作为内存描述符列表链 (MDL) 来克服这种性能影响。 Windows 8 中的新 USB 驱动程序堆栈能够接受链接的 MDL (从客户端驱动程序查看 MDL) 。通过提供链接的 MDL，客户端驱动程序可以引用内存中的不连续页面，而不是执行无关的复制操作。此功能消除了对缓冲区的数量、大小和对齐方式的限制，从而允许在物理内存中对传输缓冲区进行分段。

若要使用链接的 MDL，客户端驱动程序必须检测 Windows 加载的基础 USB 驱动程序堆栈是否支持该功能，然后以正确的顺序生成 MDL 链。

链式 MDL 功能仅支持批量传输、常时等传输和中断传输。在查询链接 MDL 功能之前，请确保客户端驱动程序具有 USBD 句柄，用于向 USB 驱动程序堆栈注册驱动程序。若要创建 USBD 句柄，请调用 USBD_CreateHandle。通常，客户端驱动程序在其 AddDevice 例程中创建 USBD 句柄。

可以在客户端驱动程序的 IRP_MN_START_DEVICE 处理程序中查询链接的 MDL 功能，或稍后随时查询。客户端驱动程序不得在其 AddDevice 例程中查询此功能：

1.调用 USBD_QueryUsbCapability 例程以确定 USB 驱动程序堆栈是否支持链接的 MDL 功能。若要查询该功能，请将 UsbCapabilityChainedMdls 指定为 GUID。将 OutputBuffer 参数设置为 NULL，将 OutputBufferSize 参数设置为 0；

2.检查 USBD_QueryUsbCapability 返回的 NTSTATUS 值并评估结果。如果例程成功完成，则支持链接的 MDL 功能。任何其他值表示不支持该功能；

3.创建 MDL 链。每个 MDL 都有一个指向另一个 MDL 的 Next 指针；

驱动程序可以通过手动设置 Next 指针来生成链 MDL；

在前面的示例中，协议驱动程序将数据包作为 MDL 发送。中间驱动程序可以创建另一个 MDL，该 MDL 使用标头数据引用内存块。若要创建链，中间驱动程序可以将标头 MDL 的 Next 指针指向从协议驱动程序接收的 MDL。然后，中间驱动程序可以将两个 MDL 的链转发到微型端口驱动程序，该驱动程序为请求的 URB 中的链接 MDL 提供引用，并将请求提交到 USB 驱动程序堆栈。

4.为使用链接的 MDL 的 I/O 请求生成 URB 时，请将关联 URB 结构的 TransferBufferMDL 成员 (（如 _URB_BULK_OR_INTERRUPT_TRANSFER 或 _URB_ISOCH_TRANSFER) ）设置为链中的第一个 MDL，并将 TransferBufferLength 设置为要传输的总字节数。数据可以跨 MDL 链中的多个 MDL 条目。

在 Windows 8 中添加了两种新类型的 URB 函数，使客户端驱动程序能够使用链接的 MDL 进行数据传输。如果要使用此功能，请确保将 URB 标头的 Function 成员设置为以下 URB 函数之一：

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER_USING_CHAINED_MDL
URB_FUNCTION_ISOCH_TRANSFER_USING_CHAINED_MDL

如何从 USB 管道错误中恢复

在数据传输到 USB 管道失败时，USB设备可以尝试某些步骤来处理这个异常信息。本文中所述的机制涵盖批量、中断和常时常量管道上的中止、重置和循环端口操作。

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

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

下面是有关通过这些操作进行错误恢复的准则：

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

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

关于协调各种恢复机制：

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

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

先决条件

客户端驱动程序必须已创建框架 USB 目标设备对象。如果使用 Microsoft Visual Studio Professional 2012 随附的 USB 模板，则模板代码将执行这些任务。模板代码会获取目标设备对象的句柄并将其存储在设备上下文中。KMDF 客户端驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters 方法来获取 WDFUSBDEVICE 句柄；
客户端驱动程序必须具有框架目标管道对象的句柄；

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

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

如果通过调用 WdfUsbTargetDeviceSendUrbSynchronously 方法提交了 URB，请在方法返回后检查 URB 结构的 Hdr.Status 成员。
如果通过调用 WdfRequestSend 方法异步提交了 URB，检查EVT_WDF_REQUEST_COMPLETION_ROUTINE中的 URB 状态。 Params 参数指向WDF_REQUEST_COMPLETION_PARAMS结构。若要检查 USBD 状态代码，请检查 Usb-UsbdStatus> 成员。有关代码的信息，请参阅 USBD_STATUS。

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

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

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

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

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

通过调用 WdfIoTargetStop 方法停止 I/O 目标：

若要停止 I/O 目标，请首先通过调用 WdfUsbTargetPipeGetIoTarget 方法获取与框架管道对象关联的 WDFIOTARGET 句柄。通过使用句柄，调用 WdfIoTargetStop。在调用中，将操作设置为 WdfIoTargetCancelSentIo (see WDF_IO_TARGET_SENT_IO_ACTION) ** 指示框架取消 USB 驱动程序堆栈尚未完成的所有请求。对于已完成的请求，客户端驱动程序必须等待框架调用其完成回调。

发送中止管道请求。可以通过调用以下方法之一来发送请求：

调用 WdfUsbTargetPipeAbortSynchronously 方法。

调用是同步的，仅在取消所有挂起的请求后返回。 WdfUsbTargetPipeAbortSynchronously 采用可选的 Request 参数。建议将 WDFREQUEST 句柄传递给预先分配的框架请求对象。参数允许框架使用指定的请求对象，而不是驱动程序无法访问的内部请求对象。此参数值可确保 WdfUsbTargetPipeAbortSynchronously 不会因内存不足而失败。

调用 WdfUsbTargetPipeFormatRequestForAbort 方法以格式化 abort-pipe 请求的请求对象，然后通过调用 WdfRequestSend 方法发送请求。

如果驱动程序异步发送请求，则必须指定指向驱动程序实现的驱动程序 EVT_WDF_REQUEST_COMPLETION_ROUTINE 的指针。若要指定指针，请调用 WdfRequestSetCompletionRoutine 方法。

驱动程序可以通过将 WDF_REQUEST_SEND_OPTION_SYNCHRONOUS 指定为 WdfRequestSend 中的请求选项之一来同步发送请求。如果以同步方式发送请求，请改为调用 WdfUsbTargetPipeAbortSynchronously 。

步骤 4：重置 USB 管道

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

调用 WdfUsbTargetPipeResetSynchronously 以同步发送重置管道请求；
调用 WdfUsbTargetPipeFormatRequestForReset 方法以格式化重置管道请求的请求对象，然后通过调用 WdfRequestSend 方法发送请求。这些调用类似于中止管道请求的调用，如步骤 3 中所述；

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

重置管道请求清除设备和主机控制器硬件中的错误条件。为了清除设备错误，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.取消到设备的所有传输。请确保取消针对当前配置中每个管道计划的挂起请求；

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

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

调用 WdfUsbTargetDeviceCyclePortSynchronously 以同步发送周期端口请求。
调用 WdfUsbTargetDeviceFormatRequestForCyclePort 方法以格式化循环端口请求的请求对象，然后通过调用 WdfRequestSend 方法发送请求。这些调用类似于中止管道请求的调用，如步骤 3 中所述；

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

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

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