Flash BSP Image

Purpose

Push a promoted

bsp_image

to a Jetson DUT by running the NVIDIA flashing toolchain (

flash.sh

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:

If the active profile records the boot device, use it.
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

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.

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

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)>
Profile     →   module.sku=<value-or-(any)>    module.revision=<value-or-(any)>
                (reconciled per the "Preflight checks" step's EEPROM cross-check)

Boot device:    <boot-dev>
Flow tool:      flash.sh  |  l4t_initrd_flash.sh
boardctl:       <bsp_image.root_path>/Linux_for_Tegra/tools/board_automation/boardctl
                (or the path the "Put the DUT into recovery mode" step resolved)
RCM entry:      <boardctl> -t <user-selected target> recovery  |  manual recovery + reset buttons
Post-flash:     <boardctl> -t <user-selected target> reset   (T26x / Thor)
                not required — flash tool resets internally    (T23x / Orin)
Default user:   <username> (autologin)
              | already staged in rootfs (kept)
              | none — OEM config wizard on first boot

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:

bash

cd <bsp_image.root_path>/Linux_for_Tegra
sudo ./<flow-tool> [<resolved flags>] <board> <boot-dev>

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:

bash

<boardctl> -t <user-selected target> reset

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

Error	Cause	Solution
`lsusb -d 0955:` reports nothing matching `0955:7X23` (T23x) or `0955:7026` (T26x)	DUT did not enter RCM mode — `boardctl recovery` failed or the manual recovery + reset sequence didn't take.	If `boardctl` was used, surface its output and re-prompt; manual path, re-confirm the recovery jumper / button and power-cycle. Re-run the "DUT in RCM mode" preflight.
Preflight EEPROM cross-check refuses with `board_sku` / `board_FAB` mismatch vs. profile	EEPROM holds a real non-empty value that disagrees with `module.sku` / `module.revision` in the active profile.	Fix the profile ( `/jetson-set-target` or `/jetson-init-target` ) to match the DUT's actual EEPROM. Do not override EEPROM from the profile — EEPROM is authoritative.
Preflight refuses with "per-board conf not found"	Active profile points at a `flash_config` that does not exist under `<bsp_image.root_path>/Linux_for_Tegra/` .	For custom carriers: run `/jetson-derive-carrier` to produce the conf. For reference devkits: re-run `/jetson-promote-image` / `/jetson-init-image` to repopulate the BSP image.
Preflight refuses because `rootfs/etc/nv_tegra_release` is missing	`apply_binaries.sh` has not been run against `<bsp_image.root_path>/Linux_for_Tegra/` .	Re-run `/jetson-init-image` (which invokes `apply_binaries.sh` ) or run `apply_binaries.sh` manually from `Linux_for_Tegra/` .
`boardctl -t <target> recovery` errors out or has no effect	Wrong `boardctl` (a `$PATH` binary instead of the in-tree one) or a target name not enumerated by `<boardctl> -h` .	Use the in-tree `<bsp_image.root_path>/Linux_for_Tegra/tools/board_automation/boardctl` ; pick the target from `<boardctl> -h` . Fall back to manual recovery + reset buttons if needed.
Flash succeeds on T26x but the DUT stays in recovery / does not boot the new image	T26x does not auto-reset out of recovery after `flash.sh` / `l4t_initrd_flash.sh` returns.	Run `<boardctl> -t <target> reset` (same target used for RCM entry), or for the manual path remove the force-recovery jumper / button and power-cycle. T23x / Orin needs no extra step.
First boot lands on Ubuntu's OEM configuration wizard despite expecting autologin	No default user was staged into `rootfs` before flashing.	Either re-flash after staging via `l4t_create_default_user.sh --autologin --accept-license` (see the default-user-staging step), or complete the OEM wizard on the DUT this once.
`flash.sh` exits non-zero on an artifact-not-found error (DTB / BPFDTB / partition XML)	EEPROM-driven dispatch resolved a filename that doesn't exist in `bsp_image` — usually `/jetson-promote-image` didn't copy the customized artifact, or the EEPROM SKU is unsupported by the BSP.	Re-run `/jetson-promote-image` . If the SKU is unsupported, the DUT needs a different BSP version.
`kernel/Image` ↔ `rootfs/boot/Image` drift, missing `bootloader/l4t_initrd.img` / `rootfs/boot/initrd` , or `modprobe` "disagrees about version of symbol …" on the DUT	`/jetson-promote-image` 's mirror / refresh steps were skipped, or `bsp_image` was hand-edited outside Deploy.	Re-run `/jetson-promote-image` and re-flash. If initramfs files are entirely absent, run `/jetson-init-image` first. See promote-image's kernel-image-and-initramfs reference for the manual escape hatch.

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.

jetson-flash-image

NPX Install

Tags

SKILL.md Content