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）；见 ../../context/bsp-customization-workflow.md 中的 BSP 叠加工作流。

设计原则。 四个不变性约束本技能；每个在拥有它的说明步骤中都有完整解释。

• 主机侧烧录变量（<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）。

解析烧录配置路径

使用 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-* 技能定位要编辑的文件），见 ../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common 中的独立代码片段——该片段对 BSP 侧解析有效，但不作为烧录时预览。

选择 <boot-dev> 和烧录流程

<boot-dev> 是经过慎重解析的，从不假设。来源顺序：

1. 如果活动配置文件记录了启动设备，使用它。
2. 否则，提示用户选择每板配置实际支持的选项（internal、external、nvme0n1p1、mmcblk0p1 等，取决于芯片系列和配置变体）。

从以下矩阵中选择流程工具：

大规模烧录和 --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 检测之后进行，因为恢复通道使读取成为可能。

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，显示其输出并拒绝；如果"将 DUT 置于恢复模式"步骤使用了手动路径，重新提示用户确认跳线/按钮并重新上电。

• 这是所有下游的门控。 flash.sh 的镜像生成阶段通过相同的恢复通道读取 EEPROM；这里未处于 RCM 的设备在那里也会失败。

5.3 EEPROM 交叉检查 vs 活动配置文件。

使用 sudo ./nvautoflash.sh --print_boardid 从 <bsp_image.root_path>/Linux_for_Tegra/ 在恢复模式下从 DUT 的 EEPROM 读取 board_sku 和 board_FAB（以及活动芯片系列使用的任何额外分发输入）。完整参考——示例输出、标签到分发输入映射、空值语义和 EEPROM-vs-配置文件协调表——见 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 内部复位。
• 大规模烧录 / --flash-only 使用相同的工具选择 + 各自标志；大规模烧录拓扑设置在此范围之外。

故障排除

参考

• references/recovery-mode-boardctl.md — 定位树内 boardctl、枚举目标、调用 recovery / reset、手动备选（"将 DUT 置于恢复模式"步骤 / "烧录后复位"步骤细节）。
• references/eeprom-cross-check.md — nvautoflash.sh --print_boardid 示例、标签到分发输入映射、EEPROM-vs-配置文件协调表（由"预检检查"步骤使用）。
• references/default-user-staging.md — l4t_create_default_user.sh 调用 + 标志理由（由"预检检查"步骤使用）。
• ../../context/target-platform-contract.md — 目标平台契约。
• ../../context/bsp-customization-workflow.md — 工作区编辑协议（本技能是部署的烧录环节）。
• Per-board conf dispatch — 从活动配置文件中解析 <board>、DTB 和 BCT。
• ../jetson-promote-image/SKILL.md — 前一环节；将叠加层复制到 bsp_image。
• ../jetson-derive-carrier/SKILL.md — 生成"解析烧录配置路径"步骤使用的定制载板烧录配置。