jetson-customize-mgbe

MGBE / 25G QSFP のカスタマイズ

概要

Thor T264 は mgbe0..mgbe3 を公開します。カスタムキャリアでは、25G QSFP ケージ（または 10G / 1G ファイバー経路）が、SerDes を介してそのうちの 1 つに配線されています。ケージの手前に外部 MDIO PHY がある場合も、ない場合もあります。このスキルは、BPMP の割り当てと、&mgbeN 上のカーネル側の status="okay" および PHY の配線を組み合わせるカーネル DT オーバーレイを生成します。

対象外：

• UPHY レーンの割り当て — /jetson-customize-uphy が担当します。選択した uphy1-config-N が対象の MGBE を割り当てていない場合は、処理を拒否してください。
• すべての ODMDATA トークン（mgbeN-speed-*、サブノードの mgbeN_status=*）— /jetson-customize-uphy が単一の不可分な ODMDATA コミットで担当します。このスキルは ODMDATA= に絶対に触れてはいけません。

出力は、ハードウェアリポジトリ bsp_sources/ 内の複合カスタムオーバーレイ .dts への1 つのコミットです。/jetson-build-source が複合オーバーレイを .dtbo にコンパイルし、その Makefile と flash-conf への登録を担当します。

呼び出すタイミング

• ユーザーが「25G を有効にする」「QSFP を設定する」「MGBE PHY モードを設定する」「MGBE を QSFP に接続する」と言う場合、または 10G / 1G ファイバー経路の立ち上げを求める場合。
• コールドブートは成功するものの、設定したコントローラーで ip link show mgbe<N> が state DOWN または NO-CARRIER を報告する場合、またはコントローラーがまったく表示されない場合。
• jetson-customize-uphy が uphy1-config-8（または MGBE を割り当てる別の設定）で実行され、コントローラーごとの側を立ち上げる必要がある場合。

前提条件：

• reference_devkit:（Thor）と custom_carrier: ブロックでアクティブなプロファイルが選択されていること。
• <source.root_path>/Linux_for_Tegra/.git が存在すること（/jetson-init-source）。
• /jetson-derive-carrier が実行済みであり、キャリアの flash-conf フォークがオーバーレイトラッカーに登録されていること。
• /jetson-customize-uphy が、対象 MGBE コントローラーのレーンを割り当てる UPHY 設定を選択していること（Thor で MGBE0..3 25G の場合は uphy1-config-8）。
• 正式な情報源となるドキュメントが登録されているか、プロンプトで提供されていること：Adaptation Guide、Module Design Guide、SoC TRM。
• custom_carrier: がある場合は、documents.custom_carrier_schematic と documents.custom_carrier_pinmux_xls の両方が必須です。 いずれかが欠けている場合は実行を拒否してください。カスタムキャリア上の MGBE 配線は推測できません。リファレンス開発キットのみのプロファイルでは、この確認を省略します。
• PATH 上に dtc があること。

手順

手順の全ステップ（ステップ 1～8）については references/procedure.md を参照してください。概要：

1. アクティブなターゲットとドキュメントを特定します。 アクティブなプロファイル、custom_carrier、オーバーレイトラッカーを検証し、該当する Adaptation Guide の章とピンマップを探します。
2. コントローラーごとの質問ループ。 questions.json に基づく AskUserQuestion（コントローラー、phy_mode、接続種別、I²C バス／アドレス、リセット GPIO、compatible_list）。
3. phy_mode から max-speed を導き出します。 BPMP DTB を逆コンパイルして、サブノードとトップレベルのどちらのトークン文法を使うかを判断し、検査内容を notes に記載します。
4. HSIO ピンを検証し、自動修正します。 pin_verifier.py を MDC/MDIO/RESET/INT に対して実行し、不一致を提示して /jetson-customize-pinmux に引き継ぎます。
5. （ODMDATA は編集しません。） MGBE ODMDATA トークンは /jetson-customize-uphy が出力します。ステップ 5 では監査用に、BPMP DTB で確認したトークン形式（サブノードとトップレベルのどちらか）のみを notes[] に記録します。
6. 複合オーバーレイの断片を追加します。 コントローラーごとに 1 つの断片を複合カスタムオーバーレイ .dts に書き込み、/* custom-bsp: mgbe:mgbe... */ のマーカー規約に従い、cpp/dtc/fdtoverlay の事前チェックを実行します。
7. （予約済み。） 関連スキルの実行順序／横断的な検証。
8. 実行状態サイドカー、要約、次のステップへの連鎖。 <profile-stem>.jetson-customize-mgbe.json を書き込み、1 行の要約と表形式の要約を出力してから、references/procedure.md のステップ 8 に従い、AskUserQuestion プロンプトを順番に使って後続の連鎖を進めます。プロンプトの代わりに「Next step: …」という行を表示してはいけません。

注意点

• 標準の Thor BPMP DTB には /mgbe/mgbe@N サブツリーがありません — /uphy の mgbe<N>-speed だけがあります。これらのリリースでは、mgbe<N>_status=disabled サブノードトークンは黙って拒否され、フラッシュ時に ODMDATA 行全体が破棄されます。出力する前に必ず BPMP DTB を逆コンパイルしてください（Step 3）。サブノードがない場合は、トップレベルのハイフン形式（削除するには mgbe<N>-speed-del、設定するには mgbe<N>-speed-25G）を使用してください。jetson-customize-uphy と同じ誤った形式による失敗が起こります。
• phy_attach_kind=="phy" の場合、mdio 子ノードには #address-cells = <1> と #size-cells = <0> の両方が必要です。 どちらかが欠けていると、プローブ時にカーネルが phy@<addr> の reg プロパティを拒否し、MGBE が起動しません。
• オーバーレイのルート compatible は、実行中の DT compatible と一致する必要があります。 UEFI plugin-manager は compatible の一致に基づいてフィルタリングします。一致しないオーバーレイは黙ってスキップされるため、フラッシュは成功しても MGBE は無効のままで、dmesg にエラーも出ません。起動済みの参照用 DUT で /proc/device-tree/compatible を必ず確認してください。
• OVERLAY_DTB_FILE の順序はこのスキルではなく、jetson-build-source が担当します。 このスキルはキャリアの flash conf に一切触れません。複合カスタムオーバーレイは、正しい順序でプラットフォームの *-dynamic.dtbo の後に（/jetson-build-source Step 5.0a によって）登録されます。このスキルで OVERLAY_DTB_FILE+= を追加しようとしている場合は、担当範囲を重複させています。中止して、ビルドスキルに任せてください。
• UPHY レーンの割り当ては jetson-customize-uphy の担当です。 選択した uphy1-config-N が対象の MGBE コントローラーにレーンを割り当てていない場合、コールドブート時に BL31 SError（fmon_update_config: detected fault 0x80）が発生します。必ず先に /jetson-customize-uphy を実行し、このスキルの実行サマリーの notes[] に選択した uphy1-config-N を記載してください。
• ODMDATA だけで、標準設定で問題のないコントローラーを無効にしないでください。 jetson-customize-uphy と同じルールです。BPMP DTB ですでに無効になっているコントローラーに対する mgbe<N>_status=disabled は何も変更せず、パーサーが曖昧と判断して ODMDATA 行の残りを破棄することがあります。無効化する場合は、カーネル DT オーバーレイの status="disabled" だけを使用してください。
• <bsp_image.root_path> のアップストリーム BSP には触れないでください。 すべての編集は、オーバーレイトラッカー／bsp_sources モノレポにおいて、クリーン状態のコミットとカスタマイズのコミットのパターンに従って行います。
• JSON サイドカーは構造化された状態であり、信頼できる唯一の情報源ではありません。 jetson-customize-uphy と同じ注意事項が適用されます。デバイスに反映される出力は ODMDATA、オーバーレイ .dts、2 つの git コミットです。サイドカーはツールと冪等性のためにのみ使用します。

参考資料

• questions.json — Step 2 で使用する Q-1..Q-8 のプロンプトスキーマ。
• ../../scripts/pin_verifier.py — 共通 HSIO ピン検証ツール（Step 4）。
• ../../references/platform_template.yaml — Step 1 で使用する documents: ブロック。
• ../../context/bsp-customization-workflow.md — オーバーレイ編集プロトコル（クリーン状態のコミットとカスタマイズのコミットをまとめて行う）。
• ../jetson-customize-uphy/SKILL.md — UPHY レーン割り当てを担当する関連スキル。MGBE にレーンを割り当てる構成の uphy1-config-N を設定するため、このスキルより先に実行する必要があります。
• ../jetson-customize-pinmux/SKILL.md — Step 4 で（オペレーターの確認を得て）呼び出され、ピンの SFIO の不一致を修正する関連スキル。
• ../jetson-derive-carrier/SKILL.md — 最初に実行する必要があります。Step 5 で編集するキャリアの flash-conf フォークと、このスキルが順序を設定するキャリアベースオーバーレイを生成します。
• ../jetson-init-source/SKILL.md — このスキルがコミットするオーバーレイトラッカーと bsp_sources リポジトリを生成します。