LC-X5 刷机指南（NVIDIA Jetson Thor）

本文介绍如何使用 catdogai/lzc-x5-flash:39.2 为 LC-X5 刷入系统，包括默认模式、为 LVM 准备磁盘布局、仅重刷 NVMe，以及仅更新 QSPI 启动固件。

命令以当前 LC-X5 刷机流程为基础，官方参数说明以 Jetson Linux R39.2 为准。R39.2 对应 JetPack 7.2，目标系统基于 Ubuntu 24.04、Linux 6.8，参见 NVIDIA JetPack 7.2 下载与版本说明。不要混用其他版本的 BSP、rootfs、QSPI 固件或其他机型的镜像。

刷机会重写所选存储上的分区和系统，可能丢失已有数据。执行前备份需要保留的文件，并确认模块型号、目标 SSD 和分区配置。双盘 LVM 的初始化、扩容和恢复也涉及磁盘写入。

1. 选择刷机方式

需求	使用方式	主要影响
首次安装或完整重装 LC-X5	默认刷机模式	按板级配置更新启动固件和系统盘
建立 APP 恢复系统，并准备 LVM 运行系统	LC-X5 自定义 NVMe 分区模式	按自定义 XML 刷盘；启动后继续完成 LVM 初始化
启动固件正常，只需要重装 SSD 系统	`--external-only`	重刷指定 NVMe；不更新 QSPI
修复或更新启动固件	`--qspi-only`	更新 QSPI 启动固件；不重装 NVMe rootfs

2. 刷机前准备

2.1 主机与设备

准备以下设备和环境：

一台 Linux 刷机主机。建议使用 x86_64 Ubuntu 22.04 或 24.04；R39.2 官方刷机主机发行版要求见 Release Notes。
可正常运行的 Docker，以及运行带 USB 设备访问权限的容器的权限。
已安装目标 NVMe SSD 的 LC-X5，以及稳定的电源。
一根支持数据传输的 USB 线，连接主机与设备的 Recovery 接口。建议直接连接主机。
显示器和键盘，或能够查看设备启动日志的串口控制台。
足够的主机磁盘空间，存放容器镜像、BSP、生成的镜像和日志。先检查 df -h，空间需求随 rootfs 和分区大小变化。

以下容器命令按原生 Linux 主机编写。容器仍依赖主机的 USB 和内核环境，不能把 Windows/macOS 上的 Docker Desktop 直接视为同等刷机环境。

首次操作时只连接一台待刷机设备。刷机主机上的 lsblk 显示的是主机磁盘，不能据此判断通过 Recovery USB 连接的 Jetson 内部 SSD。

2.2 选择模块配置

Jetson Thor 模块	NVIDIA 模块编号	板级配置 `<board>`	Force Recovery USB ID
T5000，128 GB 内存	P3834-0008	`jetson-agx-thor-devkit`	`0955:7026`
T4000，64 GB 内存	P3834-0000	`jetson-agx-thor-t4000`	`0955:7226`

配置名和 USB ID 来自 NVIDIA R39.2 Quick Start。结合模块标签与配套 BSP 确认型号；自定义载板还需要设备厂商提供的适配，不能仅凭相同模块就套用其他载板的 BSP。

3. 进入 Force Recovery 模式

3.1 使用实体按键

实体按键需要拆开底部的盖子, 设备已经上电时：

按住 Force Recovery / RECOVERY 按键。
保持按住 RECOVERY，短按并松开 RESET 按键。
松开 RECOVERY。

关机状态下，也可以按住 RECOVERY，按下并松开 POWER，再松开 RECOVERY。

3.3 使用 UEFI 菜单

设备还能进入 UEFI 时，可尝试当前 LC-X5 流程中的菜单入口：

开机看到 NVIDIA 标志时，反复按 Esc。
进入 Device Manager → NVIDIA Configuration → Boot Configuration。
启用 Boot Into Recovery，保存设置并继续或重启。

菜单名称和位置可能随固件变化。操作后必须在主机确认 Recovery USB ID；若未出现，使用实体按键进入 Force Recovery。不要把 Linux recovery shell 或 LC-X5 的 APP recovery 当成已经进入 USB 刷机模式。

3.4 确认主机识别到设备

在刷机主机上执行：

bash

lsusb -d 0955:

T5000 应能看到 0955:7026，T4000 应能看到 0955:7226，设备名称可能带有 NVIDIA Corp. 或 APX。没有对应设备时，先检查数据线、Recovery 接口、供电和按键操作，再执行刷机命令。

4. 启动容器并准备 BSP

4.1 创建工作目录

在刷机主机上创建用于保存日志和文件的目录：

bash

mkdir -p ~/lc-x5-flash/workspace
cd ~/lc-x5-flash

这里的 workspace 是主机目录，进入容器后映射为 /workspace。放在 /workspace 中的文件会保留在主机上。

4.2 启动刷机容器

bash

docker run -it --rm \
  --privileged \
  --network host \
  -v /dev/bus/usb:/dev/bus/usb \
  -v /dev:/dev \
  -v "${PWD}/workspace:/workspace" \
  catdogai/lzc-x5-flash:39.2 \
  bash

若当前用户没有 Docker 权限，在 docker run 前加 sudo。

参数	用途
`--privileged`	允许刷机工具访问 USB、设备节点并执行所需系统操作
`--network host`	使用主机网络环境
`/dev/bus/usb`、`/dev` 挂载	访问 Recovery USB，以及设备重新枚举后的节点
`workspace` 挂载	保留日志和手动保存的产物
`--rm`	退出时删除该容器

/workspace 挂载不会自动保存镜像中的 /Linux_for_Tegra。容器退出后，未挂载目录中的修改和新文件会随容器删除；需要保留的日志或产物应在退出前复制到 /workspace。

4.3 准备 LC-X5 刷机环境

以下命令在容器内执行；每一步成功后再执行下一步：

bash

cd /Linux_for_Tegra
sudo ./tools/l4t_flash_prerequisites.sh
sudo ./apply_binaries.sh --openrm
sudo ./twsetup/install.sh

l4t_flash_prerequisites.sh 安装 NVIDIA 刷机依赖。
apply_binaries.sh 将 NVIDIA 二进制组件应用到 rootfs。R39.2 的 Thor 流程仍接受 --openrm，但该参数不再改变结果，见官方 BSP 准备步骤。
twsetup/install.sh 是配套安装步骤，按镜像中的提示完成；它不是 NVIDIA 标准 BSP 命令。

检查关键路径和当前脚本支持的参数：

bash

pwd
ls -ld bootloader kernel rootfs nv_tegra
ls -l l4t_initrd_flash.sh jetson-agx-thor-*.conf
sudo ./l4t_initrd_flash.sh -h
lsusb -d 0955:

本文沿用 LC-X5 BSP 顶层的 ./l4t_initrd_flash.sh 入口。官方工具目录是 tools/kernel_flash/；如果使用原版 BSP，按实际文件位置和该版本教程调用脚本。配套脚本缺失时，先核对镜像，不要直接跳过安装步骤。

确认 SSD、容量与分区布局

1 确认目标盘

--external-device nvme0n1 指的是 Jetson 端的设备名，不是刷机主机的磁盘名。安装多块 NVMe 时，不能仅凭插槽位置认定某块盘一定是 nvme0n1。

如果设备还能正常启动，在 LC-X5 系统内查看：

bash

lsblk -d -o NAME,PATH,SIZE,MODEL,SERIAL
lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,PARTLABEL,MOUNTPOINTS
cat /sys/block/nvme0n1/size
sudo blockdev --getsize64 /dev/nvme0n1

记录目标 SSD 的型号、序列号和实际容量。正常系统与刷机 initrd 中的枚举顺序也应核对，特别是双盘场景。

2 在刷机 initrd 中查询容量

如果设备已经进入配套刷机工具启动的 initrd，且该阶段已提供 ADB，可使用配套 ADB 工具。在容器内 /Linux_for_Tegra 执行：

bash

ADB=./unified_flash/out/bsp_images/tools/flashtools/flash/adb
"${ADB}" devices

将下面的占位符替换为上一步显示的设备序列号：

bash

THOR_SERIAL='<设备序列号>'
"${ADB}" -s "${THOR_SERIAL}" shell \
  /tmp/wr_sh.sh cat /sys/block/nvme0n1/size
"${ADB}" -s "${THOR_SERIAL}" shell \
  /tmp/wr_sh.sh cat /sys/block/nvme1n1/size

第二条容量查询只适用于装有第二块 NVMe 的情况。ADB 路径和 /tmp/wr_sh.sh 属于配套刷机环境；文件不存在时不能直接套用。

Force Recovery 的 BootROM 阶段不会提供上述 Linux sysfs 查询接口。 只有刷机工具已启动 initrd，并且 adb devices 能识别设备时，才能使用这些命令。

3 设置 `EXT_NUM_SECTORS`

EXT_NUM_SECTORS 指定外部存储布局使用的扇区数量。对于本文使用的 512 字节扇区布局：

text

字节容量 = EXT_NUM_SECTORS × 512
GiB 容量 = EXT_NUM_SECTORS × 512 ÷ 1024³

Linux 的 /sys/block/nvme0n1/size 按 512 字节单位返回容量。核对 XML 的 sector_size 后，可将该读数用于对应布局，不要使用 SSD 包装上的标称 GB 容量估算。

扇区数示例	对应容量	使用条件
`167772160`	80 GiB	明确使用 80 GiB 布局，且目标 SSD 容量不小于该值
`488397168`	约 232.89 GiB，即 250.06 GB	目标盘实际读数相符，或明确使用不超过实际容量的该布局

这些数字不适用于所有 LC-X5。比 SSD 更大的值可能导致分区越界和刷机失败；更小的值也不会自动使用全部剩余空间。

R39.2 默认 Thor 布局假定 NVMe 大于约 234 GiB；更小的盘需要设置实际容量，详见 R39.2 Release Notes 中的 NVMe 容量限制。

-S <size> 控制 APP 分区大小，与整盘扇区数量不同。调整容量时，要保证 APP、其他分区和 GPT 都能放入目标盘，不能把 APP 设置为整盘大小。布局字段见 NVIDIA 分区配置说明。

4 区分 LC-X5 自定义 XML 与 NVIDIA 原版 XML

本文的 LC-X5 自定义分区命令使用：

text

/Linux_for_Tegra/flash_l4t_t264_nvme.xml

NVIDIA 原版 NVMe 配置通常位于：

text

/Linux_for_Tegra/tools/kernel_flash/flash_l4t_t264_nvme.xml

两者即使文件名相同，内容和分区用途也可能不同。建立 LC-X5 的 APP recovery 与 LVM runtime 时，必须使用配套自定义布局，不能用原版 XML 替代。

在容器中检查自定义文件：

bash

test -f flash_l4t_t264_nvme.xml
grep -nE 'sector_size|num_sectors|partition name=|APP|DATA_PV' \
  flash_l4t_t264_nvme.xml

后续运行 lzc-thor provision 时，布局必须包含该工具要求的 APP 和 DATA_PV 分区。XML 缺失或布局不符时，先取得正确的配套文件。

5. 执行刷机

本节各方案按需求选择，不要依次全部执行。命令都在容器内 /Linux_for_Tegra 执行，设备应处于 Force Recovery 模式。更换方案、容量、模块或 XML 后，应重新生成对应镜像，不要直接复用上一次的产物。

官方参数见 Flashing Support for Jetson Thor（R39.2）。

5.1 自定义 NVMe 分区模式：为 LVM 准备布局

此模式用于准备 LC-X5 的 LVM 存储布局。命令首先按 LC-X5 自定义 XML 刷写指定 NVMe；--external-device 本身不会自动把两块 SSD 合并为 LVM。

T5000：

bash

sudo ./l4t_initrd_flash.sh \
  --external-device nvme0n1 \
  -c flash_l4t_t264_nvme.xml \
  jetson-agx-thor-devkit external

T4000：

bash

sudo ./l4t_initrd_flash.sh \
  --external-device nvme0n1 \
  -c flash_l4t_t264_nvme.xml \
  jetson-agx-thor-t4000 external

需要覆盖容量时，在 sudo 后加入 EXT_NUM_SECTORS=<已核对的扇区数>。

刷机并启动后，在 LC-X5 上检查布局和初始化状态：

bash

lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,PARTLABEL,MOUNTPOINTS
findmnt /
sudo lzc-thor provision status

如果配套流程尚未建立 LVM runtime，按 LC-X5 配置文档中的 provision 流程完成 APP recovery 和 LVM 初始化。该流程分两个阶段，每阶段都会重启，不要跳过恢复环境检查。

根文件系统已经使用 /dev/aipod_vg/lv_root 后，才可按同一文档中的 expand-lvm 流程加入第二块盘。先核对其型号和序列号，再执行只读预演：

bash

# /dev/nvme1n1 仅为示例，请替换为已核对的第二块盘
sudo lzc-thor expand-lvm --disk /dev/nvme1n1 --dry-run

LVM 扩容不等于磁盘镜像或冗余保护。成员盘加入根文件系统后，缺失任意成员盘都可能导致无法启动。

5.2 仅重刷 NVMe，不更新 QSPI

适用于 QSPI 正常且与目标 BSP 兼容，只需要重装 SSD 系统的情况。以下是 T4000 的示例：

bash

sudo ./l4t_initrd_flash.sh \
  --external-only \
  --external-device nvme0n1 \
  -c flash_l4t_t264_nvme.xml \
  jetson-agx-thor-t4000 external

T5000 将配置名替换为 jetson-agx-thor-devkit。

--external-only 仍会重写外部磁盘分区和系统，不是保留数据的增量更新。若 QSPI 损坏或版本不兼容，此方案不能修复启动固件。

生成外部镜像后，可辅助检查本次记录的目标设备：

bash

grep -n '^external_device=' tools/kernel_flash/images/external/flash.cfg

该文件可能在生成镜像后才存在，也可能来自旧任务。它记录的是刷机配置，不能代替 SSD 型号、序列号和 initrd 枚举结果的核对。

5.3 仅更新 QSPI 启动固件

QSPI 保存启动链固件，包括 bootloader 和 UEFI。此操作不重装 NVMe 系统，也不等同于更新 Linux 内核、GPU 驱动或 CUDA。

T5000：

bash

sudo ./l4t_initrd_flash.sh \
  --qspi-only jetson-agx-thor-devkit mmcblk0p1

T4000：

bash

sudo ./l4t_initrd_flash.sh \
  --qspi-only jetson-agx-thor-t4000 mmcblk0p1

mmcblk0p1 沿用官方 QSPI-only 示例中的位置参数；在此模式下，不应理解为要刷写一块 eMMC 系统盘。

仅在型号正确、固件与系统版本配套的前提下更新 QSPI。NVIDIA 标志后黑屏可能与启动固件有关，也可能是启动顺序、SSD、rootfs 或显示服务问题，应先按故障排查章节定位。

5.4 保存刷机日志

将选定的命令接到 tee 可留存日志。以下以 T5000 默认模式为例，它本身就会执行刷机：

bash

set -o pipefail
sudo ./l4t_initrd_flash.sh jetson-agx-thor-devkit internal \
  2>&1 | tee "/workspace/flash-$(date +%Y%m%d-%H%M%S).log"

pipefail 让管道保留刷机命令的失败状态，避免日志保存成功掩盖刷机失败。选择其他模式时替换为对应刷机命令，并保留容量和 XML 参数。

6. 刷机后的启动与验证

6.1 等待完成后重启

等工具明确报告成功并退出后，再重启设备。不要在写盘或更新 QSPI 时断电。

Thor 刷机后可能停留在 initrd 提示符，并不会自动进入安装好的 Linux。按 RESET，或在确认刷机结束后重新上电。参见官方刷机完成后的重启步骤。

若进入 UEFI Boot Manager，选择刚刷写的 NVMe 启动项。移除不再需要的 ISO 安装 U 盘，以免再次进入安装程序。

6.2 完成首次启动配置

如果出现 NVIDIA/Ubuntu 首次启动向导，按提示创建用户、设置密码、时区和网络。如果镜像已预建用户，按交付说明登录，不要假定所有镜像使用相同的默认密码。

6.3 验证版本、磁盘和 GPU

以下命令在刷好后的 LC-X5 上执行：

bash

cat /etc/nv_tegra_release
uname -r
dpkg-query -W nvidia-l4t-core
findmnt /
lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,PARTLABEL,MOUNTPOINTS
df -h /
nvidia-smi
sudo nvpmodel -q

检查要点：

nvidia-l4t-core 与目标 BSP 的 R39.2 版本一致；不能仅根据容器标签判断设备版本。
根文件系统来自预期磁盘或逻辑卷，容量与所选布局相符。
GPU 能被驱动识别；nvidia-smi 失败时继续检查软件包和内核日志。
LVM 模式进一步执行 sudo pvs、sudo vgs、sudo lvs，核对成员盘与 /dev/aipod_vg/lv_root。

常规初始化、JetPack 软件包、Docker、算力舱代理、VNC 和存储维护见 LC-X5 配置与 lzc-thor 使用。先确认配套首次启动流程已完成，再按需初始化。

7. 常见问题

7.1 主机看不到 Recovery 设备

确认 USB 线支持数据传输，连接到 Recovery 接口。
保持供电，重新按 RECOVERY + RESET。
在主机检查 lsusb -d 0955:；必要时用 sudo dmesg -w 观察 USB 插拔日志。
主机已识别但容器看不到时，检查 /dev 挂载和容器权限，再在容器内执行 lsusb。

Recovery 模式下没有正常桌面显示，并不代表设备损坏；以 USB 枚举结果为准。

7.2 等待目标启动、USB/ADB 超时

检查供电、数据线和设备重新枚举后的 USB 状态。
核对 T5000/T4000 配置是否选对，是否完成 BSP 准备。
断开不参与刷机的 USB 外设后重试，并重新进入 Force Recovery。
保存主机刷机日志与设备串口日志，定位是在生成镜像、启动 initrd、识别磁盘还是写入阶段失败。

ADB 查询仅适用于 initrd 已启动的阶段；adb devices 为空时，反复执行容量查询不能解决问题。

7.3 分区容量超出磁盘、GPT 或写盘失败

重新读取目标盘 /sys/block/nvme0n1/size，核对 EXT_NUM_SECTORS、XML 的 sector_size/num_sectors，以及 APP 和其他分区总大小。即使标称 256 GB 的 SSD，也应使用实际读数检查是否满足默认布局。

参数或布局改变后重新生成镜像。不要只修改 flash.cfg，也不要复用不同容量磁盘生成的产物。

7.4 NVIDIA 标志后黑屏或无法进入系统

按以下顺序排查：

确认刷机成功，并在结束后手动重启过设备。
按 Esc 查看 UEFI 能否识别 SSD，检查 Boot Manager 与启动顺序。

如果仍可 SSH 登录，先检查显示与系统服务：

bash

systemctl --failed
systemctl status display-manager
sudo journalctl -b -p err --no-pager
sudo dmesg -T | grep -Ei 'nvme|I/O error|ext4|nvidia|drm'

如果无法进入系统，用串口日志判断是否缺失 NVMe、找不到 rootfs，或停在恢复环境。双盘 LVM 还要检查所有成员盘是否连接。
如果此前只刷过 NVMe，且证据指向 QSPI 损坏或固件与 BSP 不配套，再使用 QSPI-only 模式更新启动固件。

仅重刷 QSPI 无法修复损坏的 rootfs 或缺失的 LVM 成员盘。

7.5 容器退出后找不到日志或产物

--rm 会删除容器；只有挂载目录中的文件仍在主机上。日志应保存到 /workspace，对应主机的 ~/lc-x5-flash/workspace。退出前保存所需 XML、日志和本次参数记录。

8. 官方教程与进一步阅读

与本文版本匹配的官方开发文档：

官方资料	适合查看的内容
JetPack 7.2 下载与版本说明	R39.2 对应关系、BSP 和 sample rootfs 下载
Jetson Linux R39.2 Quick Start	BSP 准备、模块配置、Recovery 与 USB ID
Flashing Support for Jetson Thor	initrd、NVMe、QSPI-only、单分区与批量刷机
Partition Configuration	XML、分区、扇区大小和容量设置
UEFI Adaptation	启动顺序、启动模式和恢复启动设置
R39.2 Release Notes（PDF）	主机支持范围、容量限制和已知问题
NVIDIA Jetson 文档归档	按实际 BSP 版本查找开发指南与发行说明

开发套件操作与其他安装方式：

官方教程	适用场景
Thor 开发套件硬件布局	参考开发套件的 Recovery、供电与调试接口
Thor Quick Start：制作 ISO 安装 U 盘	通过至少 16 GB 的 U 盘安装官方系统
Thor BSP Setup：ISO、SDK Manager 与脚本	比较安装路径及升级范围
使用 SDK Manager 安装 Jetson 软件	图形化刷机和 SDK 安装
SDK Manager 系统要求	主机资源和系统兼容要求
Thor UEFI 与 Jetson ISO 兼容说明	确认固件与 ISO 是否配套

带 /latest/ 的开发套件教程会随 NVIDIA 新版本更新，可能已使用 R39.2.1 或后续版本。本文命令仍基于 39.2 配套镜像；下载或刷写前应核对版本，不要直接将新版文件替换到当前 BSP。

随包说明同样应保留参考：Linux_for_Tegra/tools/kernel_flash/README_initrd_flash.txt；备份与恢复操作说明位于 Linux_for_Tegra/tools/backup-restore/README_backup_restore.txt，使用前确认该版本支持当前设备和存储布局。

LC-X5 刷机指南（NVIDIA Jetson Thor） ​

1. 选择刷机方式 ​

2. 刷机前准备 ​

2.1 主机与设备 ​

2.2 选择模块配置 ​

3. 进入 Force Recovery 模式 ​

3.1 使用实体按键 ​

3.3 使用 UEFI 菜单 ​

3.4 确认主机识别到设备 ​

4. 启动容器并准备 BSP ​

4.1 创建工作目录 ​

4.2 启动刷机容器 ​

4.3 准备 LC-X5 刷机环境 ​

1 确认目标盘 ​

2 在刷机 initrd 中查询容量 ​

3 设置 EXT_NUM_SECTORS ​

4 区分 LC-X5 自定义 XML 与 NVIDIA 原版 XML ​

5. 执行刷机 ​

5.1 自定义 NVMe 分区模式：为 LVM 准备布局 ​

5.2 仅重刷 NVMe，不更新 QSPI ​

5.3 仅更新 QSPI 启动固件 ​

5.4 保存刷机日志 ​

6. 刷机后的启动与验证 ​

6.1 等待完成后重启 ​

6.2 完成首次启动配置 ​

6.3 验证版本、磁盘和 GPU ​

7. 常见问题 ​

7.1 主机看不到 Recovery 设备 ​

7.2 等待目标启动、USB/ADB 超时 ​

7.3 分区容量超出磁盘、GPT 或写盘失败 ​

7.4 NVIDIA 标志后黑屏或无法进入系统 ​

7.5 容器退出后找不到日志或产物 ​

8. 官方教程与进一步阅读 ​

LC-X5 刷机指南（NVIDIA Jetson Thor）

1. 选择刷机方式

2. 刷机前准备

2.1 主机与设备

2.2 选择模块配置

3. 进入 Force Recovery 模式

3.1 使用实体按键

3.3 使用 UEFI 菜单

3.4 确认主机识别到设备

4. 启动容器并准备 BSP

4.1 创建工作目录

4.2 启动刷机容器

4.3 准备 LC-X5 刷机环境

1 确认目标盘

2 在刷机 initrd 中查询容量

3 设置 `EXT_NUM_SECTORS`

4 区分 LC-X5 自定义 XML 与 NVIDIA 原版 XML

5. 执行刷机

5.1 自定义 NVMe 分区模式：为 LVM 准备布局

5.2 仅重刷 NVMe，不更新 QSPI

5.3 仅更新 QSPI 启动固件

5.4 保存刷机日志

6. 刷机后的启动与验证

6.1 等待完成后重启

6.2 完成首次启动配置

6.3 验证版本、磁盘和 GPU

7. 常见问题

7.1 主机看不到 Recovery 设备

7.2 等待目标启动、USB/ADB 超时

7.3 分区容量超出磁盘、GPT 或写盘失败

7.4 NVIDIA 标志后黑屏或无法进入系统

7.5 容器退出后找不到日志或产物

8. 官方教程与进一步阅读