jetson-promote-image

Promote BSP Image

Purpose

Stage every Customize-* and Build output into bsp_image so it is ready for /jetson-flash-image. This is the promote leg of Deploy — it copies files, never flashes and never builds.

Prerequisites

• Active target-platform profile with both source: and bsp_image: resolved (run /jetson-init-source and /jetson-init-image first).
• <source.root_path>/Linux_for_Tegra/ initialized as a git repo (overlay tracker) with a clean working tree.
• <bsp_image.root_path>/Linux_for_Tegra/ extracted from a BSP tarball + apply_binaries.sh already run.
• git, yq, cmp, and sudo (for rootfs/* destinations) on the host.
• <source.root_path>/.build-manifest.yaml + .build-state.yaml from /jetson-build-source (required when kernel-side repos have customize-* commits).

Overview

This is the promote leg of Deploy — see ../../context/bsp-customization-workflow.md for the pipeline view. The two channels this skill walks are:

The skill computes the union of files to copy and writes each into <bsp_image.root_path>/Linux_for_Tegra/ with diff-aware skip-if-identical logic. When the copy pass touches the kernel Image or anything under rootfs/lib/modules/, it also rebuilds the initramfs via NVIDIA's tools/l4t_update_initrd.sh so the freshly promoted kernel + modules ship in the initrd the bootloader actually loads. After it returns, bsp_image carries every Customize and Build output. The skill does not flash and does not modify the workspace.

When to invoke

• First leg of the typical Deploy chain jetson-promote-image → jetson-flash-image → jetson-validate-image.
• Standalone, when the user wants bsp_image updated but isn't ready to flash yet (e.g. to inspect resolved files, run an out-of-band build that reads bsp_image, or hand bsp_image to a separate flashing host).

Procedure

Resolve active target + paths

Resolve the active profile per the contract in ../../context/target-platform-contract.md.

Refuse and route in these cases:

Resolve paths:

• <workspace> = parent of the active profile's target-platform/ directory (discovered at load time).
• <bsp_image.root_path> from bsp_image.root_path: if present, else <workspace>/Image.
• <source.root_path> from source.root_path: if present, else <workspace>/Source.

Bind shell variables for the rest of the procedure:

LFT_SRC="<source.root_path>/Linux_for_Tegra"   # overlay tracker
LFT_DST="<bsp_image.root_path>/Linux_for_Tegra"
MANIFEST="<source.root_path>/.build-manifest.yaml"   # build outputs

Validate the two channels

The skill needs at least one channel populated. Refuse if the overlay tracker has uncommitted changes (status --porcelain non-empty), if $MANIFEST exists but doesn't parse as YAML, or if both channels are empty. Records OVERLAY_HAS_COMMITS / OVERLAY_HEAD and MANIFEST_PRESENT for downstream steps.

See references/copy-pass-snippets.md for the shell snippet and refuse messages.

Verify build-source freshness

Refuse if .build-state.yaml shows any kernel-side repo in Source/bsp_sources/ dirty since the last /jetson-build-source — otherwise the copy pass would silently ship stale artifacts. Detection rules + shell snippet in references/build-source-freshness-gate.md. Records BUILD_FRESH=1.

Pre-promote collision check (overlay only)

When the overlay tracks a remote, refuse if upstream has commits not yet pulled. Skip gracefully when no remote is configured (the default git init empty tracker from jetson-init-source). Manifest channel has no git remote concept — this check is overlay-only. Records COLLISION_CHECK for the Summary.

See references/copy-pass-snippets.md for the shell snippet.

Enumerate sources (both channels)

Channel A — overlay: git ls-files against $LFT_SRC is the source of truth (transparent to symlink mounts when source.repos.Linux_for_Tegra was overridden, excludes untracked / .gitignored files). Each entry maps src = $LFT_SRC/<rel> → dst = $LFT_DST/<rel>.

Channel B — manifest: parse artifacts[].{src,dst} from $MANIFEST. Refuse if any src is missing on disk (build was interrupted, or manifest stale — re-run /jetson-build-source). The manifest schema is written by jetson-build-source v0.2.0.

See references/copy-pass-snippets.md for both shell snippets and the manifest YAML schema.

Diff-aware copy into bsp_image

Iterate the union of overlay files and manifest entries. For each dst: if byte-identical, skip; otherwise cp -p (with sudo for rootfs/* destinations, where the sample rootfs was extracted as root). Tag INITRD_DIRTY=1 on any rootfs/lib/modules/* or kernel/Image write — the "Refresh initramfs" step gates on this flag. Counts / FIRST / LAST are recorded for the Summary.

Fail-fast: if any cp fails, surface the failed path and stop. bsp_image may be left partially updated — re-running after fixing the cause resumes via the diff-aware skip. Channel order is overlay first, then manifest: on a dst collision the manifest wins (freshly built artifact beats the older overlay copy).

See references/copy-pass-snippets.md for the copy_one() function and the two driving loops.

Mirror kernel Image into rootfs (when kernel changed)

The kernel Image lives in two paths inside bsp_image: <LFT_DST>/kernel/Image (read by the flash tool) and <LFT_DST>/rootfs/boot/Image (the rootfs-side copy, visible as /boot/Image from inside the rootfs chroot the refresh tool will run in). The build manifest only carries the kernel/Image dst, so this step mirrors kernel/Image → rootfs/boot/Image (diff-aware, no-op when already in sync) so the chrooted refresh tool resolves the kernel against the freshly promoted binary, not the stale rootfs copy. The mirror also sets INITRD_DIRTY=1 so a kernel-only promote (no rootfs/lib/modules/* writes) still triggers the refresh.

See references/kernel-image-and-initramfs.md for the shell snippet, the failure mode this prevents, and the INITRD_DIRTY corner case.

Refresh initramfs (when kernel or modules changed)

Run tools/l4t_update_initrd.sh from <LFT_DST>/ whenever INITRD_DIRTY=1 (set by the diff-aware copy or the mirror step above). The tool chroots into rootfs/, runs NVIDIA's nv-update-initrd, and writes both <LFT_DST>/bootloader/l4t_initrd.img (used by the flash tool) and <LFT_DST>/rootfs/boot/initrd (/boot/initrd on the DUT). Idempotent; ~30 s. Skip when INITRD_DIRTY=0 (overlay-only edits). DUT-side workarounds (update-initramfs -u + manual cp) are out of scope — fix the gap here so flash ships a coherent image.

See references/kernel-image-and-initramfs.md for the shell snippet, refuse paths, the "module shadowing" and "vermagic skew" failure modes the rebuild closes, and why bootloader/initrd (a different file) is left alone.

Summary

Report:

• Overlay scope: overlay HEAD ($OVERLAY_HEAD) or "(empty)".
• Manifest scope: mode=<...>, bsp_version=<...>, rebuilt_at=<...>, N artifacts or "(absent)".
• Collision check: $COLLISION_CHECK.
• Counts:
  • overlay: $COPIED_OVERLAY copied, $IDENTICAL_OVERLAY identical
  • manifest: $COPIED_MANIFEST copied, $IDENTICAL_MANIFEST identical
• Kernel Image mirror: $KIMG_MIRRORED and initramfs: $INITRD_STATUS (copied … / rebuilt when triggered by kernel/Image or rootfs/lib/modules/* writes; skipped … otherwise).
• First / last paths copied (omit if both COPIED totals are 0).
• Resolved <source.root_path>, <bsp_image.root_path>.
• Next step: /jetson-flash-image (or /jetson-validate-image if the user only wanted bsp_image refreshed for inspection / static validation).

Limitations

• Two channels, one destination. bsp_image/Linux_for_Tegra/ is written by both passes. Overlay carries customize-* outputs (overlay-only edits like nvfancontrol.conf); manifest carries rebuilt binaries (kernel/OOT/DT). The two are intentionally disjoint by construction: build outputs don't go into the overlay, and customize-* edits to non-build files don't enter the manifest.
• Build manifest is the trace-to-dirty contract. Anything in the manifest came from a dirty source repo (per jetson-build-source's "Write the build manifest" step trace policy). Promoting the manifest is therefore safe: every entry is a customization-bearing artifact, not toolchain-divergence noise. The skill does not re-derive the trace — it trusts the manifest.
• Manifest entries can outlive their build outputs. If the user wipes Source/.build/ or bsp_sources/'s build artifacts between jetson-build-source and jetson-promote-image, the manifest will reference missing files. The "Enumerate sources (both channels)" step refuses in that case and points the user at /jetson-build-source to rebuild.
• Manifest absence is fine when only overlay edits happened. A purely overlay-side customization (e.g. customize-fan) produces no build outputs and writes no manifest — the "Enumerate sources (both channels)" step is a no-op, the "Diff-aware copy into bsp_image" step promotes only overlay files. The skill prints "manifest: (absent)" in the summary and continues.
• Diff-aware, idempotent. Re-running with no overlay commits or manifest changes since the last promote is a no-op (all files identical). Use this to confirm bsp_image is in sync without side effects.
• Symlink-mount transparency. When source.repos.Linux_for_Tegra was overridden in jetson-init-source, the canonical mount is a symlink into <source.root_path>/.repos/Linux_for_Tegra/<subdir>. git -C, cp -p, and cmp -s all follow it transparently — no special handling needed at this layer. Manifest src paths are absolute, so symlinks under bsp_sources/ don't matter for the manifest channel.
• sudo is scoped to rootfs/ destinations. Files under rootfs/ were extracted with sudo tar xpjf by jetson-init-image, so they carry root ownership and special mode bits the flashing toolchain reads back. sudo cp -p preserves them. Everything else (bootloader/, kernel/, kernel/dtb/, tools/, etc.) is user-owned and does not need sudo. This applies to both channels.
• Channel-overlap precedence. If the same dst appears in both overlay and manifest, manifest wins (later in the "Diff-aware copy into bsp_image" step's loop). This is the desired semantic — manifest entries are freshly built, overlay entries may be older state. Hand-editing binary files into the overlay is discouraged (Build's job is to rebuild them); the precedence rule makes such mistakes recoverable.
• bsp_image is read-only outside Deploy. This skill is the only writer in the normal flow (matches the workflow invariant). Hand-edits to <bsp_image.root_path>/Linux_for_Tegra/ outside Deploy will be silently overwritten on the next promote run if the same path exists in either channel; conversely they will not be reverted if no entry shadows them. Both behaviors are wrong for the diff trail — never hand-edit upstream.
• Scope is overlay HEAD only (channel A). Named tags / manifests / commit ranges are deferred (see below). To promote a historical state, git -C $LFT_SRC checkout <ref> first, then re-run. The manifest channel has no ranged scope — it reflects whatever jetson-build-source's last run produced.
• No automatic rollback on partial failure. If cp fails partway through, bsp_image is left in an intermediate state. Fix the underlying cause (usually permissions / disk full) and re-run — the "Diff-aware copy into bsp_image" step will resume by skipping already-promoted files.
• Kernel Image mirror + initramfs refresh. Gated on copy-pass writes to kernel/Image or rootfs/lib/modules/*; the mirror feeds the refresh's chroot. Both are diff-aware and skipped on pure-overlay edits. tools/l4t_update_initrd.sh must exist in bsp_image (ships with apply_binaries.sh); a missing tool refuses and routes to /jetson-init-image. See references/kernel-image-and-initramfs.md for the full contract and failure modes.

Troubleshooting

Spec status

Locked in for v0.2.0:

• Two-channel scope — overlay HEAD + build manifest, both diff-aware, both copying into <bsp_image.root_path>/Linux_for_Tegra/.
• Channel-overlap precedence — manifest wins on dst collision.
• Source-repo collision check — overlay only; manifest has no remote concept and source repos under bsp_sources/ are not fetched (their state was sealed when jetson-build-source wrote the manifest).
• Atomicity — fail-fast, no rollback. Diff-aware copy makes resume natural.
• Audit trail — stdout-only at promote time. The overlay tracker's git log is the canonical record for channel A; the manifest itself is the canonical record for channel B.
• Kernel Image mirror + initramfs refresh. Locked in as a paired step. The mirror copies kernel/Image → rootfs/boot/Image whenever the copy pass touched kernel/Image; the refresh runs tools/l4t_update_initrd.sh whenever kernel/Image or any rootfs/lib/modules/* was promoted, rebuilding both bootloader/l4t_initrd.img and rootfs/boot/initrd. Inseparable because the refresh chroots into rootfs/ and resolves the kernel through /boot/Image — the mirror has to run first. Closes both module-shadowing and vermagic-skew failure modes; both diff-aware, both skipped on overlay-only edits. Full contract in references/kernel-image-and-initramfs.md.

Still deferred:

• Named-tag / commit-range scope for the overlay channel. Revisit when a "promote release X" use case appears.
• Manifest history. Currently only the last build's manifest exists; if a user wants to roll bsp_image back to a previous build state, they'd need to re-run /jetson-build-source at the prior commit. A manifest archive (saved per-build-mode or per-commit) would enable rollback without rebuild.
• Sidecar manifest in bsp_image. Revisit when promotion happens on a host that does not have access to the overlay tracker repo (or the workspace's manifest file).

References

• references/kernel-image-and-initramfs.md — full contract for the kernel Image mirror + l4t_update_initrd.sh refresh: shell snippets, failure modes, tool semantics, output filenames.
• ../../context/target-platform-contract.md — target-platform contract.
• ../../context/bsp-customization-workflow.md — workspace edit protocol (this skill is the promote leg of Deploy).
• ../jetson-init-source/SKILL.md — Setup; materializes the overlay tracker this skill reads (channel A) and authors source.toolchain.
• ../jetson-build-source/SKILL.md — Build builder; writes the .build-manifest.yaml this skill reads (channel B).
• ../jetson-flash-image/SKILL.md — next leg; flashes the just-promoted bsp_image to the DUT.
• ../jetson-validate-image/SKILL.md — final leg; static + on-target validation.