跳转至
项目
版本
全文检索

Update

Update（Upgrade）提供固件升级（FOTA，Firmware Over-The-Air）功能，支持升级包存储、校验、解密、解压和差分更新，覆盖升级全流程管理。

模块公共头文件

#include "middleware/utils/upg.h"

接口清单

接口名称 功能简述
uapi_upg_init 初始化升级模块
uapi_upg_start 开始本地升级
uapi_upg_register_progress_callback 注册升级进度通知回调函数
uapi_upg_get_result 获取升级结果
uapi_upg_get_status 获取升级状态
uapi_upg_prepare 准备本地存储空间以保存升级包
uapi_upg_reset_upgrade_flag 重置升级标记
uapi_upg_write_package_async 异步写入升级包数据到本地存储
uapi_upg_write_package_sync 同步写入升级包数据到本地存储
uapi_upg_read_package 从本地存储读取升级包数据
uapi_upg_get_storage_size 获取可存放升级包的空间大小
uapi_upg_request_upgrade 申请开始本地升级
uapi_upg_verify_file_head 校验升级包头结构
uapi_upg_verify_file_image 校验升级包中的升级镜像
uapi_upg_verify_file 校验整个升级包
uapi_upg_register_user_defined_verify_func 注册用户自定义字段校验函数

Functions

uapi_upg_init 

errcode_t uapi_upg_init(const upg_func_t *func_list)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 初始化升级模块，注册内存分配、释放和串口输出函数。
  • 标记升级模块为已初始化。
  • 获取并保存当前升级状态。

前置条件

  • 调用时序约束：首次使用升级模块其他接口前必须调用本接口完成初始化。
  • 依赖关系：func_list 中 malloc 和 free 函数必须有效。
  • 上下文限制：禁止重复调用，重复调用返回 ERRCODE_UPG_ALREADY_INIT。

入参

名称 参数类型 说明 约束取值范围
func_list upg_func_t* 升级模块使用的注册函数列表 允许为 NULL（实现接受 NULL，按默认函数表处理）

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 初始化成功
ERRCODE_UPG_ALREADY_INIT：0x80003041 模块已初始化 重复调用初始化接口
Other 其他错误码，参考 errcode_t 执行失败

参考案例

  • src/middleware/chips/ws53/update/common/upg_common_porting.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_start 

errcode_t uapi_upg_start(void)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 开始本地升级流程，读取升级标记并校验升级包。
  • 根据升级包中的镜像列表逐个执行升级任务。
  • 升级完成后更新升级标记和完成标记。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖升级标记区已存在有效的升级包信息。
  • 上下文限制：升级流程中禁止并发调用。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 升级流程执行成功
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
ERRCODE_UPG_NOT_NEED_TO_UPDATE：0x80003047 不需要升级 升级区无有效升级包
Other 其他错误码，参考 errcode_t 升级流程执行失败

参考案例

  • src/bootloader/flashboot_ws53/startup/main.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_register_progress_callback 

errcode_t uapi_upg_register_progress_callback(uapi_upg_progress_cb func)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 注册升级进度通知回调函数，升级过程中通过回调上报进度百分比。
  • 注册后升级流程执行期间会计算已完成镜像大小占总镜像大小的百分比并通知。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖 UPG_CFG_PROCESS_NOTIFY_SUPPORT 配置开启。

入参

名称 参数类型 说明 约束取值范围
func uapi_upg_progress_cb 进度通知回调函数指针；升级过程中按进度百分比调用 允许为 NULL（实现接受 NULL，直接赋值）

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 注册成功
ERRCODE_UPG_NOT_SUPPORTED：0x80003046 不支持 UPG_CFG_PROCESS_NOTIFY_SUPPORT 未开启
Other 其他错误码，参考 errcode_t 执行失败

参考案例

  • src/middleware/chips/ws53/update/common/upg_common_porting.c

Kconfig配置

配置项 宏类型 说明 默认值
UPG_CFG_PROCESS_NOTIFY_SUPPORT 特性宏 支持升级进度通知功能（接口级，无前缀注入宏，包裹实现体，upg_config.h 默认 YES） y
配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_get_result 

errcode_t uapi_upg_get_result(upg_result_t *result, uint32_t *last_image_index)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 获取升级结果，包括升级成功或失败的具体原因。
  • 获取最后一个处理的升级镜像序号。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖升级标记区已写入升级结果。

出参

名称 数据类型 输出说明
result upg_result_t* 保存获取的升级结果，由调用方分配内存、函数填充
last_image_index uint32_t* 保存获取的最后一个处理的升级镜像的序号，由调用方分配内存、函数填充

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 获取升级结果成功
ERRCODE_UPG_NULL_POINTER：0x80003045 空指针 result 或 last_image_index 为 NULL
Other 其他错误码，参考 errcode_t 执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_get_status 

upg_status_t uapi_upg_get_status(void)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 获取当前升级状态，包括成功、失败、升级中或非升级状态。
  • 返回从升级标记区读取并缓存的状态值。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。

返回值

返回类型：upg_status_t

返回值 文字含义 触发场景
UPG_STATUS_SUCC：0 升级成功 升级标记区记录升级成功
UPG_STATUS_FAIL：1 升级失败 升级标记区记录升级失败
UPG_STATUS_UPDATING：2 正在升级 升级标记区记录升级进行中
UPG_STATUS_NONE：3 非升级状态 无升级记录或标记区无效

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_prepare 

errcode_t uapi_upg_prepare(upg_prepare_info_t *prepare_info)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 准备本地存储空间以保存升级包，擦除升级区和进度状态区。
  • 初始化升级标记区中的头部偏移、升级包长度和头部魔数。
  • 该函数阻塞等待执行完成后返回。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后、写入升级包数据前调用。
  • 依赖关系：当前接口依赖 Flash 升级分区已就绪。
  • 上下文限制：该函数为阻塞调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
prepare_info upg_prepare_info_t* 准备信息的指针，包含升级包总长度 非 NULL，package_len > 0

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 存储空间准备成功
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
ERRCODE_UPG_INVALID_PARAMETER：0x80003042 参数无效 prepare_info 为 NULL 或 package_len 为 0
Other 其他错误码，参考 errcode_t 执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_reset_upgrade_flag 

errcode_t uapi_upg_reset_upgrade_flag(void)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 重置升级标记，擦除标记区后重新初始化头部偏移、头部魔数和升级包长度。
  • 该函数阻塞等待执行完成后返回。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖 Flash 升级标记区已就绪。
  • 上下文限制：该函数为阻塞调用，禁止在中断上下文调用。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 升级标记重置成功
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
Other 其他错误码，参考 errcode_t 执行失败

参考案例

  • src/bootloader/flashboot_ws53/startup/main.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_write_package_async 

errcode_t uapi_upg_write_package_async(uint32_t offset, const uint8_t *buff, uint16_t len, uapi_upg_write_done_cb callback)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 将升级包数据异步写入本地存储，写入完成后调用回调函数通知结果。
  • 写入位置由相对升级包起始的偏移量指定。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_prepare 成功返回后调用。
  • 依赖关系：当前接口依赖本地存储区已准备完成。
  • 上下文限制：前一次写入的回调返回前禁止再次调用本接口。

入参

名称 参数类型 说明 约束取值范围
offset uint32_t 相对升级包开头的偏移 0 ~ 升级包大小-1
buff const uint8_t* 存放升级包数据的缓冲区 非 NULL
len uint16_t 升级包数据缓冲区的长度 > 0
callback uapi_upg_write_done_cb 写入完成的回调函数 允许为 NULL（实现接受 NULL，无回调时不通知）

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 数据写入成功
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
ERRCODE_UPG_NOT_PREPARED：0x80003054 未准备存储空间 未调用 uapi_upg_prepare
ERRCODE_UPG_NULL_POINTER：0x80003045 空指针 buff 为 NULL
ERRCODE_UPG_INVALID_BUFF_LEN：0x80003055 缓冲区长度无效 len 为 0
Other 其他错误码，参考 errcode_t 执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_write_package_sync 

errcode_t uapi_upg_write_package_sync(uint32_t offset, const uint8_t *buff, uint16_t len)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 将升级包数据同步写入本地存储，写入完成后直接返回。
  • 写入位置由相对升级包起始的偏移量指定。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_prepare 成功返回后调用。
  • 依赖关系：当前接口依赖本地存储区已准备完成。

入参

名称 参数类型 说明 约束取值范围
offset uint32_t 相对升级包开头的偏移 0 ~ 升级包大小-1
buff const uint8_t* 存放升级包数据的缓冲区 非 NULL
len uint16_t 升级包数据缓冲区的长度 > 0

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 数据写入成功
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
ERRCODE_UPG_NOT_PREPARED：0x80003054 未准备存储空间 未调用 uapi_upg_prepare
ERRCODE_UPG_NULL_POINTER：0x80003045 空指针 buff 为 NULL
ERRCODE_UPG_INVALID_BUFF_LEN：0x80003055 缓冲区长度无效 len 为 0
Other 其他错误码，参考 errcode_t 执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_read_package 

errcode_t uapi_upg_read_package(uint32_t offset, uint8_t *buff, uint32_t len)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 从本地存储读取升级包数据。
  • 读取位置由相对升级包起始的偏移量指定。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖本地存储区已写入升级包数据。

入参

名称 参数类型 说明 约束取值范围
offset uint32_t 相对升级包开头的偏移 0 ~ 升级包大小-1
buff uint8_t* 存放读取数据的缓冲区 非 NULL
len uint32_t 要读取的数据长度 > 0

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 数据读取成功
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
ERRCODE_UPG_NULL_POINTER：0x80003045 空指针 buff 为 NULL
ERRCODE_UPG_INVALID_BUFF_LEN：0x80003055 缓冲区长度无效 len 为 0
Other 其他错误码，参考 errcode_t 执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_get_storage_size 

uint32_t uapi_upg_get_storage_size(void)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 获取可存放升级包的空间大小。
  • 返回本地存储中可用于保存升级包的最大字节数。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。

返回值

返回类型：uint32_t

返回值 文字含义 触发场景
0 获取失败 模块未初始化或获取存储大小失败
Others 可用空间大小 获取成功

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_request_upgrade 

errcode_t uapi_upg_request_upgrade(bool reset)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 申请开始本地升级，校验升级包后写入升级请求数据到标记区。
  • 可选择升级流程结束后是否重启系统。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用，且升级包已完整写入本地存储。
  • 依赖关系：当前接口依赖本地存储区已写入完整升级包。

入参

名称 参数类型 说明 约束取值范围
reset bool 申请流程结束后是否重启系统 true；
false。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 升级申请成功
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
Other 其他错误码，参考 errcode_t 执行失败

参考案例

  • src/bootloader/flashboot_ws53/startup/main.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_verify_file_head 

errcode_t uapi_upg_verify_file_head(const upg_package_header_t *pkg_header)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 校验升级包头结构，包括使用根公钥校验密钥区签名、使用二级公钥校验信息区签名。
  • 若注册了自定义字段校验函数，则校验用户自定义字段。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖根公钥已烧录到 Flash。

入参

名称 参数类型 说明 约束取值范围
pkg_header upg_package_header_t* 指向升级包头结构的指针 非 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 包头校验通过
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
ERRCODE_UPG_VERIFICATION_KEY_ERROR：0x80003063 校验密钥错误 获取根公钥失败
ERRCODE_FAIL：0xFFFFFFFF 校验失败 签名校验不通过或镜像 ID 不正确
Other 其他错误码，参考 errcode_t 执行失败

Kconfig配置

配置项 宏类型 说明 默认值
UPG_CFG_VERIFICATION_SUPPORT 特性宏 支持升级包校验分支（分支级，upg_config.h 默认 YES） y
CONFIG_MIDDLEWARE_SUPPORT_UPG_SAMPLE_VERIFY 特性宏 样例自校验分支（分支级，构建系统注入） n
配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_verify_file_image 

errcode_t uapi_upg_verify_file_image(const upg_image_header_t *img_header, const uint8_t *hash, uint32_t hash_len, bool verify_old)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 校验升级包中的升级镜像，包括镜像头哈希校验和新镜像数据哈希校验。
  • 若为差分升级且 verify_old 为 true，则校验旧镜像哈希。
  • 校验镜像头魔术字有效性。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖升级包数据已写入本地存储。

入参

名称 参数类型 说明 约束取值范围
img_header upg_image_header_t* 指向升级镜像头结构的指针 非 NULL
hash const uint8_t* 升级镜像的哈希值 非 NULL
hash_len uint32_t 哈希的长度（单位 Bytes） SHA_256_LENGTH(32)
verify_old bool 是否校验旧镜像 true；
false。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 镜像校验通过
ERRCODE_FAIL：0xFFFFFFFF 校验失败 镜像头魔术字不正确或哈希校验不通过
Other 其他错误码，参考 errcode_t 执行失败

Kconfig配置

配置项 宏类型 说明 默认值
UPG_CFG_VERIFICATION_SUPPORT 特性宏 支持升级包校验分支（分支级，upg_config.h 默认 YES） y
CONFIG_MIDDLEWARE_SUPPORT_UPG_SAMPLE_VERIFY 特性宏 样例自校验分支（分支级，构建系统注入） n
配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_verify_file 

errcode_t uapi_upg_verify_file(const upg_package_header_t *pkg_header)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 校验整个升级包，依次执行包头校验、镜像哈希表校验和逐个镜像校验。
  • 包括防回滚版本号校验（若开启防回滚功能）。

前置条件

  • 调用时序约束：当前接口必须在 uapi_upg_init 成功返回后调用。
  • 依赖关系：当前接口依赖升级包数据已完整写入本地存储。

入参

名称 参数类型 说明 约束取值范围
pkg_header upg_package_header_t* 指向升级包头结构的指针 非 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 执行成功 整包校验通过
ERRCODE_UPG_NOT_INIT：0x80003040 模块未初始化 未调用 uapi_upg_init
ERRCODE_FAIL：0xFFFFFFFF 校验失败 签名或哈希校验不通过
Other 其他错误码，参考 errcode_t 执行失败

参考案例

  • src/bootloader/flashboot_ws53/startup/main.c

Kconfig配置

配置项 宏类型 说明 默认值
UPG_CFG_VERIFICATION_SUPPORT 特性宏 支持升级包校验分支（分支级，upg_config.h 默认 YES） y
CONFIG_MIDDLEWARE_SUPPORT_UPG_SAMPLE_VERIFY 特性宏 样例自校验分支（分支级，构建系统注入） n
配置项 宏类型 说明 默认值
CONFIG_MIDDLEWARE_SUPPORT_UPDATE 编译参与宏 update 组件纳入编译的组件集配置（WS53 组件集） n
CONFIG_MIDDLEWARE_SUPPORT_UPG 编译参与宏 支持 FOTA 功能（接口级） n

uapi_upg_register_user_defined_verify_func 

void uapi_upg_register_user_defined_verify_func(uapi_upg_user_defined_check func, uintptr_t param)

声明头文件

#include "middleware/utils/upg.h"

功能说明

  • 注册用户自定义字段校验函数。
  • 注册后调用 uapi_upg_verify_file_head 和 uapi_upg_verify_file 时，校验函数会被调用。

前置条件

  • 调用时序约束：当前接口须在调用 uapi_upg_verify_file_head 或 uapi_upg_verify_file 之前注册。

入参

名称 参数类型 说明 约束取值范围
func uapi_upg_user_defined_check 用于校验用户自定义字段的校验函数 允许为 NULL（实现接受 NULL，直接赋值）
param uintptr_t 注册参数，透传给校验函数 不限

Kconfig配置

配置项 宏类型 说明 默认值
UPG_CFG_VERIFICATION_SUPPORT 特性宏 支持升级包校验分支（接口级，upg_config.h 默认 YES） y
CONFIG_MIDDLEWARE_SUPPORT_UPG 特性宏 update 组件纳入编译的组件集配置（编译参与宏） y

Type definitions

uapi_upg_write_done_cb 

typedef void (*uapi_upg_write_done_cb)(errcode_t result);

使用说明

作为 uapi_upg_write_package_async 接口的回调类型，用于通知升级包数据写入完成。

  • 调用时机：异步写入操作完成后，由内部调用已注册的回调。
  • 参数 result：写入操作的返回值，ERRCODE_SUCC 表示写入成功，其他值表示写入失败。
  • 返回值处理：回调返回类型为 void，无返回值。

uapi_upg_progress_cb 

typedef void (*uapi_upg_progress_cb)(uint32_t percent);

使用说明

作为 uapi_upg_register_progress_callback 接口的回调类型，用于上报升级进度百分比。

  • 调用时机：升级流程执行期间，每完成部分镜像写入后计算进度并调用。
  • 参数 percent：进度百分比值，范围 0 ~ 100。
  • 返回值处理：回调返回类型为 void，无返回值。

uapi_upg_user_defined_check 

typedef errcode_t (*uapi_upg_user_defined_check)(uint8_t *user_info, uint32_t info_len, uintptr_t param);

使用说明

作为 uapi_upg_register_user_defined_verify_func 接口的回调类型，用于校验升级包中用户自定义字段。

  • 调用时机：调用 uapi_upg_verify_file_head 和 uapi_upg_verify_file 时，若已注册则被调用。
  • 参数 user_info：指向升级包信息区中用户自定义字段的指针。
  • 参数 info_len：用户自定义字段的长度。
  • 参数 param：注册时传入的透传参数。
  • 返回值处理：返回 ERRCODE_SUCC 表示校验通过，其他值表示校验失败。

upg_func_malloc 

typedef void *(*upg_func_malloc)(const uint32_t size);

使用说明

作为 upg_func_t 结构体成员 malloc 的类型，升级模块使用的内存分配函数。

upg_func_free 

typedef void (*upg_func_free)(void *ptr);

使用说明

作为 upg_func_t 结构体成员 free 的类型，升级模块使用的内存释放函数。

upg_func_serial_putc 

typedef void (*upg_func_serial_putc)(const char c);

使用说明

作为 upg_func_t 结构体成员 serial_putc 的类型，升级模块使用的串口输出函数。

Enumerations

upg_result 

typedef enum upg_result {
    UPG_RESULT_UPDATE_SUCCESS,
    UPG_RESULT_VERIFY_HEAD_FAILED,
    UPG_RESULT_VERIFY_HASH_TABLE_FAILED,
    UPG_RESULT_VERIFY_IMAGE_FAILED,
    UPG_RESULT_VERIFY_OLD_IMAGE_FAILED,
    UPG_RESULT_DECOMPRESS_IMAGE_FAILED,
    UPG_RESULT_DECRYPT_IMAGE_FAILED,
    UPG_RESULT_RECRYPT_IMAGE_FAILED,
    UPG_RESULT_DIFF_IMAGE_FAILED,
    UPG_RESULT_UPDATE_IMAGE_FAILED,
    UPG_RESULT_PROCESS_NV_FAILED,
    UPG_RESULT_VERIFY_VERSION_FAILED,
    UPG_RESULT_IMAGE_ID_FAILED,
    UPG_RESULT_RETRY_ALL_FAILED,
    UPG_RESULT_MAX,
} upg_result_t;
枚举成员 取值 描述
UPG_RESULT_UPDATE_SUCCESS 0 升级成功
UPG_RESULT_VERIFY_HEAD_FAILED 1 校验升级包头失败
UPG_RESULT_VERIFY_HASH_TABLE_FAILED 2 校验哈希表失败
UPG_RESULT_VERIFY_IMAGE_FAILED 3 校验镜像失败
UPG_RESULT_VERIFY_OLD_IMAGE_FAILED 4 校验旧镜像失败
UPG_RESULT_DECOMPRESS_IMAGE_FAILED 5 解压缩失败
UPG_RESULT_DECRYPT_IMAGE_FAILED 6 解密失败
UPG_RESULT_RECRYPT_IMAGE_FAILED 7 重加密失败
UPG_RESULT_DIFF_IMAGE_FAILED 8 差分恢复失败
UPG_RESULT_UPDATE_IMAGE_FAILED 9 更新镜像到 Flash 失败
UPG_RESULT_PROCESS_NV_FAILED 10 处理 NV 镜像失败
UPG_RESULT_VERIFY_VERSION_FAILED 11 防回滚校验失败
UPG_RESULT_IMAGE_ID_FAILED 12 镜像 ID 校验失败
UPG_RESULT_RETRY_ALL_FAILED 13 所有升级尝试均失败
UPG_RESULT_MAX 14 升级结果最大值

upg_status 

typedef enum upg_status {
    UPG_STATUS_SUCC,
    UPG_STATUS_FAIL,
    UPG_STATUS_UPDATING,
    UPG_STATUS_NONE
} upg_status_t;
枚举成员 取值 描述
UPG_STATUS_SUCC 0 升级成功
UPG_STATUS_FAIL 1 升级失败
UPG_STATUS_UPDATING 2 正在进行升级
UPG_STATUS_NONE 3 非升级状态

Structures

upg_key_area_data 

typedef struct upg_key_area_data {
    uint32_t image_id;
    uint32_t struct_version;
    uint32_t struct_length;
    uint32_t signature_length;
    uint32_t key_owner_id;
    uint32_t key_id;
    uint32_t key_alg;
    uint32_t ecc_curve_type;
    uint32_t key_length;
    uint32_t fota_key_version_ext;
    uint32_t mask_fota_key_version_ext;
    uint32_t msid_ext;
    uint32_t mask_msid_ext;
    uint32_t maintenance_mode;
    uint8_t die_id[DIE_ID_LEN];
    uint32_t fota_info_addr;
    uint8_t reserved[KEY_AREA_RESERVED_LEN];
    uint8_t fota_external_public_key[PUBLIC_KEY_LEN];
    uint8_t sig_fota_key_area[SIG_LEN];
} upg_key_area_data_t;

成员说明

成员名称 数据类型 描述
image_id uint32_t FOTA 密钥区域的标识
struct_version uint32_t FOTA 密钥区域结构版本
struct_length uint32_t 结构长度
signature_length uint32_t 签名长度
key_owner_id uint32_t FOTA 二级公钥的所有者 ID
key_id uint32_t FOTA 二级公共密钥的密钥 ID
key_alg uint32_t 二级公钥算法
ecc_curve_type uint32_t ECC 曲线类型
key_length uint32_t FOTA 二级公共密钥的长度
fota_key_version_ext uint32_t FOTA 二级公共密钥的版本
mask_fota_key_version_ext uint32_t FOTA 密钥版本扩展的掩码
msid_ext uint32_t 细分市场 ID
mask_msid_ext uint32_t MSID 掩码
maintenance_mode uint32_t 维护模式
die_id uint8_t[DIE_ID_LEN] 芯片组芯片 ID，在启用维护模式时有效
fota_info_addr uint32_t FOTA 信息区域的偏移地址
reserved uint8_t[KEY_AREA_RESERVED_LEN] 为字节对齐而保留的字段
fota_external_public_key uint8_t[PUBLIC_KEY_LEN] FOTA 二级公钥
sig_fota_key_area uint8_t[SIG_LEN] FOTA 密钥区域签名

upg_fota_info_data 

typedef struct upg_fota_info_data {
    uint32_t image_id;
    uint32_t struct_version;
    uint32_t struct_length;
    uint32_t signature_length;
    uint32_t fota_version_ext;
    uint32_t mask_fota_version_ext;
    uint32_t msid_ext;
    uint32_t mask_msid_ext;
    uint32_t image_hash_table_addr;
    uint32_t image_hash_table_length;
    uint8_t image_hash_table_hash[SHA_256_LENGTH];
    uint32_t image_num;
    uint32_t hardware_id;
    uint8_t user_defined[INFO_AREA_USER_LEN];
    uint8_t sign_fota_info[SIG_LEN];
} upg_fota_info_data_t;

成员说明

成员名称 数据类型 描述
image_id uint32_t FOTA 信息区标识
struct_version uint32_t FOTA 密钥区域结构版本
struct_length uint32_t 结构长度
signature_length uint32_t 签名长度
fota_version_ext uint32_t FOTA 信息区的版本
mask_fota_version_ext uint32_t FOTA 二级公共密钥的版本
msid_ext uint32_t 细分市场 ID
mask_msid_ext uint32_t MSID 掩码
image_hash_table_addr uint32_t FOTA 包中镜像哈希表的地址
image_hash_table_length uint32_t 镜像哈希表的长度
image_hash_table_hash uint8_t[SHA_256_LENGTH] 镜像哈希表的哈希
image_num uint32_t FOTA 镜像的总数
hardware_id uint32_t 硬件 ID
user_defined uint8_t[INFO_AREA_USER_LEN] 预留字节供用户自定义使用
sign_fota_info uint8_t[SIG_LEN] FOTA 信息签名

upg_package_header 

typedef struct upg_package_header {
    upg_key_area_data_t  key_area;
    upg_fota_info_data_t info_area;
} upg_package_header_t;

成员说明

成员名称 数据类型 描述
key_area upg_key_area_data_t 升级密钥区域数据
info_area upg_fota_info_data_t FOTA 信息区数据

upg_image_header 

typedef struct upg_image_header {
    uint32_t header_magic;
    uint32_t image_id;
    uint32_t image_offset;
    uint32_t image_len;
    uint8_t image_hash[SHA_256_LENGTH];
    uint32_t old_image_len;
    uint8_t old_image_hash[SHA_256_LENGTH];
    uint32_t new_image_len;
    uint32_t version_ext;
    uint32_t version_mask;
    uint32_t decompress_flag;
    uint32_t re_enc_flag;
    uint32_t root_key_type;
    uint8_t enc_pk_l1[PROTECT_KEY_LEN];
    uint8_t enc_pk_l2[PROTECT_KEY_LEN];
    uint8_t iv[IV_LEN];
    uint8_t padding[4];
} upg_image_header_t;

成员说明

成员名称 数据类型 描述
header_magic uint32_t 镜像头魔术字
image_id uint32_t FOTA 密钥区域的标识
image_offset uint32_t 要更新的镜像数据的偏移地址
image_len uint32_t 更新的镜像数据的长度（实际数据长度，不包括填充字段）
image_hash uint8_t[SHA_256_LENGTH] 更新镜像数据的哈希
old_image_len uint32_t 旧镜像长度
old_image_hash uint8_t[SHA_256_LENGTH] 旧镜像的哈希值
new_image_len uint32_t 新镜像长度
version_ext uint32_t 新镜像版本
version_mask uint32_t 版本掩码
decompress_flag uint32_t 解压标志
re_enc_flag uint32_t 重新加密标志
root_key_type uint32_t 用于加密镜像的密钥
enc_pk_l1 uint8_t[PROTECT_KEY_LEN] 用于解密更新镜像的一级加密保护密钥
enc_pk_l2 uint8_t[PROTECT_KEY_LEN] 用于解密更新镜像的二级加密保护密钥
iv uint8_t[IV_LEN] 用于解密升级镜像的 IV
padding uint8_t[4] 保留字段，以保证整个结构 16 Bytes 对齐

upg_func 

typedef struct upg_func {
    upg_func_malloc malloc;
    upg_func_free free;
    upg_func_serial_putc serial_putc;
} upg_func_t;

成员说明

成员名称 数据类型 描述
malloc upg_func_malloc 升级使用内存分配函数（必选函数）
free upg_func_free 升级释放内存函数（必选函数）
serial_putc upg_func_serial_putc 升级串口输出函数（可选函数）

upg_prepare_info 

typedef struct upg_prepare_info {
    uint32_t package_len;
} upg_prepare_info_t;

成员说明

成员名称 数据类型 描述
package_len uint32_t 升级包的大小

Macros

SHA_256_LENGTH 

#define SHA_256_LENGTH  32

DIE_ID_LEN 

#define DIE_ID_LEN      16

PROTECT_KEY_LEN 

#define PROTECT_KEY_LEN 16

IV_LEN 

#define IV_LEN          16

KEY_AREA_RESERVED_LEN 

#define KEY_AREA_RESERVED_LEN 52

INFO_AREA_USER_LEN 

#define INFO_AREA_USER_LEN 112

SIG_LEN 

#define SIG_LEN         64

PUBLIC_KEY_LEN 

#define PUBLIC_KEY_LEN 64