USB バルクエンドポイントにおける静的ストリームのオープン/クローズ方法

[アーティクル]
04/12/2024

この記事では、静的ストリーム機能について説明し、USB クライアントドライバーが USB 3.0 デバイスのバルクエンドポイントでストリームを開いたり閉じたりする方法を示しています。

USB 2.0 以前のデバイスでは、一括エンドポイントは、エンドポイントを介して 1 つのデータストリームを送受信できます。 USB 3.0 デバイスでは、一括エンドポイントには、エンドポイントを介して複数のデータストリームを送受信する機能があります。

Windows の Microsoft 提供の USB ドライバースタックは、複数のストリームをサポートしています。これにより、クライアントドライバーは、USB 3.0 デバイスの一括エンドポイントに関連付けられている各ストリームに独立した I/O 要求を送信できます。異なるストリームへの要求はシリアル化されません。

クライアントドライバーの場合、ストリームは同じ特性のセットを持つ複数の論理エンドポイントを表します。特定のストリームに要求を送信するには、クライアントドライバーには、そのストリームへのハンドル (エンドポイントのパイプハンドルと同様) が必要です。ストリームへの I/O 要求の URB は、一括エンドポイントへの I/O 要求の URB に似ています。唯一の違いは、パイプハンドルです。ストリームに I/O 要求を送信するために、ドライバーはストリームへのパイプハンドルを指定します。

デバイスの構成中に、クライアントドライバーは選択構成要求と必要に応じて、インターフェイスの選択要求を送信します。これらの要求は、インターフェイスのアクティブな設定で定義されているエンドポイントへのパイプハンドルのセットを取得します。ストリームをサポートするエンドポイントの場合、ドライバーがストリームを開くまで (次に説明します) まで、エンドポイントパイプハンドルを使用して既定のストリーム (最初のストリーム) に I/O 要求を送信できます。

クライアントドライバーがデフォルトストリーム以外のストリームにリクエストを送信したい場合、ドライバーはすべてのストリームへのハンドルを開いて取得する必要があります。これを行うために、クライアントドライバーは、開くストリームの数を指定して、オープンストリーム要求を送信します。クライアントドライバーがストリームの使用を終了した後、ドライバーは必要に応じて、クローズストリーム要求を送信することで、それらを閉じることができます。

カーネルモードドライバーフレームワーク (KMDF) は、本質的に静的ストリームをサポートしません。クライアントドライバーは、ストリームを開いたり閉じたりする Windows Driver Model (WDM) スタイルの URL を送信する必要があります。この記事では、これらの URL を書式設定して送信する方法について説明します。ユーザーモードドライバーフレームワーク (UMDF) クライアントドライバーでは、静的ストリーム機能を使用できません。

この記事には、WDM ドライバーとしてラベル付けされたいくつかのメモが含まれています。これらのメモでは、ストリーム要求を送信する WDM ベースの USB クライアントドライバーのルーチンについて説明します。

前提条件

クライアントドライバーがストリームを開いたり閉じたりするには、ドライバーに次のものが必要です。

WdfUsbTargetDeviceCreateWithParameters メソッドを呼び出しました。

このメソッドでは、クライアント契約のバージョンが USBD_CLIENT_CONTRACT_VERSION_602 である必要があります。そのバージョンを指定することで、クライアントドライバーは一連の規則に従う必要があります。詳細については、「ベストプラクティス: URB の使用」に関するページを参照してください。

この呼び出しは、フレームワークの USB ターゲットデバイスオブジェクトに対する WDFUSBDEVICE ハンドルを取得します。そのハンドルは、後続の呼び出しを行ってストリームを開くために必要です。通常、クライアントドライバーは、ドライバーの EVT_WDF_DEVICE_PREPARE_HARDWARE イベントコールバックルーチンに自身を登録します。

WDM ドライバー: USBD_CreateHandle ルーチンを呼び出し、USB ドライバースタックにドライバーの登録の USBD ハンドルを取得します。
デバイスを構成し、ストリームをサポートするバルクエンドポイントへの WDFUSBPIPE パイプハンドルを取得しました。パイプハンドルを取得するには、選択した構成のインターフェイスの現在の代替設定で WdfUsbInterfaceGetConfiguredPipe メソッドを呼び出します。

WDM ドライバー: 選択構成または選択インターフェイス要求を送信して USBD パイプハンドルを取得します。詳細については、「USB デバイス用の構成の選択方法」を参照してください。

静的ストリームを開く方法

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 で説明します)。これらの要求では、機能のクエリと URB の割り当てに同じハンドルを使用していることを確認してください。これは、ドライバースタックがハンドルを使用して、ドライバーが使用できるサポートされている機能を追跡するためです。
  
  たとえば、(USBD_CreateHandle を呼び出して) USBD_HANDLE を取得した場合は、USBD_QueryUsbCapability を呼び出してドライバースタックにクエリを実行し、USBD_UrbAllocate を呼び出して URB を割り当てます。両方の呼び出しで同じ USBD_HANDLE を渡します。
  
  KMDF メソッド WdfUsbTargetDeviceQueryUsbCapability および WdfUsbTargetDeviceCreateUrb を呼び出す場合は、これらのメソッド呼び出しでフレームワークターゲットオブジェクトに対して同じ WDFUSBDEVICE ハンドルを指定します。
- GUID_USB_CAPABILITY_STATIC_STREAMS に割り当てられた GUID。
- 出力バッファー (USHORT へのポインター)。完了すると、バッファーには、ホストコントローラーでサポートされている (エンドポイントごとの) ストリームの最大数が入力されます。
- 出力バッファの長さ (バイト単位)。ストリームの場合、長さは sizeof (USHORT) です。
返された NTSTATUS 値を評価します。ルーチンが正常に完了し、STATUS_SUCCESS を返す場合は、静的ストリーム機能がサポートされます。それ以外の場合、メソッドは適切なエラーコードを返します。
開くストリームの数を決定します。開くことができるストリームの最大数は、次の方法で制限されます。
- ホストコントローラーでサポートされるストリームの最大数。この番号は、呼び出し元が指定した出力バッファーで WdfUsbTargetDeviceQueryUsbCapability (WDM ドライバー、USBD_QueryUsbCapability) によって受信されます。マイクロソフト提供の USB ドライバースタックは、最大 255 のストリームをサポートしています。 WdfUsbTargetDeviceQueryUsbCapability では、ストリームの数を計算する際にその制限を考慮します。このメソッドは、255 より大きい値を返すことはありません。
- デバイス内のエンドポイントでサポートされるストリームの最大数。その番号を取得するには、エンドポイントコンパニオン記述子を調べます (Usbspec.h の USB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR を参照してください)。エンドポイントコンパニオン記述子を取得するには、構成記述子を解析する必要があります。構成記述子を取得するには、クライアントドライバーが WdfUsbTargetDeviceRetrieveConfigDescriptor メソッドを呼び出す必要があります。ヘルパールーチン、USBD_ParseConfigurationDescriptorEx および USBD_ParseDescriptor を使用する必要があります。コード例については、「USB パイプを列挙する方法」の RetrieveStreamInfoFromEndpointDesc という名前の関数の例を参照してください。
ストリームの最大数を決定するには、ホストコントローラーとエンドポイントでサポートされる 2 つの値のうち小さい方を選択します。
n 個の要素を持つ USBD_STREAM_INFORMATION 構造体の配列を割り当てます。n は、開くストリームの数です。クライアントドライバーは、ドライバーがストリームの使用を終了した後にこの配列を解放する必要があります。
WdfUsbTargetDeviceCreateUrb メソッドを呼び出して、オープンストリーム要求に URB を割り当てます。呼び出しが正常に完了した場合、メソッドは WDF メモリオブジェクトと、USB ドライバースタックによって割り当てられている URB 構造体のアドレスを取得します。

WDM ドライバー: USBD_UrbAllocate ルーチンを呼び出します。
オープンストリーム要求の URB を書式設定します。 URB は、__URB_OPEN_STATIC_STREAMS 構造体を使用して要求を定義します。 URB の書式を設定するには、次のものが必要です。
- エンドポイントへの USBD パイプハンドル。 WDF パイプオブジェクトがある場合は、WdfUsbTargetPipeWdmGetPipeHandle メソッドを呼び出すことによって USBD パイプハンドルを取得できます。
- ストリーム配列 (手順 4 で作成)
- URB 構造体へのポインター (手順 5 で作成)。
URB の書式を設定するには、UsbBuildOpenStaticStreamsRequest を呼び出して、必要な情報をパラメーター値として渡します。 UsbBuildOpenStaticStreamsRequest に指定されたストリームの数が、サポートされているストリームの最大数を超えていないことを確認します。
WdfRequestSend メソッドを呼び出して、URB を WDF 要求オブジェクトとして送信します。要求を同期的に送信するには、代わりに WdfUsbTargetDeviceSendUrbSynchronously メソッドを呼び出します。

WDM ドライバー: URB を IRP に関連付け、IRP を USB ドライバースタックに送信します。詳細については、「URB の送信方法」に関する記事を参照してください。
要求が完了したら、要求の状態を確認します。

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 はフレームワークによってインターセプトされます。フレームワークは、IRP を表す WDF 要求オブジェクトを割り当てます。その後、フレームワークは WDF 要求オブジェクトをクライアントドライバーに渡します。クライアントドライバーは、要求オブジェクトをデータ転送 URB に関連付け、USB ドライバースタックに送信できます。

クライアントドライバーがフレームワークから WDF 要求オブジェクトを受信せず、要求を非同期的に送信する場合、ドライバーは WdfRequestCreate メソッドを呼び出して WDF 要求オブジェクトを割り当てる必要があります。 WdfUsbTargetPipeFormatRequestForUrb を呼び出して新しいオブジェクトを書式設定し、WdfRequestSend を呼び出して要求を送信します。

同期の場合、WDF 要求オブジェクトの受け渡しは省略可能です。

ストリームにデータを転送するには、URL を使用する必要があります。 URB は、WdfUsbTargetPipeFormatRequestForUrb を呼び出して書式設定する必要があります。

ストリームでは、次の WDF メソッドはサポートされていません。

次の手順では、クライアントドライバーがフレームワークから要求オブジェクトを受信することを前提としています。

WdfUsbTargetDeviceCreateUrb を呼び出して URB を割り当てます。このメソッドは、新しく割り当てられた URB を含む WDF メモリオブジェクトを割り当てます。クライアントドライバーは、すべての I/O リクエストに URB を割り当てるか、URB を割り当てて同じタイプのリクエストに再利用するかを選択できます。
UsbBuildInterruptOrBulkTransferRequest を呼び出して、一括転送の URB を書式設定します。 PipeHandle パラメーターで、ストリームへのハンドルを指定します。ストリームハンドルは、「静的ストリームを開く方法」セクションで説明した、前の要求で取得されています。
WdfUsbTargetPipeFormatRequestForUrb メソッドを呼び出して、WDF 要求オブジェクトを書式設定します。呼び出しで、データ転送 URB を含む WDF メモリオブジェクトを指定します。メモリオブジェクトは、手順 1 で割り当てられています。
WdfRequestSend または WdfUsbTargetPipeSendUrbSynchronously を呼び出して、URB を WDF 要求として送信します。 WdfRequestSend を呼び出す場合は、非同期操作が完了したときにクライアントドライバーに通知を受け取ることができるように、WdfRequestSetCompletionRoutine を呼び出して完了ルーチンを指定する必要があります。完了ルーチンでデータ転送 URB を解放する必要があります。

WDM ドライバー:USBD_UrbAllocate を呼び出して URB を割り当て、一括転送用に書式設定します (_URB_BULK_OR_INTERRUPT_TRANSFER を参照)。 URB の書式を設定するには、UsbBuildInterruptOrBulkTransferRequest を呼び出すか、URB 構造体を手動で書式設定します。 URB の UrbBulkOrInterruptTransfer.PipeHandle メンバーのストリームへのハンドルを指定します。

静的ストリームを閉じる方法

クライアントドライバーは、ドライバーの使用が完了した後にストリームを閉じる可能性があります。ただし、ストリームの閉じる要求は省略可能です。 USB ドライバースタックは、ストリームに関連付けられたエンドポイントの構成が解除されると、すべてのストリームを閉じます。エンドポイントは、代替構成またはインターフェイスが選択されたとき、デバイスが削除されたときなどに構成解除されます。クライアントドライバーは、ドライバーが別の数のストリームを開く場合は、ストリームを閉じる必要があります。ストリームを閉じる要求を送信するには:

WdfUsbTargetDeviceCreateUrb を呼び出して URB 構造体を割り当てます。
クローズストリーム要求の URB を書式設定します。 URB 構造体の UrbPipeRequest メンバーは、_URB_PIPE_REQUEST 構造体です。そのメンバーを次のように入力します。
- _URB_PIPE_REQUEST の Hdr メンバーは、URB_FUNCTION_CLOSE_STATIC_STREAMS である必要があります
- PipeHandle メンバーは、使用中の開いているストリームを含むエンドポイントへのハンドルである必要があります。
WdfRequestSend または WdfUsbTargetDeviceSendUrbSynchronously を呼び出して、URB を WDF 要求として送信します。

クローズハンドル要求は、クライアントドライバーによって以前に開かれたすべてのストリームを閉じます。クライアントドライバーは、要求を使用してエンドポイント内の特定のストリームを閉じることはできません。

静的ストリーム要求を送信するためのベストプラクティス

USB ドライバースタックは、受信した URB で検証を実行します。検証エラーを回避するには:

ストリームをサポートしていないエンドポイントには、オープンストリームまたはクローズストリーム要求を送信しないでください。 WdfUsbTargetDeviceQueryUsbCapability (WDM ドライバー、USBD_QueryUsbCapability) を呼び出して静的ストリームのサポートを決定し、エンドポイントがサポートしている場合にのみストリーム要求を送信します。
サポートされているストリームの最大数を超える数 (開くストリームの数) をリクエストしたり、ストリーム数を指定せずに要求を送信したりしないでください。 USB ドライバースタックとデバイスのエンドポイントでサポートされているストリームの数に基づいてストリームの数を決定します。
既に開いているストリームがあるエンドポイントには、オープンストリーム要求を送信しないでください。
開いているストリームがないエンドポイントには、クローズストリーム要求を送信しないでください。
エンドポイントの静的ストリームが開いた後は、構成選択要求またはインターフェイス選択要求を通じて取得したエンドポイントパイプハンドルを使用して I/O 要求を送信しないでください。これは、静的ストリームが閉じられている場合でも当てはまります。

パイプ操作のリセットと中止

場合によっては、エンドポイントとの間の転送が失敗することがあります。このようなエラーは、停止状態や停止状態など、エンドポイントまたはホストコントローラーのエラー状態によって発生する可能性があります。エラー状態をクリアするために、クライアントドライバーはまず保留中の転送をキャンセルし、次にエンドポイントが関連付けられているパイプをリセットします。保留中の転送を取り消すために、クライアントドライバーは中止パイプ要求を送信できます。パイプをリセットするには、クライアントドライバーがパイプのリセット要求を送信する必要があります。

ストリーム転送の場合、一括エンドポイントに関連付けられた個々のストリームでは、パイプ中止リクエストとリセットパイプリクエストの両方がサポートされません。特定のストリームパイプで転送が失敗した場合、ホストコントローラーは他のすべてのパイプ (他のストリームの場合) での転送を停止します。エラー状態から回復するには、クライアントドライバーは各ストリームへの転送を手動でキャンセルする必要があります。次に、クライアントドライバーは、パイプハンドルを使用してパイプリセット要求をバルクエンドポイントに送信する必要があります。その要求の場合、クライアントドライバーは、_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;
}

USB I/O 操作

次の方法で共有

USB バルクエンドポイントにおける静的ストリームのオープン/クローズ方法

前提条件

静的ストリームを開く方法

特定のストリームにデータを転送する方法

静的ストリームを閉じる方法

静的ストリーム要求を送信するためのベストプラクティス

パイプ操作のリセットと中止

コード例全体

フィードバック

その他のリソース

次の方法で共有

USB バルク エンドポイントにおける静的ストリームのオープン/クローズ方法

前提条件

静的ストリームを開く方法

特定のストリームにデータを転送する方法

静的ストリームを閉じる方法

静的ストリーム要求を送信するためのベスト プラクティス

パイプ操作のリセットと中止

コード例全体

関連トピック

フィードバック

その他のリソース

USB バルクエンドポイントにおける静的ストリームのオープン/クローズ方法

静的ストリーム要求を送信するためのベストプラクティス