USBエンドポイントHALT復旧：CLEAR_FEATURE、STALLループ、バルク失敗、ドライバリセット挙動

USBエンドポイントHALTは「1回は動くがその後失敗する」系のバグの定番です。バルク転送がストールし、ドライバがHALTをクリアし、デバイスが再びストール、最終的にアプリが「タイムアウト」「I/Oエラー」「デバイスリセット」「切断」を報告する。デバイスは消えないものの、特定エンドポイントでのトラフィック受付を止めてしまう——そんなときに USB endpoint halt、CLEAR_FEATURE ENDPOINT_HALT、USB STALL loop、bulk endpoint stalled、libusb clear halt といった検索がされます。

Bus Scopeが効くのは、エンドポイントHALTの復旧が「シーケンス」であり、単発のイベントではないからです。最初のSTALL、ホストの復旧リクエスト、その後のデバイスの挙動、そして同じコマンドで再度ストールしていないかを見る必要があります。

エンドポイントHALTの意味

HALT状態とは、エンドポイントがストールしており、HALT状態がクリアされるまで通常の転送ができない、ということです。ホストは次を発行できます。

CLEAR_FEATURE(ENDPOINT_HALT)

対象エンドポイントに対して。クリア後も、エンドポイントのdata toggleとデバイス側の状態が一貫していないと、転送が正しく再開しません。

ファームウェアがUSBハードウェアフラグだけクリアして内部プロトコル状態を直さないと、次の転送も失敗します。

STALL vs タイムアウト

STALLは明示的。タイムアウトは「期待時間内に完了しなかった」ことを意味します。タイムアウトの原因は、エンドポイントが応答しない／デバイスがNAKし続ける／デバイスが切断した、のいずれかです。

HALT復旧の出発点はSTALLです。ホストがSTALLを見ずにタイムアウトばかり見るなら、復旧パスは別の話になります。

バルクエンドポイントのHALT

バルクエンドポイントは、コマンドが不正、プロトコルフェーズが誤り、ファームウェアがエラーを検出したときなどにHALTしがちです。

例：

Host -> Device bulk OUT command
Device -> Host STALL on bulk IN
Host -> Device CLEAR_FEATURE(ENDPOINT_HALT)
Host retries bulk IN
Device stalls again

このパターンは、HALTが単なる一時的なバスエラーではなく、デバイスプロトコル状態の症状であることを示しています。

復旧はエンドポイントの方向と一致させる必要がある

エンドポイントアドレスには方向があります。エンドポイント 0x81 と 0x01 は方向が違うので別物。誤ったエンドポイントをクリアしても、ストールしたパイプは復旧しません。

確認ポイント：

• どのエンドポイントがストールしたか？
• INかOUTか？
• ホストは同じエンドポイントをクリアしたか？
• クリア後に転送が再開したか？
• data toggle／状態が正しく復旧したか？

これは「clear haltが効かない」報告が誤解のもとになる定番ポイントです。

繰り返されるSTALLループ

クリア後もSTALLが繰り返されるなら、根本原因が残っています。

• ホストが未対応のコマンドを再送している
• ファームウェアのステートマシンがエラーのまま
• デバイスがリトライ前にリセットを期待している
• ホストが誤ったエンドポイントから読んでいる
• コマンド長やチェックサムが間違っている
• エンドポイントのdata toggle／状態に不整合
• ファームウェアが再開前にクラス／ベンダーリクエストを要する

トレースには、復旧試行だけでなく、最初のSTALLの直前のコマンドも残しておいてください。

ドライバのリセット挙動

Clear-HALT復旧に失敗すると、ドライバはデバイスをリセットすることがあります。これで本来のエンドポイントエラーが覆い隠されます。ユーザーの目には再接続やデバイス消滅しか見えませんが、バスの証拠を見れば、最初の失敗はSTALLループだったと分かります。

保全すべきタイムライン：

1. 最後の成功コマンド
2. 最初のSTALL
3. Clear halt試行
4. リトライ
5. 再STALLまたはタイムアウト
6. デバイスリセットまたは切断

デバッグチェックリスト

次の流れで作業すると、原因に早くたどり着けます。

1. ストールしたエンドポイントを特定する
2. エンドポイントの方向と転送種別を記録する
3. STALL直前のコマンド／転送を確認する
4. ホストが CLEAR_FEATURE(ENDPOINT_HALT) を送ったかを確認する
5. 正しいエンドポイントを対象としているかを確認する
6. 転送が再開したかを確認する
7. STALLが再発するならファームウェアプロトコル状態を確認する
8. 復旧失敗後にデバイスリセットが走っていないか確認する
9. 既知の正常なコマンドシーケンスと比較する
10. STALLの前に十分なコンテキストを残しておく

最終的な診断

USBエンドポイントHALTの復旧は「ステートマシン」の問題です。CLEAR_FEATURE(ENDPOINT_HALT) はUSBエンドポイント状態をクリアしますが、ファームウェアのプロトコル状態、不正コマンド、誤エンドポイント、ドライバのリトライ論理までは自動で直してくれません。

Bus ScopeはHALTと復旧シーケンス全体を可視化するので、エンドポイント失敗を「実際のUSB挙動」から診断できます。