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-sources 基线”步骤中的优先级物化 bsp_sources。
4. 解析并记录 source.toolchain。
5. 克隆 source.repos: 中额外的用户自定义仓库。

何时调用

• 用户要求引导、初始化或同步 BSP 定制工作区时。
• 下游定制技能因“在 <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:。保留所有其他块、注释和引号格式——使用可往返处理的 YAML 加载器（例如 ruamel.yaml）。

每个配置文件最多触发一次。否则，按需创建 <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 选择以下三个分支之一：

顺序	配置文件状态	分支
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 布局的客户 fork。

分支 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 中使用两个标志运行 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 中前两个以点分隔的部分来生成："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 行的数量进行验证；如果数量非零，则拒绝执行。全部失败最可能的原因是到 gitlab.com/nvidia/nv-tegra / nv-tegra.nvidia.com 的 Git 出站流量受阻；请明确指出这一点，并引导用户通过 /quick-start 下载 public_sources.tbz2，以使用分支 A。

分支 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 的规范工具链。jetson-download-bsp 负责通过网络获取 x-tools.tbz2；此技能只负责发现、解压、验证并写入解析出的前缀。解析按以下三级流程进行：

自动发现

在 <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。 如果恰好有一个匹配项，则绑定：

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

跳转到下方的“写入配置文件”。如果没有匹配项，则继续执行下方的“从 Downloads/x-tools.tbz2 自动提取”。如果有多个匹配项，则拒绝并列出这些匹配项，请用户删除不需要的项（我们绝不会在存在歧义的安装项中擅自选择一个——不同的 Crosstool-NG 变体会生成 ABI 不兼容的二进制文件）。

从 Downloads/x-tools.tbz2 自动提取

如果 <workspace>/Downloads/x-tools.tbz2 存在（遵循“Materialize the BSP-sources baseline”步骤中 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/引用）。
• 工具链前缀、解析来源，以及 ${TC_PREFIX}gcc --version 的第一行。
• 提醒用户，customize-* 技能会将后续 BSP 编辑暂存到 <source.root_path>/Linux_for_Tegra/；之后由 promote 将已提交的覆盖更改复制到 bsp_image。

如果本次运行由下游技能触发，请告知用户重新发出原始请求。

注意事项

• Linux_for_Tegra 和 bsp_sources 的挂载路径是规范路径。 path: 仅适用于额外的用户自定义仓库。
• 默认的 Linux_for_Tegra 跟踪器有意保持为空；不要预先填充。
• bsp_sources 的优先级依次为 url: → archive: → 自动发现 Downloads/public_sources.tbz2 → source_sync.sh。url: 和 archive: 不能同时使用。
• 分支 A 的自动发现不会提示，也不会写回配置文件。只有通过 source.repos.bsp_sources.archive: 才能将其持久化。
• 分支 A 的 $DEST/Makefile 冲突。 public_sources.tbz2 中的内部 tar 包包含两个名为 Makefile 的文件：Tegra 编排文件（kernel_oot_modules_src.tbz2）和 dGPU/OpenRM 专有 Makefile（nvidia_kernel_display_driver_source_without_ root_dir.tbz2）。按字母顺序解压时，R36.x 上 dGPU 文件会覆盖另一个文件；随后下游 arm64 交叉编译会因 '-mlittle-endian' unrecognized 而失败。如果缺少 Tegra modules: hwpm nvidia-oot nvgpu nvidia-display 特征标记，步骤 3a 会强制从 <bsp_image>/Linux_for_Tegra/source/Makefile 替换该文件。R38+ 解压后的文件本来就正确；此处检查不会产生任何操作。
• 分支 C 的客户仓库必须提供规范的 source_sync.sh 子路径布局，也可以通过 subdir: 调整路径。
• 优先根据 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 解析活动目标配置文件。
• 已运行 /jetson-init-image，因此已记录 bsp_image.version （分支 B 的 source_sync.sh 标签由此推导）。
• 对于分支 A：已将本地 public_sources.tbz2（以及可选的 x-tools.tbz2）放在 Downloads/ 下。
• 对于分支 C：可访问客户 Git 覆盖仓库 URL。

限制

• 仅负责 source: 块；绝不修改 bsp_image、 reference_devkit、custom_carrier 或 documents。
• 仅分支 B（source_sync.sh）和分支 C（客户 Git 克隆）允许联网；分支 A 完全离线。
• 拒绝静默替换系统工具链——必须存在或可解压 NVIDIA Crosstool-NG 前缀。

故障排除

• 找不到 ${toolchain}gcc — 将 x-tools.tbz2 重新放入 Downloads/，然后重试；或者传入已验证的绝对前缀路径。
• source_sync.sh 无法解析 jetson_<major.minor> 标签 — 记录的 bsp_image.version 有误；重新运行 /jetson-init-image 以刷新该值。
• Linux_for_Tegra/.git 显示有未提交的手动修改 — 中止并 请用户提交或暂存更改；此技能要求跟踪器保持干净。
• 分支 C 克隆缺少规范子路径 — 仓库布局与 source_sync.sh 不匹配；将 subdir: 设为正确的子根目录，或回退到 source.repos: 下的多仓库覆盖配置。

参考资料

• ../../references/platform_template.yaml — source: 架构，包括 repos: 映射。
• ../../context/target-platform-contract.md — 目标平台契约。
• ../../context/bsp-customization-workflow.md — 工作区编辑协议。
• ../jetson-init-target/SKILL.md — 创建此技能所使用的配置文件。
• ../jetson-init-image/SKILL.md — 解压 BSP 并回填 bsp_image.version；请在运行此技能前执行。