如何打开和关闭 USB 大容量终结点中的静态流

  • 项目

本文讨论 静态流功能 ，并说明 USB 客户端驱动程序如何在 USB 3.0 设备的批量终结点中打开和关闭流。

在 USB 2.0 和更早版本的设备中，批量终结点可以通过该终结点发送或接收单个数据流。 在 USB 3.0 设备中，批量终结点能够通过该终结点发送和接收多个数据流。

Windows 中 Microsoft 提供的 USB 驱动程序堆栈支持多个流。 这使客户端驱动程序能够将独立的 I/O 请求发送到与 USB 3.0 设备中的批量终结点关联的每个流。 不会序列化对不同流的请求。

对于客户端驱动程序，流表示具有相同特征集的多个逻辑终结点。 若要将请求发送到特定流，客户端驱动程序需要该流的句柄 (类似于终结点) 的管道句柄。 流 I/O 请求的 URB 类似于针对批量终结点的 I/O 请求的 URB。 唯一的区别是管道句柄。 若要向流发送 I/O 请求，驱动程序会指定流中的管道句柄。

在设备配置期间，客户端驱动程序发送选择配置请求和选择接口请求（可选）。 这些请求检索接口的活动设置中定义的终结点的一组管道句柄。 对于支持流的终结点，终结点管道句柄可用于将 I/O 请求发送到默认 流 (第一个流) ，直到驱动程序打开流 (下一) 讨论。

如果客户端驱动程序想要将请求发送到默认流以外的流，则驱动程序必须打开并获取所有流的句柄。 为此，客户端驱动程序通过指定要 打开的流 数来发送开放流请求。 客户端驱动程序使用完流后，驱动程序可以选择通过发送 关闭流请求来关闭它们。

内核模式驱动程序框架 (KMDF) 本身不支持静态流。 客户端驱动程序必须发送 Windows 驱动程序模型 (WDM) 样式的 URL，以打开和关闭流。 本文介绍如何设置这些 URL 的格式并发送这些 URL。 用户模式驱动程序框架 (UMDF) 客户端驱动程序无法使用静态流功能。

本文包含一些标记为 WDM 驱动程序的注释。 这些说明描述了想要发送流请求的基于 WDM 的 USB 客户端驱动程序的例程。

先决条件

在客户端驱动程序可以打开或关闭流之前，驱动程序必须具有：

  • 调用 WdfUsbTargetDeviceCreateWithParameters 方法。

    方法要求USBD_CLIENT_CONTRACT_VERSION_602客户端协定版本。 通过指定该版本，客户端驱动程序必须遵守一组规则。 有关详细信息，请参阅 最佳做法：使用 URL。

    调用检索框架的 USB 目标设备对象的 WDFUSBDEVICE 句柄。 需要该句柄才能对打开的流进行后续调用。 通常，客户端驱动程序在驱动程序的 EVT_WDF_DEVICE_PREPARE_HARDWARE 事件回调例程中注册自身。

    WDM 驱动程序： 调用 USBD_CreateHandle 例程并获取 USB 驱动程序堆栈中驱动程序注册的 USBD 句柄。

  • 配置了设备并获取了支持流的批量终结点的 WDFUSBPIPE 管道句柄。 若要获取管道句柄，请在所选配置中的接口的当前备用设置上调用 WdfUsbInterfaceGetConfiguredPipe 方法。

    WDM 驱动程序： 通过发送 select-configuration 或 select-interface 请求获取 USBD 管道句柄。 有关详细信息，请参阅 如何为 USB 设备选择配置。

如何打开静态流

  1. 通过调用 WdfUsbTargetDeviceQueryUsbCapability 方法，确定基础 USB 驱动程序堆栈和主机控制器是否支持静态流功能。 通常，客户端驱动程序在驱动程序的 EVT_WDF_DEVICE_PREPARE_HARDWARE 事件回调例程中调用例程。

    WDM 驱动程序： 调用 USBD_QueryUsbCapability 例程。 通常，驱动程序会查询要在驱动程序的启动设备例程中使用的功能， (IRP_MN_START_DEVICE) 。 有关代码示例，请参阅 USBD_QueryUsbCapability。

    提供以下信息：

    • 在先前调用 WdfUsbTargetDeviceCreateWithParameters 时检索到的 USB 设备对象的句柄，用于注册客户端驱动程序。

      WDM 驱动程序： 将上一次调用中检索到的 USBD 句柄传递给 USBD_CreateHandle。

      如果客户端驱动程序想要使用特定功能，则驱动程序必须首先查询基础 USB 驱动程序堆栈，以确定驱动程序堆栈和主机控制器是否支持该功能。 如果支持该功能，则只有这样，驱动程序才应发送使用该功能的请求。 某些请求需要 URL，例如步骤 5) 中 (讨论的流功能。 对于这些请求，请确保使用相同的句柄来查询功能和分配 URL。 这是因为驱动程序堆栈使用句柄来跟踪驱动程序可以使用的受支持功能。

      例如，如果通过调用 USBD_CreateHandle) 获取 了USBD_HANDLE ( ，则通过调用 USBD_QueryUsbCapability 查询驱动程序堆栈，并通过调用 USBD_UrbAllocate 来分配 URB。 在这两个调用中传递相同的USBD_HANDLE。

      如果调用 KMDF 方法、 WdfUsbTargetDeviceQueryUsbCapability 和 WdfUsbTargetDeviceCreateUrb，请在这些方法调用中为框架目标对象指定相同的 WDFUSBDEVICE 句柄。

    • 分配给GUID_USB_CAPABILITY_STATIC_STREAMS的 GUID。

    • 输出缓冲区 (指向 USHORT) 的指针。 完成后，缓冲区将填充主机控制器支持的每个终结点 (的最大流数) 。

    • 输出缓冲区的长度，以字节表示。 对于流，长度为 sizeof (USHORT)。

  2. 评估返回的 NTSTATUS 值。 如果例程成功完成，则返回STATUS_SUCCESS，则支持静态流功能。 否则，该方法将返回相应的错误代码。

  3. 确定要打开的流数。 可打开的最大流数受以下限制：

    若要确定流的最大数目，请选择主机控制器和终结点支持的两个值中的较小一个。

  4. 分配包含 n 个元素的USBD_STREAM_INFORMATION结构的数组，其中 n 是要打开的流数。 客户端驱动程序负责在驱动程序使用完流后释放此数组。

  5. 通过调用 WdfUsbTargetDeviceCreateUrb 方法为开放流请求分配 URB。 如果调用成功完成，该方法将检索 WDF 内存对象以及 USB 驱动程序堆栈分配的 URB 结构的地址。

    WDM 驱动程序： 调用 USBD_UrbAllocate 例程。

  6. 设置开放流请求的 URB 格式。 URB 使用 _URB_OPEN_STATIC_STREAMS 结构来定义请求。 若要设置 URB 的格式，需要：

    • 指向终结点的 USBD 管道句柄。 如果有 WDF 管道对象，可以通过调用 WdfUsbTargetPipeWdmGetPipeHandle 方法获取 USBD 管道句柄。
    • 在步骤 4 中创建 (流数组)
    • 指向 (步骤 5) 中创建的 URB 结构的指针。

    若要设置 URB 的格式，请调用 UsbBuildOpenStaticStreamsRequest 并将所需的信息作为参数值传递。 确保指定到 UsbBuildOpenStaticStreamsRequest 的流数不超过支持的最大流数。

  7. 通过调用 WdfRequestSend 方法将 URB 作为 WDF 请求对象发送。 若要以同步方式发送请求，请改为调用 WdfUsbTargetDeviceSendUrbSynchronously 方法。

    WDM 驱动程序： 将 URB 与 IRP 相关联，并将 IRP 提交到 USB 驱动程序堆栈。 有关详细信息，请参阅 如何提交 URB。

  8. 请求完成后，检查请求的状态。

    如果 USB 驱动程序堆栈请求失败，则 URB 状态包含相关的错误代码。 “备注”部分介绍了一些常见的故障条件。

如果请求的状态 (IRP 或 WDF 请求对象) 指示USBD_STATUS_SUCCESS，则表示请求已成功完成。 检查完成时收到的 USBD_STREAM_INFORMATION 结构的数组。 数组中填充了有关所请求流的信息。 USB 驱动程序堆栈使用流信息填充数组中的每个结构，例如USBD_PIPE_HANDLE) 接收的句柄 (、流标识符和最大数字传输大小。 流现在可传输数据。

对于开放流请求，需要分配 URB 和数组。 在打开的流请求完成后，客户端驱动程序必须通过在关联的 WDF 内存对象上调用 WdfObjectDelete 方法来释放 URB。 如果驱动程序通过调用 WdfUsbTargetDeviceSendUrbSynchronously 以同步方式发送请求，则必须在方法返回后释放 WDF 内存对象。 如果客户端驱动程序通过调用 WdfRequestSend 异步发送了请求，则驱动程序必须在与请求关联的驱动程序实现的完成例程中释放 WDF 内存对象。

可以在客户端驱动程序使用完流后释放流数组，或者为 I/O 请求存储流数组。 在本文中包含的代码示例中，驱动程序将流数组存储在设备上下文中。 驱动程序在释放设备对象之前释放设备上下文。

如何将数据传输到特定流

若要向特定流发送数据传输请求，需要 WDF 请求对象。 通常，客户端驱动程序不需要分配 WDF 请求对象。 当 I/O 管理器收到来自应用程序的请求时，I/O 管理器会为该请求创建 IRP。 该 IRP 被框架截获。 然后，框架分配一个 WDF 请求对象来表示 IRP。 之后，框架将 WDF 请求对象传递给客户端驱动程序。 然后，客户端驱动程序可以将请求对象与数据传输 URB 相关联，并将其发送到 USB 驱动程序堆栈。

如果客户端驱动程序未从框架接收 WDF 请求对象，并且想要以异步方式发送请求，则驱动程序必须通过调用 WdfRequestCreate 方法分配 WDF 请求对象。 通过调用 WdfUsbTargetPipeFormatRequestForUrb 设置新对象的格式，并通过调用 WdfRequestSend 发送请求。

在同步情况下，传递 WDF 请求对象是可选的。

若要将数据传输到流，必须使用 URB。 必须通过调用 WdfUsbTargetPipeFormatRequestForUrb 设置 URB 的格式。

流 不支持 以下 WDF 方法：

以下过程假定客户端驱动程序从框架接收请求对象。

  1. 通过调用 WdfUsbTargetDeviceCreateUrb 来分配 URB。 此方法分配包含新分配的 URB 的 WDF 内存对象。 客户端驱动程序可以选择为每个 I/O 请求分配 URB，或分配 URB 并将其用于同一类型的请求。

  2. 通过调用 UsbBuildInterruptOrBulkTransferRequest 格式化 URB 进行批量传输。 在 PipeHandle 参数中，指定流的句柄。 流句柄是在上一个请求中获取的，如 如何打开静态流 部分所述。

  3. 通过调用 WdfUsbTargetPipeFormatRequestForUrb 方法设置 WDF 请求对象的格式。 在调用中，指定包含数据传输 URB 的 WDF 内存对象。 在步骤 1 中分配了内存对象。

  4. 通过调用 WdfRequestSend 或 WdfUsbTargetPipeSendUrbSynchronously 将 URB 作为 WDF 请求发送。 如果调用 WdfRequestSend，则必须通过调用 WdfRequestSetCompletionRoutine 来指定完成例程，以便客户端驱动程序可以在异步操作完成时收到通知。 必须在完成例程中释放数据传输 URB。

WDM 驱动程序： 通过调用 USBD_UrbAllocate 分配 URB，并格式化它进行批量传输 (请参阅 _URB_BULK_OR_INTERRUPT_TRANSFER) 。 若要设置 URB 的格式，可以调用 UsbBuildInterruptOrBulkTransferRequest 或手动设置 URB 结构的格式。 在 URB 的 UrbBulkOrInterruptTransfer.PipeHandle 成员中指定流的句柄。

如何关闭静态流

客户端驱动程序可以在驱动程序使用完流后关闭流。 但是，关闭流请求是可选的。 当取消配置与流关联的终结点时，USB 驱动程序堆栈将关闭所有流。 选择备用配置或接口、删除设备等时，将取消配置终结点。 如果客户端驱动程序想要打开不同数量的流，则必须关闭流。 发送关闭流请求：

  1. 通过调用 WdfUsbTargetDeviceCreateUrb 来分配 URB 结构。

  2. 设置关闭流请求的 URB 格式。 URB 结构的 UrbPipeRequest 成员是_URB_PIPE_REQUEST结构。 按如下所示填写其成员：

    • 必须URB_FUNCTION_CLOSE_STATIC_STREAMS_URB_PIPE_REQUEST的 Hdr 成员
    • PipeHandle 成员必须是包含正在使用的打开流的终结点的句柄。

  3. 通过调用 WdfRequestSend 或 WdfUsbTargetDeviceSendUrbSynchronously 将 URB 作为 WDF 请求发送。

关闭句柄请求关闭以前由客户端驱动程序打开的所有流。 客户端驱动程序无法使用请求关闭终结点中的特定流。

发送静态流请求的最佳做法

USB 驱动程序堆栈对收到的 URB 执行验证。 若要避免验证错误，请执行以下操作：

  • 不要向不支持流的终结点发送开放流或关闭流请求。 调用 WDM 驱动程序的 WdfUsbTargetDeviceQueryUsbCapability (，USBD_QueryUsbCapability) 来确定静态流支持，并且仅在终结点支持时发送流请求。
  • 不要请求超过支持的最大流数的流 (打开) ，或者在未指定流数的情况下发送请求。 根据 USB 驱动程序堆栈和设备终结点支持的流数确定流数。
  • 不要向已具有开放流的终结点发送开放流请求。
  • 不要向没有开放流的终结点发送关闭流请求。
  • 为终结点打开静态流后，请勿使用通过选择配置或选择接口请求获取的终结点管道句柄发送 I/O 请求。 即使静态流已关闭，也是如此。

重置和中止管道操作

有时，传入或传出终结点的传输可能会失败。 此类故障可能是由于终结点或主机控制器上的错误条件（例如停止或停止条件）导致的。 为了清除错误条件，客户端驱动程序首先取消挂起的传输，然后重置与终结点关联的管道。 若要取消挂起的传输，客户端驱动程序可以发送中止管道请求。 若要重置管道，客户端驱动程序必须发送重置管道请求。

对于流传输，与批量终结点关联的单个流不支持 abort-pipe 和 reset-pipe 请求。 如果特定流管道上的传输失败，主机控制器将停止) 其他流 (的所有其他管道上的传输。 若要从错误条件中恢复，客户端驱动程序应手动取消到每个流的传输。 然后，客户端驱动程序必须使用管道句柄向批量终结点发送重置管道请求。 对于该请求，客户端驱动程序必须在 _URB_PIPE_REQUEST 结构中指定终结点的管道句柄，并将 URB 函数 (Hdr.Function) 设置为URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL。

完整示例

下面的代码示例演示如何打开流。

NTSTATUS
    OpenStreams (
    _In_ WDFDEVICE Device,
    _In_ WDFUSBPIPE Pipe)
{
    NTSTATUS status;
    PDEVICE_CONTEXT deviceContext;
    PPIPE_CONTEXT pipeContext;
    USHORT cStreams = 0;
    USBD_PIPE_HANDLE usbdPipeHandle;
    WDFMEMORY urbMemory = NULL;
    PURB      urb = NULL;

    PAGED_CODE();

    deviceContext =GetDeviceContext(Device);
    pipeContext = GetPipeContext (Pipe);

    if (deviceContext->MaxStreamsController == 0)
    {
        TraceEvents(TRACE_LEVEL_ERROR, TRACE_DEVICE,
            "%!FUNC! Static streams are not supported.");

        status = STATUS_NOT_SUPPORTED;
        goto Exit;
    }

    // If static streams are not supported, number of streams supported is zero.

    if (pipeContext->MaxStreamsSupported == 0)
    {
        status = STATUS_DEVICE_CONFIGURATION_ERROR;

        TraceEvents(TRACE_LEVEL_ERROR, TRACE_DEVICE,
            "%!FUNC! Static streams are not supported by the endpoint.");

        goto Exit;
    }

    // Determine the number of streams to open.
    // Compare the number of streams supported by the endpoint with the
    // number of streams supported by the host controller, and choose the
    // lesser of the two values. The deviceContext->MaxStreams value was
    // obtained in a previous call to WdfUsbTargetDeviceQueryUsbCapability
    // that determined whether or not static streams is supported and
    // retrieved the maximum number of streams supported by the
    // host controller. The device context stores the values for IN and OUT
    // endpoints.

    // Allocate an array of USBD_STREAM_INFORMATION structures to store handles to streams.
    // The number of elements in the array is the number of streams to open.
    // The code snippet stores the array in its device context.

    cStreams = min(deviceContext->MaxStreamsController, pipeContext->MaxStreamsSupported);

    // Allocate an array of streams associated with the IN bulk endpoint
    // This array is released in CloseStreams.

    pipeContext->StreamInfo = (PUSBD_STREAM_INFORMATION) ExAllocatePoolWithTag (
        NonPagedPool,
        sizeof (USBD_STREAM_INFORMATION) * cStreams,
        USBCLIENT_TAG);

    if (pipeContext->StreamInfo == NULL)
    {
        status = STATUS_INSUFFICIENT_RESOURCES;

        TraceEvents(TRACE_LEVEL_ERROR, TRACE_DEVICE,
            "%!FUNC! Could not allocate stream information array.");

        goto Exit;
    }

    RtlZeroMemory (pipeContext->StreamInfo,
        sizeof (USBD_STREAM_INFORMATION) * cStreams);

    // Get USBD pipe handle from the WDF target pipe object. The client driver received the
    // endpoint pipe handles during device configuration.

    usbdPipeHandle = WdfUsbTargetPipeWdmGetPipeHandle (Pipe);

    // Allocate an URB for the open streams request.
    // WdfUsbTargetDeviceCreateUrb returns the address of the
    // newly allocated URB and the WDFMemory object that
    // contains the URB.

    status = WdfUsbTargetDeviceCreateUrb (
        deviceContext->UsbDevice,
        NULL,
        &urbMemory,
        &urb);

    if (status != STATUS_SUCCESS)
    {
        TraceEvents(TRACE_LEVEL_ERROR, TRACE_DEVICE,
            "%!FUNC! Could not allocate URB for an open-streams request.");

        goto Exit;
    }

    // Format the URB for the open-streams request.
    // The UsbBuildOpenStaticStreamsRequest inline function formats the URB by specifying the
    // pipe handle to the entire bulk endpoint, number of streams to open, and the array of stream structures.

    UsbBuildOpenStaticStreamsRequest (
        urb,
        usbdPipeHandle,
        (USHORT)cStreams,
        pipeContext->StreamInfo);

    // Send the request synchronously.
    // Upon completion, the USB driver stack populates the array of with handles to streams.

    status = WdfUsbTargetPipeSendUrbSynchronously (
        Pipe,
        NULL,
        NULL,
        urb);

    if (status != STATUS_SUCCESS)
    {
        goto Exit;
    }

Exit:
    if (urbMemory)
    {
        WdfObjectDelete (urbMemory);
    }

    return status;
}