jetson-init-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Initialize BSP Image

初始化BSP镜像

Output is only

bsp_image:

in the active profile: derived

version

plus

root_path

only when overriding

<workspace>/Image

输出仅为当前配置文件中的

bsp_image:

：包含推导的

version

，仅当覆盖

<workspace>/Image

时才会添加

root_path

。

When to invoke

调用时机

The user asks to extract, prepare, or initialize the BSP image.
A downstream skill reports missing
```
<bsp_image.root_path>/Linux_for_Tegra/
```
.
The active profile has no
```
bsp_image:
```
block yet.

用户要求提取、准备或初始化BSP镜像时。
下游技能报告缺少
```
<bsp_image.root_path>/Linux_for_Tegra/
```
时。
当前配置文件中尚未存在
```
bsp_image:
```
块时。

Procedure

操作流程

Resolve target and image path

解析目标与镜像路径

Resolve the active profile per

../../context/target-platform-contract.md

. Refuse if there is no active profile or

reference_devkit:

is missing.

<workspace>

is the parent of the active profile's

target-platform/

directory.

<bsp_image.root_path>

defaults to

<workspace>/Image

Profile state	Action
`bsp_image.root_path` exists	Use it without prompting.
`bsp_image:` exists without `root_path`	Use `<workspace>/Image` .
No `bsp_image:` block	Ask once: Enter for default, or absolute override path.

For an override, validate that the closest existing parent is writable. Omit

root_path

when the default is used.

根据

../../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:` 块	询问一次：直接回车使用默认路径，或输入绝对路径进行覆盖。

若使用覆盖路径，需验证其最近的现有父目录是否可写入。使用默认路径时，省略

root_path

。

Determine GPU stack

确定GPU栈

Use the shared GPU-driver invariant from

../../context/target-platform-contract.md

. Derive the expected stack from

reference_devkit.module.id

and the catalogue:

Chip family	Module IDs	Stack	`apply_binaries.sh` flag
T234 / Orin	`p3701` , `p3767`	nvgpu	none
T264 and later / Thor+	`p3834`	OpenRM	`--openrm`

Refuse unknown module IDs. The

--openrm

flag is only valid on BSP releases that ship the OpenRM stack; if the active BSP doesn't expose the flag, omit it regardless of what the target wants.

使用

../../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不支持该参数，无论目标需求如何，均省略该参数。

Reuse or extract

复用或提取

<bsp_image.root_path>/Linux_for_Tegra/

already exists:

Do not extract over it unless the user explicitly requested re-extraction and accepted the overwrite risk.
Derive the on-disk version from
```
Linux_for_Tegra/nv_tegra_release
```
. Ask before replacing a different recorded
```
bsp_image.version
```
.
Verify the installed GPU stack against the platform-derived expectation when possible. Detection precedence (first probe that yields a definitive answer wins):
1. ```
Linux_for_Tegra/rootfs/etc/nv_tegra_release
```
  carries an
```
INSTALL_TYPE=
```
  token on BSP releases that expose it (newer lines). Read and compare directly.
2. Otherwise,
```
find Linux_for_Tegra -name nvgpu.ko
```
  : present → nvgpu, absent → OpenRM.
3. If the chip family has only ever shipped one stack (e.g. T234 / Orin is always nvgpu in current BSPs), fall back to the catalogue-derived expectation without disk probing.

If the installed stack conflicts with the active target, refuse and ask the user to re-extract with the correct stack or fix the target profile. Otherwise skip extraction and update the profile.

若

<bsp_image.root_path>/Linux_for_Tegra/

已存在：

除非用户明确要求重新提取并接受覆盖风险，否则不得覆盖现有内容。
从
```
Linux_for_Tegra/nv_tegra_release
```
推导磁盘上的版本。若与已记录的
```
bsp_image.version
```
不同，需询问用户后再替换。
尽可能验证已安装的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），则直接使用目录推导的预期结果，无需探测磁盘。

若已安装的栈与当前目标冲突，拒绝执行并要求用户重新提取正确的栈或修复目标配置文件。否则跳过提取步骤并更新配置文件。

Locate tarballs

定位压缩包

When extraction is needed, search:

```
<bsp_image.root_path>/
```
```
<workspace>/
```
current working directory

Prompt for absolute paths for anything missing. Required filenames:

```
Jetson_Linux_R<ver>_aarch64.tbz2
```

Tegra_Linux_Sample-Root-Filesystem_R<ver>_aarch64.tbz2

Both filenames must contain the same

R<ver>

token. Refuse mismatches and record

<ver>

bsp_image.version

. Do not download tarballs.

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

```
<bsp_image.root_path>/
```
```
<workspace>/
```
当前工作目录

若缺少文件，提示用户输入绝对路径。所需文件名：

```
Jetson_Linux_R<ver>_aarch64.tbz2
```

Tegra_Linux_Sample-Root-Filesystem_R<ver>_aarch64.tbz2

两个文件名必须包含相同的

R<ver>

标记。若版本不匹配则拒绝执行，并将

<ver>

记录为

bsp_image.version

。不提供压缩包下载功能。

Extract and apply binaries

提取并应用二进制文件

Use absolute tarball paths; they may live outside

<bsp_image.root_path>

bash

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

Set

GPU_STACK

from the "Determine GPU stack" step above. Abort on the first failing command and surface the failed command.

使用压缩包的绝对路径；它们可能位于

<bsp_image.root_path>

之外。

bash

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_STACK

的值来自“确定GPU栈”步骤。若任一命令执行失败则终止操作，并显示失败的命令。

Update the active profile

更新当前配置文件

Persist the resolved BSP image metadata in the active target profile so later skills can find the BSP without re-prompting. Preserve existing blocks, comments, and quoted SKU values; use a round-tripping YAML writer such as

ruamel.yaml

yaml

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

Rules:

Same version and same root path: no rewrite.
Different version: ask before updating.
Different recorded
```
root_path
```
: refuse automatic rewrite.
Always quote
```
version
```
.

将解析后的BSP镜像元数据持久化到当前目标配置文件中，以便后续技能无需重新提示即可找到BSP。保留现有块、注释和带引号的SKU值；使用支持往返的YAML写入工具（如

ruamel.yaml

）。

yaml

bsp_image:
  root_path: <absolute override path>  # 使用<workspace>/Image时省略
  version: "<derived version>"

规则：

版本和根路径均相同：不重写。
版本不同：询问用户后再更新。
已记录的
```
root_path
```
不同：拒绝自动重写。
```
version
```
始终需加引号。

Finish

完成

Report the image path, extracted vs reused state, GPU stack, derived version, and profile update status. Then suggest

/jetson-init-source

报告镜像路径、提取/复用状态、GPU栈、推导的版本以及配置文件更新状态。然后建议使用

/jetson-init-source

。

Purpose

目的

Materialize

Linux_for_Tegra/

on disk by extracting the right Jetson Linux + sample-rootfs tarballs and running

apply_binaries.sh

with the GPU-stack flag derived from the active target (nvgpu for T234, OpenRM for T264+). Then commit the derived BSP version into the profile's

bsp_image:

block.

通过提取正确的Jetson Linux和sample-rootfs压缩包，并根据当前目标推导的GPU栈参数（T234使用nvgpu，T264+使用OpenRM）运行

apply_binaries.sh

，在磁盘上生成

Linux_for_Tegra/

目录。然后将推导的BSP版本提交到配置文件的

bsp_image:

块中。

Prerequisites

前提条件

Active target profile resolved per

../../context/target-platform-contract.md

Jetson Linux BSP tarball and matching sample-rootfs tarball staged on disk (e.g. by
```
/jetson-download-bsp
```
or hand-placed).
Write access to the workspace
```
Image/
```
root (or the override
```
bsp_image.root_path
```
).
```
sudo
```
available for
```
apply_binaries.sh
```
.

已根据
```
../../context/target-platform-contract.md
```
解析出当前目标配置文件。
Jetson Linux BSP压缩包和匹配的sample-rootfs压缩包已存放在磁盘上（例如通过
```
/jetson-download-bsp
```
或手动放置）。
对工作区
```
Image/
```
根目录（或覆盖的
```
bsp_image.root_path
```
）具有写入权限。
可使用
```
sudo
```
执行
```
apply_binaries.sh
```
。

Limitations

限制

Writes only the
```
bsp_image:
```
block; source tree, documents, and carrier profile are owned by sibling skills.
Refuses to overwrite an existing
```
Linux_for_Tegra/
```
without explicit user direction.
Does not download tarballs; rely on
```
/jetson-download-bsp
```
or hand-stage the inputs.

仅写入
```
bsp_image:
```
块；源码树、文档和载体配置文件由同级技能负责。
若无明确用户指令，拒绝覆盖已存在的
```
Linux_for_Tegra/
```
目录。
不提供压缩包下载功能；依赖
```
/jetson-download-bsp
```
或手动准备输入文件。

Troubleshooting

故障排除

apply_binaries.sh
exits non-zero — re-read its console output; most failures are missing
```
sudo
```
, missing rootfs tarball, or wrong GPU stack flag for the SoC generation.
nv_tegra_release
absent after extract — extraction stopped early; verify tarball integrity and rerun.
Recorded
version
disagrees with the tarball filename — the tarball was renamed; trust the value parsed from
```
Linux_for_Tegra/nv_tegra_release
```
over filenames.
Different recorded
root_path
already in profile — refuse and ask the user to confirm before overwriting.

apply_binaries.sh
非零退出 — 重新查看其控制台输出；大多数失败原因是缺少
```
sudo
```
、缺少rootfs压缩包或针对SoC世代使用了错误的GPU栈参数。
提取后缺少
nv_tegra_release
— 提取过程提前终止；验证压缩包完整性后重新运行。
已记录的
version
与压缩包文件名不一致 — 压缩包已被重命名；优先信任从
```
Linux_for_Tegra/nv_tegra_release
```
解析的值，而非文件名。
配置文件中已存在不同的
root_path
记录 — 拒绝执行，要求用户确认后再覆盖。

References

参考资料

../../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
```

../../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
```