jetson-customize-usb

USB のカスタマイズ（ポートごとの有効化／無効化／ロール設定）

目的

Jetson Thor（Tegra264）または Orin（Tegra234）のカスタムキャリア上で、USB2／USB3 SS ポートを有効化、無効化、またはロール変更します。ポートごとの配線（ロール、最大速度、VBUS-EN／OC GPIO、Type-C 用 CC1／CC2 GPIO、USB3 SS UPHY レーン）を取得し、ツリー内の DTB から SS と USB2 コンパニオンのグラフを解決したうえで、すべてのポート操作を3か所（レーンのステータス、ポートのステータス、ホスト xHCI の phys + phy-names）で連動して切り替える、自己完結型のカーネル DT オーバーレイを生成します。

UPHY レーンの割り当ては jetson-customize-uphy が担当します。ODMDATA は編集しません。出力は、bsp_sources/ ハードウェアリポジトリ内の複合カスタムオーバーレイ .dts に対する1つのコミットです。

前提条件

• reference_devkit: と custom_carrier: ブロックを含むアクティブなプロファイル。
• <source.root_path>/Linux_for_Tegra/.git が存在する （/jetson-init-source）。
• /jetson-derive-carrier が実行済みであること — オーバーレイトラッカー内にキャリアのフラッシュ設定のフォークがあること。
• 有効にする USB3 SS ポートで、標準とは異なる UPHY レーン割り当てが必要な場合は、/jetson-customize-uphy が実行済みであること。その JSON サイドカー <workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json を参照して SS レーンの割り当てを確認します。
• 正式な参照ドキュメント：Adaptation Guide §「Universal Serial Bus の移植」、Module Design Guide §USB、SoC TRM（xusb ブロック）。
• custom_carrier: が存在する場合、documents.custom_carrier_schematic と documents.custom_carrier_pinmux_xls の両方が必須です。 いずれかが欠けている場合は実行を拒否します。カスタムキャリア上のポートごとの配線（VBUS-EN／OC／CC GPIO、SS レーン配線、ハブの分岐）は推測できません。リファレンス開発キットのみのプロファイルでは、このチェックをスキップします。
• PATH 上に dtc と fdtoverlay があること。

概要

Tegra の USB は、3つの IP 領域にまたがっています。xusb_padctl ブロック（USB2 OTG + USB3 SS PHY）、tegra-xusb xHCI ホストコントローラー、および単一の OTG 対応 USB2 ポート（usb2-0）に接続されるオプションの tegra-xudc デバイスコントローラーです。

ポートごとの切り替えでは、カーネル DT の3か所を必ず連動して変更する必要があります。 これらがすべてそろっていないと、ホスト xHCI のプローブが失敗し、すべてのポートで lsusb の結果が空になります（標準状態で動作するポートにも影響します）。

#	箇所	パス	制御対象
1	レーン（PHY プロバイダー）	xusb_padctl/pads/usb<2|3>/lanes/usb<2|3>-N	SS／OTG PHY のハードウェアバインディングです。status="disabled" にすると、レーンは PHY を提供しなくなります。
2	ポート（コントローラーバインディング）	xusb_padctl/ports/usb<2|3>-N	ポートごとのモード（host/device/otg）、コンパニオンリンク、VBUS／OC／CC ピン参照です。status="disabled" にすると、ポートはユーザー向けトポロジーから削除されます。
3	ホスト xHCI の phys リスト	bus@0/usb@<addr>.phys + .phy-names	xHCI ドライバーが反復処理する、phandle と名前の配列です。無効な PHY への参照は -ENODEV を返し、ホスト全体のプローブを中断します。

NVIDIA の標準 DTB で無効化されている Thor の usb3-3 は、3か所すべてを連動して切り替える標準的なパターンです。

3か所を変更するパターンには、さらに2つのルールが適用されます。

• ルール A — レーンとポートのペア。 レーン（箇所1）と対応するポート（箇所2）は、必ず一緒に切り替える必要があります。
• ルール B — コンパニオンの連鎖。 xusb_padctl/ports/usb3-N.nvidia,usb2-companion は USB2 ポートの phandle を参照します。その USB2 ポートを無効化するときに、SS コンパニオンにも連鎖して切り替えない場合、tegra-xusb: failed to enable PHYs: -19 が発生します。

エージェントによる実行であり、テーブル駆動ではありません — すべてのポート、コントローラー、レーン、コンパニオンリンク、phandle、__symbols__ の検索は、ドキュメント、DTB、キャリアのピンマップ、回路図から実行時に解決されます。

呼び出すタイミング

• ユーザーが「USB を有効にする」「USB ハブを無効にする」「USB3 SS を設定する」「USB のロールを設定する」「VBUS-EN を配線する」「tegra-xusb / xudc / dr_mode」などと言った場合、またはカスタムキャリア上の USB コントローラーを起動／停止するよう求めた場合。
• フラッシュ後にキャリア上の USB レセプタクルでデバイスが列挙されない場合、または以前の jetson-customize-usb の実行後に USB 全体に影響する問題（lsusb の結果が空）が発生し、修正が必要な場合。
• jetson-customize-uphy によって USB3 SS ポートに影響する UPHY レーンが再割り当てされ、ポートごとの DT もそれに合わせる必要がある場合。

手順（概要）

詳細な手順は references/procedure.md にあります。

1. ステップ 1 — アクティブなターゲットを特定し、信頼できる参照元のドキュメントを開きます。
2. ステップ 2 — ツリー内の DTB から USB トポロジーとコンパニオングラフを構築します。
3. ステップ 3 — 有効化／無効化するポートを AskUserQuestion で確認します。コンパニオンの連鎖動作とキャリアボード上のハブの分岐を明示します。
4. ステップ 4 — ポートごとに検証（モジュール＋キャリアボード＋UPHY レーン）し、配線を記録します（pin_verifier.py を使用して VBUS-EN／OC／CC GPIO を確認）。
5. ステップ 5 — 3 箇所のパターンを使用してカーネル DT オーバーレイを生成し、フラグメント（usb:padctl、usb:xhci、任意の usb:xudc）を複合カスタムオーバーレイ .dts に追加して、fdtoverlay と 3 つのマージ後の不変条件チェックを実行し、bsp_sources/ にコミットします。
6. ステップ 6 — 実行状態 JSON サイドカー（形式は references/run-state-sidecar.md）を書き込み、見出しを出力した後、references/procedure.md のステップ 6 に従い、AskUserQuestion のプロンプトを順番に提示して後続の次のステップへ進めます。プロンプトの代わりに「次のステップ: …」という行を出力してはいけません。

重大な失敗要因については references/gotchas.md を参照してください。

制限事項

• カーネル DT オーバーレイのみを担当します。ODMDATA ではポートごとの USB status ノブを公開していないため、編集しないでください。
• UPHY レーンは割り当てません。割り当ては jetson-customize-uphy が担当します。uphy の実行状態でレーンが割り当て済みと確認できるまで、SS の有効化をコミットしてはいけません。
• pinmux DTSI を直接変更しません。SFIO の不一致は /jetson-customize-pinmux set-pin に引き継ぎます。
• .dtbo のコンパイルや OVERLAY_DTB_FILE+= の登録は行いません。ビルドとフラッシュ設定への登録は /jetson-build-source が担当します。
• Tegra プラットフォームの不変条件：OTG に対応するのは usb2-0 のみで、xudc はそこにのみ接続します。他のすべての USB2 ポートと USB3 SS ポートはホスト専用です。

トラブルシューティング

• すべてのポートで lsusb が空なのに、192.168.55.1 の USB イーサネットはまだ動作している： ホスト xHCI が停止しています。3 箇所の同期が崩れています。マージ後の DTB を調べ、references/procedure.md のステップ 5d にあるマージ後の不変条件を確認してください。
• tegra-xusb: failed to enable PHYs: -19： コンパニオンの連鎖動作（ルール B）に違反しています。SS のコンパニオンを無効化せずに USB2 を無効化しています。
• no port found または Requested PHY is disabled： ルール A に違反しています。レーンのステータスとポートのステータスが一致していません。
• fdtoverlay からの FDT_ERR_NOTFOUND： フラグメントで、__symbols__ にラベルがないノード（ホスト xHCI／tegra-xudc によくあるケース）に target = <&label> を使用しています。target-path = "/bus@0/usb@<addr>" に切り替えてください。
• dtc 警告 phys_property: cell 0 is not a phandle reference： 問題ありません。ホストの phys オーバーライドで生の整数 phandle を使用した場合に想定される警告です。
• ポートは起動するが、VBUS が一度もアサートされない： vbus-supply が、存在しない親ノードのレギュレーターを参照しています。参照する前に、固定レギュレーターノードが存在することを確認してください。
• 起動時に xHCI が誤ったポートをバインドする： ホストの phys 要素の順序が保持されていません。無効なエントリーのみを省略し、有効なエントリーの順序は変更しないでください。

参考資料

• references/procedure.md — 手順の全ステップを記載しています。
• references/gotchas.md — 影響の大きい失敗要因を記載しています。
• references/run-state-sidecar.md — 実行状態 JSON の形式を記載しています。
• references/usb-architecture.md — Tegra USB IP アーキテクチャに関する 注記（xusb_padctl、tegra-xusb、xudc）を記載しています。
• references/usb-dt-bindings.md — USB DT バインディングのチートシート （レーン／ポート／phys-list の形式）を記載しています。
• ../../scripts/pin_verifier.py — 共有 HSIO ピン検証ツールです。
• ../../references/platform_template.yaml — Step 1 で 使用される documents: ブロックです。
• ../../context/bsp-customization-workflow.md — オーバーレイ編集 プロトコルです。
• ../../references/bsp-customization-kernel-dtb.md — 複合 オーバーレイ追加プロトコルです。
• ../jetson-customize-uphy/SKILL.md — UPHY レーン割り当てを担当する 関連スキルです。
• ../jetson-customize-pinmux/SKILL.md — VBUS-EN／OC／CC SFIO の修正を行う 関連スキルです。
• ../jetson-derive-carrier/SKILL.md — 最初に実行する必要があります。
• ../jetson-init-source/SKILL.md — オーバーレイトラッカーと bsp_sources リポジトリを生成します。