jetson-flash-image

Flash BSP Image

Purpose

Push a promoted bsp_image to a Jetson DUT by running the NVIDIA flashing toolchain (flash.sh or l4t_initrd_flash.sh) from the in-tree Linux_for_Tegra/. The DUT must be in RCM (recovery) mode at flash time. This is the flash leg of the BSP overlay deploy chain (/jetson-promote-image → /jetson-flash-image); see the BSP overlay workflow at ../../context/bsp-customization-workflow.md.

Design principle. Four invariants govern this skill; each is fully explained in the Instructions step that owns it.

• Host-side flash variables (<board>, <boot-dev>, flow tool, per-board .conf, boardctl) are resolved from the active profile or the in-tree BSP.
• Artifact paths (DTB_FILE, BPFDTB_FILE, partition XML, BCTs, DRAM training) are resolved inside flash.sh / l4t_initrd_flash.sh at flash time from board_sku / board_FAB read off the DUT's EEPROM.
• The DUT's EEPROM is authoritative; the profile is an authoring-time prediction reconciled by the preflight cross-check. Empty EEPROM values are valid, not refusal triggers.
• The user explicitly confirms a printed resolution before flashing.

Out of scope: BSP customization (use the /jetson-customize-* skills), promoting the overlay tracker into bsp_image (use /jetson-promote-image), and producing a custom carrier's flash conf (use /jetson-derive-carrier).

Prerequisites

• Active target-platform profile resolved per ../../context/target-platform-contract.md with a populated bsp_image: block. Refuse and route to /jetson-init-image if missing.
• <bsp_image.root_path>/Linux_for_Tegra/ exists on the host and has been through apply_binaries.sh (route to /jetson-init-image otherwise).
• A per-board flash .conf resolvable via the active-block precedence rule (custom_carrier.flash_config → reference_devkit.flash_config). Refuse and route to /jetson-derive-carrier or /jetson-init-image if absent.
• For the prior overlay → image leg: /jetson-promote-image has already run (or a standalone re-flash with no promotion changes since the last flash).
• A DUT cabled to the host that can be driven into RCM mode either via the in-tree boardctl or by manual recovery + reset buttons.

When to invoke

• After /jetson-promote-image has updated bsp_image to carry the desired customizations.
• Standalone re-flash with no promotion changes since the last flash.
• DUT must be in RCM mode before invocation.

Instructions

Resolve target and bsp_image

Resolve the active profile per ../../context/target-platform-contract.md. Refuse if bsp_image: is missing or <bsp_image.root_path>/Linux_for_Tegra/ does not exist (route the user to /jetson-init-image).

Resolve the flash conf path

Pick the per-board .conf using the active-block precedence rule from target-platform-contract.md: custom_carrier.flash_config when present, else reference_devkit.flash_config. Verify the chosen file exists under <bsp_image.root_path>/Linux_for_Tegra/. Refuse if absent — route the user at /jetson-derive-carrier (custom carrier) or /jetson-promote-image / /jetson-init-image (reference devkit).

Bind <board> as the basename of the resolved .conf minus the .conf suffix (e.g. jetson-agx-thor-devkit.conf → <board>=jetson-agx-thor-devkit). the "Invoke the flash" step's command shape consumes this binding directly.

No dispatch preview at this stage. Artifact resolution (DTB_FILE, BPFDTB_FILE, partition XML, MB1 BCTs, DRAM training tables) happens inside flash.sh / l4t_initrd_flash.sh during image generation, using board_sku and board_FAB read from the DUT's EEPROM in recovery mode — not values typed in from the profile. The profile is an authoring-time prediction; the DUT EEPROM is authoritative at flash time. The "Preflight checks" step's EEPROM cross-check reads EEPROM and refuses the flash on profile / EEPROM mismatch, so passing preflight is what guarantees the flash-time dispatch will pick the artifacts the profile expects.

For static analyses outside the flash flow that need predicted artifact paths (KB generation, customize-* skills locating files to edit), see the standalone snippet in per-board conf dispatch — that snippet is valid for BSP-side resolution but not as a flash-time preview.

Select <boot-dev> and flash flow

<boot-dev> is resolved deliberately, never assumed. Source order:

1. If the active profile records the boot device, use it.
2. Otherwise, prompt the user with the choices the per-board conf actually supports (internal, external, nvme0n1p1, mmcblk0p1, etc., depending on chip family and conf variant).

Pick the flow tool from the matrix below:

Massflash and --flash-only re-runs use the same tool selection but add their respective flags.

Put the DUT into recovery mode

Drive the device into recovery via the in-tree boardctl (preferred) or by manually pressing the recovery button followed by the reset button.

The full procedure — where to find boardctl under Linux_for_Tegra/, how to enumerate -t targets and pick one (recommend topo), the exact recovery verb to use, and the manual fallback — lives in references/recovery-mode-boardctl.md.

Bind the resolved binary path as <boardctl> for the remainder of this skill. Never substitute a $PATH boardctl, never invent a target name not present in <boardctl> -h. The "Preflight checks" step's DUT-recovery verification covers — for both paths — that the DUT actually landed in RCM mode.

Preflight checks

Performing the following preflight checks in the specified order, and never skip each check. Host-side checks run first (fail early before asking the user to flip recovery), then DUT-side checks once the user has put the device in RCM mode. EEPROM-dependent checks come after RCM detection, since the recovery channel is what makes the read possible.

5.1 bsp_image readiness (host-side).

• Per-board conf exists at <bsp_image.root_path>/Linux_for_Tegra/<flash_config>.
• Artifact subtrees populated: kernel/dtb/, bootloader/, bootloader/generic/BCT/, rootfs/.
• apply_binaries.sh has been run — check for rootfs/etc/nv_tegra_release and the chip's nvidia-l4t-bsp-* marker package files.
• The exact resolved DTB_FILE / BPFDTB_FILE / BCT filenames are intentionally not checked here — those are picked from EEPROM at flash time (see the "Resolve the flash conf path" step).
• Kernel Image mirror invariant. When both <LFT_DST>/kernel/Image and <LFT_DST>/rootfs/boot/Image exist, they must be byte-identical (cmp -s); drift means /jetson-promote-image's Mirror step was skipped — route back. Initramfs presence. l4t_initrd_flash.sh requires <LFT_DST>/bootloader/l4t_initrd.img and <LFT_DST>/rootfs/boot/initrd; absent → route to /jetson-init-image. (Freshness vs. rootfs/lib/modules/<ver>/ is not checked here — owned by /jetson-promote-image's Refresh initramfs step.)

5.2 DUT in RCM mode.

• Verifies the outcome of the "Put the DUT into recovery mode" step (either the user-selected <boardctl> -t <target> invocation or the manual fallback).

• lsusb -d 0955: must report at least one device matching the active chip family's recovery VID:PID pair:

  Chip family	Recovery VID:PID
  T23x / Orin	0955:7X23 (X is any hex digit — module variant)
  T26x / Thor	0955:7026

  For T23x, match on the trailing 23 (e.g. lsusb -d 0955: | grep -E ' 0955:7.23 '); a literal 0955:7023 check will miss valid T23x variants.

• Absent → if the "Put the DUT into recovery mode" step used boardctl, surface its output and refuse; if the "Put the DUT into recovery mode" step used the manual path, re-prompt the user to confirm the jumper / button and power-cycle.

• This is the gate for everything downstream. flash.sh's image-generation phase reads EEPROM over the same recovery channel; a device that's not in RCM here will fail there too.

5.3 EEPROM cross-check vs. active profile.

Read board_sku and board_FAB (and any additional dispatch inputs the active chip family uses) from the DUT's EEPROM in recovery mode using sudo ./nvautoflash.sh --print_boardid from <bsp_image.root_path>/Linux_for_Tegra/. The full reference — sample output, label-to-dispatch-input mapping, empty-value semantics, and the EEPROM-vs-profile reconciliation table — lives in references/eeprom-cross-check.md.

Refusal trigger is a real non-empty disagreement, never a missing value. Empty EEPROM values are valid and not a refusal trigger. The cross-check is the primary defense against the wrong-target / wrong-SKU class of failures whenever both sides supply enough information to disagree.

5.4 Default user staging (host-side, interactive).

A freshly applied bsp_image has no Linux user pre-staged. Detect via <bsp_image.root_path>/Linux_for_Tegra/rootfs/home/ and rootfs/etc/passwd UID ≥ 1000. If none, issue one AskUserQuestion with four click-to-select options: ubuntu / ubuntu, nvidia / nvidia, custom (sub-prompt for username + password), or skip (OEM wizard on first boot). Non-skip picks run l4t_create_default_user.sh --autologin --accept-license. Full invocation + rationale in references/default-user-staging.md.

Record the resolution so the "Confirm resolution" step can display it. This step is not a refusal gate — it is a user-interaction point.

Confirm resolution

Print the resolved plan and require explicit acceptance. The format is the resolution, not the shell command — the user is approving what will flash, not the string that will be executed:

Target:         <reference_devkit.name> [+ custom_carrier.name]
Profile:        target-platform/<active>.yaml
bsp_image:      <bsp_image.root_path>/Linux_for_Tegra  (version <X>)
Flash conf:     <flash_config>   (path verified in the "Resolve the flash conf path" step)

DUT EEPROM  →   board_sku=<value-or-(empty)>  board_FAB=<value-or-(empty)>

Artifact paths (DTB_FILE, BPFDTB_FILE, partition XML, BCTs) are not shown — they are resolved by flash.sh from EEPROM at flash time, not by this skill. The "Preflight checks" step's EEPROM cross-check is what guarantees those flash-time picks will line up with what the profile expects.

This is the user-acceptance gate. Refuse to fall back to a raw "paste this command" workflow — that path is how stale doc snippets, wrong dashes, and prompt-character paste artifacts make it into production flashes.

Invoke the flash

Construct the command from the resolved variables — never accept a verbatim command from the user, the docs, or memory:

Abort and surface the failed step on the first non-zero exit. Do not auto-retry on transient USB errors.

Post-flash reset (T26x / Thor only)

T26x platforms do not auto-reboot from the freshly flashed image when flash.sh / l4t_initrd_flash.sh returns. Run, using the <boardctl> resolved in the "Put the DUT into recovery mode" step and the same target the user selected for RCM entry:

T23x / Orin issues the reset internally; skip this step on Orin. If the "Put the DUT into recovery mode" step used the manual path, prompt the user to remove the force-recovery jumper / button and power-cycle by hand. Gate this step on chip family resolved from the active profile.

Summary

Report: command line(s) used (flash + post-flash reset if it ran), exit code, log location (if teed). Persist the resolved plan and outcome where validation can re-read it.

Limitations

• DUT must be in RCM mode. Image-generation (EEPROM read) and the flash itself both use the recovery USB channel; not-in-RCM at the gate fails image-gen too.
• Artifact paths resolved at flash time. DTB_FILE, BPFDTB_FILE, partition XML, BCTs, DRAM training are picked from EEPROM (board_sku / board_FAB) by flash.sh / l4t_initrd_flash.sh; this skill validates only host-side scaffolding.
• EEPROM is authoritative over the profile. Real non-empty disagreement refuses; empty EEPROM values are valid.
• No raw-command bypass. Refuses to fall back to user-supplied "paste this command" — that path is how stale doc snippets and prompt-character paste artifacts reach production flashes.
• No transient-error auto-retry. USB hiccups abort; re-enter RCM and re-invoke.
• T26x needs an explicit post-flash reset. T26x doesn't auto-reboot from a freshly flashed image; <boardctl> -t <target> reset (or manual power-cycle) required. T23x resets internally.
• Massflash / --flash-only uses the same tool selection + respective flags; massflash topology setup is out of scope here.

Troubleshooting

References

• references/recovery-mode-boardctl.md — locate the in-tree boardctl, enumerate targets, invoke recovery / reset, manual fallback (the "Put the DUT into recovery mode" step / the "Post-flash reset" step details).
• references/eeprom-cross-check.md — nvautoflash.sh --print_boardid sample, label-to-dispatch-input map, EEPROM-vs-profile reconciliation table (used by the "Preflight checks" step).
• references/default-user-staging.md — l4t_create_default_user.sh invocation + flag rationale (used by the "Preflight checks" step).
• ../../context/target-platform-contract.md — target-platform contract.
• ../../context/bsp-customization-workflow.md — Workspace edit protocol (this skill is the flash leg of Deploy).
• Per-board conf dispatch — <board>, DTB, and BCT resolution from the active profile.
• ../jetson-promote-image/SKILL.md — prior leg; copies overlay → bsp_image.
• ../jetson-derive-carrier/SKILL.md — produces the custom carrier's flash conf consumed by the "Resolve the flash conf path" step.