jetson-customize-pcie

PCIe のカスタマイズ（コントローラーごとの状態／レーン数／速度）

概要

Tegra264（Thor、[email protected]）および Tegra234（Orin、 [email protected]）では、PCIe は複数のコントローラーに分割されており、 USB3／MGBE／UFS と UPHY レーンプールを共有しています。各コントローラーの 実行時の動作は、両方が必須となる 2 つの設定箇所によって決まります。

設定箇所	対象	ここで決まる内容
ODMDATA pcie@N_status=…（および pcie@N_max-link-speed、pcie@N_pcie-mode、pcie@N_clk-scheme、pcie-cN-endpoint-enable）	BPMP DTB 内の /pcie/pcie@N	UPHY レーンの電源、refclk のゲーティング、コントローラー側の電源レール
&pcieN に対するカーネル DT オーバーレイ	カーネル DTB 内の /bus@0/pcie@<addr>	カーネルのプローブ、レーン幅、リンク速度、RC／EP モード

無効化の際にカーネルオーバーレイを省略すると、電源がオフの PHY をカーネルが プローブしてしまい、dmesg にリンクタイムアウトが記録されます。無効化の際に ODMDATA トークンを省略すると、BPMP が PHY を有効な状態に保持します。

テーブル駆動ではなく、エージェント駆動です — コントローラーのテーブルも questions.json もありません。各コントローラー、レーン幅、回路図上で配線された コネクター、信頼できる DT ノードのアドレスはすべて、ドキュメント、DTB、 キャリアのピンマップから実行時に検出します。

出力されるのはカーネル DT オーバーレイのコミットのみです。コントローラーごとの fragment@N ブロックを、次のドキュメントに従って複合カスタムオーバーレイの .dts に追加し、 ../../references/bsp-customization-kernel-dtb.md bsp_sources/ ハードウェアリポジトリにコミットします。 /jetson-build-source が複合オーバーレイを .dtbo にコンパイルし、Makefile と flash-conf への登録を管理します。

このスキルは ODMDATA="..." を編集してはいけません。 すべての ODMDATA トークン （pcie@N_status=…、pcie@N_max-link-speed、pcie@N_pcie-mode、 pcie@N_clk-scheme、pcie-cN-endpoint-enable に加え、 uphyX-config-N の設定箇所のトークンと UPHY_CONFIG="" によるクリア）は、 /jetson-customize-uphy がキャリアの flash-conf フォーク上で単一のアトミックな コミットとして出力します。このスキルが UPHY サイドカーから取得する割り当てテーブルには、 各コントローラーの okay／disabled／レーンごとのサイズ設定がすでに示されています。 このスキルはそのテーブルをカーネル DT オーバーレイのフラグメントに変換するだけで、 オーバーレイがすでに customize-uphy によってコミット済みの ODMDATA と一致することを 検証します（Step 8 の整合性チェック — 不一致は報告し、黙って修正することはありません）。

呼び出すタイミング

• ユーザーが「PCIe を設定」「PCIe コントローラーを有効化」「PCIe の num-lanes を 設定」「PCIe のリンク速度を変更」と指示した場合、または pcie@N_status トークンの 切り替えを依頼した場合。
• 特定の PCIe スロットまたは M.2 コネクターがフラッシュ後に列挙されない場合、または リンクが誤ったレーン幅／速度でトレーニングされる場合。
• jetson-customize-uphy が実行され、PCIe コントローラー間でレーンが再割り当てされた場合 （例：uphy0-config-7 から uphy0-config-6 に切り替えて PCIe C3 を有効化）。 この場合、コントローラーごとの設定も有効化する必要があります。
• QSFP 経路が配線済みだと jetson-customize-mgbe が報告したものの、カーネルが PCIe 側の 付随デバイスをプローブしない場合（まれなケース。XFI 構成）。

前提条件：

• reference_devkit: と custom_carrier: ブロックを含む有効なプロファイル。
• <source.root_path>/Linux_for_Tegra/.git が存在すること （/jetson-init-source）。
• /jetson-derive-carrier が実行済みであること — キャリアの flash-conf フォークが オーバーレイトラッカーに登録されていること。
• /jetson-customize-uphy が実行済みであること — その JSON サイドカー <workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json が コントローラーごとの enable 判定を決定します。
• 信頼できる情報源となるドキュメントが登録済み、またはプロンプトで提供されていること： Adaptation Guide、Module Design Guide、SoC TRM。
• custom_carrier: が存在する場合、 documents.custom_carrier_schematic と documents.custom_carrier_pinmux_xls の両方が必須です。 いずれかが欠けている場合は 実行を拒否してください。カスタムキャリア上の配線は推測できません。 リファレンス開発キットのみのプロファイルでは、この確認を省略します。
• dtc が PATH 上にあること。

手順（概要）

手順の詳細な手順説明は references/procedure.md にあります。大まかな流れは次のとおりです。

1. 有効なターゲットを特定し、信頼できるソース文書（<carrier-pinmap>、<ref-dtb>、<uphy-state> を含む）を開きます。<uphy-state> がない場合は拒否します。
2. <ref-dtb> を逆コンパイルし、回路図で PEX<N>_* ネットラベルを検索して、PCIe トポロジー（開発キットとカスタムキャリア）を比較します。
3. AskUserQuestion（multiSelect）を使い、カスタマイズするコントローラーを選びます。
4. コントローラーごとに、ピンマップ、回路図、pin_verifier.py を使用して PE<N>_CLKREQ_L、PE<N>_RST_L、任意の PE<N>_WAKE_L を検証します。
5. コントローラーごとの計画を自動導出します（<uphy-state> から enable、Adaptation Guide から lanes / speed を取得し、mode は "rc" に固定）。その後、必須の確認またはカスタマイズのゲートを設けます。
6. コントローラーごとの fragment@N ブロック（マーカー /* custom-bsp: pcie:pcie@<addr> */）を、bsp_sources/ 内の複合カスタムオーバーレイ .dts に追加します。事前チェックとして dtc と fdtoverlay を実行します。ワークフローのプレビューゲートを通じてコミットします。 ODMDATA は編集しないでください — /jetson-customize-uphy は、単一のアトミックな ODMDATA コミットで pcie@N_status=…、pcie@N_max-link-speed、pcie@N_pcie-mode、pcie@N_clk-scheme、pcie-cN-endpoint-enable をすでに出力しています。このスキルでは、コントローラーごとの計画をカーネル DT オーバーレイのフラグメントに変換するだけです。
7. （この手順はステップ 6 に統合されています — オーバーレイのみを出力します。）
8. ODMDATA とオーバーレイの整合性を相互確認します。矛盾する行がある場合は、処理を停止し、2 つのコミットからどう復旧するかユーザーに尋ねてください。 自律的に git reset --hard を実行してはいけません。
9. 実行状態の JSON サイドカーを <workspace>/target-platform/<profile-stem>.jetson-customize-pcie.json に書き込み、概要を作成します。その後、references/procedure.md のステップ 9 に従い、AskUserQuestion プロンプトを順番に使用して、下流の次の手順のチェーンを進めます。プロンプトの代わりに「次の手順: …」という行を表示してはいけません。

制限事項

• モードは RC に固定されています。 エンドポイントモードは、オペレーターがステップ 5c で mode_override="ep" を渡した場合にのみ出力されます。
• enable は導出され、質問しません。 UPHY に割り当てられたコントローラーは必ず okay に、割り当てられていないコントローラーは必ず disabled に設定されます。
• 上流の BSP は編集しません。 出力先は Linux_for_Tegra/ と bsp_sources/ のみです。
• オーバーレイの事前マージは妥当性確認であり、本番ビルドではありません。 正式な処理は /jetson-build-source が担います。
• Flash-conf のオーバーレイ登録は対象外です。 /jetson-build-source のステップ 5.0a が担当します。

トラブルシューティング

• <uphy-state> がない → 先に /jetson-customize-uphy を実行します。
• フラッシュ後にスロットが列挙されない → dmesg | grep pcie を確認し、ODMDATA の pcie@<N>_status=okay とオーバーレイのフラグメントが一致していることを再確認します（references/procedure.md のステップ 8 の表）。
• リンクが誤った幅でトレーニングされる → <uphy-state> の UPHY 設定で想定されるレーン数が割り当てられていることを確認します。カーネルフラグメントの num-lanes はその値と一致する必要があります。
• compatible が一致しない → フラグメントではなく、複合ルートを修正します。不一致の場合、UEFI プラグインマネージャーは警告なしでスキップします。
• ODMDATA とオーバーレイの行に矛盾がある → ユーザーに尋ねます。自動的に git reset --hard を実行してはいけません。gotchas を参照してください。
• よくある落とし穴 — references/gotchas.md を参照してください（RC の固定、ノードアドレスの取得元、標準で無効になっているコントローラー、jetson-customize-uphy とのファイル内ハンドオフ）。

参考資料

• references/procedure.md — 9 ステップの手順全体（トポロジーの差分、プランの導出、オーバーレイの追記、ODMDATA の照合、サイドカー）。
• references/gotchas.md — 失敗モードと不変条件（RC のピン留め、アドレスの取得元、BPMP の引き継ぎ）。
• ../../scripts/pin_verifier.py — 共通 HSIO ピン検証ツール（ステップ 4）。
• ../../references/platform_template.yaml — ステップ 1 で使用する documents: ブロック。
• ../../context/bsp-customization-workflow.md — オーバーレイ編集プロトコルとコミットメッセージのプレビューゲート。
• ../../references/bsp-customization-kernel-dtb.md — 複合オーバーレイのファイル名／スケルトン／追記プロトコル。
• ../jetson-customize-uphy/SKILL.md — UPHY レーン割り当てを担当する兄弟スキル。そのサイドカーがコントローラーごとの enable 判定を制御します。
• ../jetson-customize-pinmux/SKILL.md — HSIO ピンの SFIO 不一致を修正するため、ステップ 4 で（オペレーターの確認を得て）呼び出す兄弟スキル。
• ../jetson-customize-mgbe/SKILL.md — MGBE コントローラー用の兄弟スキル。2 つの対象面（ODMDATA とオーバーレイ）のパターンを共有します。
• ../jetson-derive-carrier/SKILL.md — 最初に実行する必要があります。ステップ 6 で編集するキャリアの flash-conf フォークを生成します。
• ../jetson-init-source/SKILL.md — このスキルが変更をコミットするオーバーレイトラッカーと bsp_sources リポジトリを生成します。