jetson-init-image

初始化 BSP 镜像

输出仅包含活动配置文件中的 bsp_image:：派生的 version 以及仅在覆盖 <workspace>/Image 时才包含的 root_path。

调用时机

• 用户要求提取、准备或初始化 BSP 镜像。
• 下游技能报告缺少 <bsp_image.root_path>/Linux_for_Tegra/。
• 活动配置文件尚无 bsp_image: 块。

流程

解析目标和镜像路径

根据 ../../context/target-platform-contract.md 解析活动配置文件。如果没有活动配置文件或缺少 reference_devkit:，则拒绝操作。

<workspace> 是活动配置文件的 target-platform/ 目录的父目录。<bsp_image.root_path> 默认为 <workspace>/Image。

配置文件状态	操作
bsp_image.root_path 存在	使用该路径，无需询问。
bsp_image: 存在但没有 root_path	使用 <workspace>/Image。
没有 bsp_image: 块	询问一次：按 Enter 使用默认路径，或输入绝对覆盖路径。

如果使用覆盖路径，请验证最近的现有父目录可写。 使用默认路径时，省略 root_path。

确定 GPU 栈

使用 ../../context/target-platform-contract.md 中的共享 GPU 驱动不变量。根据 reference_devkit.module.id 和目录派生预期的栈：

芯片系列	模块 ID	栈	apply_binaries.sh 标志
T234 / Orin	p3701、p3767	nvgpu	无
T264 及更高版本 / Thor+	p3834	OpenRM	--openrm

对于未知模块 ID，拒绝操作。--openrm 标志仅适用于提供 OpenRM 栈的 BSP 版本；如果活动 BSP 未提供该标志，则无论目标需要什么，都应省略该标志。

复用或提取

如果 <bsp_image.root_path>/Linux_for_Tegra/ 已存在：

1. 除非用户明确要求重新提取并接受覆盖风险，否则不要提取覆盖现有内容。

2. 从 Linux_for_Tegra/nv_tegra_release 派生磁盘上的版本。如果记录的 bsp_image.version 不同，请先询问是否替换。

3. 尽可能根据平台派生的预期验证已安装的 GPU 栈。检测优先级如下（第一个得出明确结果的探测方式优先）：

   1. 在提供该信息的 BSP 版本（较新的版本系列）中，Linux_for_Tegra/rootfs/etc/nv_tegra_release 包含 INSTALL_TYPE= 标记。直接读取并比较。
   2. 否则，执行 find Linux_for_Tegra -name nvgpu.ko：存在则为 nvgpu，不存在则为 OpenRM。
   3. 如果该芯片系列历来只提供一种栈（例如，当前 BSP 中的 T234 / Orin 始终使用 nvgpu），则无需探测磁盘，回退到目录派生的预期。

如果已安装的栈与活动目标不符，则拒绝操作，并请用户使用正确的栈重新提取或修正目标配置文件。否则，跳过提取并更新配置文件。

查找 tar 包

需要提取时，按以下顺序搜索：

1. <bsp_image.root_path>/
2. <workspace>/
3. 当前工作目录

对于任何缺失的文件，请提示用户提供绝对路径。所需文件名：

• Jetson_Linux_R<ver>_aarch64.tbz2
• Tegra_Linux_Sample-Root-Filesystem_R<ver>_aarch64.tbz2

两个文件名必须包含相同的 R<ver> 标记。如果不匹配，则拒绝操作，并将 <ver> 记录为 bsp_image.version。不要下载 tar 包。

提取并应用二进制文件

使用 tar 包的绝对路径；它们可以位于 <bsp_image.root_path> 之外。

ROOT="<bsp_image.root_path>"
BSP_TARBALL="<absolute path to Jetson_Linux_R<ver>_aarch64.tbz2>"
ROOTFS_TARBALL="<absolute path to Tegra_Linux_Sample-Root-Filesystem_R<ver>_aarch64.tbz2>"

mkdir -p "$ROOT"
tar xjf "$BSP_TARBALL" -C "$ROOT"
sudo tar xpjf "$ROOTFS_TARBALL" -C "$ROOT/Linux_for_Tegra/rootfs"

cd "$ROOT/Linux_for_Tegra"
if [ "$GPU_STACK" = "openrm" ]; then
  sudo ./apply_binaries.sh --openrm
else
  sudo ./apply_binaries.sh
fi

根据上面的“确定 GPU 栈”步骤设置 GPU_STACK。首条命令失败时立即中止，并显示失败的命令。

更新活动配置文件

将解析出的 BSP 镜像元数据写入活动目标配置文件，以便后续技能查找 BSP，而无需再次提示。保留现有区块、注释和带引号的 SKU 值；使用 ruamel.yaml 等支持往返读写的 YAML 写入器。

bsp_image:
  root_path: <absolute override path>  # omit for <workspace>/Image
  version: "<derived version>"

规则：

• 版本和根路径相同：不重写。
• 版本不同：更新前先询问。
• 记录的 root_path 不同：拒绝自动重写。
• 始终为 version 加引号。

完成

报告镜像路径、提取或复用状态、GPU 堆栈、派生版本和配置文件更新状态。然后建议运行 /jetson-init-source。

用途

通过提取正确的 Jetson Linux 和 sample-rootfs tarball，并使用根据活动目标派生的 GPU 堆栈标志（T234 使用 nvgpu，T264+ 使用 OpenRM）运行 apply_binaries.sh，在磁盘上生成 Linux_for_Tegra/。然后将派生的 BSP 版本写入配置文件的 bsp_image: 区块。

前置条件

• 已根据 ../../context/target-platform-contract.md 解析活动目标配置文件。
• Jetson Linux BSP tarball 和匹配的 sample-rootfs tarball 已暂存到磁盘上（例如通过 /jetson-download-bsp 下载或手动放置）。
• 对工作区 Image/ 根目录（或覆盖路径 bsp_image.root_path）具有写入权限。
• apply_binaries.sh 需要 sudo。

限制

• 仅写入 bsp_image: 区块；源代码树、文档和载板配置文件由相关技能负责。
• 若已存在 Linux_for_Tegra/，除非用户明确指示，否则拒绝覆盖。
• 不会下载 tarball；请使用 /jetson-download-bsp 或手动暂存输入文件。

故障排除

• apply_binaries.sh 以非零状态退出 — 重新查看其控制台输出；多数故障是由于缺少 sudo、缺少 rootfs tarball，或 SoC 代际对应的 GPU 堆栈标志不正确。
• 提取后缺少 nv_tegra_release — 提取提前停止；请验证 tarball 完整性并重新运行。
• 记录的 version 与 tarball 文件名不一致 — tarball 曾被重命名；请以从 Linux_for_Tegra/nv_tegra_release 解析出的值为准，而非文件名。
• 配置文件中已记录了不同的 root_path — 拒绝覆盖，并在覆盖前请用户确认。

参考资料

• ../../context/target-platform-contract.md
• ../../references/bsp-platforms-catalogue.md
• ../../references/platform_template.yaml
• ../jetson-init-target/SKILL.md
• ../jetson-init-source/SKILL.md
• ../jetson-flash-image/SKILL.md