K1 OH5.0 方案 OTA 使用说明

修订记录

修订版本	修订日期	修订说明
001	2025-02-14	初始版本

1. 概述

按照 OTA 升级方式分为：

本地升级（支持）
网络升级（支持）

按照 OTA 包种类分为：

全量包升级（支持）
差分包升级（支持）
变分区包升级（暂不支持）

2. OTA 包制作

2.1 准备工作

2.1.1 安装必要工具

$ sudo apt update
$ sudo apt upgrade
$ sudo apt install bsdiff
$ sudo pip install xmltodict asn1crypto imgdiff cryptography e2fsdroid

2.1.2 修改代码

通过修改代码添加一些差异，比如为验证 OTA 升级效果，可在源码中添加可识别的修改（如打印信息）。

2.2 全量包制作

2.2.1 全量编译源码

./build.sh --product-name xxx --ccache --prebuilt-sdk

需要用到的内容如下：

系统的镜像文件，在 out\xxx\packages\phone\images 中，如下：

fuqiang@snode2:~/WorkSpace/oh5/out/musepaper2/packages/phone/images$ tree
.
|-- bootfs
|   |-- bianbu.bmp
|   |-- env_k1-x.txt
|   |-- Image.itb
|   `-- k1-x_MUSE-Paper2.dtb
|-- boot.img
|-- chip_prod.img
|-- eng_system.img
|-- env.bin
|-- factory
|   |-- bootinfo_emmc.bin
|   |-- bootinfo_sd.bin
|   |-- bootinfo_spinand.bin
|   |-- bootinfo_spinor.bin
|   `-- FSBL.bin
|-- fastboot.yaml
|-- fw_dynamic.itb
|-- genimage.cfg
|-- partition_universal.json
|-- ramdisk.img
|-- sys_prod.img
|-- system.img
|-- u-boot.itb
|-- updater.img
|-- userdata.img
`-- vendor.img

2 directories, 25 files

二进制升级文件 updater_binary，即 out\xxx\packages\phone\system\bin\updater_binary

2.2.2 制作全量包

进入 OTA 打包工具目录，并创建 target_package、output_package 和 sign_cert 文件夹。如果已经存在，就不需要再创建
```
$ cd base/update/packaging_tools
$ mkdir target_package output_package sign_cert
```

sign_cert 文件夹中放入公钥，公钥来自

base/update/updater/test/unittest/test_data/src/signing_cert.crt

target_packet 文件夹中放入要打包生成 OTA 全量包的文件，包括以下文件：

私钥，rsa_private_key2048.pem，来自

base/update/updater/test/unittest/test_data/src/rsa_private_key2048.pem

镜像文件，来自文件夹

out\xxx\packages\phone\images

二进制升级文件，updater_binary，来自

out\xxx\packages\phone\system\bin\updater_binary

升级组件配置文件夹 updater_config，该文件夹内部包括：

升级包支持的产品列表：BOARD.list，来自

device/board/hisilicon/hispark_taurus/linux/updater/config/BOARD.list

内容如下：

HI3516
MUSEPAPER
MUSEPAPER2
DEB1
ZT001H

注：HI3516 必须有，否则 OTA 包校验失败而导致 OTA 升级失败，因为 base/update/updater/utils/utils.cpp 代码匹配 BOARD 时，固定了默认值，如下：

std::string GetLocalBoardId()
{
    return "HI3516";
}

升级包所支持的版本范围：VERSION.mbn，来自

device/board/hisilicon/hispark_taurus/linux/updater/config/VERSION.mbn

注：VERSION.mbn 与设置的软件版本保持一致即可，

OpenHarmony 5.0.0.71

组件配置文件：updater_specified_config.xml，来自

device/board/hisilicon/hispark_taurus/linux/system/updater_specified_config.xml

修改fileVersion为2（4.0更新的校验方式）
softVersion改为当前软件版本
compType改为0,表示全量(1 表示增量)
修改img打包路径，./vendor.img和./system.img等

最终内容如下：

<?xml version="1.0"?>
<package>
    <head name="Component header information">
        <info fileVersion="02" prdID="123456" softVersion="OpenHarmony 5.0.0.71" date="2025-02-13" time="14:30">head info</info>
    </head>
    <group name = "Component information">
        <component compAddr="vendor" compId="1" resType="05" compType="0" compVer="0o00">./vendor.img</component>
        <component compAddr="system" compId="2" resType="05" compType="0" compVer="0o00">./system.img</component>
        <component compAddr="boot" compId="3" resType="05" compType="0" compVer="0o00">./boot.img</component>
        <component compAddr="uboot" compId="4" resType="05" compType="0" compVer="0o00">./u-boot.itb</component>
        <component compAddr="fsbl" compId="5" resType="05" compType="0" compVer="0o00">./factory/FSBL.bin</component>
        <component compAddr="env" compId="6" resType="05" compType="0" compVer="0o00">./env.bin</component>
        <component compAddr="opensbi" compId="7" resType="05" compType="0" compVer="0o00">./fw_dynamic.itb</component>
        <component compAddr="ramdisk" compId="8" resType="05" compType="0" compVer="0o00">./ramdisk.img</component>
        <component compAddr="updater" compId="9" resType="05" compType="0" compVer="0o00">./updater.img</component>
        <component compAddr="sys_prod" compId="10" resType="05" compType="0" compVer="0o00">./sys_prod.img</component>
        <component compAddr="chip_prod" compId="11" resType="05" compType="0" compVer="0o00">./chip_prod.img</component>
    </group>
</package>

target_packet 的完整内容如下：

fuqiang@snode2:~/WorkSpace/oh5/base/update/packaging_tools/target_package$ tree
.
|-- bootfs
|   |-- bianbu.bmp
|   |-- env_k1-x.txt
|   |-- Image.itb
|   |-- k1-x_MUSE-Paper2.dtb
|   `-- Thumbs.db
|-- boot.img
|-- chip_prod.img
|-- eng_system.img
|-- env.bin
|-- factory
|   |-- bootinfo_emmc.bin
|   |-- bootinfo_sd.bin
|   |-- bootinfo_spinand.bin
|   |-- bootinfo_spinor.bin
|   `-- FSBL.bin
|-- fastboot.yaml
|-- fw_dynamic.itb
|-- genimage.cfg
|-- partition_universal.json
|-- ramdisk.img
|-- rsa_private_key2048.pem
|-- sys_prod.img
|-- system.img
|-- u-boot.itb
|-- updater_binary
|-- updater_config
|   |-- BOARD.list
|   |-- updater_specified_config.xml
|   `-- VERSION.mbn
|-- updater.img
|-- userdata.img
`-- vendor.img

3 directories, 30 files

全量包打包，会在 base/update/packaging_tools/output_package 目录生成 updater_full.zip 全量包，执行打包命令如下：
```
python3 build_update.py ./target_package/ ./output_package/ -pk ./target_package/rsa_private_key2048.pem
```

正常 log 输出如下：

fuqiang@snode2:~/WorkSpace/oh5/base/update/packaging_tools$ python3 build_update.py ./target_package/ ./output_package/ -pk ./target_package/rsa_private_key2048.pem
2025-02-13 20:56:04 INFO : []
2025-02-13 20:56:04 INFO : VERSION.mbn file parsing complete! path: ./target_package/updater_config/VERSION.mbn
2025-02-13 20:56:04 INFO : BOARD.list file parsing complete! path: ./target_package/updater_config/BOARD.list
2025-02-13 20:56:04 INFO : []
2025-02-13 20:56:04 INFO : XML file parsing completed!
2025-02-13 20:56:04 INFO : []
2025-02-13 20:56:05 INFO : Image vendor full processing completed
2025-02-13 20:56:08 INFO : Image system full processing completed
2025-02-13 20:56:09 INFO : Image boot full processing completed
2025-02-13 20:56:09 INFO : Image u-boot full processing completed
2025-02-13 20:56:09 INFO : Image FSBL full processing completed
2025-02-13 20:56:09 INFO : Image env full processing completed
2025-02-13 20:56:09 INFO : Image fw_dynamic full processing completed
2025-02-13 20:56:09 INFO : Image ramdisk full processing completed
2025-02-13 20:56:09 INFO : Image updater full processing completed
2025-02-13 20:56:09 INFO : Image sys_prod full processing completed
2025-02-13 20:56:09 INFO : Image chip_prod full processing completed
2025-02-13 20:56:09 INFO : All full image processing completed! image count: 11
2025-02-13 20:56:09 INFO : []
2025-02-13 20:56:09 INFO : []
2025-02-13 20:56:09 INFO : []
2025-02-13 20:56:09 INFO : Get hash content success! path: ./target_package/updater_config/VERSION.mbn
2025-02-13 20:56:09 INFO : Get hash content success! path: ./target_package/updater_config/BOARD.list
2025-02-13 20:56:11 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imagevendoru8blfa8f
2025-02-13 20:56:22 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imagesystem2124936b
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imagebootolvjuuro
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imageu-bootyx5utu44
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imageFSBLgyd5y0tc
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imageenv48uz1h5n
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imagefw_dynamicd_lhhf2r
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imageramdisk_xd3t7d3
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imageupdatertarhn6ph
2025-02-13 20:56:24 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imagesys_prodgj47qc31
2025-02-13 20:56:25 INFO : Get hash content success! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/target_package/full_imagechip_prod1l3n34w4
2025-02-13 20:56:25 INFO : Write package header complete
2025-02-13 20:56:25 INFO : Add component b'/version_list'
2025-02-13 20:56:25 INFO : component information  StartOffset:180
2025-02-13 20:56:25 INFO : Add component b'/board_list'
2025-02-13 20:56:25 INFO : component information  StartOffset:267
2025-02-13 20:56:25 INFO : Add component b'/vendor'
2025-02-13 20:56:25 INFO : component information  StartOffset:354
2025-02-13 20:56:25 INFO : Add component b'/system'
2025-02-13 20:56:25 INFO : component information  StartOffset:441
2025-02-13 20:56:25 INFO : Add component b'/boot'
2025-02-13 20:56:25 INFO : component information  StartOffset:528
2025-02-13 20:56:25 INFO : Add component b'/uboot'
2025-02-13 20:56:25 INFO : component information  StartOffset:615
2025-02-13 20:56:25 INFO : Add component b'/fsbl'
2025-02-13 20:56:25 INFO : component information  StartOffset:702
2025-02-13 20:56:25 INFO : Add component b'/env'
2025-02-13 20:56:25 INFO : component information  StartOffset:789
2025-02-13 20:56:25 INFO : Add component b'/opensbi'
2025-02-13 20:56:25 INFO : component information  StartOffset:876
2025-02-13 20:56:25 INFO : Add component b'/ramdisk'
2025-02-13 20:56:25 INFO : component information  StartOffset:963
2025-02-13 20:56:25 INFO : Add component b'/updater'
2025-02-13 20:56:25 INFO : component information  StartOffset:1050
2025-02-13 20:56:25 INFO : Add component b'/sys_prod'
2025-02-13 20:56:25 INFO : component information  StartOffset:1137
2025-02-13 20:56:25 INFO : Add component b'/chip_prod'
2025-02-13 20:56:25 INFO : component information  StartOffset:1224
2025-02-13 20:56:25 INFO : Write hashdata sign tlv complete
2025-02-13 20:56:25 INFO : .bin package header signing success! SignOffset: 1589
2025-02-13 20:56:25 INFO : Add component to package  StartOffset:1589
2025-02-13 20:56:25 INFO : Write component complete  ComponentSize:22
2025-02-13 20:56:25 INFO : Add component to package  StartOffset:1611
2025-02-13 20:56:25 INFO : Write component complete  ComponentSize:40
2025-02-13 20:56:25 INFO : Add component to package  StartOffset:1651
2025-02-13 20:56:25 INFO : Write component complete  ComponentSize:268431360
2025-02-13 20:56:25 INFO : Add component to package  StartOffset:268433011
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:2097152000
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2365585011
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:268435456
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2634020467
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:1965474
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2635985941
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:189728
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2636175669
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:16384
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2636192053
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:136599
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2636328652
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:3035582
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2639364234
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:19612459
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2658976693
2025-02-13 20:56:29 INFO : Write component complete  ComponentSize:52428800
2025-02-13 20:56:29 INFO : Add component to package  StartOffset:2711405493
2025-02-13 20:56:30 INFO : Write component complete  ComponentSize:52428800
2025-02-13 20:56:30 INFO : Write update package complete
2025-02-13 20:56:30 INFO : Create update package .bin complete! path: /data/home2/fuqiang/WorkSpace/oh5/oh5_r_release/base/update/packaging_tools/output_package/update_bin-bap8m1xh
2025-02-13 20:56:30 INFO : Verse-script.us generation complete!
2025-02-13 20:56:30 INFO : loadScript.us generation complete!
2025-02-13 20:56:30 INFO : []
2025-02-13 20:56:30 INFO : []
2025-02-13 20:56:30 INFO : []
2025-02-13 20:57:45 INFO : []
2025-02-13 20:57:45 INFO : []
2025-02-13 20:57:51 INFO : Resource cleaning completed!

2.3 差分包制作

2.3.1 全量编译源码

./build.sh --product-name xxx --ccache --prebuilt-sdk

需要用到的内容如下：

系统的镜像文件，在 out\xxx\packages\phone\images 中，如下：

fuqiang@snode2:~/WorkSpace/oh5/out/musepaper2/packages/phone/images$ tree
.
|-- bootfs
|   |-- bianbu.bmp
|   |-- env_k1-x.txt
|   |-- Image.itb
|   `-- k1-x_MUSE-Paper2.dtb
|-- boot.img
|-- chip_prod.img
|-- eng_system.img
|-- env.bin
|-- factory
|   |-- bootinfo_emmc.bin
|   |-- bootinfo_sd.bin
|   |-- bootinfo_spinand.bin
|   |-- bootinfo_spinor.bin
|   `-- FSBL.bin
|-- fastboot.yaml
|-- fw_dynamic.itb
|-- genimage.cfg
|-- openharmony-spacemit-musepaper2.zip
|-- partition_universal.json
|-- ramdisk.img
|-- sys_prod.img
|-- system.img
|-- u-boot.itb
|-- updater.img
|-- userdata.img
`-- vendor.img

2 directories, 25 files

二进制升级文件 updater_binary，即 out\xxx\packages\phone\system\bin\updater_binary

2.3.2 制作差分包

创建 lib 文件夹, 放入差分镜像二进制工具，如果已经存在这些文件，则忽略这步

fuqiang@snode2:~/WorkSpace/oh5/base/update/packaging_tools$ mkdir lib
fuqiang@snode2:~/WorkSpace/oh5/base/update/packaging_tools$ cp -rf ../../../out/musepaper2/clang_x64/updater/updater/diff lib/
fuqiang@snode2:~/WorkSpace/oh5/base/update/packaging_tools$ cp -rf ../../../out/musepaper2/clang_x64/thirdparty/e2fsprogs/* lib/

得到 lib 文件夹内容如下：

fuqiang@snode2:~/WorkSpace/oh5base/update/packaging_tools/lib$ tree
.
|-- diff
|-- e2fsck
|-- e2fsdroid
|-- libext2_blkid.so
|-- libext2_com_err.so
|-- libext2_e2p.so
|-- libext2fs.so
|-- libext2_misc.so
|-- libext2_quota.so
|-- libext2_uuid.so
`-- mke2fs

0 directories, 11 files

packaging_tools 目录下，拷贝上一次 target_package 作为制作差分包的 source_package

fuqiang@snode2:~/WorkSpace/oh5/base/update/packaging_tools$ cp -rf target_package/* source_package/

更新 target_package 目录中的文件

替换成新的镜像文件
替换成新的二进制升级文件
更新 target_package/updater_config/updater_specified_config.xml 的 softVersion 和 compType，修改 softVersion 需大于当前系统版本； compType 设为 1，表示增量，部分小的 img 的 compType 还是设置为 0，使用全量升级

<?xml version="1.0"?>
<package>
    <head name="Component header information">
        <info fileVersion="02" prdID="123456" softVersion="OpenHarmony 5.0.0.72" date="2025-02-14" time="14:30">head info</info>
    </head>
    <group name = "Component information">
        <component compAddr="vendor" compId="1" resType="05" compType="1" compVer="0o00">./vendor.img</component>
        <component compAddr="system" compId="2" resType="05" compType="1" compVer="0o00">./system.img</component>
        <component compAddr="boot" compId="3" resType="05" compType="0" compVer="0o00">./boot.img</component>
        <component compAddr="uboot" compId="4" resType="05" compType="0" compVer="0o00">./u-boot.itb</component>
        <component compAddr="fsbl" compId="5" resType="05" compType="0" compVer="0o00">./factory/FSBL.bin</component>
        <component compAddr="env" compId="6" resType="05" compType="0" compVer="0o00">./env.bin</component>
        <component compAddr="opensbi" compId="7" resType="05" compType="0" compVer="0o00">./fw_dynamic.itb</component>
        <component compAddr="ramdisk" compId="8" resType="05" compType="0" compVer="0o00">./ramdisk.img</component>
        <component compAddr="updater" compId="9" resType="05" compType="0" compVer="0o00">./updater.img</component>
        <component compAddr="sys_prod" compId="10" resType="05" compType="1" compVer="0o00">./sys_prod.img</component>
        <component compAddr="chip_prod" compId="11" resType="05" compType="1" compVer="0o00">./chip_prod.img</component>
    </group>
</package>

打包差分包：

python3 build_update.py ./target_package/ ./output_package/ -s ./source_package/ -pk ./target_package/rsa_private_key2048.pem

得到差分包 base/update/packaging_tools/output_package/updater_diff.zip

3. OTA 升级

3.1 本地 OTA 升级

将制作好的全量包 updater_full.zip（或者差分包 updater_diff.zip）放入设备，设置 reboot 模式

D:\>hdc file send Y:\WorkSpace/oh5/base/update/packaging_tools\output_package\updater_xxx.zip /data/updater/updater.zip
D:\>hdc shell
# write_updater updater /data/updater/updater.zip
# reboot updater

升级成功后，设备自动重启

3.2 在线 OTA 升级

待添加

4. 注意事项

4.1 分区

系统中需要有如下分区：

updater
misc

其中，misc 分区是一个没有文件系统的分区

5. 问题处理

5.1 misc 分区问题

问题描述：

执行以下命令后

reboot updater

系统直接重启，没有进入升级模式，如下异常打印：

Line  700: [    7.014566] [pid=1][BEGET][ERROR][reboot_misc.c:80]Failed to get misc info
Line  842: [    9.214689] [pid=213][ueventd][INFO][ueventd_device_handler.c:85]symlink /dev/block/mmcblk2p11->/dev/block/platform/soc/d4281000.sdh/by-name/misc
Line  843: [    9.229333] [pid=213][ueventd][INFO][ueventd_device_handler.c:85]symlink /dev/block/mmcblk2p11->/dev/block/by-name/misc

分析：系统在读取 misc 分区时尝试访问路径 /dev/block/platform/soc/d4281000.sdh/by-name/misc，然而此路径尚未生成。

尝试的解决方案：

尝试使用 /dev/block/mmcblk2p11；结果：不可行
尝试在 ramdisk 中将 misc 挂载；结果：可行

5.2 `updater_binary` 问题

问题描述：

在 OH5.0 系统上，遇到生成的二进制 updater_binary 无法执行，执行会触发 signal11。经过和 OH4.0 对比，发现 OH5.0 并未将 updater_binary 定义为 executable，怀疑这导致了运行异常。

解决方案：

按照 OH4.0 修改即可，补丁如下：

commit bd630d88068992467681f2a2c39da41abfc688aa
Author: 付强 <qiang.fu@spacemit.com>
Date:   Thu Oct 31 18:58:11 2024 +0800

    fix bug: ota fail: When executing updater-binary, it reports signal 11.

diff --git a/bundle.json b/bundle.json
index 3bd29e92..925dec8d 100644
--- a/bundle.json
+++ b/bundle.json
@@ -173,16 +173,6 @@
                         ]
                     }
                 },
-                {
-                    "name": "//base/update/updater/services/updater_binary:libupdater_binary",
-                    "header": {
-                        "header_files": [],
-                        "header_base": [
-                            "//base/update/updater/interfaces/kits/include",
-                            "//base/update/updater/services/updater_binary"
-                        ]
-                    }
-                },
                 {
                     "name": "//base/update/updater/services/applypatch:libapplypatch",
                     "header": {
diff --git a/services/updater_binary/BUILD.gn b/services/updater_binary/BUILD.gn
index 754e1e2f..35efd13e 100644
--- a/services/updater_binary/BUILD.gn
+++ b/services/updater_binary/BUILD.gn
@@ -32,18 +32,7 @@ config("updater_config") {
   ]
 }

-config("updater_binary_lc++") {
-  ldflags = [ "-lc++" ]
-}
-
-updater_gen("updater_binary") {
-  deps = [ "${updater_path}/services/updater_binary:libupdater_binary" ]
-  configs = [ ":updater_binary_lc++" ]
-  part_name = "updater"
-  subsystem_name = "updater"
-}
-
-ohos_static_library("libupdater_binary") {
+ohos_executable("updater_binary") {
   sources = [
     "${updater_path}/services/updater_binary/main.cpp",
     "${updater_path}/services/updater_binary/update_image_block.cpp",

修订记录

1. 概述

2. OTA 包制作

2.1 准备工作​

2.1.1 安装必要工具​

2.1.2 修改代码​

2.2 全量包制作​

2.2.1 全量编译源码​

2.2.2 制作全量包​

2.3 差分包制作​

2.3.1 全量编译源码​

2.3.2 制作差分包​