/jetson-flash-image

name: jetson-flash-image
description: Use to flash a promoted BSP image to a Jetson DUT in RCM mode via flash.sh or l4t_initrd_flash.sh. Do NOT use for BSP customization, image promotion, or carrier derivation.
version: 0.0.1
license: "Apache-2.0"
metadata:
  data-classification: public
  author: "Jetson Team"
  tags:
    - bsp
    - flash
  domain: meta

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`](../../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`](../../context/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](../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common) — 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:

| Chip family | Default boot media | Tool | |---|---|---| | T234 / Orin | eMMC / SD | `flash.sh` | | T234 / Orin | NVMe / USB | `l4t_initrd_flash.sh` | | T264 / Thor | NVMe / UFS | `l4t_initrd_flash.sh` |

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 [`ref