U-Boot 命令参考：地址、存储、启动与版本边界

参考速查更新于 2026-10-03编辑本文

U-Boot 命令由版本、板级配置和驱动共同决定。本页以 上游 U-Boot v2024.01 的命令源码为固定核对基线，补充链接到官方现行文档。它用于理解和查找命令；板上真正支持的参数，以该镜像的 version 和 help 命令名 为准。厂商 BSP 新增命令单独列在文末。

完整操作流程见加载、校验与存储更新。=> 表示 U-Boot 提示符，文中的命令不在 Linux shell 中执行。

1. 先认识版本、地址、数量与返回值

version
help
help mmc
bdinfo
coninfo
printenv kernel_addr_r fdt_addr_r ramdisk_addr_r loadaddr

bdinfo 可以帮助识别 DRAM 和重定位位置，但“位于 DRAM 内”不等于“可以随意覆盖”：U-Boot 自身、栈、堆、设备树、已加载镜像以及固件保留区都可能占用其中一部分。加载地址还要为内核解压和重定位留空间。

表达方式	含义与例子
普通命令名称	推荐完整拼写。`pri` 等缩写只在当前命令表中唯一时成立；不能当作永久别名。
`.b`、`.w`、`.l`、`.q`	对支持这些后缀的内存命令，分别为 1、2、4、8 字节元素；`.q` 可用性取决于构建。
数字进制	`md`、`mw`、`cp`、`cmp`、`setexpr`、`itest` 等通常按十六进制解析。`10` 在这些位置表示十进制 16，不能沿用 shell 的十进制直觉。
数量单位	`cp.l … 0x100` 是 256 个 4 字节元素，共 1024 字节；`cp.b … 0x100` 才是 256 字节。
块数与字节数	`mmc read/write` 的末参数是块数；`load` 设置的 `filesize` 是字节数。两者不能直接混用。
返回状态	一般命令以 0 表示成功。`if 命令; then …` 判断的是执行状态，不自动等于传感器读数或镜像可信。

不要把所有命令的参数都当十六进制：例如 sleep 的秒数、部分设备序号和总线速率有各自解析规则，查对应帮助。test 的数字解析与 itest 也不同；比较 U-Boot 的十六进制地址或长度时优先明确使用 itest。

2. 环境变量：修改、使用与持久化

printenv bootcmd bootargs bootdelay
setenv example hello
printenv example
setenv example

setenv example 删除变量。setenv 修改当前内存中的环境，后续读取它的命令即可使用新值；并非一律等到重启才生效。saveenv 将当前环境写入配置的持久存储，目的在于下次启动仍能保留。试验期间先临时修改并验证，再决定是否保存。

命令	作用及边界
`env print` / `printenv`	显示环境变量。
`env set` / `setenv`	设置或删除变量；受只读、只写一次等标志影响。
`env save` / `saveenv`	持久保存；需要存在可写的环境后端。
`env default bootcmd`	仅把该变量恢复为编译默认值；默认值也要与实际板卡匹配。
`env default -a`	恢复整个默认环境，当前内存中的其他设置可能丢失。
`env default -f -a`	强制恢复，包括受标志保护的变量；不应作为一般启动故障的第一步。
`env export -t 地址`	导出文本环境，成功后将实际长度写入 `filesize`。
`env export -b -s 长度地址`	导出指定大小的二进制环境；`-s` 不能省略成一个普通尾参数。
`env import -t 地址长度`	导入文本环境；明确长度。`-d` 会先删除相关现有变量，不能随意追加。
`editenv 名称`、`askenv 名称`	行编辑或交互输入变量，不是启动一个 vi 编辑器。
`env exists 名称`	检查环境变量是否存在。
`env erase` / `eraseenv`	在提供该功能的构建中擦除持久环境；与只改当前变量不同，不能作常规清理。
`showvar`	Hush 本地变量，和可保存的环境变量有区别。

不要把 save 当作 saveenv 的通用简写：支持通用文件系统写入的构建中，save 本身可能是写文件命令。

自动启动相关变量

变量	含义
`bootcmd`	自动启动流程要执行的命令字符串。
`bootargs`	交给操作系统的命令行；不是 U-Boot 自己的参数列表。
`bootdelay=3`	通常等待 3 秒，期间允许中断；板级配置可能覆盖它。
`bootdelay=-1`	禁止自动执行启动流程。
`bootdelay=-2`	不等待，也不检查中断按键，立即自动启动。它绝不是“完全禁用启动”。
`autoload=no`	在常见 BOOTP/DHCP 流程中只取得网络配置，不继续下载镜像。
`autostart=no`	调试加载时避免相关加载命令自动启动镜像；具体适用命令看版本文档。

展开时机与错误传播

setenv load_kernel 'load mmc 0:1 ${kernel_addr_r} zImage'
setenv load_dtb 'load mmc 0:1 ${fdt_addr_r} board.dtb'

单引号让 ${kernel_addr_r} 留在命令字符串中，等 run load_kernel 时展开。相反，给已有 bootargs 追加参数时，需要展开旧值：

setenv bootargs "${bootargs} loglevel=8"

run load_kernel; run load_dtb; run boot_kernel 中，分号不会保证前一步失败后停止。可用嵌套 if，或在兼容的 Hush 中用 &&。run load_kernel load_dtb boot_kernel 对多个变量的失败处理也应与目标版本帮助核对；不能把分号串等同于事务。

3. 内存命令与数值计算

下列地址都须先确认为专用测试缓冲区。

命令形式	说明
`md.b 地址 0x10`	显示 16 字节。默认显示数量和元素宽度可沿用前次命令；需要可重复结果时明确给出。
`mm.l 地址`	交互修改后递增地址。
`nm.l 地址`	交互修改同一地址。
`mw.b 地址 0xaa 0x10`	填充 16 字节为 `0xaa`。
`cp.b 源地址目标地址字节数`	复制数据；两区及其占用必须合法，不将它当作任意重叠区的通用 `memmove`。
`cmp.b 地址1 地址2 字节数`	比较精确字节数。
`crc32 地址字节数`	检测意外损坏，不证明来源可信。普通形式不自动创建 `crc32_result` 环境变量。
`hash sha256 地址字节数`	计算摘要；预期摘要必须来自可信渠道。
`base` / `base 偏移`	查看或设置部分内存命令的基址偏移；读旧操作记录时必须注意是否被改过。
`mtest 起点终点模式次数`	破坏性 RAM 测试，算法/终点行为随配置变化；不能覆盖当前程序和保留内存。
`loop` / `loopw`	循环访问，参数及可否响应中断要查构建，不能假设必有“微秒延时”尾参数。

setexpr result 0x10 + 0x20
printenv result
itest 0x100 -eq 0x100

第一个结果是十六进制 30，即十进制 48。itest 0x100 -eq 256 比较的是 0x100 与 0x256，并不相等。按位运算可给操作符加单引号，避免被 shell 当作控制符，例如 setexpr mask 0xff '&' 0x0f。setexpr result ~ 0 不是该基线支持的通用一元取反语法；明确字宽后可用按位异或掩码。

4. 设备、硬件分区、磁盘分区与文件

这是最容易混淆的四层：

控制器/设备号 → eMMC硬件分区 → GPT/MBR磁盘分区 → 文件系统内文件

mmc dev 0 1 的 1 是 eMMC 硬件分区号，不是 FAT/GPT 的第一个分区；load mmc 0:1 … 的 :1 才是块设备上的磁盘分区号。SD 卡与 eMMC 是否为设备 0/1 取决于板级编号。

目标	发现与读取	写入边界
MMC/SD/eMMC	`mmc list`、`mmc dev 设备号`、`mmc info`、`mmc part`、`mmc read 地址起始块块数`	`mmc write` / `mmc erase` 按块操作，会绕过文件系统。
USB 存储	`usb start`、`usb tree`、`usb storage`、`usb dev`、`usb part`	原始 `usb read/write` 的数量同样按块解释。
SATA/IDE	`sata`、`ide` 对应初始化、信息、选择与原始读写	具体子命令由该版本 `help sata` / `help ide` 决定。
磁盘分区	`part list mmc 0`、`part uuid mmc 0:1 变量名`	`part start`、`part size` 的语法为 `接口设备分区变量名`，不是所有子命令都用 `设备:分区`。
FAT	`fatls`、`fatinfo`、`fatload`、`fatsize`	`fatwrite`、`fatrm`、`fatmkdir` 需要对应写功能。
EXT	`ext2ls/load`、`ext4ls/load/size`	`ext4write` 的特性支持和内存开销要查版本，不能假设等同 Linux 完整文件系统实现。
通用文件访问	`ls`、`load`、`size`、`fstype`、`fstypes`	`save` 需对应文件系统支持；`fstype` 保存结果需提供变量名，不能假定自动生成同名变量。

mmc list
mmc dev 0
mmc part
part start mmc 0 1 first_lba
part size mmc 0 1 block_count
ls mmc 0:1 /

原始分区读命令 read 接口设备:分区地址起始块块数 与 load … 文件名 不同。usbboot 也不能笼统理解为 usb start + fatload 文件 + bootz；应查目标镜像是否支持其特定镜像格式与分区方式。

表中 EXT 缩写对应 ext2load、ext4load、ext4size 等完整命令；mmcinfo 是部分构建的独立信息入口。创建链接的 ln 只在相关文件系统写功能存在时使用，不能假定 FAT 具备 Unix 符号链接语义。

5. Flash、MTD、UBI 与 UBIFS

层次	命令与用途
SPI NOR	`sf probe` 后才能 `sf read/write/erase/update/test`；`sf write` 前需有正确擦除状态。
并行 NOR	`flinfo`、`protect`、`erase`，不是所有板卡都有。
NAND	`nand info/device/bad/dump/read/write`；普通数据写入、OOB、ECC及坏块处理必须匹配镜像制作和 ROM 要求。
MTD 分区	`mtdparts` 管理该环境的分区定义；它不是为任意现有数据自动创建文件系统。
UBI	`ubi part 分区名` 附着 MTD，随后查询/创建/读写卷。
UBIFS	`ubifsmount ubi0:卷名` 后 `ubifsls`、`ubifsload`，`ubifumount` 卸载。

三个关键区别：

sf update 逐擦除单元比较和更新；末单元不足整块时，数据后面的区域也可能被擦除，不能把它当作无条件保护相邻数据的任意字节更新。
ubi part 分区名偏移 中偏移是 VID header offset，不是从分区中任取一个字节开始附着。
ubi write.part 是分段写入已有卷，不会自动创建卷；.ubifs 文件系统镜像、包含卷布局的 .ubi 镜像与裸 NAND 镜像不是可互换的格式。

nand write.trimffs、.yaffs、旧 .jffs2 等后缀须按版本和镜像格式核查，不依据文件扩展名猜写法。nand scrub 会破坏坏块标记；markbad、torture、整片擦除也不是日常恢复流程。

6. 网络与串口加载

printenv ipaddr serverip netmask gatewayip ethact
setenv autoload no
setenv autostart no

命令	用途与容易误解的地方
`ping 服务器IP`	只能证明这条 ICMP 路径可达，不能证明 TFTP 文件可读。
`tftpboot 地址文件名`	从 `serverip` 下载到内存；成功后立即保存本次 `filesize`，后续加载会覆盖它。`tftp` 常可作唯一缩写。
`tftpput 地址字节数 [[服务器IP:]文件名]`	上传内存中的实际字节，服务器也要允许该上传；不能把 `md 地址 > log.txt` 当作通用重定向来准备文件。
`dhcp` / `bootp`	获取地址，可继续下载镜像；只配置网络时显式设置 `autoload no`。
`nfs 地址服务器IP:路径`	由 U-Boot 读取 NFS 文件；与 Linux 启动后挂载 NFS 根文件系统是两个阶段。
`mii` / `mdio`	查询 PHY 和管理总线，子命令参数查实际版本。响应地址不是自动识别出准确芯片型号。
`loadb`、`loadx`、`loady`	Kermit、XMODEM、YMODEM；主机终端和固件必须支持对应协议。
`loads`	Motorola S-record；参数是记录地址的偏移，不等于无地址原始二进制的简单加载地址。

net list、sntp 等命令也依赖配置。TFTP 不是带认证和加密的传输；校验用途见后文。

7. 镜像格式、启动和脚本

命令	输入与边界
`boot` / `bootd`	执行当前 `bootcmd`。
`bootm`	Legacy uImage 或 FIT 等受支持格式；并非仅 uImage。
`bootz`	支持的平台上的 Linux zImage；设备树型平台必须提供正确 DTB。
`booti`	支持的平台上的 Linux Image；Image 有架构定义的头部，不是“无头任意bin”。是否支持压缩取决于配置及解压内存安排。
`bootelf -p 地址`	按 ELF program headers 加载并执行；`-p` 不是“只加载不运行”。`-s` 对应 section headers。
`go 地址参数…`	调用符合平台约定的独立程序入口，不保证能直接启动任意 Linux 或 Cortex-M 固件。
`bootaux`	SoC 专用辅助核心启动，需链接布局、地址映射和装载步骤配合。
`source 地址`	执行已封装为 Legacy/FIT 的脚本，不是直接解释任意文本。没有通用 `source 地址 arg1 arg2` 的位置参数接口。
`iminfo`、`imxtract`	查看受支持镜像结构或抽取组件；普通裸 zImage 不能冒充 Legacy/FIT。
`bootflow`、`pxe`、`sysboot`	标准启动扫描、网络或 extlinux/syslinux 配置入口；新旧版本和配置有差异。
`reset`、`poweroff`	请求平台复位/关机；具体复位域和断电能力由硬件实现，不能断言与按键完全相同。

原始 initramfs 常需 地址:大小；不带大小的 ramdisk 参数可能按带头镜像解释。例如：

bootz ${kernel_addr_r} ${ramdisk_addr_r}:${ramdisk_size} ${fdt_addr_r}

这条命令的三个对象应事先全部成功加载，且 ramdisk_size 必须来自那一次 ramdisk 加载。

Hush 控制结构包括 if/then/else/fi、循环以及 run；可用功能由 shell 配置决定。source、run、exit 的作用域与返回状态应实际测试，不能把 Bash 脚本原样复制进来。

true 与 false 分别返回成功和失败，适合验证分支结构；echo 只打印文字。脚本最后打印 echo Failed 通常会把该分支的最终状态变为成功，若调用者需要得到失败状态，应在后面执行 false。

8. FDT：操作的是内存中的哪一棵树

fdt addr ${fdt_addr_r}
fdt header
fdt print /chosen
fdt rsvmem print

工作 FDT 通常是交给操作系统的设备树；U-Boot 自己用于驱动模型的 control FDT 可能是另一份。修改前先确认对象和所在缓冲区。

命令	作用
`fdt print` / `fdt list`	查看节点/属性或较浅层结构。
`fdt set`、`mknode`、`rm`	改属性、建节点、删节点或属性，仅修改当前内存副本。
`fdt move`	复制到新地址并切换工作树；目标缓冲区需可写且足够大。
`fdt resize` / `fdt addr 地址长度`	调整树可用空间；不替你申请或保护该段 RAM。
`fdt memory`	更新内存描述，多个连续调用不能简单理解为追加多段内存。
`fdt chosen`	处理启动相关属性，包括版本支持的 initrd 范围参数。
`fdt rsvmem add/delete/print`	管理 FDT 内存保留项，范围仍需与固件和系统设计一致。

reg 的编码取决于父节点的 #address-cells 和 #size-cells。不能对所有 32/64 位板卡统一套 fdt set /memory reg <起点大小> 两个 cell 的例子。

9. GPIO、I²C 与 SPI

GPIO 的读数不等于命令成功状态

gpio status -a
gpio read button_value 实际引脚名
printenv button_value

gpio read 需要“变量名、引脚”两个参数。确认读取成功后，再比较 button_value 与电路的有效电平。gpio set/clear/toggle 会操作输出；LED 亮灭由接线极性决定，不能固定称高电平必亮。GPIO 名和 LED 驱动标签也不保证可互换。

I²C 内部地址长度用后缀表示

i2c dev 0
i2c speed
i2c probe
i2c read 0x50 0x00.1 0x10 ${loadaddr}
md.b ${loadaddr} 0x10

上述读取 7 位地址 0x50 设备内部 0x00 起的 16 字节，.1 表示发送 1 字节内部地址。.0 表示不发送内部地址，.2 为 2 字节。不要把地址长度另写成一个参数，从而把后面的 RAM 地址或长度挤错位置。

写入形式是 i2c write 内存地址芯片地址内部地址.长度字节数。EEPROM 还涉及页边界、写周期和 ACK 轮询；probe 有响应也不证明该地址一定是 EEPROM。md/mm/nm/mw/crc32/loop 等辅助命令同样必须匹配被访问器件的寄存器语义。

SPI 的片选边界

sspi 发送原始传输，sf 是 SPI Flash 协议驱动。JEDEC ID 的命令字与后续时钟一般需要位于同一次片选有效期间；把 0x9f 和三个空字节拆为四条各自释放片选的命令，不能保证读到 ID。优先用 sf probe 识别 Flash，其他原始交易按器件时序和 help sspi 的数据格式构造。

10. 其他主题索引与版本边界

下列主题需要对应的驱动和构建选项。先通过帮助定位，再按硬件和版本查参数。

主题	查找入口	关键条件
时间、性能	`date`、`sleep`、`time`、`gettime`、`timer`	RTC、计时单位和 `timer` 子命令看构建；不保证通用 `timer reset`。
RTC 器件	`rtc list/dev/read/write`	基线中的 `rtc` 用于选择器件及访问寄存器；日期时间通常经 `date`，不是通用 `rtc get/set`。
CPU 与缓存	`cpu`、`dcache`、`icache`	CPU 子命令、缓存清理/失效和一致性要求依体系结构；关缓存不是解决 DMA 或多核一致性的通用办法。
压缩	`unzip`、`unlz4`、`lzmadec`、`gzwrite`	上游 `unzip` 解 gzip 内存流，不是解多文件 ZIP 压缩包；目标容量/重叠区须检查。`gzwrite` 直接写块设备。
驱动与引脚	`dm tree/uclass/drivers`、`pinmux`	`dm tree` 是驱动模型设备树，与 FDT 原始节点树不同。
电源、时钟	`pmic`、`regulator`、`clk`、`clocks`	名称、单位与可写子命令需核对；改核心电压/时钟不能脱离工作条件。
GPIO 外围	`led`、`button`、`adc`、`pwm`、`temperature`、`wdt`	驱动绑定、通道和单位必须确定；看门狗不一定能停止。
视频与控制台	`bmp`、`video`、`cls`、`setcurs`、`lcdputs`	BMP 位深/压缩、视频后端、控制台与固件版本各有条件。
USB 更新	`dfu`、`fastboot`、`ums`	DFU 第一个位置参数是 USB 控制器号，不是主机 `dfu-util -a` 的 alternate setting；UMS 暴露存储供主机读写。
UEFI / 其他 OS	`bootefi`、`efidebug`、`eficonfig`、`bootvx`	需相关功能，GUI 形式、设备树、体系结构和负载 ABI 都不通用。
分区与缓存	`gpt`、`blkcache`	GPT 写入改磁盘结构，缓存配置不等于更改文件系统。
调试总线	`pci`、`eeprom`、`fpga`	地址宽度、总线设备号、bitstream 类型与具体驱动一致。
安全与 OTP	`hash`、`fuse`、`tpm` / `tpm2`、`blob`、`optee_rpmb`	摘要、签名、OTP、TPM 和 RPMB 是不同机制；子命令不能混用不同 TPM 版本。
测试与信息	`random`、`cyclic`、`trace`、`acpi`、`license`、`panic`	测试随机数不自动达到密钥生成要求；日志/测试命令可能改变运行状态。
历史或平台扩展	`autoscr`、`diskboot`、`rarpboot`、JFFS2/CRAMFS 命令、`sha256sum`、`loadm7`、`qspihdr`、`videolink`、`qspi`、`elfload`、`alias`、`kermit`、`intr`	未指定 BSP 的扩展命令不能套通用参数表。先在目标镜像确认存在，再读取该厂商实现；例如 QSPI Flash 常经 `sf` 操作，SHA-256 可查 `hash sha256`。

安全启动的准确含义

hash sha256 或 crc32 只能给出摘要/校验值；verify=yes、文件名加 .signed 或 iminfo 打印成功，都不能单独建立安全启动链。FIT 验签还需要启用相应实现、正确的镜像与配置签名、受信任且受保护的公钥、强制验证策略，并防止其他启动路径绕过。防回滚又需要独立的版本策略和可信状态。官方 Verified Boot

11. 本页的核对依据

U-Boot v2024.01 源码：特别是 cmd/mem.c、cmd/i2c.c、cmd/part.c、cmd/ubi.c、cmd/read.c、cmd/unzip.c。
环境变量与 env 命令。
MMC、GPIO、itest、SPI Flash。
bootelf、source、booti。

本页的语法和软件行为核对不等于在某块实际硬件上烧录验证；涉及板级电气、Flash布局、镜像签名与 ROM 恢复能力的部分需要对应工程证据。

数值进制、内存元素计数、环境展开、导出/导入和脚本封装已在本地编译的 v2024.01 sandbox 中执行验证。模拟器只使用模拟 RAM 和临时文件；没有连接真实存储设备。