jetson-init-image

Initialize BSP Image

Output is only bsp_image: in the active profile: derived version
plus root_path only when overriding <workspace>/Image.

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.

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.

Determine GPU stack

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.

Reuse or extract

If <bsp_image.root_path>/Linux_for_Tegra/ already exists:

1. Do not extract over it unless the user explicitly requested
   re-extraction and accepted the overwrite risk.

2. Derive the on-disk version from Linux_for_Tegra/nv_tegra_release.
   Ask before replacing a different recorded bsp_image.version.

3. 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.

Locate tarballs

When extraction is needed, search:

1. <bsp_image.root_path>/
2. <workspace>/
3. 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> as bsp_image.version. Do not download tarballs.

Extract and apply binaries

Use absolute tarball paths; they may live outside
<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

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

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.

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.

Finish

Report the image path, extracted vs reused state, GPU stack, derived
version, and profile update status. Then suggest /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.

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.

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.

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.

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