jetson-flash-image

Files (8)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• default-user-staging.md · references/
• eeprom-cross-check.md · references/
• recovery-mode-boardctl.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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
[`references/recovery-mode-boardctl.md`](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/`,

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills