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:

Channel	Source	Carrier	Owner
Overlay tracker	<source.root_path>/Linux_for_Tegra/ (git repo at HEAD)	Customize-* outputs that don't require a build (e.g. nvfancontrol.conf, nvpmodel.conf, BPMP DTB hand-edits)	Customize customize-* skills commit here
Build manifest	<source.root_path>/.build-manifest.yaml	Rebuilt kernel Image, in-tree .ko, OOT .ko, NVIDIA DTBs	Build jetson-build-source writes here

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:

Condition	Refuse with
No active profile, or active: NA	Route to /jetson-set-target or /jetson-init-target.
Profile lacks bsp_image:	Route to /jetson-init-image.
<bsp_image.root_path>/Linux_for_Tegra/ missing	Route to /jetson-init-image.
<source.root_path>/Linux_for_Tegra/ missing or not a git repo	Route to /jetson-init-source.

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

Error	Cause	Solution
Overlay has uncommitted changes at <LFT_SRC>	Customize-* edits not committed before promote	Run git -C $LFT_SRC commit (or stash), then re-run.
origin has N unpulled commits on <upstream>	Remote overlay diverged from local	git -C $LFT_SRC pull, resolve conflicts, then re-run.
Both overlay and manifest are empty — nothing to promote	No Customize-* commits and no Build manifest	Run a customize-* skill or /jetson-build-source first.
Kernel-side source(s) changed since last /jetson-build-source	Freshness gate detected unprocessed customize-* edits under Source/bsp_sources/	Commit pending edits, run /jetson-build-source, re-run promote.
Manifest entry references missing build output: <src>	bsp_sources/ build outputs wiped or stale manifest	Re-run /jetson-build-source to regenerate.
Build manifest at <MANIFEST> is not valid YAML	Manifest hand-edited or partially written	Re-run /jetson-build-source to rewrite the manifest.
cp: permission denied under rootfs/	Missing sudo privilege on the host	Run on an account that can sudo cp; re-run resumes via diff-aware copy.
Profile lacks bsp_image: / source:	Workspace not bootstrapped	Run /jetson-init-image and/or /jetson-init-source.
tool not found at <LFT_DST>/tools/l4t_update_initrd.sh	tools/ was pruned, or bsp_image extracted from a non-NVIDIA tarball	Re-run /jetson-init-image to repopulate.
l4t_update_initrd.sh exited non-zero	Insufficient sudo, broken rootfs (missing lib/modules/<ver>/modules.dep), or out-of-space /tmp	Run depmod -a -b <LFT_DST>/rootfs <ver> against the rootfs first; verify /tmp headroom; rerun promote.
DUT boots with stale kernel / modules after promote, modules fail to load with disagrees about version of symbol …, or initramfs ships pre-customize modules even after the refresh ran	The mirror / refresh gate didn't fire (manual hand-edit under <LFT_DST> outside the skill), or rootfs/boot/Image drifted from kernel/Image so the chrooted refresh built against the stale kernel	Force the gate by sudo touch <LFT_DST>/kernel/Image + re-run promote, or run the two steps manually: sudo cp -p <LFT_DST>/kernel/Image <LFT_DST>/rootfs/boot/Image && cd <LFT_DST> && sudo ./tools/l4t_update_initrd.sh. Then re-flash. See references/kernel-image-and-initramfs.md.

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.