USBファームウェアデバッグワークフロー：列挙失敗から証拠へ
ディスクリプタ・エンドポイント・コントロール転送・キャプチャの証拠を確保してからコード修正に進む、ファームウェアエンジニア向け実践的USBデバッグワークフロー。
USBファームウェアのバグは高くつきます。見える症状があいまいだからです。「Windowsがデバイスディスクリプタリクエストに失敗したと言う」「Linuxがリセットループをログする」「HIDレポートが何かおかしい」「バルクエンドポイントが負荷時にストールする」——こんな文言に集約されがち。Bus Scopeは、ディスクリプタ・エンドポイント挙動・ホストドライバの前提を書き換える前に、ファームウェアチームがバスレベルの証拠を集めるためのローカルワークフローを提供します。
このページは、Bus Scopeを使ったUSBデバッグの出発点です。最初に何をキャプチャするか、どの失敗境界が重要か、ハードウェアラボにケースを送る前にソフトウェアUSBアナライザで十分か——その判断に使ってください。
ワークフロー
| ステップ | 証明すること | 取得する証拠 |
|---|---|---|
| 1. 列挙を確認する | ホストはディスクリプタを要求し、受理したか？ | デバイス／コンフィギュレーション／インターフェース／エンドポイント／HID／CDC／BOS／文字列／ステータスの証拠 |
| 2. エンドポイントゼロを観察する | コントロール転送はクリーンに完了したか？ | Setupパケットのフィールド、データステージ長、ステータスステージ、STALL、タイムアウト、ZLP挙動 |
| 3. クラス挙動を確認する | 提示されたクラス挙動はトラフィックと整合しているか？ | HIDレポート、CDCラインコーディング、Mass Storage BOT、UVC Alternate Setting、ベンダー固有リクエスト |
| 4. トランスポートのタイミングを切り分ける | エンドポイントは遅いのか、HALTしているのか、帯域過剰か？ | バルクタイムアウト、インタラプトポーリング、アイソクロナスギャップ、bInterval、最大パケットサイズ、帯域変化 |
| 5. ケースを保存する | 別のエンジニアが同じ証拠を再オープンできるか？ | Bus Scope .bscope セッション、レポートエクスポート、要点メモ |
列挙の証拠から始める
ドライバが読み込まれる前にデバイスが失敗するなら、USBデバイス列挙失敗から入ってください。最初のキャプチャポイント——リセット、アドレス割り当て、ディスクリプタ読み取り、コンフィギュレーション選択、ファームウェア応答とホストポリシーの境界——をカバーしています。
WindowsがCode 43や「device descriptor request failed」を報告するなら、列挙ワークフローとWindows USBデバイスディスクリプタリクエスト失敗を組み合わせてください。意味のある問いは「Windowsが不満かどうか」ではなく、「バスが短いディスクリプタ／不正な長さ／繰り返されるリセット／無応答のどれを示しているか」です。
ファームウェアを変更する前にエンドポイントゼロを観察する
エンドポイントゼロは、多くのファームウェアバグが顕在化する場所です。Setup／DATA／STATUSのどこかで失敗するならUSBコントロール転送STALLのデバッグ、データに問題がないのに完了しないならUSBコントロール転送ステータスステージのデバッグを活用してください。
Bus Scopeは、Setupフィールド・方向・リクエスト種別・Value・Index・Length・生バイト・ステータス・デコーダ出力を同じローカルビューにまとめます。これが「別のファームウェアビルドを試す」と「ホストは64バイト要求、デバイスは18バイト返却、その後次をストール」の差です。
ディスクリプタとクラス挙動を結びつける
ディスクリプタは単なる事務作業ではなく、どのドライバがバインドされ、ホストがデバイスの能力をどう信じるかを左右します。HID／CDCデバイスについては、HID／CDC向けUSBディスクリプタのデバッグ、USB HIDフィーチャーレポートのデバッグ、USB CDC ACMシリアルのデバッグを読んでください。
複合デバイスには特別な注意が必要です。USB複合デバイスのデバッグとUSB複合デバイスの誤ドライババインドで、アプリコードが走る前にインターフェース番号・IAD・クラスコード・エンドポイント配置がドライバ結果をどう変えるかを説明しています。
エンドポイントのタイミングと復旧を確認する
列挙は成功したのに転送が後段で失敗するなら、エンドポイントの証拠へ移ります。USBエンドポイントSTALLとバルク転送タイムアウトとUSBエンドポイントHALT復旧が、CLEAR_FEATURE／ストールしたバルクパイプ／リトライループの最初の止まり木です。
タイミングに敏感なデバイスでは、USBインタラプトエンドポイントのbIntervalデバッグとUSBアイソクロナス転送のドロップアウトを使ってください。これらは、ポーリング間隔／Alternate Setting／帯域／パケットサイズ挙動を証明するまで「ファームウェアの不安定」に見えることが多いです。
適切なアナライザ経路を選ぶ
Bus Scopeは日常のファームウェア／ドライバ作業向けの、フォーカスされたソフトウェアアナライザです。USBアナライザソフト比較、Bus Scope vs WiresharkとUSBPcap、ソフトウェアUSBアナライザ vs ハードウェアアナライザが、ソフトウェアに留まるべき場面と物理層ハードウェアへエスカレーションする場面を分けてくれます。
すでにWiresharkを使っているチームには、WiresharkでUSBPcapとusbmonを使ったUSBフィルタも有用です。Bus Scopeはパケット知識を捨てさせるものではなく、ファームウェアチームの日々の必要に応じたUSB中心の構造を提供します。
セットアップと次のステップ
ローカルキャプチャを始めるにはBus Scope接続ヘルプを、Linux usbmon／Windows USBPcapの準備確認にはBus Scopeプラットフォーム別キャプチャ設定を参照してください。より広いコンテンツはBus Scopeブログ一覧からどうぞ。