深度解析 RK 平台 U-Boot 环境变量（env）：原理、配置与实战

环境变量（env）是 U-Boot 的核心配置机制，无需重新编译即可灵活调整启动参数。在 Rockchip（RK）平台上，环境变量不仅继承了 U-Boot 的通用特性，还针对 RK 芯片架构做了大量定制化设计。本文将从通用概念、RK 平台特殊处理、工作流程、调试方法等维度，全面拆解 RK 平台环境变量的底层逻辑与实操技巧。

一、环境变量的通用概念

1.1 什么是环境变量？

环境变量是 U-Boot 中以 “键值对” 形式存储的配置信息，示例如下：

 

bootdelay=3bootcmd=mmc dev 0; fatload mmc 0 0x40400000 Image; booti 0x40400000

 

这些变量在 U-Boot 启动时加载，直接控制启动流程、设备信息、内存布局等核心配置。

1.2 环境变量的存储结构

环境变量在存储介质上的结构定义于include/environment.h，核心结构如下：

 

typedef struct environment_s {    uint32_t    crc;        /* CRC32校验 */#ifdef CONFIG_SYS_REDUNDAND_ENVIRONMENT    unsigned char flags;    /* 冗余标志 */#endif    unsigned char data[ENV_SIZE]; /* 实际数据 */} env_t;

 

数据区存储规则：

•以结尾的字符串列表，格式为name=value；

•整个列表以双结束。

1.3 环境变量的存储位置

U-Boot 支持多类存储介质，RK 平台常用的有：

•MMC/eMMC（最主流）；

•SPI Flash（SPI NOR/NAND）；

•NAND Flash（大容量存储）；

•FAT 文件系统（以文件形式存储）；

•NOWHERE（仅内存运行，不持久化）。

二、RK 平台的特殊处理

2.1 架构专属配置

RK 平台在u-boot/env/Kconfig中设有专属配置段，定义环境变量的核心参数：

 

if ARCH_ROCKCHIPconfig ENV_OFFSET    hex "Environment offset"    default 0x3f8000  /* 默认偏移地址 */config ENV_SIZE    hex "Environment size"    default 0x8000    /* 32KB大小 */if ENVF    config ENV_OFFSET_REDUND    config ENV_NAND_OFFSET    config ENV_NOR_OFFSET    ...endifendif

 

2.2 分区布局规范

RK 平台默认分区布局定义于include/configs/rockchip-common.h，核心片段如下：

 

#define PARTS_RKIMG     "uuid_disk=${uuid_gpt_disk};"     "name=uboot,start=8MB,size=4MB,uuid=${uuid_gpt_loader2};"     "name=trust,size=4M,uuid=${uuid_gpt_atf};"     "name=misc,size=4MB,uuid=${uuid_gpt_misc};"     "name=resource,size=16MB,uuid=${uuid_gpt_resource};"     "name=kernel,size=32M,uuid=${uuid_gpt_kernel};"     "name=boot,size=32M,bootable,uuid=${uuid_gpt_boot};"     ...

 

 关键结论：环境变量通常存储在uboot分区的0x3f8000偏移位置（4MB - 32KB）。

2.3 RK3576 内存布局定制

针对 RK3576 芯片，include/configs/rk3576_common.h定义了内存布局相关环境变量：

 

#define ENV_MEM_LAYOUT_SETTINGS     "scriptaddr=0x40500000"     "pxefile_addr_r=0x40600000"     "fdt_addr_r=0x48300000"     "kernel_addr_r=0x40400000"     "kernel_addr_c=0x45480000"     "ramdisk_addr_r=0x4a200000"

 

2.4 启动设备自动检测

RK 平台内置智能启动设备检测逻辑，自动识别启动介质：

 

#define RKIMG_DET_BOOTDEV     "rkimg_bootdev="     "if mmc dev 1 && rkimgtest mmc 1; then "         "setenv devtype mmc; setenv devnum 1; echo Boot from SDcard;"     "elif mmc dev 0; then "         "setenv devtype mmc; setenv devnum 0;"     "elif mtd_blk dev 0; then "         "setenv devtype mtd; setenv devnum 0;"     "elif rknand dev 0; then "         "setenv devtype rknand; setenv devnum 0;"     "elif rksfc dev 0; then "         "setenv devtype spinand; setenv devnum 0;"     "elif rksfc dev 1; then "         "setenv devtype spinor; setenv devnum 1;"     "else;"         "setenv devtype ramdisk; setenv devnum 0;"     "fi; "

 

2.5 多启动方式支持

RK 平台支持 Android、Fit、RKP、Distro 等多种启动方式：

 

#define RKIMG_BOOTCOMMAND     "boot_android ${devtype} ${devnum};"     "boot_fit;"     "bootrkp;"     "run distro_bootcmd;"

 

三、环境变量的工作流程

3.1 整体流程

3.2 MMC 存储详细流程

RK 平台最常用的 MMC 存储流程如下：

3.3 核心代码路径

初始化核心逻辑（env/env.c）：

 

int env_init(void) {    struct env_driver *drv = env_driver_lookup_default();    int ret = -ENOENT;
    if (!drv)        return -ENODEV;    if (drv->init)        ret = drv->init();    if (ret == -ENOENT) {        // 使用默认环境        gd->env_addr = (ulong)&default_environment[0];        gd->env_valid = ENV_VALID;        return 0;    }    return ret;}

 

环境驱动查找逻辑：

 

static struct env_driver *env_driver_lookup(enum env_location loc) {    struct env_driver *drv;    const int n_ents = ll_entry_count(struct env_driver, env_driver);    struct env_driver *entry;
    drv = ll_entry_start(struct env_driver, env_driver);    for (entry = drv; entry != drv + n_ents; entry++) {        if (loc == entry->location)            return entry;    }    return NULL;}

 

四、环境变量的使用与调试

4.1 常用命令

功能	命令示例
查看所有环境变量	printenv / env
查看特定变量	printenv bootcmd
设置环境变量	setenv bootcmd "mmc dev 0; fatload mmc 0 0x40400000 Image; booti 0x40400000"
保存环境变量	saveenv
删除环境变量	setenv bootcmd
恢复默认环境	env default -a

4.2 调试技巧

1.启用调试日志：编译时开启 Kconfig 调试选项，或在源码中添加printf输出；

2.检查环境有效性：

 

if (gd->env_valid == ENV_INVALID) {    printf("使用默认环境n");}

 

3.手动读取环境数据：

 

# 从MMC读取环境数据到内存0x40500000mmc read 0x40500000 0x3f8000 0x10# 查看内存数据md 0x40500000

 

4.CRC 校验验证：环境数据前 4 字节为 CRC32 值，可手动计算验证。

4.3 常见问题排查

问题现象	可能原因	解决方法
保存环境变量后重启丢失	1. saveenv 执行失败 2. 存储介质故障 3. 偏移地址配置错误	1. 检查 saveenv 输出日志 2. 验证 CONFIG_ENV_OFFSET 配置 3. 测试存储介质读写功能
启动提示 bad CRC	1. 环境数据损坏 2. 首次启动无环境数据	执行env default -a恢复默认环境
环境变量过大无法保存	变量数量 / 长度超出 ENV_SIZE 限制	1. 清理无用变量 2. 增大 CONFIG_ENV_SIZE 配置

4.4 关键配置选项

配置项	作用	默认值（RK 平台）
CONFIG_ENV_IS_IN_MMC	启用 MMC 存储环境变量	开启
CONFIG_ENV_OFFSET	环境变量存储偏移	0x3f8000
CONFIG_ENV_SIZE	环境变量存储空间大小	0x8000（32KB）
CONFIG_SYS_MMC_ENV_DEV	指定 MMC 设备号	根据硬件配置
CONFIG_ENV_OFFSET_REDUND	冗余环境备份偏移	可选配置

五、RK 专属：ENVF 环境片段机制

ENVF（Environment Fragment）是 RK 平台特有的环境变量增强机制，允许将环境变量存储在专用分区，实现动态覆盖与合并。

5.1 核心配置

 

config ENVF    bool "Environment fragment is store in envf partition"    depends on ENV_IS_NOWHEREconfig ENVF_LIST    string "Specific environments white list of env fragment"    default "blkdevparts mtdparts sys_bootargs app reserved"

 

5.2 典型使用场景

•动态配置分区信息；

•存储产品定制化参数；

•跨固件版本共享核心配置。

六、实战案例：RK3576 自定义环境变量

6.1 修改默认环境（编译期）

在板级配置文件include/configs/rk3576_common.h中添加自定义变量：

 

#define CONFIG_EXTRA_ENV_SETTINGS     ENV_MEM_LAYOUT_SETTINGS     "partitions=" PARTS_RKIMG     ROCKCHIP_DEVICE_SETTINGS     RKIMG_DET_BOOTDEV     BOOTENV     "my_custom_var=hello_rk3576"     "bootargs_append=console=ttyS2,1500000n8"

 

6.2 运行时修改（命令行）

 

# 设置自定义启动参数setenv bootargs console=ttyS2,1500000n8 root=/dev/mmcblk0p7 rootwait rw# 保存配置saveenv# 重启生效reset

 

七、总结

RK 平台的 U-Boot 环境变量机制，在通用 U-Boot 基础上做了三大核心增强：

1.多介质适配：完美支持 MMC、SPI、NAND 等主流存储；

2.智能启动：自动检测启动设备，适配多场景启动需求；

3.灵活扩展：通过 ENVF 机制实现环境变量动态管理。

掌握上述知识点，既能快速定位环境变量相关问题，也能根据项目需求灵活定制启动配置，充分发挥 RK 平台的硬件特性。

参考文件

•u-boot/env/env.c：核心环境管理逻辑；

•u-boot/env/mmc.c：MMC 存储实现；

•u-boot/include/environment.h：环境数据结构定义；

•u-boot/include/configs/rockchip-common.h：RK 通用配置；

•u-boot/include/configs/rk3576_common.h：RK3576 专属配置；

•u-boot/env/Kconfig：环境变量配置选项。

审核编辑 黄宇