jetson-init-source

BSP カスタマイズワークスペースの初期化

概要

このスキルは、customize-* / build スキルが依存するソース側のワークスペースをブートストラップします。対象は、Linux_for_Tegra オーバーレイトラッカー（初期状態とカスタマイズのコミットを管理する git リポジトリ）、bsp_sources/ モノツリー（カーネル、OOT、nvgpu、ディスプレイ、hwpm、ハードウェア DT）、および動作する NVIDIA Crosstool-NG クロスコンパイル用プレフィックスです。このスキルが管理するのは、アクティブなプロファイルの source: ブロックと、<source.root_path>（デフォルト：<workspace>/Source）配下のディスク上のソースワークスペースのみです。

担当する内容：

1. デフォルト以外の source.root_path を任意で記録します。
2. Linux_for_Tegra オーバーレイトラッカーを作成またはマウントします。
3. 「BSP ソースのベースラインを具体化する」手順の優先順位に従って、bsp_sources を具体化します。
4. source.toolchain を解決して記録します。
5. source.repos: から、ユーザーが追加で指定したリポジトリをクローンします。

呼び出すタイミング

• ユーザーが BSP カスタマイズワークスペースのブートストラップ、初期化、または同期を求めたとき。
• 下流のカスタマイズスキルが「no workspace tracker at <source.root_path>/Linux_for_Tegra/」として処理を拒否したとき。
• jetson-init-image の後（新しいターゲットで Setup が次に実行する手順）。

手順

クイックスタートの事前入力マッピング

共通の quick_start_prefill contract に従います。このスキル固有のマッピングは次のとおりです。

• quick_start_prefill.source.public_sources_archive は、Branch-A アーカイブ候補に対応します。
• quick_start_prefill.source.repos は、提案された source.repos: エントリに対応します。書き込む前に、予約キーと url: / archive: の相互排他を検証します。
• quick_start_prefill.source.toolchain には、クロスコンパイル用プレフィックス、gcc パス、bin/ ディレクトリのパス、x-tools.tbz2 アーカイブのパス、または skip を指定できます。

このスキルのみが、プロファイルの source.root_path、source.repos:、source.toolchain の書き込みを担当します。

アクティブなターゲットとパスを解決する

../../context/target-platform-contract.md の契約に従って、アクティブなプロファイルとワークスペースのデフォルトを解決します。

• <bsp_image.root_path> に Linux_for_Tegra/ が含まれていない場合は、処理を拒否します（BSP が展開されていません。/jetson-init-image に案内してください）。
• プロファイルに source.root_path: がある場合は、その値を使用します。ない場合、<source.root_path> のデフォルトは <workspace>/Source です。このデフォルトをそのまま使用し、プロファイルに source.root_path: を書き込みません。明示的なカスタムパスの指定、デフォルトパスに無関係な内容がある場合、または親ディレクトリに書き込み権限がない場合に限り、質問してください。

存在する場合は source.repos: を読み込み、各エントリの名前をキーとするマップにします。各エントリには、任意の url、ref、subdir、path を保持します。予約キーは Linux_for_Tegra（オーバーレイトラッカー）と bsp_sources（カーネルソースリポジトリ）です。それ以外のキーは、すべてユーザーが追加で指定したリポジトリです。

（任意）source.root_path の上書きを確認する

プロファイルに source.root_path がなく、かつ上記の上書き条件のいずれかに該当する場合に限ります。

source.root_path：デフォルト = <workspace>/Source。デフォルトを使用する場合は Enter キーを押し、上書きする場合は絶対パスを入力してください。

• Enter キーを押した場合 — デフォルトを使用し、プロファイルには触れません。
• 上書きパスを入力した場合 — 最も近い既存の親ディレクトリが書き込み可能であることを検証します。書き込み不可の場合は拒否し、再入力を求めます。target-platform/<active>.yaml を直接編集して source.root_path: を追加または更新します。他のブロック、コメント、引用符はすべて保持してください（例：ruamel.yaml などの往復可能な YAML ローダーを使用）。

この確認は、プロファイルごとに最大 1 回だけ行います。それ以外の場合は、必要に応じて <workspace>/Source を作成し、確認せずに続行します。

Linux_for_Tegra を具体化する

マウント先は正規のパスである <source.root_path>/Linux_for_Tegra/ です。

デフォルト（source.repos.Linux_for_Tegra エントリがない場合）：

LFT="<source.root_path>/Linux_for_Tegra"
mkdir -p "$LFT"
[ -d "$LFT/.git" ] || git -C "$LFT" init

空のトラッカーです。ここでは何もコミットしないでください — 初期状態のインポートは、カスタマイズスキルの実行時にファイル単位で行われます。

上書き（url、ref、任意の subdir）：

# Clone the user's repo to a side location, then mount the
# expected tree (subdir or repo root) at the canonical path.
CLONE="<source.root_path>/.repos/Linux_for_Tegra"
git clone <url> -b <ref> "$CLONE"
ln -s "$CLONE/<subdir or .>" "<source.root_path>/Linux_for_Tegra"

マウント先がすでに有効な git 状態にある場合はスキップします。無関係な内容が存在する場合は処理を拒否します。

BSP-sources ベースラインのマテリアライズ

source.repos.bsp_sources のプロファイルエントリーに対して、優先順位順に次の3つのブランチを選択します。

順序	プロファイルの状態	ブランチ
1	url: が設定されている	C. 顧客の git クローン（明示的なオーバーライドが常に優先されます）
2	archive: が設定されている、または エントリーがなく、かつ <workspace>/Downloads/public_sources.tbz2 が存在する	A. ローカルアーカイブの展開（デフォルト）
3	エントリーがなく、ローカルアーカイブもない	B. source_sync.sh（フォールバック）

url: と archive: は相互に排他的です。同じエントリーに両方が設定されている場合は拒否してください。

ブランチ A は、NVIDIA の git 外向き通信を完全に回避できるため、デフォルトとして推奨されます（Setup で最もよく発生する失敗要因です）。ブランチ B は、事前にダウンロードした tarball がない新しいワークスペース向けです。ブランチ C は、BSP レイアウト全体の顧客フォーク向けです。

ブランチ A — ローカルアーカイブの展開（デフォルト）

デフォルトのブランチでは、事前にダウンロードした public_sources.tbz2 を <source.root_path>/bsp_sources/ に単一のモノレポとして展開します（git init + 初期コミット）。アーカイブの構成、パス解決ルール、展開スクリプト（R36.x 向けの Tegra OOT Makefile 強制置換の回避策を含む）の詳細については、references/branch-a-extraction.md を参照してください。

ブランチ B と C では、コンポーネントごとに別のリポジトリが作成される場合もあります。後続のビルドロジックは引き続き、<source.root_path>/bsp_sources/ 以下の正規サブパスを参照します。

ブランチ B — source_sync.sh（フォールバック）

ローカルアーカイブが見つからず、url: も設定されていない場合にのみ実行します。<source.root_path> の下に bsp_sources/ のマウントディレクトリを作成し、展開済みの BSP から2つのフラグを指定して source_sync.sh を実行します。

mkdir -p "<source.root_path>/bsp_sources"
bash "<bsp_image.root_path>/Linux_for_Tegra/source/source_sync.sh" \
     -d "<source.root_path>/bsp_sources" \
     -t "jetson_<major.minor>"

• -d <source.root_path>/bsp_sources — クローンをワークスペースの bsp_sources/ サブディレクトリに書き込み、ディスク上のフォルダー名をスキーマキーと一致させます。-d を指定しないと、スクリプトは自身のディレクトリ（BSP 自体）の下に書き込みます。これはオーバーレイモデルでは誤りです。
• -t jetson_<major.minor> — タグを BSP のリリース系列に固定します。bsp_image.version をもとに、ピリオドで区切られた先頭2つの要素までに短縮します。例："38.4.0" → jetson_38.4。タグ形式のフォールバック：拒否された場合は jetson_<bsp_image.version> を試します（古い L4T では完全な形式が使われることがあります）。それも失敗した場合は、エラーを表示して停止してください。「latest」への暗黙のフォールバックは絶対に行わないでください。

source_sync.sh が存在しない場合は拒否し、/jetson-init-image を再実行して Linux_for_Tegra/source/ を再作成してください。

source_sync.sh は、すべてのクローンに失敗した場合でも終了コード 0 を返します。出力にある Failed to clone の行数を数えて確認し、0 以外なら拒否してください。すべてのクローンが失敗する最も可能性の高い原因は、gitlab.com/nvidia/nv-tegra / nv-tegra.nvidia.com への git 外向き通信がブロックされていることです。その旨を明示し、ブランチ A を使うため、/quick-start 経由で public_sources.tbz2 をダウンロードするようユーザーに案内してください。

ブランチ C — 顧客の git クローン（url: オーバーライド）

明示的な url: フィールドがある場合に実行します。顧客のリポジトリを一度クローンし、その正規のカーネル側サブパスを <source.root_path>/bsp_sources/ の下に公開します。正規サブパスの一覧は、実行時に source_sync.sh の SOURCE_INFO から読み取ります。今後の NVIDIA による追加や削除を自動的に反映できるよう、一覧をハードコードしないでください。

# Parse canonical sub-paths from source_sync.sh's SOURCE_INFO
# (only the kernel-side entries marked `k:` in the second field).
SUBPATHS=$(grep -oP '^\s*k:[^:]+:' \
  "<bsp_image.root_path>/Linux_for_Tegra/source/source_sync.sh" \
  | sed 's/^\s*k://; s/:$//')

mkdir -p "<source.root_path>/bsp_sources"
CLONE="<source.root_path>/.repos/bsp_sources"
git clone <url> -b <ref> "$CLONE"
ROOT="$CLONE/<subdir or .>"
for SUB in $SUBPATHS; do
  [ -d "$ROOT/$SUB" ] && \
    ln -s "$ROOT/$SUB" "<source.root_path>/bsp_sources/$SUB"
done

有効なチップファミリーで必要とされる正規サブパスが顧客のリポジトリ内に存在しない場合は、その旨を報告してください（警告にとどめ、拒否はしないでください。顧客がすべてのリポジトリを持っていないことは正当な場合があります）。

クロスコンパイルツールチェーンを解決する

後続の jetson-build-source は、このプロファイルから source.toolchain を読み取り、CROSS_COMPILE としてエクスポートします。init-source が終了する前に有効なプレフィックスを設定する必要があります。設定されていない場合、それ以降のカーネル、OOT、DT のビルドは拒否されます。

NVIDIA 公式の Crosstool-NG Toolchain gcc は、L4T の標準ツールチェーンです。x-tools.tbz2 のネットワーク取得は jetson-download-bsp が担当します。このスキルは、解決済みのプレフィックスの検出、展開、検証、書き込みのみを行います。解決は次の3段階で進みます。

自動検出

<workspace>/toolchain/x-tools/ 内から、Crosstool-NG のレイアウトを探します。通常は次のいずれかです。

<workspace>/toolchain/x-tools/aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu-gcc
<workspace>/toolchain/x-tools/aarch64-buildroot-linux-gnu/bin/aarch64-buildroot-linux-gnu-gcc

Glob: <workspace>/toolchain/x-tools/aarch64-*-linux-gnu/bin/aarch64-*-linux-gnu-gcc。 一致するものがちょうど 1 つの場合は、次のように設定します。

TC_PREFIX=<absolute path to that .../bin/<triple>->   # trailing dash mandatory

下記の「プロファイルに書き込む」に進みます。一致するものが 0 件の場合は、下記の「Downloads/x-tools.tbz2 から自動展開する」に進みます。複数ある場合は、一覧を示して不要なものを削除するようユーザーに求めます（インストールが曖昧な場合に、こちらで黙って 1 つを選ぶことはありません。Crosstool-NG の異なるバリエーションでは、ABI に互換性のないバイナリが生成されるためです）。

Downloads/x-tools.tbz2 から自動展開する

<workspace>/Downloads/x-tools.tbz2 が存在する場合（「BSP ソースのベースラインを準備する」ステップにおける Branch-A パターンの public_sources.tbz2 と同じです。インターネット接続がない／外部への接続ができないユーザーは、ここにアーカイブを配置します）。

file -b "<workspace>/Downloads/x-tools.tbz2" | grep -q "bzip2 compressed" || \
  refuse "<workspace>/Downloads/x-tools.tbz2 is not a bzip2 tarball"
mkdir -p "<workspace>/toolchain"
tar xjf "<workspace>/Downloads/x-tools.tbz2" -C "<workspace>/toolchain"

その後、上記の「自動検出」を再実行します。展開に成功しても x-tools/aarch64-*-linux-gnu/bin/ が生成されない場合は拒否します（アーカイブの内容が Crosstool-NG のレイアウトに一致しません）。

ユーザーに尋ねる

自動検出と自動展開の両方で見つからなかった場合は、次のように尋ねます。

<workspace>/toolchain/ 内にも <workspace>/Downloads/x-tools.tbz2 内にも、Crosstool-NG ツールチェーンが見つかりません。

次のいずれかで返信してください。

• aarch64-*-linux-gnu-gcc バイナリの絶対パス、またはそれを含む bin/ ディレクトリの絶対パス
• 中止するには cancel

代わりにアーカイブを取得するには、この実行をキャンセルし、 /jetson-download-bsp を実行してから、/jetson-init-source を再実行してください。

パスで返信された場合は、[ -f "${TC_PREFIX}gcc" ] で検証します。失敗した場合は拒否して、再度入力を求めます。

プロファイルに書き込む

$TC_PREFIX が解決され、${TC_PREFIX}gcc が存在する場合は、ラウンドトリップ可能な YAML ローダーを使って、アクティブなプロファイルに書き込みます。

source:
  toolchain: <TC_PREFIX>   # absolute, with trailing dash

source: がほかに空（root_path のオーバーライドも repos: エントリもない）場合、source: ブロックは空ではなくなり、プロファイルに保持されます。以降の jetson-init-source の実行では、source.toolchain がすでに設定されており、動作する gcc を指している場合、「クロスコンパイルツールチェーンを解決する」ステップはスキップされます。

ユーザー定義の追加リポジトリをクローンする

source.repos: 内にある、名前が Linux_for_Tegra または bsp_sources ではない各エントリについて、次のようにします。

MOUNT="<source.root_path>/<entry.path or entry.name>"
if [ -n "<entry.subdir>" ]; then
  CLONE="<source.root_path>/.repos/<entry.name>"
  git clone <entry.url> -b <entry.ref> "$CLONE"
  ln -s "$CLONE/<entry.subdir>" "$MOUNT"
else
  git clone <entry.url> -b <entry.ref> "$MOUNT"
fi

マウントパスに無関係なコンテンツがすでに存在する場合は拒否します。

概要

次の内容を表示します。

• 解決した <workspace>、<bsp_image.root_path>、<source.root_path>。
• 準備した各コンポーネントについて、作成、再利用、スキップ、または拒否のいずれか。
• bsp_sources について、選択したブランチと主な根拠（アーカイブのパス、source_sync.sh の失敗回数、またはクローン URL／ref）。
• ツールチェーンのプレフィックス、解決元、${TC_PREFIX}gcc --version の先頭行。
• customize-* スキルでは、今後の BSP の編集を <source.root_path>/Linux_for_Tegra/ にステージングし、後でコミット済みのオーバーレイ変更を bsp_image にコピーするのは promote であることをリマインドします。

下流のスキルによってこの実行が開始された場合は、元のリクエストをもう一度送信するようユーザーに伝えます。

注意事項

• Linux_for_Tegra と bsp_sources のマウントパスは標準です。 path: は追加のユーザー定義リポジトリにのみ適用されます。
• デフォルトの Linux_for_Tegra トラッカーは意図的に空のままです。事前にデータを入力しないでください。
• bsp_sources の優先順位は url: → archive: → 自動検出された Downloads/public_sources.tbz2 → source_sync.sh です。url: と archive: は相互に排他的です。
• Branch A の自動検出ではプロンプトは表示されず、プロファイルにも書き戻されません。永続化するには source.repos.bsp_sources.archive: のみを使用してください。
• Branch A の $DEST/Makefile の衝突。 public_sources.tbz2 内の tarball には、Tegra オーケストレーター（kernel_oot_modules_src.tbz2）と dGPU/OpenRM 独自の Makefile（nvidia_kernel_display_driver_source_without_ root_dir.tbz2）という、Makefile という名前のファイルが 2 つ含まれています。アルファベット順に展開されるため、R36.x では dGPU 側のファイルが優先され、その後の arm64 クロスビルドで '-mlittle-endian' unrecognized エラーが発生します。手順 3a では、Tegra の modules: hwpm nvidia-oot nvgpu nvidia-display シグネチャが見つからない場合、<bsp_image>/Linux_for_Tegra/source/Makefile から強制的に置き換えます。R38 以降の展開内容はすでに一致しているため、このチェックは何も行いません。
• Branch C の顧客リポジトリは、必要に応じて subdir: で位置をずらした、標準の source_sync.sh サブパス構成を公開する必要があります。
• bsp_image.version から source_sync.sh のタグを導出する際は、まず jetson_<major.minor> を使用してください。ピン留めされていない最新バージョンには絶対にフォールバックしないでください。
• jetson-download-bsp が public_sources.tbz2 と x-tools.tbz2 のネットワークダウンロードを担当します。このスキルではローカルのアーカイブのみを使用します。
• source.toolchain は末尾にハイフンが付いた NVIDIA Crosstool-NG プレフィックスであり、${prefix}gcc が動作する必要があります。$PATH を暗黙的に使用しないでください。
• プロファイルを編集する際は、ラウンドトリップ可能な YAML ライターを使用してください。

前提条件

• ../../context/target-platform-contract.md に従ってアクティブなターゲットプロファイルが解決されていること。
• bsp_image.version が記録されるように /jetson-init-image がすでに実行されていること（Branch B の source_sync.sh タグはこの値から導出されます）。
• Branch A の場合：ローカルの public_sources.tbz2（および任意で x-tools.tbz2）が Downloads/ 配下に配置されていること。
• Branch C の場合：顧客の Git リポジトリの URL にアクセスできること。

制限事項

• source: ブロックのみを管理します。bsp_image、 reference_devkit、custom_carrier、documents は編集しません。
• ネットワークへの外部接続は Branch B（source_sync.sh）と Branch C （顧客の Git クローン）のみです。Branch A は完全にオフラインです。
• システムのツールチェーンへの暗黙的な置き換えは行いません。NVIDIA Crosstool-NG プレフィックスが存在するか、展開可能である必要があります。

トラブルシューティング

• ${toolchain}gcc が見つからない — Downloads/ 配下に x-tools.tbz2 を再配置して再実行するか、検証済みの絶対パスのプレフィックスを渡してください。
• source_sync.sh で jetson_<major.minor> タグを解決できない — 記録された bsp_image.version が誤っています。/jetson-init-image を再実行して更新してください。
• Linux_for_Tegra/.git に未コミットの手編集が表示される — 中止して、ユーザーにコミットまたはスタッシュを依頼してください。このスキルではトラッカーがクリーンであることを前提としています。
• Branch C のクローンに標準のサブパスがない — リポジトリの構成が source_sync.sh と一致していません。subdir: に正しいサブルートを設定するか、source.repos: による複数リポジトリのオーバーライドに切り替えてください。

参考資料

• ../../references/platform_template.yaml — repos: マップを含む source: スキーマ。
• ../../context/target-platform-contract.md — ターゲットプラットフォームの契約。
• ../../context/bsp-customization-workflow.md — ワークスペース編集プロトコル。
• ../jetson-init-target/SKILL.md — このスキルが使用するプロファイルを作成します。
• ../jetson-init-image/SKILL.md — BSP を展開し、bsp_image.version を補完します。このスキルの実行前に実行してください。