eMMC OTA 参数配置

4 Dec 2024

Read time: 8 minute(s)

eMMC OTA 主要涉及以下参数配置，以 d211_demo 的配置流程为例：

主系统：配置文件 d211_demo_defconfig。

1. target/d211/demo/image_cfg.json //分区配置和烧录
2. target/d211/common/env.txt //U-Boot 环境变量
3. target/d211/demo/rootfs_overlay/etc/fw_env.config //环境变量分区信息
4. target/d211/demo/rootfs_overlay/etc/swupdate_main //挂载 OTA 本地升级文件系统
5. target/d211/demo/swupdate/sw-description //OTA 策略描述文件
6. target/d211/demo/swupdate/sw-images.cfg //打包相应文件到 OTA 升级包中
7. target/configs/d211_demo_defconfig //板级配置文件

Recovery 系统：配置文件 d211_ota_emmc_defconfig。

1. target/d211/ota_emmc/rootfs_overlay/etc/fw_env.config //环境变量分区信息
2. target/d211/ota_emmc/rootfs_overlay/etc/init.d/S91swupdate_ota //开机自动挂载 OTA 分区与启动 OTA 升级程序
3. target/configs/d211_ota_emmc_defconfig //OTA 配置文件

主系统与 Recovery 系统启动脚本文件 package/third-party/swupdate/S90swupdate，开机后台执行 SWUpdate 程序。

Recovery 系统配置

为了简化使用，Recovery 系统的 OTA 相关配置已打开，用户无需手动配置。

配置SWUpdate 包
Recovery 系统配置文件路径为 target/configs/d211_ota_emmc_defconfig。
1. 执行下列命令进入 Recovery 系统 SDK 生产环境：
```
lunch ota_emmc
```
2. 在 Luban 根目录下，执行下列命令进入 Luban SDK 功能配置界面。
```
make m
```
3. 在 Luban SDK 功能配置界面，按如下选择：
```
Third-party packages  --->
    -*- libubootenv  --->
    -*- libconfig  --->
    -*- libcurl  --->
    [*] swupdate  --->
```

配置 RootFS 为 initramfs

默认切换 RootFS 配置为 initial RAM filesystem (initramfs)，执行命令 make m。

配置如下：

Filesystem images  --->
    RootFS images  --->
        -*- cpio the root filesystem (for use as an initial RAM filesystem)
            Compression method (gzip)  --->
    [*] initial RAM filesystem linked into linux kernel

默认将 initramfs 编译进 Kernel，执行命令 make km。

配置如下：

General setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
    [*]   Support initial ramdisk/ramfs compressed using gzip

编译 Recovery 系统
检查或配置完成后，执行 make m 命令编译 Recovery 系统。
- 编译完成后，output/d211_ota_emmc/images 目录下会生成 Recovery 系统的打包文件 Recovery.gz。
- Recovery.gz 为 d211 eMMC 平台通用 Recovery 系统。
- 拷贝 Recovery.gz 到 target/d211/common 目录下，各板级文件编译时会打包 Recovery.gz 到最终的镜像文件中，从而烧录到 recovery 分区 中。

主系统配置

配置 SWUpdate 包参数
注：如果需要重新配置 SWUpdate 参数，必须关掉 SWUpdate 预编译功能，修改的 SWUpdate 配置才能够生效
1. 执行下列命令进入主系统 SDK 生产环境：
```
lunch d211_demo
```
2. 在 Luban 根目录下执行配置命令：
```
make m
```
3. 进入 Luban SDK 功能配置，按如下配置选择：
```
Third-party packages  --->
    -*- libubootenv  --->
    -*- libconfig  --->
    -*- libcurl  --->
    [*] swupdate  --->
```
4. 查看并修改 SWUpdate 库相关配置。
  
  关于 SWUpdate 包参数描述，可查看SWUpdate 包重要配置描述。
  示例如下：
```
[*]   use prebuilt binary instead of building from source
(package/third-party/swupdate/luban_swupdate.config) swupdate configuration file
[*]   swupdate webserver
```
  1. 关闭 SWUpdate 预编译功能：
    [ ] use prebuilt binary instead of building from source
  2. 执行下列命令查看和修改 SWUpdate 相关配置：
    make swupdate-menuconfig

增加 recovery 分区并烧录系统镜像程序

在 image_cfg.json 中，添加 recovery 分区配置，同时确保 kernel.its 和 recovery.its 文件存在并正确配置：

"kernel":   { "size": "12m" },
+ "recovery": { "size": "16m" },          //在 kernel 分区后面增加 recovery 分区

"kernel": {
        "file": "kernel.itb",
        "attr": ["mtd", "required"],      //在 kernel 镜像烧录配置后面添加 recovery 镜像烧录配置
        "part": ["kernel"]
},
+ "recovery": {
+    "file": "recovery.itb",              //将 recovery.itb 镜像文件烧录到 recovery 分区里面
+    "attr": ["mtd", "required"],
+    "part": ["recovery"]
+ },

"kernel.itb": {
        "its": "kernel.its"               //在 kernel 镜像生成方法后面增加 recovery 镜像生成方法

},
+ "recovery.itb": {
+    "its": "recovery.its"                //配置 recovery.itb 文件通过 recovery.its 指导编译完成
+ },

在 image 目录中检查 recovery.itb 文件是否生成。

通过升级信息判断 recovery.itb 是否烧录到 recovery 分区。

增加 OTA 分区并烧录 OTA 升级包，用于验证本地 OTA 使用。

如使用网络 OTA 或 SD 卡 OTA，可略过此步。

在 target/d211/demo/image_cfg.json 文件中，增加 OTA 分区配置：

"partitions": { // Partition table apply to device
        "rootfs": { "size": "72m" },
+       "ota": { "size": "96m" },
},

"rootfs": {
    "file": "rootfs.ext4",
    "attr": ["block", "required"],
    "part": ["rootfs"]
},
+ "ota": {
+    "file": "ota.ext4",
+    "attr": ["block", "required"],
+    "part": ["ota"]
+ },

将 OTA 升级包下载到 ota 分区，方便测试 OTA 本地升级功能。

关于 ota 分区说明，可查看 Luban OTA 方案介绍。
执行下列命令进入主系统 SDK 生产环境：
```
lunch d211_demo
```

在 Luban 根目录下执行配置命令 make m

配置如下：

Filesystem images  --->
    [*] UserFS 1  --->
    (ota) Name
        FS Type (Ext4)  --->
    [*]   generate sparse format filesystem
    (96M) Size
    (0)   Number of inodes (leave at 0 for auto calculation)
    (5)   Reserved blocks percentage
    (-O ^64bit) Additional mke2fs options
    (target/$(LUBAN_CHIP_NAME)/$(LUBAN_BOARD_NAME)/ota) Overlay directory

将 target/$(LUBAN_CHIP_NAME)/$(LUBAN_BOARD_NAME)/ota 目录里的内容生成 ota.ext4 镜像文件，之后将整个文件烧录到 ota 分区中。

U-Boot 环境变量配置

为了简化使用，U-Boot 环境变量的 OTA 相关配置已添加和开启，无需用户手动配置。

通过环境变量 boot_partition 确定从 kernel 分区 还是 recovery 分区 引导启动。

修改 project directory/common/env.txt 文件中的相关参数，以 d211/common/env.txt 为例：

+ set_commonargs_recovery=setenv bootargs earlycon=${earlycon} earlyprintk console=${console} rdinit=/linuxrc
+  //从 Recovery 系统启动, 引导 initramfs 启动

+ set_mmc_bootargs_recovery=run set_commonargs_recovery; \ //设置环境变量 set_mmc_bootargs_recovery
                      run set_mmc_root; \
                      setenv bootargs "${bootargs}";

+ boot_partition=kernel   //初始化环境变量 boot_partition 从 kernel 分区启动

+ run set_mmc_bootargs_recovery; \
+ loadknl mmc ${boot_devnum} recovery ${knl_addr}; \
+ bootm ${knl_addr};      //mmc_boot 环境变量增加从 recovery 分区引导启动

手动配置环境变量 boot_partition 后保存并重启，测试 U-Boot 是否能够引导 Recovery 系统启动，以此判断配置文件是否生效。

在分区表中，增加 env 备份分区，保障 env 数据掉电安全。

在 image_cfg.json 配置修改如下：

"env":      { "size": "256k" },
+ "env_r":    { "size": "256k" },         //在 env 分区后面增加 env_r 分区

"env": {
    "file": "env.bin",
    "attr": ["mtd", "required"],
-    "part": ["env"]
+    "part": ["env","env_r"]             //将 env.bin 文件同时烧录到 env、env_r 分区
},

通过升级串口打印信息可以判断 env.bin 文件是否烧录到 env_r 分区，判断配置是否生效。

U-Boot 使能 redundant environment 配置
执行 make um 使能 redundant environment 机制：
```
Environment  --->
    [*] Enable redundant environment support
    (0x200000) Redundant environment offset
```
- 当升级过程中掉电时，其中一份环境变量如果被破坏，另外一份环境变量还能够继续引导启动。
- 用户可以手动擦除其中一份环境变量，测试系统能否正常启动，写入保存环境变量后，被擦除的环境变量是否能够恢复。
- CONFIG_ENV_OFFSET_REDUND 为 env_r 分区的偏移值，需要与分区表匹配。
故障：
当使能了 redundant 机制，编译后烧录程序，可能会出现如下错误信息：
Loading Environment from RAM... *** Warning - bad CRC, using default environment
这是因为 U-Boot 解析的方法发生了改变，解析数据格式增加了一个字节，判断那一份 env 数据最新，具体可以通过 redundant 宏查看对应的程序。可在 image_cfg.json 中做如下修改进行解决：
"uboot_env": { "env.bin": { "file": "env.txt", "size": "0x4000", + "redundant": "enable", }, },
注：
不使能 env 备份区域，设置 “redundant” 为 “disable” 或者不设置。
配置 fw_env.config
在 OTA 升级过程中，主系统和 Recovery 系统都使用到 SWUpdate 命令。SWUpdate 依赖 U-Boot 环境变量，需要在 Linux 中配置 U-Boot 环境变量索引路径。fw_env.config 和 fw_setenv 命令默认会读取 /etc/fw_env.config 文件来获取环境变量的分区信息。
1. 编辑 fw_env.config 文件，添加 eMMC 的分区信息。
  - fw_printenv/fw_setenv 命令默认索引路径为 /etc/fw_env.config。
    因为使用到了 env_r 备份分区，fw_env.config 需要包含 env 和 env_r 分区信息。
    如果用户修改了 env 和 env_r 分区信息，确保主系统和 Recovery 系统的 fw_env.config 文件同步更新。
  - Recovery 系统 SDK 生产环境默认存储在 fw_env.config 文件中，路径为 target/d211/ota_emmc/rootfs_overlay/etc/fw_env.config。
  - 主系统 SDK 生产环境默认存储在 fw_env.config 文件中，路径为 target/d211/demo/rootfs_overlay/etc/fw_env.config。
  eMMC 的默认的配置信息如下：
```
//device name   Device offset   Env. size
/dev/mmcblk0    0x1C0000        0x4000
/dev/mmcblk0    0x200000        0x4000
```
  - /dev/mmcblk0： eMMC 分区的设备号
  - Device offset：环境变量分区的偏移值
  - Env. size：实际环境变量的大小
2. 在 Linux 环境下执行 fw_printenv/fw_setenv 命令，测试能够正常打印 U-Boot 环境变量信息。
```
fw_printenv/fw_setenv
```

启动脚本配置

提示：

为了简化使用，启动脚本配置一般无需修改即可使用。

S90swupdate
主系统和 Recovery 系统默认启动脚本 S90swupdate，路径为 package/third-party/swupdate/S90swupdate。
在后台执行 swupdate-progress 命令，可以接受 SWUpdate 传递的升级信息并打印到调试串口，用户也可以重定向到显示屏上：
```
exec /usr/bin/swupdate-progress -w -r &
```
S91swupdate_ota
Recovery 系统启动脚本路径为 target/d211/ota_emmc/rootfs_overlay/etc/init.d/S91swupdate_ota
主要功能如下：
```
mkdir -p /mnt/ota
mount /dev/mmcblk0p7 /mnt/ota               //挂载 ota 分区到 mnt/ota 目录下
./usr/lib/swupdate/swupdate_cmd.sh          //调用 swupdate_cmd.sh 脚本执行 OTA 升级程序
```
注：
如需自定义分区，则对应的设备节点会有变更，此时需要修改对应的挂载方式。