USB ハードウェア検証ツール (USB3HWVerifierAnalyzer.exe)
この記事では、特定のハードウェア・イベントのテストとデバッグに使用するUSBハードウェア検証ツール（USB3HWVerifierAnalyzer.exe）について説明します。
ハードウェアの問題の多くは、エンドユーザー体験の低下につながる形で現れ、正確な障害を特定するのは難しいことが多い。 USBハードウェア・ベリファイアーは、デバイス、ポート、ハブ、コントローラー、またはそれらの組み合わせで発生するハードウェア障害を捕捉することを目的としています。
USBハードウェアベリファイアは、これらのタスクを実行することができます：
- ハードウェアイベントをキャプチャし、リアルタイムで情報を表示します。
- すべてのイベントに関する情報を含むトレース・ファイルを生成する。
- イベント情報のために既存のトレースファイルを解析する。
この記事は、次のセクションで構成されています。
USB ハードウェア検証アナライザー ツールの入手
The USB hardware verifier tool is included with the MUTT software package that is available for download at Tools in the MUTT software package.
ツール パッケージには、ストレス テストと転送テスト (電源遷移を含む) および SuperSpeed テストを実行するいくつかのツールが含まれています。 パッケージにはReadme文書もある（別途ダウンロード可能）。 この資料では、MUTTハードウェアの種類を簡単に紹介しています。 実行すべきさまざまなテストについてステップバイステップのガイダンスを提供し、コントローラ、ハブ、デバイス、BIOS/UEFIテストのトポロジーを提案します。
USBハードウェア・ベリファイアを使用してイベントをキャプチャする方法
ハードウェア検証機を使用してイベントをキャプチャするには、以下の手順を実行する：
昇格コマンドプロンプトでこのコマンドを実行してセッションを開始する。
USB3HWVerifierAnalyzer.exeこのツールは以下のオプションをサポートしている：
オプション 説明 -v <VendorID> 指定した VendorID のすべてのハードウェア検証イベントをログに記録します。 -p <ProductID> 指定した ProductID のすべてのハードウェア検証イベントをログに記録します。 -f <ETL file> 指定されたETLファイルを解析します。 リアルタイム解析はサポートされていない。 このオプションでは、ツールはオフラインでファイルを解析する。 /v output すべてのイベントをコンソールに表示する。 ハードウェアイベントをキャプチャするテストシナリオを実行します。
セッション中、USBハードウェアベリファイアは、発生したハードウェアイベントに関する情報をキャプチャします。 特定のハードウェアのイベントをフィルタリングしたい場合は、ハードウェアのVendorIdとProductIdを指定します。 ツールは、デバイスが完全に列挙される前に発生したイベントに関するいくつかの情報（VID/PIDなど）を捕捉しない可能性がある。 不足している情報は、セッション終了時に作成される詳細レポートで確認できる（次で説明）。
Note
AllEvents ETLファイルには、常にすべてのデバイスのすべてのETWイベントが含まれます。 -v および -p スイッチの影響を受けません。
VendorId と ProductId でフィルターするコマンド ラインは次のとおりです。
USB3HWVerifierAnalyzer.exe -v 0781 -p 5595ハードウェア検証ツールからの出力例を次に示します。
Session Name : TraceSessionFriJan271351112023 Attempting to start session TraceSessionFriJan271351112023... Trace Session created...Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 13319329877.425596: (UsbHub3/179) Event Message: Client Initiated Recovery Action VendorID/ProductID: 0x5e3/0x612 DeviceInterfacePath: \??\USB#VID_05E3&PID_0612#6&130491ac&0&4#{f18a0e88-c30c-11d0-8815-00a0c906bed8} DeviceDescription: Generic SuperSpeed USB Hub PortPath: 0x12, 0x4, 0x0, 0x0, 0x0, 0x0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Session Stopped...Status : 0CTRL+C を押してセッションを停止します。
セッションの終了時に、AllEvents.etl という名前のファイルが現在のディレクトリに追加されます。 このファイルには、セッション中にキャプチャされたすべてのイベントに関するトレース情報が含まれています。
AllEvents.etl に加えて、コマンド ウィンドウにはレポートが表示されます。 レポートには、リアルタイム出力では欠落していた特定の情報が含まれています。 次の出力は、前のセッションのテスト レポートの例を示しています。 レポートには、USB ハードウェア検証ツールが発生したすべてのイベントが表示されます。
Record #1 (Key = 0x57ff0de4858) VendorID/ProductID: 0x451/0x2077 DeviceInterfacePath: \??\USB#VID_0451&PID_2077#6&c4be011&0&2#{f18a0e88-c30c-11d0-8815-00a0c906bed8} DeviceDescription: Generic USB Hub PortPath: 0x2, 0x0, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/176): DescriptorValidationError20HubPortPwrCtrlMaskZero #2: (UsbHub3/179): Client Initiated Recovery Action #3: (UsbHub3/179): Client Initiated Recovery Action #4: (UsbHub3/179): Client Initiated Recovery Action #5: (UsbHub3/179): Client Initiated Recovery Action #6: (UsbHub3/179): Client Initiated Recovery Action #7: (UsbHub3/179): Client Initiated Recovery Action #8: (UsbHub3/179): Client Initiated Recovery Action #9: (UsbHub3/179): Client Initiated Recovery Action #10: (UsbHub3/179): Client Initiated Recovery Action #11: (UsbHub3/179): Client Initiated Recovery Action #12: (UsbHub3/179): Client Initiated Recovery Action #13: (UsbHub3/179): Client Initiated Recovery Action #14: (UsbHub3/179): Client Initiated Recovery Action Record #2 (Key = 0x57ff62a36a8) VendorID/ProductID: 0x1058/0x740 DeviceInterfacePath: \??\USB#VID_1058&PID_0740#57583931453631414E5A3331#{a5dcbf10-6530-11d2-901f-00c04fb951ed} DeviceDescription: USB Mass Storage Device PortPath: 0x2, 0x4, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/173): SuperSpeed Device is Connected on the 2.0 Bus Record #3 (Key = 0x57ff79fd4e8) VendorID/ProductID: 0x1edb/0xbd3b PortPath: 0x3, 0x0, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #2: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #3: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #4: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #5: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #6: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #7: (UsbHub3/176): DescriptorValidationErrorStringMismatchBetweenBlengthAndBufferLength #8: (UsbHub3/176): DescriptorValidationErrorStringMismatchBetweenBlengthAndBufferLength前述のレポート例では、各レコードの Key フィールドの値に注目してください。 レポートは、これらの Key 値によって情報を分類し、読みやすくしています。 AllEvents.etl でキャプチャされたイベントでは、同じ Key 値が使用されます。
次のコマンドを実行して、AllEvents.etl をテキスト形式に変換します。
USB3HWVerifierAnalyzer.exe -f AllEvents.etl /v > Output.txt出力ファイルで、以前に記録した Key 値を検索します。 The values are associated with one of these fields: fid_UcxController, fid_HubDevice, and fid_UsbDevice.
Open AllEvents.etl in Netmon and select Add <field_name> to display filter to filter events by controller, hub, and device. 詳細については Netmon および USB ETW パーサーのインストール方法を参照してください。
USBハードウェア検証フラグ
| フラグ | ...であることを示す。 |
|---|---|
| DeviceHwVerifierClientInitiatedResetPipe | クライアント・ドライバは、I/O障害に応じて特定のパイプをリセットすることで、リカバリ動作を開始した。 特定のクライアント・ドライバは、他のシナリオでエラー回復を実行するかもしれない。 |
| DeviceHwVerifierClientInitiatedResetPort | クライアント・ドライバは、I/O障害に応答してデバイスをリセットすることで、リカバリ動作を開始した。 特定のクライアント・ドライバは、他のシナリオでエラー回復を実行するかもしれない。 |
| DeviceHwVerifierClientInitiatedCyclePort | クライアント・ドライバは、ポートを循環させることでリカバリ動作を開始した。 このフラグにより、Plug and Play Managerはデバイスを再列挙する。 |
| DeviceHwVerifierSetIsochDelayFailure | USB3.0デバイスがSET_ISOCH_DELAYリクエストに失敗した。 デバイスがリクエストに失敗するのは、ドライバがリクエスト情報を必要とし ていないか、一時的なエラーが発生したかのどちらかである。 しかし、ドライバーはそれらの理由を区別することができない。 このエラーはレポートには含まれていない。 |
| DeviceHwVerifierSetSelFailure | USB 3.0 デバイスが SET_SEL 要求に失敗した。 デバイスはリンク・パワー・マネージメント（LPM）の要求情報を使用する。 デバイスがリクエストに失敗するのは、ドライバがリクエスト情報を必要とし ていないか、一時的なエラーが発生したかのどちらかである。 しかし、ドライバーはそれらの理由を区別することができない。 このエラーはレポートには含まれていない。 |
| DeviceHwVerifierSerialNumberMismatchOnRenumeration | デバイスが、最初の列挙時に報告したシリアル番号とは異なるシリアル番号を再列挙時に報告した。 再列挙は、リセット・ポートやシステムのレジューム操作の結果として起こりうる。 |
| DeviceHwVerifierSuperSpeedDeviceWorkingAtLowerSpeed | USB3.0デバイスはSuperSpeedより低いバス速度で動作している。 |
| DeviceHwVerifierControlTransferFailure | デバイスのデフォルトエンドポイントへの制御転送に失敗した。 デバイスやコントローラのエラーにより、転送が失敗することがある。 ハブのログには、転送失敗のUSBDステータスコードが表示されます。 このフラグは、SET_SEL および SET_ISOCH_DELAY 制御転送の失敗を除く。 これらのタイプのリクエストは、DeviceHwVerifierSetIsochDelayFailureと DeviceHwVerifierSetSelFailureフラグによってカバーされる。 |
| DeviceHwVerifierDescriptorValidationFailure | デバイスから返されたディスクリプタがUSB仕様に適合していない。 ハブログには正確なエラーが記録されている。 |
| DeviceHwVerifierInterfaceWakeCapabilityMismatch | デバイスのRemoteWakeビットが正しく設定されていない。 リモートウェイクをサポートするUSB 3.0デバイスは、ファンクションウェイクもサポートする必要があります。 デバイスがファンクション・ウェイクをサポートしていることを示す方法は2つある。 最初の方法は、コンフィギュレーション記述子の bmAttributes フィールドを介する方法であり、2つ目の方法は、インターフェースを対象としたGET_STATUSリクエストに対する応答である。 非複合デバイスの場合、RemoteWakeビットの値は、インターフェイス0をターゲットとするGET_STATUSリクエストによって返される値と一致しなければならない。 コンポジット・デバイスの場合、RemoteWakeビットは少なくとも1つのファンクションで1でなければならない。 そうでない場合、このフラグは、デバイスがここで矛盾した値を報告したことを示す。 |
| DeviceHwVerifierBusRenumeration | デバイスはバス上で再認識される。 再列挙は、リセット・ポートやシステムのレジューム操作の結果として起こりうる。 再列挙は、デバイスの無効化/有効化、停止/起動時にも行われる。 |
| HubHwVerifierTooManyResets | あるハブが短期間にあまりにも多くのリセット作業を経験した。 リセットが成功しても、ハブはリクエストを処理できず、エラーが繰り返される。 |
| HubHwVerifierControlTransferFailure | ハブのデフォルト・エンドポイントを対象とした制御転送に失敗した。 デバイスやコントローラのエラーにより、転送が失敗することがある。 ハブのログには、障害の USBD ステータスコードが表示されます。 |
| HubHwVerifierInterruptTransferFailure | ハブの割り込みエンドポイントを対象としたデータ転送が失敗した。 デバイスやコントローラのエラーにより、転送が失敗することがある。 ハブのログには、障害の USBD ステータスコードが表示されます。 リクエストがキャンセルされたために転送が失敗した場合、その失敗は捕捉されない。 |
| HubHwVerifierNoSelectiveSuspendSupport | ハブのコンフィギュレーション記述子で、RemoteWake ビットが 1 に設定されていない。 |
| HubHwVerifierPortResetTimeout | デバイスの列挙または再列挙中に、ポートリセットの操作がタイムアウトしている。ポートリセットの完了を示すポート変更通知を受信していない。 |
| HubHwVerifierInvalidPortStatus | ターゲット・ポートのポート・ステータスがUSB仕様に従って有効でない。 デバイスによっては、ハブが無効なステータスを報告することがあります。 |
| HubHwVerifierPortLinkStateSSInactive | ターゲットポートとダウンストリームデバイス間のリンクがエラー状態。 |
| HubHwVerifierPortLinkStateCompliance | ターゲットポートとダウンストリームデバイス間のリンクがコンプライアンスモードになっている。 システム・スリープ再開を含むいくつかのシナリオでは、コンプライアンス・モード・エラーは予期されるものであり、そのような場合、失敗は捕捉されない。 |
| HubHwVerifierPortDeviceDisconnected | ターゲットポートのダウンストリームデバイスがバスに接続されていない。 |
| HubHwVerifierPortOverCurrent | ダウンストリームポートが過電流状態を報告した。 |
| HubHwVerifierControllerOperationFailure | ターゲットポートに接続されているデバイスのコントローラ操作（デバイスの有効化、エンドポイントの設定など）に失敗しました。 SET_ADDRESSとResetエンドポイントリクエストによる失敗は捕捉されない。 |
関連トピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示