jetson-flash-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flash BSP Image

刷入BSP镜像

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

通过运行内置

Linux_for_Tegra/

目录下的NVIDIA刷机工具链（

flash.sh

或

l4t_initrd_flash.sh

），将已发布的

bsp_image

刷入Jetson DUT。刷机时DUT必须处于RCM（恢复）模式。这是BSP叠加层部署链（

/jetson-promote-image

→

/jetson-flash-image

）的刷机环节；有关BSP叠加层工作流，请参阅

../../context/bsp-customization-workflow.md

。

设计原则。本技能由四个不变规则约束；每个规则在对应步骤的说明中都有详细解释。

主机端刷机变量（
```
<board>
```
、
```
<boot-dev>
```
、流程工具、单板
```
.conf
```
文件、
```
boardctl
```
）从当前激活的配置文件或内置BSP中解析。
工件路径（
```
DTB_FILE
```
、
```
BPFDTB_FILE
```
、分区XML、BCT、DRAM训练文件）在刷机时由
```
flash.sh
```
/
```
l4t_initrd_flash.sh
```
从DUT EEPROM读取的
```
board_sku
```
/
```
board_FAB
```
中解析。
DUT的EEPROM是权威来源；配置文件是创作阶段的预测值，会通过预检交叉检查进行协调。EEPROM空值是有效的，不会触发拒绝操作。
用户需明确确认打印出的解析结果后才能开始刷机。

本技能不涵盖以下场景：BSP定制（使用

/jetson-customize-*

系列技能）、将叠加层跟踪器发布为

bsp_image

（使用

/jetson-promote-image

）、生成自定义载板的刷机配置文件（使用

/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.

已根据
```
../../context/target-platform-contract.md
```
解析出激活的目标平台配置文件，且其中包含完整的
```
bsp_image:
```
块。如果缺失，请拒绝操作并引导用户使用
```
/jetson-init-image
```
。

主机上存在

<bsp_image.root_path>/Linux_for_Tegra/

目录，且已执行过

apply_binaries.sh

（否则引导用户使用

/jetson-init-image

）。

可通过激活块优先级规则（
```
custom_carrier.flash_config
```
→
```
reference_devkit.flash_config
```
）解析出单板刷机
```
.conf
```
文件。如果缺失，请拒绝操作并引导用户使用
```
/jetson-derive-carrier
```
（自定义载板）或
```
/jetson-init-image
```
（参考开发板）。
对于之前的叠加层→镜像环节：已运行
```
/jetson-promote-image
```
（或进行独立重刷，且自上次刷机后未进行任何发布变更）。
DUT已连接到主机，且可通过内置
```
boardctl
```
或手动按恢复+重置按钮进入RCM模式。

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.

在
```
/jetson-promote-image
```
更新
```
bsp_image
```
以包含所需定制内容之后。
进行独立重刷，且自上次刷机后未进行任何发布变更。
调用前DUT必须处于RCM模式。

Instructions

操作步骤

Resolve target and

bsp_image

解析目标与

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

根据

../../context/target-platform-contract.md

解析激活的配置文件。如果

bsp_image:

缺失或

<bsp_image.root_path>/Linux_for_Tegra/

目录不存在，请拒绝操作并引导用户使用

/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.

根据

target-platform-contract.md

中的激活块优先级规则选择单板

.conf

文件：如果存在

custom_carrier.flash_config

则使用它，否则使用

reference_devkit.flash_config

。验证所选文件是否存在于

<bsp_image.root_path>/Linux_for_Tegra/

目录下。如果缺失，请拒绝操作并引导用户使用

/jetson-derive-carrier

（自定义载板）或

/jetson-promote-image

/jetson-init-image

（参考开发板）。

将

<board>

绑定为解析后的

.conf

文件的basename（去掉

.conf

后缀），例如

jetson-agx-thor-devkit.conf

→

<board>=jetson-agx-thor-devkit

。“调用刷机工具”步骤的命令格式会直接使用此绑定值。

此阶段不进行调度预览。工件解析（

DTB_FILE

、

BPFDTB_FILE

、分区XML、MB1 BCT、DRAM训练表）发生在

flash.sh

l4t_initrd_flash.sh

的镜像生成阶段，使用的是从恢复模式下DUT的EEPROM读取的
board_sku
和
board_FAB
，而非配置文件中输入的值。配置文件是创作阶段的预测值；刷机时DUT的EEPROM才是权威来源。“预检检查”步骤中的EEPROM交叉检查会读取EEPROM，若配置文件与EEPROM不匹配则拒绝刷机，因此通过预检即可保证刷机时的调度会选择配置文件预期的工件。

对于刷机流程外需要预测工件路径的静态分析（如生成知识库、

customize-*

技能定位待编辑文件），请参阅单板配置文件调度中的独立代码片段——该片段适用于BSP端解析，但不能作为刷机时的预览。

Select

<boot-dev>

and flash flow

选择

<boot-dev>

与刷机流程

<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.

<boot-dev>

需明确解析，不可默认假设。来源优先级：

如果激活的配置文件记录了启动设备，则使用该值。
否则，向用户提供单板配置文件实际支持的选项（如
```
internal
```
、
```
external
```
、
```
nvme0n1p1
```
、
```
mmcblk0p1
```
等，具体取决于芯片系列和配置变体）。

根据以下矩阵选择流程工具：

芯片系列	默认启动介质	工具
T234 / Orin	eMMC / SD	`flash.sh`
T234 / Orin	NVMe / USB	`l4t_initrd_flash.sh`
T264 / Thor	NVMe / UFS	`l4t_initrd_flash.sh`

批量刷机和

--flash-only

重刷使用相同的工具选择，但需添加各自的标志。

Put the DUT into recovery mode

将DUT置于恢复模式

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.

通过内置

boardctl

（首选方式）或手动按恢复按钮后按重置按钮，将设备置于恢复模式。

完整步骤——包括在

Linux_for_Tegra/

下找到

boardctl

的位置、枚举

-t

目标并选择（推荐

topo

）、使用的准确

recovery

命令、手动 fallback 方法——请参阅

references/recovery-mode-boardctl.md

。

将解析后的二进制路径绑定为

<boardctl>

，供后续步骤使用。绝不能使用

$PATH

中的

boardctl

，也不能使用

<boardctl> -h

中未列出的目标名称。“预检检查”步骤中的DUT恢复验证会覆盖两种方式，确保DUT确实进入了RCM模式。

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.

按指定顺序执行以下预检检查，不得跳过任何一项。先执行主机端检查（在要求用户切换恢复模式前尽早失败），然后在用户将设备置于RCM模式后执行DUT端检查。依赖EEPROM的检查需在检测到RCM后进行，因为恢复通道是读取EEPROM的前提。

5.1
bsp_image
就绪检查（主机端）

单板配置文件存在于

<bsp_image.root_path>/Linux_for_Tegra/<flash_config>

。

工件子目录已填充：

kernel/dtb/

、

bootloader/

、

bootloader/generic/BCT/

、

rootfs/

。

已执行

apply_binaries.sh

——检查

rootfs/etc/nv_tegra_release

和芯片对应的

nvidia-l4t-bsp-*

标记包文件。

此处故意不检查解析后的
```
DTB_FILE
```
/
```
BPFDTB_FILE
```
/BCT文件名——这些文件名会在刷机时从EEPROM中选择（请参阅“解析刷机配置文件路径”步骤）。
内核
Image
镜像不变规则。当
```
<LFT_DST>/kernel/Image
```
和
```
<LFT_DST>/rootfs/boot/Image
```
同时存在时，它们必须字节完全相同（使用
```
cmp -s
```
检查）；若存在差异，则说明跳过了
```
/jetson-promote-image
```
的镜像步骤——引导用户返回该步骤。Initramfs存在检查。
```
l4t_initrd_flash.sh
```
需要
```
<LFT_DST>/bootloader/l4t_initrd.img
```
和
```
<LFT_DST>/rootfs/boot/initrd
```
；如果缺失，则引导用户使用
```
/jetson-init-image
```
。（此处不检查与
```
rootfs/lib/modules/<ver>/
```
的新鲜度——由
```
/jetson-promote-image
```
的刷新initramfs步骤负责。）

5.2 DUT处于RCM模式检查

验证“将DUT置于恢复模式”步骤的结果（无论是用户选择的
```
<boardctl> -t <target>
```
调用还是手动 fallback）。
```
lsusb -d 0955:
```
必须报告至少一个匹配当前芯片系列恢复VID:PID对的设备：
芯片系列恢复VID:PID
T23x / Orin
0955:7X23
（X为任意十六进制数字——模块变体）
T26x / Thor
0955:7026
对于T23x，匹配末尾的
```
23
```
（例如
```
lsusb -d 0955: | grep -E ' 0955:7.23 '
```
）；使用字面量
```
0955:7023
```
检查会遗漏有效的T23x变体。
如果未检测到设备：如果“将DUT置于恢复模式”步骤使用了
```
boardctl
```
，则显示其输出并拒绝操作；如果使用了手动方式，则重新提示用户确认跳线/按钮并重新上电。
这是后续所有操作的入口关卡。
```
flash.sh
```
的镜像生成阶段通过同一恢复通道读取EEPROM；此处未进入RCM的设备在镜像生成阶段也会失败。

芯片系列	恢复VID:PID
T23x / Orin	`0955:7X23` （X为任意十六进制数字——模块变体）
T26x / Thor	`0955:7026`

5.3 EEPROM与激活配置文件交叉检查

使用

<bsp_image.root_path>/Linux_for_Tegra/

目录下的

sudo ./nvautoflash.sh --print_boardid

，从恢复模式下DUT的EEPROM中读取

board_sku

和

board_FAB

（以及当前芯片系列使用的任何其他调度输入）。完整参考——包括示例输出、标签到调度输入的映射、空值语义、EEPROM与配置文件协调表——请参阅

references/eeprom-cross-check.md

。

拒绝触发条件是真实的非空值不一致，而非缺失值。EEPROM空值是有效的，不会触发拒绝操作。当双方都提供足够信息导致不一致时，交叉检查是防止错误目标/错误SKU类故障的主要防御手段。

5.4 默认用户预配置（主机端，交互式）

新应用的

bsp_image

中没有预配置Linux用户。通过检查

<bsp_image.root_path>/Linux_for_Tegra/rootfs/home/

和

rootfs/etc/passwd

中UID≥1000的用户来检测。如果没有，则发出一个

AskUserQuestion

，提供四个点击选择选项：

ubuntu / ubuntu

、

nvidia / nvidia

、

custom

（子提示输入用户名+密码）或

skip

（首次启动时使用OEM向导）。非

skip

选项会执行

l4t_create_default_user.sh --autologin --accept-license

。完整调用方式及原理请参阅

references/default-user-staging.md

。

记录解析结果，以便“确认解析结果”步骤显示。此步骤不是拒绝关卡——而是用户交互点。

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.

打印解析后的计划并要求用户明确确认。格式为解析结果，而非shell命令——用户批准的是将要刷入的内容，而非将要执行的命令字符串：

目标:         <reference_devkit.name> [+ custom_carrier.name]
配置文件:        target-platform/<active>.yaml
bsp_image:      <bsp_image.root_path>/Linux_for_Tegra  (版本 <X>)
刷机配置文件:     <flash_config>   (路径已在“解析刷机配置文件路径”步骤中验证)

DUT EEPROM  →   board_sku=<值或(空)>  board_FAB=<值或(空)>
配置文件     →   module.sku=<值或(任意)>    module.revision=<值或(任意)>
                (已根据“预检检查”步骤中的EEPROM交叉检查进行协调)

启动设备:    <boot-dev>
流程工具:      flash.sh  |  l4t_initrd_flash.sh
boardctl:       <bsp_image.root_path>/Linux_for_Tegra/tools/board_automation/boardctl
                (或“将DUT置于恢复模式”步骤解析的路径)
RCM进入方式:      <boardctl> -t <用户选择的目标> recovery  |  手动恢复+重置按钮
刷机后操作:     <boardctl> -t <用户选择的目标> reset   (T26x / Thor)
                无需额外操作 — 刷机工具会自动重置    (T23x / Orin)
默认用户:   <用户名> (自动登录)
              | 已预配置在rootfs中（保留）
              | 无 — 首次启动时使用OEM配置向导

不显示工件路径（

DTB_FILE

、

BPFDTB_FILE

、分区XML、BCT）——这些路径由

flash.sh

在刷机时从EEPROM解析，而非本技能。“预检检查”步骤中的EEPROM交叉检查保证了这些刷机时选择的路径与配置文件预期一致。

这是用户确认关卡。拒绝回退到原始的“粘贴此命令”工作流——该路径会导致过时的文档片段、错误的短横线、提示符粘贴 artifacts 进入生产刷机流程。

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.

从解析后的变量构造命令——绝不接受用户、文档或记忆提供的 verbatim 命令：

bash

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

首次出现非零退出码时中止并显示失败步骤。不对临时USB错误自动重试。

Post-flash reset (T26x / Thor only)

刷机后重置（仅T26x / Thor）

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.

当

flash.sh

l4t_initrd_flash.sh

返回时，T26x平台不会从新刷入的镜像自动重启。使用“将DUT置于恢复模式”步骤中解析的

<boardctl>

和用户选择的RCM进入目标运行：

bash

<boardctl> -t <用户选择的目标> reset

T23x / Orin会在内部发出重置信号；Orin可跳过此步骤。如果“将DUT置于恢复模式”步骤使用了手动方式，则提示用户移除强制恢复跳线/按钮并手动重新上电。此步骤仅针对从激活配置文件解析出的芯片系列执行。

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.

报告：使用的命令行（刷机+刷机后重置，如果执行的话）、退出码、日志位置（如果有 tee 输出）。将解析后的计划和结果保存到可被验证重新读取的位置。

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.

DUT必须处于RCM模式。镜像生成（读取EEPROM）和刷机本身都使用恢复USB通道；入口处未进入RCM的设备在镜像生成阶段也会失败。
工件路径在刷机时解析。
```
DTB_FILE
```
、
```
BPFDTB_FILE
```
、分区XML、BCT、DRAM训练文件由
```
flash.sh
```
/
```
l4t_initrd_flash.sh
```
从EEPROM（
```
board_sku
```
/
```
board_FAB
```
）中选择；本技能仅验证主机端框架。
EEPROM优先于配置文件。真实的非空值不一致会触发拒绝操作；空EEPROM值是有效的。
不允许原始命令绕过。拒绝回退到用户提供的“粘贴此命令”——该路径会导致过时的文档片段和提示符粘贴 artifacts 进入生产刷机流程。
不对临时错误自动重试。USB故障会中止操作；重新进入RCM并重新调用。
T26x需要显式的刷机后重置。T26x不会从新刷入的镜像自动重启；需要执行
```
<boardctl> -t <target> reset
```
（或手动重新上电）。T23x会自动重置。
**批量刷机/
```
--flash-only
```
**使用相同的工具选择+各自的标志；批量刷机拓扑设置不在本技能范围内。

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.

错误	原因	解决方案
`lsusb -d 0955:` 未报告匹配 `0955:7X23` （T23x）或 `0955:7026` （T26x）的设备	DUT未进入RCM模式—— `boardctl recovery` 失败或手动恢复+重置序列未生效。	如果使用了 `boardctl` ，则显示其输出并重新提示；如果使用了手动方式，则重新确认恢复跳线/按钮并重新上电。重新运行“DUT处于RCM模式”预检。
预检EEPROM交叉检查因 `board_sku` / `board_FAB` 与配置文件不匹配而拒绝	EEPROM中的真实非空值与激活配置文件中的 `module.sku` / `module.revision` 不一致。	修改配置文件（使用 `/jetson-set-target` 或 `/jetson-init-target` ）以匹配DUT实际的EEPROM值。不要从配置文件覆盖EEPROM——EEPROM是权威来源。
预检因“未找到单板配置文件”而拒绝	激活的配置文件指向的 `flash_config` 不存在于 `<bsp_image.root_path>/Linux_for_Tegra/` 目录下。	对于自定义载板：运行 `/jetson-derive-carrier` 生成配置文件。对于参考开发板：重新运行 `/jetson-promote-image` / `/jetson-init-image` 重新填充BSP镜像。
预检因 `rootfs/etc/nv_tegra_release` 缺失而拒绝	未对 `<bsp_image.root_path>/Linux_for_Tegra/` 执行 `apply_binaries.sh` 。	重新运行 `/jetson-init-image` （该技能会调用 `apply_binaries.sh` ）或手动从 `Linux_for_Tegra/` 目录执行 `apply_binaries.sh` 。
`boardctl -t <target> recovery` 报错或无效果	使用了错误的 `boardctl` （ `$PATH` 中的二进制文件而非内置版本）或 `<boardctl> -h` 未列出的目标名称。	使用内置的 `<bsp_image.root_path>/Linux_for_Tegra/tools/board_automation/boardctl` ；从 `<boardctl> -h` 中选择目标。必要时 fallback 到手动恢复+重置按钮。
T26x刷机成功但DUT仍处于恢复模式/无法启动新镜像	T26x在 `flash.sh` / `l4t_initrd_flash.sh` 返回后不会自动从恢复模式重启。	运行 `<boardctl> -t <target> reset` （使用与RCM进入相同的目标）；如果使用了手动方式，则移除强制恢复跳线/按钮并手动重新上电。T23x / Orin无需额外步骤。
首次启动进入Ubuntu的OEM配置向导，但预期是自动登录	刷机前未在 `rootfs` 中预配置默认用户。	要么在预配置后重新刷机（使用 `l4t_create_default_user.sh --autologin --accept-license` ，请参阅默认用户预配置步骤），要么本次在DUT上完成OEM向导。
`flash.sh` 因工件未找到错误（DTB/BPFDTB/分区XML）而退出并返回非零码	EEPROM驱动的调度解析出的文件名在 `bsp_image` 中不存在——通常是 `/jetson-promote-image` 未复制定制工件，或EEPROM SKU不受BSP支持。	重新运行 `/jetson-promote-image` 。如果SKU不受支持，则DUT需要使用不同版本的BSP。
`kernel/Image` 与 `rootfs/boot/Image` 存在差异、缺失 `bootloader/l4t_initrd.img` / `rootfs/boot/initrd` ，或DUT上出现 `modprobe` “符号版本不一致”错误	跳过了 `/jetson-promote-image` 的镜像/刷新步骤，或在Deploy外手动编辑了 `bsp_image` 。	重新运行 `/jetson-promote-image` 并重新刷机。如果initramfs文件完全缺失，请先运行 `/jetson-init-image` 。有关手动解决方法，请参阅promote-image的内核镜像与initramfs参考。

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.

```
references/recovery-mode-boardctl.md
```
— 找到内置
```
boardctl
```
、枚举目标、调用
```
recovery
```
/
```
reset
```
、手动 fallback（“将DUT置于恢复模式”步骤/“刷机后重置”步骤的详细信息）。
```
references/eeprom-cross-check.md
```
—
```
nvautoflash.sh --print_boardid
```
示例、标签到调度输入的映射、EEPROM与配置文件协调表（由“预检检查”步骤使用）。
```
references/default-user-staging.md
```
—
```
l4t_create_default_user.sh
```
调用方式及标志原理（由“预检检查”步骤使用）。

../../context/target-platform-contract.md

— 目标平台协议。

```
../../context/bsp-customization-workflow.md
```
— 工作区编辑协议（本技能是Deploy的刷机环节）。
单板配置文件调度 — 从激活配置文件解析
```
<board>
```
、DTB和BCT。
```
../jetson-promote-image/SKILL.md
```
— 前序环节；将叠加层复制到bsp_image。
```
../jetson-derive-carrier/SKILL.md
```
— 生成“解析刷机配置文件路径”步骤使用的自定义载板刷机配置文件。

jetson-flash-image

Original

Translation

Flash BSP Image

刷入BSP镜像

Purpose

用途

Prerequisites

前置条件

When to invoke

调用时机

Instructions

操作步骤

Resolve target and
`bsp_image`

解析目标与
`bsp_image`

Resolve the flash conf path

解析刷机配置文件路径

Select
`<boot-dev>`
and flash flow

选择
`<boot-dev>`
与刷机流程

Put the DUT into recovery mode

将DUT置于恢复模式

Preflight checks

预检检查

Confirm resolution

确认解析结果

Invoke the flash

调用刷机工具

Post-flash reset (T26x / Thor only)

刷机后重置（仅T26x / Thor）

Summary

总结

Limitations

限制

Troubleshooting

故障排除

References

参考资料

jetson-flash-image

Original

Translation

Flash BSP Image

刷入BSP镜像

Purpose

用途

Prerequisites

前置条件

When to invoke

调用时机

Instructions

操作步骤

Resolve target and bsp_image

解析目标与bsp_image

Resolve the flash conf path

解析刷机配置文件路径

Select <boot-dev> and flash flow

选择<boot-dev>与刷机流程

Put the DUT into recovery mode

将DUT置于恢复模式

Preflight checks

预检检查

Confirm resolution

确认解析结果

Invoke the flash

调用刷机工具

Post-flash reset (T26x / Thor only)

刷机后重置（仅T26x / Thor）

Summary

总结

Limitations

限制

Troubleshooting

故障排除

References

参考资料

Resolve target and
`bsp_image`

解析目标与
`bsp_image`

Select
`<boot-dev>`
and flash flow

选择
`<boot-dev>`
与刷机流程