英語で読む

次の方法で共有

USB クライアント ドライバー検証ツール

  • [アーティクル]

この記事では、クライアント ドライバーが特定の障害ケースをテストできるようにする、USB 3.0 ドライバー スタックの USB クライアント ドライバー検証機能について説明します。

USB クライアント ドライバー検証ツールとは

USB クライアント ドライバー検証ツールは、Windows 8 に含まれる USB 3.0 ドライバー スタックの機能です。 検証ツールが有効になると、USB ドライバー スタックが失敗するか、クライアント ドライバーによって実行される特定の操作が変更されます。 これらのエラーは、見つけにくいエラー状態をシミュレートし、後で望ましくない結果を招く可能性があります。 シミュレートされた障害により、ドライバーが障害に適切に対処できることを確認する機会が得られます。 クライアントは、エラー処理コードを通じてエラーに対処することも、別のコード パスを実行することもできます。

たとえば、クライアント ドライバーは、一括エンドポイントの静的ストリームを介して I/O 操作をサポートします。 検証ツールを使用すると、さまざまなホスト コントローラーでサポートされているストリームの数に関係なく、ドライバーのストリーム ロジックが動作することを確認できます。 このシナリオをシミュレートするには、UsbVerifierStaticStreamCountOverride 設定を使用します (後で説明)。 ドライバーが USBD_QueryUsbCapability を呼び出して、ホスト コントローラーがサポートする静的ストリームの最大数を決定するたびに、ルーチンは異なる値を返します。

重要

USB クライアント ドライバー検証ツールは、さまざまな xHCI コントローラーに対してのみドライバーをテストします。 チェーンされた MDL サポートの欠如など、固有の 2.0 コントローラー動作の一部をシミュレートします。 ただし、クライアント ドライバーは USB 2.0 コントローラーでテストする必要があり、このツールをコントローラーの代替として使用しないことをお勧めします。

Windows ハードウェア ラボ キット (HLK) テストは、システム、USB ホスト コントローラー、ハブ、デバイスの追加のテストに使用できます。 これらのテストでは、基本的なデバイス機能、信頼性、および Windows との互換性について説明します。 詳細については、「USB の Windows ハードウェア ラボ キット (HLK) テスト」を参照してください。

USB クライアント ドライバー検証ツールを有効にする方法

USB クライアント ドライバー検証ツールを使用するには、Windows 8 を実行しているターゲット コンピューターでそれを有効にします。 ターゲット コンピューターには、USB デバイスが接続されている xHCI コントローラーが必要です。

USB クライアント ドライバー検証ツールは、クライアント ドライバーのドライバー検証ツールを有効にすると自動的に有効になります。 または、このレジストリ エントリを設定して、検証ツールを有効にすることもできます。

注意

Windows Driver Foundation (WDF) 検証ツール コントロール アプリケーション (WdfVerifier.exe) を有効にしても、USB クライアント ドライバー検証ツールは自動的に有効になりません。

HKEY_LOCAL_MACHINE
   SYSTEM
      CurrentControlSet
         services
            <Client Driver>
               Parameters
                  UsbVerifierEnabled (DWORD)

UsbVerifierEnabled レジストリ エントリは DWORD 値を受け取ります。 UsbVerifierEnabled が 1 の場合、USB クライアント ドライバー検証ツールが有効になります。0 では無効になります。 クライアント ドライバーでドライバー検証ツールが有効で、 UsbVerifierEnabled が 0 の場合、USB クライアント ドライバー検証ツールは無効になります。

USB クライアント ドライバー検証ツールの構成設定

検証ツールが有効になっている場合、USB ドライバー スタックは、クライアント ドライバーが割り当てる USBD_xxxUrbAllocate ルーチンを呼び出すことによって URB を継続的に追跡します (USB ルーチンを参照)。 クライアント ドライバーが URB をリークした場合、USB ドライバー スタックはその情報を使用して、ドライバー検証ツールによるバグチェックを実行します。 その場合、!usbanalyze -v コマンドを使用してリークの原因を特定します。

さらに、オプションで、特定のルーチンを変更または失敗するように USB クライアント ドライバー ベリファイアを構成し、ルーチンが失敗する頻度を指定できます。 検証ツールを構成するには、次のようにレジストリ エントリを設定します。

HKEY_LOCAL_MACHINE
   SYSTEM
      CurrentControlSet
         services
            <Client driver>
               Parameters
                  <USB client driver verifier setting> (DWORD)

<USB クライアント ドライバー検証ツール設定>レジストリ エントリは、DWORD 値を受け取ります。 設定を追加、変更、または削除する場合は、設定を適用するために、システムでデバイスを再列挙する必要があります。

次の表に、<USB クライアント ドライバー検証ツール>の設定で使用できる値を示します。 設定は、services キーで指定されたクライアント ドライバーに適用されます。

USB クライアント ドライバー検証ツールの設定 次の可能な値のいずれかを選択します。 シミュレートに使用...
UsbVerifierFailRegistration

クライアント ドライバーによる次のルーチンの呼び出しは失敗します。
  • 0: 設定は無効です。
  • 1: 呼び出しは常に失敗します。
  • N: 呼び出しは 1/N の確率で失敗します。ここで、N は 1 から0x7FFまでの 16 進値です。 たとえば、N が 10 の場合。 呼び出しは、10 回の呼び出しごとに 1 回失敗します。
 クライアント ドライバーの登録エラー。

クライアント ドライバーの初期化タスクの 1 つは、それ自体を基礎となるドライバー スタックに登録することです。 登録は、後続のいくつかの呼び出しで必要となります。

たとえば、クライアント ドライバーは登録のために USBD_CreateHandle を呼び出します。 ドライバーは、ルーチンが常に STATUS_SUCCESS を返すと想定し、失敗を処理するコードを実装していないとします。 ルーチンがエラー NTSTATUS コードを返した場合、ドライバーは誤ってエラーを無視し、無効な USBD ハンドルを使用して後続の呼び出しを続行する可能性があります。

この設定を使用すると、失敗したコード パスをテストできるように、呼び出しを失敗させることができます。

登録が失敗した場合に予想されるクライアント ドライバーの動作:

  • ドライバーは引き続き正常に機能するとは限りません。
  • ドライバーは、この障害を無視することを選択して、システムクラッシュを引き起こしたり、応答しなくなったりしてはなりません。
UsbVerifierFailChainedMdlSupport

呼び出し元が CapabilityType パラメーターに GUID_USB_CAPABILITY_CHAINED_MDLS を渡すと、クライアント ドライバーのこれらのルーチンの呼び出しが失敗します。
  • 0: 設定は無効です。
  • 1: 呼び出しは常に失敗します。
  • N: 呼び出しは 1/N の確率で失敗します。ここで、N は 1 から0x7FFまでの 16 進値です。 たとえば、N が 10 の場合。 呼び出しは、10 回の呼び出しごとに 1 回失敗します。
 チェーンされた MDL をサポートしていないホスト コントローラーとのコミュニケーション。

クライアント ドライバーがチェーンされた MDL (MDL を参照) を送信するには、USB ドライバー スタックとホスト コントローラーでサポートされている必要があります。

この設定を使用すると、クライアント ドライバーが連鎖 MDL 要求をサポートしていないホスト コントローラーに接続されているデバイスに送信するときに実行されるコードをテストできます。 ホスト コントローラーがチェーンされた MDL をサポートしているかどうかに関係なく、呼び出しは失敗します。

USB ドライバー スタックでのチェーンされた MDL のサポートの詳細については、「チェーンされた MDL を送信する方法」を参照してください。

ホスト コントローラーがチェーン MDL をサポートしていない場合に予期されるクライアント ドライバーの動作:

  • ドライバーは、チェーンされた MDL を使用せずに I/O 転送を実行し続ける必要があります。 これにより、USB 2.0 ホスト コントローラーはチェーン MDL をサポートしていないため、ドライバーがそれらのコントローラーで動作することも確認できます。
  • ドライバーは、この障害を無視することを選択して、システムクラッシュを引き起こしたり、応答しなくなったりしてはなりません。
UsbVerifierFailStaticStreamsSupport

呼び出し元が CapabilityType パラメーターに GUID_USB_CAPABILITY_STATIC_STREAMS を渡すと、クライアント ドライバーのこれらのルーチンの呼び出しが失敗します。
  • 0: 設定は無効です。
  • 1: 呼び出しは常に失敗します。
  • N: 呼び出しは 1/N の確率で失敗します。ここで、N は 1 から0x7FFまでの 16 進値です。 たとえば、N が 10 の場合。 呼び出しは、10 回の呼び出しごとに 1 回失敗します。
 静的ストリームをサポートしていないホスト コントローラーとのコミュニケーション。

クライアント ドライバーが一括エンドポイントの静的ストリームを通じて I/O 転送を送信するには、ホスト コントローラーがストリームをサポートしている必要があります。

ストリームをサポートしていないホスト コントローラーにデバイスが接続されており、ドライバーがストリーム I/O 転送を実行しようとすると、それらの転送は失敗します。 この設定を使用すると、このようなエラーが発生した場合にコードをテストできます。

ホスト コントローラーが静的ストリームをサポートしていない場合に予期されるクライアント ドライバーの動作:

  • クライアント ドライバーがストリームをサポートしていない xHCI コントローラーで動作する必要がある場合、デバイスはストリーム対応のバルク エンドポイントを使用せずに動作できる必要があります。
  • ドライバーは、この障害を無視することを選択して、システムクラッシュを引き起こしたり、応答しなくなったりしてはなりません。
UsbVerifierStaticStreamCountOverride

クライアントが GUID_USB_CAPABILITY_STATIC_STREAMS を使用してこれらのルーチンを呼び出すときに OutputBuffer パラメーターで受け取った値を変更します。

OutputBuffer 値は、ホスト コントローラーがサポートする静的ストリームの最大数を示します。
  • 0: 設定は無効です。
  • 1: 検証ツールは OutputBuffer 値をランダムに選択します。 この値は、OutputBuffer 値が繰り返されず、呼び出しがより多くのバリエーションでテストされるため、ストレス テストに役立ちます。
  • N: OutputBuffer 値を指定します。

    フラグが N 値で有効になっている場合、N は USB ドライバー スタックがサポートするストリームの最大数より小さくする必要があります。 したがって、このフラグを設定する前に、正常な呼び出しを通じて実際の値を取得しておく必要があります。

    N がストリームの最大数を超える場合、その設定は無視されます。
 さまざまなホスト コントローラーとのコミュニケーション。それぞれが異なる値の最大ストリーム数をサポートします。

この設定を使用すると、さまざまなホスト コントローラーでサポートされているストリームの数に関係なく、ドライバーのストリーム ロジックが動作することを確認できます。

I/O 転送に使用できるストリームの数は、ホスト コントローラーがサポートするストリームの数によって制限されます。

クライアント ドライバーで静的ストリームをサポートする方法については、「USB 一括エンドポイントで静的ストリームを開いたり閉じたりする方法」を参照してください。

ホスト コントローラーがサポートするストリームがエンドポイントよりも少ない場合に予期されるクライアント ドライバーの動作:

  • クライアント ドライバーは、少ない数のストリームでデータ転送を実行することを選択できます。
  • ドライバーは、この障害を無視することを選択して、システムクラッシュを引き起こしたり、応答しなくなったりしてはなりません。
UsbVerifierFailEnableStaticStreams

クライアント ドライバーのオープン静的ストリーム要求 (URB_FUNCTION_OPEN_STATIC_STREAMS) が失敗します。
  • 0: 設定は無効です。
  • 1: 要求は常に失敗します。
  • N: 要求は 1/N の確率で失敗します。ここで、N は 1 から0x7FFまでの 16 進値です。 たとえば、N が 10 の場合。 要求は 10 回の呼び出しごとに 1 回失敗します。


注:USBD_QueryUsbCapability または WdfUsbTargetDeviceQueryUsbCapability への以前の呼び出しが失敗した場合、オープン静的ストリーム要求は失敗します。		 静的ストリームをサポートしているが、他の理由により要求が失敗するホスト コントローラーとのコミュニケーション。

たとえば、デバイスはストリームをサポートするホスト コントローラーに接続されています。 クライアント ドライバーは、ホスト コントローラーでサポートされているストリームの最大数を超える数 (開くストリームの数) を含むオープン ストリーム要求を送信します。 USB ドライバー スタックは、このような要求に失敗します。

この設定を使用すると、オープン ストリーム要求エラーのエラー処理コードをテストできます。

オープンストリーム要求が失敗した場合に予想されるクライアント ドライバーの動作:

  • ドライバーは引き続き正常に機能するとは限りません。
  • ドライバーは、この障害を無視することを選択して、システムクラッシュを引き起こしたり、応答しなくなったりしてはなりません。