jetson-derive-carrier

jetson-derive-carrier

カスタムキャリアで、すべての customize-* スキルに対する初回実行時のゲートをカスタマイズします。アクティブなターゲットは target-platform-contract.md に従って解決します。 custom_carrier: ブロックがない場合、または <source.root_path>/Linux_for_Tegra/.git が見つからない場合は拒否します（先に jetson-init-source を実行してください）。テンプレートファイルの作成／コピー行は 単一のオーバーレイトラッカーのコミットにまとめられ、カスタムキャリア名に変更したターゲットパスへ直接コピーされます。参照名のままの未変更ファイルがステージされることはありません（ローカルルールについては Fork plan を参照してください。このルールは、 ワークフロー で定められた未変更ファイル＋カスタマイズの標準的な分割方法より優先されます）。conf チェーンの検出は、 ボードごとの conf ディスパッチ に従います。 カーネルのベース DTB はフォークしません。キャリアの差分は、 OVERLAY_DTB_FILE を介して接続される DT オーバーレイとして適用されます。

識別子（アクティブなプロファイルから取得）：<chip> は catalogue を介して reference_devkit.module.id から取得します（不明な場合は警告し、tegra234 にフォールバックします）。<module-id>／<module-sku> は reference_devkit.module から、<carrier-id>／<carrier-sku> は reference_devkit.carrier から取得します。<custom-id>／<custom-sku>／ <custom-flash-conf> は custom_carrier から取得します。<real-conf> は readlink <bsp_image.root_path>/Linux_for_Tegra/<reference_devkit.flash_config> で取得します（NVIDIA の慣例では <devkit>.conf → <carrier>-<module>-a<rev>.conf です。シンボリックリンクでない場合は警告し、トップレベルのファイルを実ファイルとして扱い、シンボリックリンクラッパーの行をスキップします）。

<custom-id> はカスタムキャリアボードのトークンであり、NVIDIA 形式の pNNNN ID とは限りません。ハイフン形式のファイル名と DT の compatible 文字列には、そのまま使用してください。ターゲットのファイル群で p を除いた数値トークンを使う場合は、<custom-id> が ^p[0-9]{4}$ に一致する場合に限り、<custom-id-file-token> を NNNN とします。それ以外の場合は、<custom-id> を変更せずに使用します。カスタムキャリア ID が p で始まらないという理由だけで拒否しないでください。

Instructions

以下のフォーク計画が指示セットです。検出を 1 回実行した後、git commit の前にコミットメッセージのプレビューで確認しながら、ボードごとのファイルセットを 1 行ずつフォークします。

フォーク計画

このスキルで実行されるすべての git commit は、オーバーレイトラッカー（Linux_for_Tegra/）でも hardware/ ソースリポジトリでも、 コミットメッセージのプレビューゲートを通過します。 ステージ済みファイルの一覧と提案するメッセージをオペレーターに提示し、各 git commit の前に承認／編集／キャンセルを求めてください。 キャンセルの場合は、手動で解決できるよう、インデックスをステージ済みのままにしてください。

バイト列に変更がない場合でも、名前を変更したフォークを実体化します。 承認済みのフォーク計画の各行について、カスタムキャリアのターゲットパスを作成して追跡してください。フォークが名前変更／コピーのみの場合や、参照元とバイト列が同一の場合でも、ターゲットがないことを理由にスキップしないでください。これには、pinmux、GPIO/GPIOINT、padvoltage/PMC、misc、MB2 misc などの BCT フォークも含まれます。スキップできるのは、Acceptance 列で許可されている場合、ソースが明示的な警告付きスキップの対象である場合、または想定されるターゲットパスがすでに追跡されている場合に限ります。最後の場合は、すでに派生済みとして報告し、空のコミットを作成しないでください。

テンプレートファイルの作成／コピー行は、オーバーレイトラッカーの単一コミットにまとめます。参照元の名前が付いた未変更ファイルは決してステージしません。 オーバーレイトラッカーに新しいファイル（テンプレート由来）を実体化するすべての行、すなわち、ボードの flash-conf、flash-conf シンボリックリンク、MB1 BCT（pinmux、GPIO/GPIOINT、padvoltage/PMC、misc）、MB2 BCT（misc）、BPMP DTB（オプトイン時）、nvpmodel、nvfancontrol は、<bsp_image.root_path>/Linux_for_Tegra/<rel>/<reference-name> から <source.root_path>/Linux_for_Tegra/<rel>/<custom-name> へ直接コピーし、ステージ前にコンテンツの編集を適用してください。参照元の名前（<carrier-id>-<carrier-sku> をキーとする）が付いたファイルは、オーバーレイトラッカーでは決してステージもコミットもせず、追跡するのはカスタムキャリア名に変更したファイルのみです。これは、 コミットのバッチ化にある、未変更ファイルとカスタマイズを分ける標準方式に優先します。このような行はすべて、次を追加する単一のオーバーレイトラッカーコミットに含めます。（i）コンテンツの編集を適用済みの、ターゲットパスにあるカスタムキャリア名のファイル、（ii）flash-conf シンボリックリンク、（iii）名前を変更した flash-conf 内で対象となる、PINMUX_CONFIG／GPIO_CONFIG／GPIOINT_CONFIG／PMC_CONFIG／MISC_CONFIG／MB2_BCT の書き換え（BPMP DTB をオプトインしている場合は BPFDTB_FILE も含む）。テンプレートの作成ではなく既存のアップストリームファイルを編集する行、すなわち nvpower.sh のパッチと、オーバーレイの接続（作成直後の flash-conf フォークへの OVERLAY_DTB_FILE+= の追記。これは コミットのバッチ化に従い、時間的に別個のフェーズとして扱います）は、それぞれ独自の行に従って個別のコミットにします。DT オーバーレイのスケルトンはオーバーレイトラッカーではなく bsp_sources/hardware/ にコミットするため、影響を受けません。コミットメッセージのプレビューゲートは、まとめたコミットに対して一度だけ実行します。警告付きでスキップした行は含めません。バンドル内のすべての行がすでに追跡済みの場合、コミット全体を省略します。

検出（1 回の一括処理）

検出は1 回だけ実行し、ステージングと並行して行わないでください。一覧を切り詰めないでください。スキャン対象の各ディレクトリ内にあるすべての候補ファイル名を、照合処理で確認できる状態にしてください。この手順では head、tail、| head -N、| tail -N、その他行数を制限するフィルターを使用しないでください。出力を切り詰めずに ls -1／find を使うか、全出力に対して grep を実行してください。一覧を切り詰めると、一致するファイルが上限より後ろにある場合に、誤って警告付きスキップと判断するおそれがあります。次を取得してください。

• Flash-conf 変数: DTB_FILE / TBCDTB_FILE / BPFDTB_FILE / PINMUX_CONFIG / PMC_CONFIG / GPIO_CONFIG / GPIOINT_CONFIG。 DTB_FILE / TBCDTB_FILE は 参照専用 として取り込まれ、 オーバーレイの配線がオーバーレイのファイル名用に <dtb-stem> を 導出できるようにします — これらがこのスキルによって書き換えられることは ありません。
• BCT .dts は bootloader/generic/BCT/ にあります。.dtsi の兄弟ファイルは 1 つ上の階層である bootloader/ にあり、並置されているのでは ありません。
• nvpmodel: nvpmodel_<module-id>_<module-sku>*.conf。nvfancontrol: nvfancontrol_<module-id>_<module-sku>_<carrier-id>_<carrier-sku>.conf。
• (a)〜(d) の nvpower.sh アンカー: <carrier-id> の cvb ブランチ、 <module-id>-<module-sku> の SKU elif、tegra<chip> の nvpmodel カスケード、tegra<chip> の nvfancontrol カスケード。 | ファイル／カテゴリ | 検出方法 | 採用条件 | フォーク規則 | |---|---|---|---| | ボードのフラッシュ設定 | <real-conf> | 常に | ファイル名の <carrier-id>-<carrier-sku> を <custom-id>-<custom-sku> に置換します。内容の置換対象は限定的であり、一括ではありません。このスキルでフォークするファイルを参照する変数（PINMUX_CONFIG、PMC_CONFIG、GPIO_CONFIG／GPIOINT_CONFIG、MISC_CONFIG、MB2_BCT）のみ、右辺を置換します。その他のキャリアキー付き変数（DTB_FILE、TBCDTB_FILE、SCR_CONFIG、PMIC_CONFIG、DEVICEPROD_CONFIG、PROD_CONFIG、MINRATCHET_CONFIG、UPHY_CONFIG、動的な OVERLAY_DTB_FILE+=）は、参照値のままにする必要があります。ここではそれらのファイルをフォークしないため、一括置換の sed を実行すると、存在しないファイルを参照してしまいます。特に DTB_FILE／TBCDTB_FILE については、ベース DTB はフォークしません。オーバーレイの行では、新しい OVERLAY_DTB_FILE+= 行を追加します。BPFDTB_FILE は追加のコミットをオプトインで行います。<chip>、<module-id>、xxxx は変更しません。 | | フラッシュ設定のシンボリックリンク | 無条件 | 常に（<real-conf> がシンボリックリンクでない場合はスキップ） | 新しいシンボリックリンク <custom-flash-conf> → フラッシュ設定のフォーク | | MB1 BCT のピンマックス | PINMUX_CONFIG ＋ #include は¶に従う | 常に | 名前変更ルール † | | MB1 BCT の GPIO | GPIO_CONFIG／GPIOINT_CONFIG ＋ #include は¶に従う | 常に | 名前変更ルール † | | MB1 BCT のパッド電圧 | PMC_CONFIG ＋ #include は¶に従う | 常に | 名前変更ルール † | | MB1 BCT のその他の設定 | MISC_CONFIG ＋ #include は¶に従う | 常に | 名前変更ルール † | | MB2 BCT のその他の設定 | MB2_BCT ＋ #include は¶に従う | 常に | 名前変更ルール † | | カーネル DTB ＋ ソース DTS | （参照のみ — ヘッダーを参照） | フォークしない | ベース DTB は参照先のままにします。オーバーレイトラッカーに未加工のバイナリコピーは含めません。また、bsp_sources/hardware/ ではソース DTS をフォークしません。キャリアの差分はすべて DT オーバーレイ（次の行）に含めます。 | | DT オーバーレイのスケルトン（NEW） | 無条件 | 常に | <source.root_path>/hardware/nvidia/<chip>/nv-public/overlay/<chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dts を作成します（スケルトン ‡）。hardware/ でコミットし、origin にプッシュします | | ディレクトリごとの Makefile 登録 | <source.root_path>/bsp_sources/hardware/nvidia/<chip>/nv-public/overlay/Makefile | 常に | 最後のリテラル名付き dtbo-y += エントリの後に、dtbo-y += <chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dtbo を追加します（$(addprefix $(makefile-path)/,$(dtbo-y)) のプレフィックスブロックより前です。dtbo-y += $(old-dtbo) の後に挿入すると、.dtbo が気付かれないまま除外されます）。同じ位置依存の記述方法とスニペットは、コンポジットスロットの Makefile パッチにあります（../jetson-build-source/references/composite-registration.md#makefile-patch-idempotent-position-sensitive）。hardware/ でコミットします。この行がないと、nvidia-dtbs は次の行の OVERLAY_DTB_FILE+= が参照する .dtbo を生成せず、ファイルが見つからないため flash.sh がフラッシュ処理の途中で中断します。 | | オーバーレイの接続設定 | 無条件 | 常に | フラッシュ設定のフォークに OVERLAY_DTB_FILE+=",<chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dtbo" を追加します（追加のコミット） | | nvpmodel 設定 | rootfs/etc/nvpmodel/nvpmodel_<module-id-num>_<module-sku>.conf | 常に | ファイル名に _<custom-id-file-token>_<custom-sku> を追加します | | nvfancontrol 設定 | rootfs/etc/nvpower/nvfancontrol/nvfancontrol_<module-id-num>_<module-sku>_<carrier-id-num>_<carrier-sku>.conf | 常に | ファイル名のキャリア部分を置換します（ソースがモジュールキーのみの場合は _<custom-id-file-token>_<custom-sku> を追加） | | nvpower.sh パッチ | rootfs/etc/systemd/nvpower.sh | 常に | 未加工の状態から、次の 4 つの挿入を含む単一のカスタマイズコミットを作成します：（a）参照設定の前に cvb のカスケードとして elif [[ "${machine}" =~ "<custom-id>" ]]; then cvb="<custom-id-file-token>" を追加します。（b）モジュール SKU の分岐内で machine="<module-id>-<module-sku>-<custom-id>-<custom-sku>" を設定します。（c）コンポジットマシンキーの nvpmodel カスケード分岐を追加し、conf_file= に nvpmodel のフォークを設定します。（d）cvb キー付き nvfancontrol のカスケード分岐を追加し、conf_file= に nvfancontrol のフォークを設定します | | BPMP DTB | bootloader/generic/<BPFDTB_FILE> にあるプリビルド版（別の命名形式：p の接頭辞なし、SKU は xxxx） | オプトイン y/N、既定値は N — モジュールレベルで、通常は参照先と共有 | バイナリをフォークします。未加工の状態から、ファイル名の -<carrier-id-num>- を -<custom-id-file-token>- に置換します（内容は変更しません）。フラッシュ設定のフォークに BPFDTB_FILE を名前変更後のバイナリに書き換える追加コミットを作成します。 | ¶ #include をたどります。 キャプチャした各 .dts をスキャンし、ファイル内のあらゆる場所にある #include "..." ディレクティブを確認します（NVIDIA BSP では BCT ノード本体の内部に記述されていることがあります）。キャリアをキーとする include はフォーク一覧に追加します。 1 階層まで確認します。

† 名前変更ルール。 キャリアをキーとするソース（例： …-p3834-xxxx-p4071-0000.dts）→ ファイル名の <carrier-id>-<carrier-sku> を <custom-id>-<custom-sku> に置換します。同じカスタマイズコミット内で、フラッシュ設定変数（例：PINMUX_CONFIG）を変更後のファイル名に書き換えます。モジュール部分は pristine からそのまま引き継ぎます。pristine が p3834-xxxx なら、フォークも p3834-xxxx を維持します。pristine が p3834-0008 なら、フォークも p3834-0008 を維持します。モジュール SKU を独自に固定してはいけません。pristine でキャリア SKU の位置に他の xxxx ワイルドカード（例：p4071-xxxx）が使われている場合も、同じルールを適用します（例：p1234-xxxx）。モジュールをキーとするソース（例：…-p3767-dp-a03.dtsi）→ _<custom-id-file-token>_<custom-sku>（アンダースコア形式）または -<custom-id>-<custom-sku>（ハイフン形式）を追加します。さらに、フラッシュ設定のフォークに対する追加コミットで、変数（例：PINMUX_CONFIG）をサフィックス付きの名前に書き換えます。デフォルトでは内容を置換しません。内容にキャリア ID と SKU のリテラルによる相互参照が含まれる場合は、プロンプトで確認します。

‡ オーバーレイの骨格。 DT プラグインオーバーレイ（/plugin/;）に、target-path = "/" を指定した fragment@0 を 1 つ配置します。__overlay__ 内で、model = "<custom_carrier.name> carrier board" と compatible = "nvidia,<custom-id>-<custom-sku>+<module-id>-<module-sku>", "nvidia,<chip>" を設定します。nvpower.sh によるマシンの絞り込みでは compatible を参照します。

編集内容の検証

sed やパッチを適用するたびに、再度 grep で確認します。sed は対象が見つからなくても何もせずに終了します。終了コード 0 でも成功の証明にはなりません。複数行の置換には、複数行の sed（空白の差異に弱く、何もせずに終了することがあります）ではなく、Python の str.replace(old, new) を使用します。検証で対象が見つからなかった場合は、コミットを拒否します。

概要。 リポジトリごとのフォーク数とコミット SHA、BPMP-DTB の判断、警告してスキップした行（この BSP に必須のソースファイルがない場合。実行全体を失敗させない）、書き込んだオーバーレイのパスを出力します。

例

オペレーターが使用する可能性のあるトリガーフレーズ：

derive custom carrier
bootstrap custom carrier
fork carrier board from reference devkit

スキルが検出することを想定している、アクティブプロファイル内の最小限の custom_carrier: ブロック：

custom_carrier:
  id: p1234            # any token; need not be NVIDIA pNNNN style
  sku: 0000
  flash_config: p1234.conf
  name: Acme Custom Carrier

目的

新しいキャリアボード向けにボードごとのファイルセットをカスタマイズし、後続の customize-* スキル、nvpower.sh、ブートチェーンが参照用開発キットではなく、カスタムキャリアを使用するようにします。ベース DTB は参照用のまま維持し、キャリア固有の差分は DT オーバーレイに保持します。これにより、新しい参照 BSP に対する再導出では、このスキルを再実行するだけで済みます。

前提条件

• アクティブプロファイルが target-platform-contract.md に従って解決され、custom_carrier: ブロック（ID、SKU、フラッシュ設定、わかりやすい名前）が設定されていること。
• source.root_path/Linux_for_Tegra/.git が初期化されていること。まず /jetson-init-source を実行してください。オーバーレイのトラッカーがない場合、このスキルは実行を拒否します。
• /jetson-init-image によって bsp_image.root_path が設定され、参照用フラッシュ設定のシンボリックリンクを解決できること。
• reference_devkit:（モジュールとキャリア）が設定され、名前変更ルールで置換対象となるキャリア ID／SKU のトークンが指定されていること。

制限事項

• カーネルベースの DTB とそのソース DTS はフォークされません。キャリアの差分は、OVERLAY_DTB_FILE 経由で接続された DT オーバーレイを通じて適用する必要があります。
• BPMP DTB のフォークはオプトイン方式です（デフォルトは OFF）。ほとんどのキャリア交換では参照 BPMP DTB を共有します。ボードの電源／クロック構成が異なる場合にのみオプトインしてください。
• フラッシュ設定のコンテンツ置換は対象を限定しており、一律には行いません。このスキルでファイルをフォークしない変数（DTB_FILE、TBCDTB_FILE、SCR_CONFIG、PMIC_CONFIG、DEVICEPROD_CONFIG、PROD_CONFIG、MINRATCHET_CONFIG、UPHY_CONFIG、動的な OVERLAY_DTB_FILE+=）は参照値のままです。書き換えると、存在しないファイルを指すことになります。
• カスタムキャリア ID は NVIDIA の pNNNN 形式に従う必要はありません。p を除いた数値トークンが導出されるのは、ID が ^p[0-9]{4}$ に一致する場合のみです。
• モジュールレベルのファイルはカスタマイズしません。ピンマックス、クロック、ファンカーブ、nvpmodel、PCIe、UPHY、USB、MGBE、またはカメラの差分には、該当する jetson-customize-* スキルを使用してください。

トラブルシューティング

• 「custom_carrier: ブロックがない」として拒否される — 再実行する前に、アクティブなプロファイルにブロックを宣言してください。このスキルが推測して補うことはありません。
• 「Linux_for_Tegra/ に .git がない」として拒否される — オーバーレイトラッカーが初期化されていません。まず /jetson-init-source を実行してください。
• 「<real-conf> がシンボリックリンクではない」 — NVIDIA の慣例では、<devkit>.conf は <carrier>-<module>-a<rev>.conf へのシンボリックリンクです。トップレベルが実際の conf の場合、このスキルは警告を出して実ファイルとして扱い、シンボリックリンクラッパーの行をスキップします。これはエラーではありません。
• sed は成功を報告したのに編集内容が反映されていない — sed は該当箇所が見つからない場合、何もせずに終了します。このスキルはパッチ適用後に毎回 grep で再確認し、検証に失敗した場合はコミットを拒否します。複数行の置換では Python の str.replace に切り替えてください。
• 「chip: unknown」または tegra234 へのフォールバック — モジュール ID がカタログにありません。プロファイルで上書きするのではなく、カタログを更新してください。
• コミットメッセージのプレビュー確認で実行が停止する — commit-batchingで定められた想定どおりのゲートです。承認、編集、またはキャンセルしてください。キャンセルした場合、インデックスはステージ済みのまま残るため、手動で解決してください。
• この BSP に必須のソースファイルがない — サマリーでは警告付きでスキップされたものとして記録されます。実行の残りの部分はそのまま完了します。