jetson-customize-uphy

UPHY レーン割り当てのカスタマイズ

目的

Jetson カスタムキャリアで UPHY レーン割り当てを選択し、キャリア用 flash-conf フォークの ODMDATA="..." を編集して、選択した uphyX-config-N トークンを適用します（uphy0-config-6 に必要な UPHY_CONFIG="" のクリアも含みます）。コントローラーごとのカーネル DT との整合はここでは行いません。ODMDATA のコミットが適用された後、このスキルはコントローラーごとのスキル（/jetson-customize-pcie、/jetson-customize-mgbe、/jetson-customize-usb）を呼び出します。各スキルは、選択した割り当てをリファレンスカーネル DTBとノード単位で比較し、K-stock の値が選択した割り当てと異なる場合にのみオーバーレイフラグメントを出力します。調査はエージェント主体で行います。オプション、レーン、コントローラーは、実行時に Adaptation Guide、キャリアの回路図、Module / SoC TRM から取得し、ハードコードはしません。ユーザーに表示する各ステップでは、データを Markdown テーブルとして表示し、最終サマリーには変更内容のサマリーテーブルを含めます。

前提条件

• reference_devkit: と custom_carrier: を含むアクティブなターゲットプラットフォームプロファイル。
• <source.root_path>/Linux_for_Tegra/.git が初期化済み（/jetson-init-source）。
• キャリア用フォークの conf が存在する（/jetson-derive-carrier）。
• documents.adaptation_guide -> documents.bsp_developer_guide -> Web 取得 -> Step-1 プロンプトのフォールバックを通じて、Adaptation Guide にアクセスできること。
• custom_carrier: が存在する場合は、documents.custom_carrier_schematic と documents.custom_carrier_pinmux_xls の両方が必須です。 いずれかが欠けていると、このスキルは実行を拒否します。カスタムキャリアのルーティングは推測できないためです。リファレンス開発キットのみのプロファイル（custom_carrier: ブロックなし）では、これらは不要です。

概要

UPHY（unified PHY）は、Tegra264（Thor）と Tegra234（Orin）で共有される高速 PHY プールです。レーン割り当ては ODMDATA トークン（uphy0-config-N、Thor では uphy1-config-N も使用）で選択します。これらのトークンはフラッシュ時に tegraflash_impl_t264.py::tegraflash_update_bpmp_dtb() によって解析され、BPMP DTB の /uphy/uphy{0,1}-config に書き込まれます。

出力は <source.root_path>/Linux_for_Tegra/ 内で行う単一のアトミックな ODMDATA コミットです。このコミットには、選択した uphyX-config-N トークン、UPHY_CONFIG="" のクリア（uphy0-config-6 の場合）、および選択した割り当てから導出されるすべてのコントローラーごとの ODMDATA トークン（pcie@N_status=*、mgbeN-speed-*、USB SS のポートごとのトークン）が含まれます。サブスキル（/jetson-customize-pcie、/jetson-customize-mgbe、/jetson-customize-usb）が担当するのはカーネル DT オーバーレイフラグメントのみです。これらは ODMDATA を変更してはなりません。すべてのコミットは ../../context/bsp-customization-workflow.md に記載された、バッチでの pristine + カスタマイズのパターンに従います。上流 BSP は <bsp_image.root_path>/ にあり、編集されることはありません。

呼び出すタイミング

• ユーザーが「UPHY を設定」「uphy レーン割り当て」「uphy0-config-N を設定」「MGBE の速度を変更」と言った場合、またはカスタムキャリアの PCIe / MGBE / USB3 / UFS の再マッピングを依頼した場合。
• UPHY に接続されたコントローラーがフラッシュ後に列挙されない場合、またはコールドブートが BL31 SError / BPMP firmware is not ready で失敗する場合。
• 下流スキルが FMON エラーまたは BPMP-DTB のレーン不一致を報告した場合。

手順（概要）

8 つのステップの詳細は references/procedure.md を参照してください。

1. 対象とドキュメントを特定します。 有効なプロファイル、カスタムキャリア、ソースツリーの git、またはフォークされたキャリア conf がない場合は拒否します。Adaptation Guide／回路図／Module Design Guide／SoC TRM を特定します。

2. Adaptation Guide（PDF／HTML ミラー／WebFetch）で「Configure the UPHY Lane」を見つけます。Module Design Guide と SoC TRM で照合します。

3. キャリア回路図と相互参照します。 UPHY ネット名（MGBE2_TX_P/N、PEX5_LN0+- など）を示します。一致するネットが 0 件の場合は、未配線です。

4. 一致する UPHY オプションを列挙します。 ドキュメントに記載された uphy0-config-N（および Thor の uphy1-config-N）のインデックスをすべて提示します。

5. 使用する config をユーザーに確認します（必須ゲート）。 まず表を表示してから、AskUserQuestion を実行します。UPHY サーフェスごとに 1 つずつ質問し、割り当てられたレーンが未配線の場合はキャリア配線の確認も行います。回答は JSON サイドカー（references/run-state-sidecar.md）に保存します。

6. キャリア flash-conf のフォークを編集します（ODMDATA を一括コミット）。 このスキルが、今回の実行におけるすべての ODMDATA トークンを管理します。1 つの ODMDATA="..." 行にすべてのトークンをまとめてコミットします。サブスキルは ODMDATA に触れてはなりません。

   BPMP DTB を <bsp_image.root_path>/Linux_for_Tegra/bootloader/generic/<BPFDTB_FILE>（キャリア conf の BPFDTB_FILE）から逆コンパイルして、標準状態のスナップショットを取得します。その後、次の順序でトークンを出力します。

   a. UPHY サーフェストークン — 選択した uphyX-config-N をすべて指定します（Thor では、一方がガイドのデフォルトと同じ場合も両方のサーフェスを指定します）。順序は uphy0、次に uphy1、区切り文字は , です。 b. コントローラーごとのトークン — 計画状態が BPMP の標準状態と異なる行ごとに 1 つ指定します。状態が一致する行にはトークンを指定しません（冗長なトークンがある場合は、行全体を削除できます）。

   • PCIe：pcie@N_status=okay|disabled。
   • MGBE：割り当て時は mgbeN-speed-<rate>、無効化時は mgbeN-speed-del。FMON は UPHY の割り当てに関係なく、コントローラー自身のクロックでアームされます。del がない場合、BL31 SError による再起動ループが発生します。Thor でフラッシュ後に最も多く発生する失敗です。
   • USB SS：SoC の文法がポート単位のトークンに対応している場合は、ポートごとに指定します。 c. uphy0-config-6 を選択した場合は、UPHY_CONFIG="" でクリアします（Adaptation Guide に基づく BCT pinmux のクリア）。

7. コントローラーごとの割り当て表を作成し、処理を振り分けます。 UPHY 給電コントローラー（PCIe／MGBE／USB SS／UFS）ごとに、{class, instance, allocated?, BPMP-stock, K-stock, routed?, Desired K state} を含む行を 1 つ作成します。この表は、（a）ステップ 6 の ODMDATA トークンと、（b）サブスキルのオーバーレイフラグメントの両方に使用します。ステップ 6 でコミットする前に作成してください。

   次に、/jetson-customize-pcie、/jetson-customize-mgbe、/jetson-customize-usb を、カーネル DT オーバーレイフラグメント専用に呼び出します（ODMDATA の編集は禁止。行の管理はステップ 6 が行います）。各サブスキルは <bsp_image.root_path>/Linux_for_Tegra/kernel/dtb/tegra<soc>-*-nv.dtb から K-stock を再読み込みし、K-stock が Desired K state と一致する場合は出力をスキップします。UFS の処理はここで直接行います（UFS サブスキルはありません）。

   対応するコントローラークラスが SoC に存在する場合は、3 つすべてを呼び出します（例：Orin では MGBE をスキップします）。まずオペレーターに確認し、yes の場合はサブスキルをインラインで実行します。

8. 概要と次のステップへの連鎖。 見出し、内訳、選択肢の表（UPHY サーフェス | 選択した config | レーンの概要 | UPHY_CONFIG のクリア）、変更概要の表（ファイル | リポジトリ | コミット SHA | このスキルのコミットと、振り分けたすべてのサブスキルのコミットを含む 1 行の概要）を示し、references/procedure.md のステップ 8 に従って、後続の処理（I/O を追加するか？ ビルドして昇格させるか？ フラッシュするか？ 検証するか？）に、AskUserQuestion プロンプトを順番に使用して進みます。プロンプトの代わりに「次のステップ：…」という行を表示してはなりません。

制限事項

• Tegra234（Orin）と Tegra264（Thor）の UPHY サーフェスのみをサポートします。
• ピンマックス、BPMP DTB に存在しない PCIe 専用 DT プロパティ（num-lanes、pcie-mode）、および上流 BSP ファイルは編集しません。
• フラッシュ、ビルド、昇格は行いません。/jetson-build-source および下流のスキルと連携させてください。
• ハードコードされたオプションテーブルは禁止です。Adaptation Guide のソースを解決できない場合は、推測せずにスキルを拒否します。
• リリースをまたいだテーブル駆動には対応していません。実行のたびに、アクティブな BSP バージョンの Guide を読み直します。

トラブルシューティング

• コールドブート時の再起動ループ／BL31 plat_setup.c:726／BPMP firmware is not ready：uphy0-config-6 の後にあるキャリア設定ファイル内の ^UPHY_CONFIG= 行で、クリアが再度上書きされています。その行をコメントアウトしてください（references/procedure.md の Step 6 を参照）。
• フラッシュ時の wait-for-device failed、BPMP DTB に変更がない：ODMDATA トークンの形式が正しくありませんでした（例：mgbe0-speed-0）。不正なトークンが1つでもあると、ODMDATA="..." 行全体が無効になります。references/procedure.md で構文を確認してください。
• MGBE を無効にした後の BL31 SError 再起動ループ：mgbeN-speed-del が欠落しています。FMON は UPHY の割り当てに関係なく、コントローラー自身のクロックでアームされます。
• 新たにルーティングされたコントローラーが列挙されない：標準のカーネル DTB では status="disabled" になっていました。オーバーレイで status="okay" を出力する必要があります（references/procedure.md のマトリックスの4行目）。
• Pinmap の差分が0なのにボードが正常に動作しない：UPHY の差動ペアがピンマックス .xlsm にありません。Pinmap ではなく、回路図のネット名に基づいて判断してください。
• pcie@<addr> フラグメントが重複している：別のスキル（jetson-customize-pcie）がすでにそのノードを所有しています。このスキルの対象を MGBE／UFS／USB3 SS／PCIe ステータスのみとし、もう一方のオーバーレイを参照してください。

参考資料

• references/procedure.md — 8ステップの手順全体。
• references/gotchas.md — 分野横断的な注意点。
• references/run-state-sidecar.md — JSON サイドカーのスキーマと冪等性。
• ../../references/platform_template.yaml — documents: スキーマ。
• ../../context/bsp-customization-workflow.md — オーバーレイ編集プロトコル。
• ../../references/bsp-customization-kernel-dtb.md — 複合オーバーレイのファイル名／追加プロトコル。
• ../jetson-derive-carrier/SKILL.md — このスキルが編集する設定ファイルを生成します。
• ../jetson-init-source/SKILL.md — このスキルがコミットする2つの Git リポジトリを生成します。
• ../jetson-generate-kb/SKILL.md — チップファミリーとファイルの場所を確認するために参照する KB。