jetson-flash-image

烧录 BSP 镜像

目的

通过在源码树内的 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）。

先决条件

• 已根据 ../../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 模式。

何时调用

• /jetson-promote-image 更新 bsp_image 以包含所需自定义内容之后。
• 自上次烧录以来没有提升更改的独立重刷。
• 调用前，DUT 必须处于 RCM 模式。

操作说明

解析目标和 bsp_image

根据 ../../context/target-platform-contract.md 解析活动配置文件。若缺少 bsp_image: 或 <bsp_image.root_path>/Linux_for_Tegra/ 不存在，则拒绝操作（引导用户至 /jetson-init-image）。

解析 flash 配置文件路径

根据 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 文件名去掉 .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 不匹配时拒绝刷写，因此通过预检即可确保刷写时的分派会选用配置文件预期的工件。

对于刷写流程之外需要预测工件路径的静态分析（生成 KB、customize-* 技能定位待编辑文件），请参阅 每板配置文件分派 中的独立代码片段——该片段适用于 BSP 侧解析，但不能用于预览刷写时的分派结果。

选择 <boot-dev> 和刷写流程

<boot-dev> 必须经过明确解析，绝不能想当然。来源顺序：

1. 如果活动配置文件记录了启动设备，则使用该设备。
2. 否则，向用户提供该板卡对应配置文件实际支持的选项（根据芯片系列和配置文件变体，可能包括 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

Massflash 和 --flash-only 重跑使用相同的工具选择，但会添加各自的标志。

将 DUT 置于恢复模式

优先通过项目内的 boardctl 将设备置于恢复模式，也可以手动先按恢复按钮，再按重置按钮。

完整步骤包括：如何在 Linux_for_Tegra/ 下找到 boardctl、如何枚举 -t 目标并选择一个（推荐 topo）、应使用的确切 recovery 子命令，以及手动操作的备用方案。详情请参阅 references/recovery-mode-boardctl.md。

将解析出的二进制文件路径绑定为 <boardctl>，供本技能后续步骤使用。绝不使用 $PATH 中的 boardctl 替代，也绝不编造 <boardctl> -h 中不存在的目标名称。“预检”步骤中的 DUT 恢复模式验证会检查这两种方式下 DUT 是否确实已进入 RCM 模式。

预检

必须按指定顺序执行以下预检，不得跳过任何一项。先执行主机端检查（尽早失败，避免先要求用户切换到恢复模式），再由用户将设备置于 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> 调用还是手动备用方案）。

• 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 模式的设备，在后续阶段也会失败。

5.3 根据当前配置文件交叉核对 EEPROM。

在恢复模式下，从 DUT 的 EEPROM 读取 board_sku 和 board_FAB（以及当前芯片系列使用的任何其他分派输入）；运行位于 <bsp_image.root_path>/Linux_for_Tegra/ 下的 sudo ./nvautoflash.sh --print_boardid。完整参考资料——示例输出、标签到分派输入的映射、空值语义以及 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。

记录处理结果，以便“确认处理结果”步骤显示。此步骤不是拒绝继续的关卡，而是用户交互环节。

确认解析结果

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

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

不显示制品路径（DTB_FILE、BPFDTB_FILE、分区 XML、BCT）；这些路径由 flash.sh 在刷写时从 EEPROM 中解析，而非由此技能解析。“预检”步骤中的 EEPROM 交叉检查可确保刷写时选用的文件与配置文件预期一致。

这是用户接受关卡。拒绝退回到原始的“粘贴此命令”工作流 — 过时的文档片段、错误的破折号和提示符字符粘贴伪影正是通过这种方式进入生产刷写流程的。

执行刷写

根据已解析的变量构造命令 — 绝不接受来自用户、文档或记忆中的原样命令：

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

首次遇到非零退出码时立即中止，并指出失败步骤。不要因 USB 暂时性错误而自动重试。

刷写后重置（仅限 T26x / Thor）

T26x 平台在 flash.sh / l4t_initrd_flash.sh 返回后，不会从刚刷写的映像自动重启。使用“使 DUT 进入恢复模式”步骤中解析出的 <boardctl>，以及用户选择用于进入 RCM 的同一目标运行：

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

T23x / Orin 会在内部执行重置；Orin 跳过此步骤。如果“使 DUT 进入恢复模式”步骤使用了手动路径，则提示用户拔下强制恢复跳线 / 按钮，并手动断电再上电。根据从当前配置文件解析出的芯片系列决定是否执行此步骤。

摘要

报告：使用的命令行（刷写命令 + 若执行了刷写后重置，则包括重置命令）、退出码、日志位置（如使用了 tee）。将已解析的计划和结果持久化保存，以便验证时重新读取。

限制

• 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 值有效。
• 不允许绕过原始命令检查。 拒绝退回到用户提供的“粘贴此命令”方式 — 过时的文档片段和提示符字符粘贴伪影正是通过这种方式进入生产刷写流程的。
• 不自动重试暂时性错误。 USB 故障会导致中止；请重新进入 RCM 并再次调用。
• T26x 需要明确执行刷写后重置。 T26x 不会从刚刷写的映像自动重启；必须执行 <boardctl> -t <target> reset（或手动断电再上电）。T23x 会在内部重置。
• Massflash / --flash-only 使用相同的工具选择及相应标志；此处不涉及 massflash 拓扑设置。

故障排查

错误	原因	解决方案
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 是权威数据源。
预检因“per-board conf not found”而拒绝继续	当前配置文件指向的 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 中选择目标。如有需要，改用手动恢复和重置按钮。
在 T26x 上刷写成功，但 DUT 仍停留在恢复模式／未启动新镜像	flash.sh／l4t_initrd_flash.sh 返回后，T26x 不会自动退出恢复模式并重置。	运行 <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 未复制自定义构件，或者 BSP 不支持该 EEPROM SKU。	重新运行 /jetson-promote-image。如果不支持该 SKU，则 DUT 需要使用其他 BSP 版本。
DUT 上出现 kernel/Image 与 rootfs/boot/Image 不一致、缺少 bootloader/l4t_initrd.img／rootfs/boot/initrd，或 modprobe 报告“disagrees about version of symbol …”	跳过了 /jetson-promote-image 的镜像同步／刷新步骤，或者在 Deploy 之外手动编辑了 bsp_image。	重新运行 /jetson-promote-image 并重新刷写。如果 initramfs 文件完全缺失，请先运行 /jetson-init-image。手动解决方法请参阅 promote-image 的 kernel-image-and-initramfs 参考文档。

参考资料

• references/recovery-mode-boardctl.md — 定位树内的 boardctl，列出目标，调用 recovery / reset，以及手动备用方案（“Put the DUT into recovery mode” 步骤 / “Post-flash reset” 步骤的详情）。
• references/eeprom-cross-check.md — nvautoflash.sh --print_boardid 示例、标签到分发输入的映射表、EEPROM 与配置文件的核对表（用于“Preflight checks”步骤）。
• references/default-user-staging.md — l4t_create_default_user.sh 调用方式及标志说明（用于“Preflight checks”步骤）。
• ../../context/target-platform-contract.md — 目标平台契约。
• ../../context/bsp-customization-workflow.md — 工作区编辑协议（此技能是 Deploy 的刷写环节）。
• 按开发板分发配置 — 根据当前配置文件解析 <board>、DTB 和 BCT。
• ../jetson-promote-image/SKILL.md — 前序环节；将 overlay 复制到 bsp_image。
• ../jetson-derive-carrier/SKILL.md — 生成自定义载板的刷写配置，由“Resolve the flash conf path”步骤使用。