upgrade

upgrade模块提供固件升级（FOTA）功能，支持升级包的写入、读取、校验和执行。该模块包含升级模块初始化、升级包数据读写、升级流程控制、升级状态查询及升级结果获取等接口，支持同步和异步写入方式，并提供升级进度通知和自定义校验功能。

头文件清单

#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"

功能说明

初始化升级模块，注册升级模块所需的内存分配、释放及串口输出函数
必须在其他升级接口调用之前完成初始化，否则其他接口返回 ERRCODE_UPG_NOT_INIT
重复调用初始化将返回 ERRCODE_UPG_ALREADY_INIT

前置条件

升级模块尚未初始化（未调用过 uapi_upg_init）
func_list 指针不为 NULL 时，其 malloc 和 free 成员必须为有效函数指针

入参

名称	参数类型	详细说明	约束取值范围
func_list	const upg_func_t *	升级模块使用的注册函数列表	NULL 或指向有效的 upg_func_t 结构体

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	初始化成功
ERRCODE_UPG_ALREADY_INIT(0x80003041)	模块已初始化	重复调用初始化

uapi_upg_start

函数声明

errcode_t uapi_upg_start(void)

头文件清单

#include "middleware/utils/upg.h"

功能说明

开始执行本地升级流程，读取升级包头并校验整包后逐个处理升级镜像
该函数阻塞等待执行完返回，升级过程中会根据升级包内容进行全镜像、压缩或差分升级
若升级区不存在有效升级包（标记不合法），则直接返回 ERRCODE_UPG_NOT_NEED_TO_UPDATE

前置条件

升级模块已通过 uapi_upg_init() 初始化完成
升级区已存在有效的升级包（head_magic 和 head_end_magic 合法，complete_flag 非0）

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	升级流程完成
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
ERRCODE_UPG_NOT_NEED_TO_UPDATE(0x80003047)	无需升级	升级区不存在有效升级包
Other	其他错误码	升级校验失败或镜像更新失败

uapi_upg_register_progress_callback

函数声明

errcode_t uapi_upg_register_progress_callback(uapi_upg_progress_cb func)

头文件清单

#include "middleware/utils/upg.h"

功能说明

注册升级进度通知回调函数，在升级过程中每完成一定比例时通过回调通知上层
配置关闭时调用该接口将返回 ERRCODE_UPG_NOT_SUPPORTED

前置条件

依赖关系：该回调函数依赖于配置项 UPG_CFG_PROCESS_NOTIFY_SUPPORT 为 YES 时生效
升级模块已通过 uapi_upg_init() 初始化完成

入参

名称	参数类型	详细说明	约束取值范围
func	uapi_upg_progress_cb	进度通知的回调函数	NULL 或有效的回调函数指针

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	回调注册成功
ERRCODE_UPG_NOT_SUPPORTED(0x80003046)	不支持	UPG_CFG_PROCESS_NOTIFY_SUPPORT 未开启

uapi_upg_get_result

函数声明

errcode_t uapi_upg_get_result(upg_result_t *result, uint32_t *last_image_index)

头文件清单

#include "middleware/utils/upg.h"

功能说明

获取升级结果，包括升级成功或失败的具体原因
若固件升级成功但NV升级未完成或失败，返回NV升级结果；否则返回固件升级结果
last_image_index 输出为 UINT32_MAX，表示不跟踪具体镜像序号

前置条件

升级模块已通过 uapi_upg_init() 初始化完成
result 和 last_image_index 指针不为 NULL

出参

名称	数据类型	输出说明
result	upg_result_t *	升级结果枚举值，参考 upg_result_t
last_image_index	uint32_t *	最后一个处理的升级镜像的序号（当前固定输出 UINT32_MAX）

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	成功获取升级结果
ERRCODE_UPG_NULL_POINTER(0x80003045)	空指针	result 或 last_image_index 为 NULL

uapi_upg_get_status

函数声明

upg_status_t uapi_upg_get_status(void)

头文件清单

#include "middleware/utils/upg.h"

功能说明

获取当前升级状态，返回升级成功、失败、进行中或非升级状态
该状态在模块初始化时从Flash升级标记区读取并缓存
返回值为 upg_status_t 枚举类型，参考 upg_status_t

前置条件

升级模块已通过 uapi_upg_init() 初始化完成，否则返回 UPG_STATUS_NONE

返回值

返回值	文字含义	触发场景
UPG_STATUS_SUCC(0)	升级成功	固件升级且NV升级均成功
UPG_STATUS_FAIL(1)	升级失败	升级结果为失败
UPG_STATUS_UPDATING(2)	正在进行升级	升级流程进行中
UPG_STATUS_NONE(3)	非升级状态	未处于升级流程或模块未初始化

uapi_upg_prepare

函数声明

errcode_t uapi_upg_prepare(upg_prepare_info_t *prepare_info)

头文件清单

#include "middleware/utils/upg.h"

功能说明

准备本地存储器以存放升级包，包括擦除FOTA分区及初始化升级标记区
该函数阻塞等待执行完返回
当升级包长度超过可用存储空间时返回 ERRCODE_UPG_INVALID_PARAMETER

前置条件

升级模块已通过 uapi_upg_init() 初始化完成
prepare_info 不为 NULL 且 package_len 不为0
升级包大小不超过 uapi_upg_get_storage_size() 返回的可用空间

入参

名称	参数类型	详细说明	约束取值范围
prepare_info	upg_prepare_info_t *	准备信息的指针	非 NULL，package_len > 0 且不超过可用存储空间

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	准备工作完成
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
ERRCODE_UPG_INVALID_PARAMETER(0x80003042)	参数无效	prepare_info 为 NULL 或 package_len 为0或超限

uapi_upg_reset_upgrade_flag

函数声明

errcode_t uapi_upg_reset_upgrade_flag(void)

头文件清单

#include "middleware/utils/upg.h"

功能说明

重置升级标记，擦除升级标记区并重新初始化 head_before_offset、Head_magic 和 package_length
该函数阻塞等待执行完返回
重置后可重新写入升级包并启动新的升级流程

前置条件

升级模块已通过 uapi_upg_init() 初始化完成

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	升级标记重置成功
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化

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_init() 初始化完成
已通过 uapi_upg_prepare() 完成存储区准备工作
上一次异步写入回调已返回成功

入参

名称	参数类型	详细说明	约束取值范围
offset	uint32_t	相对升级包开头的偏移	`0 ~ 存储空间最大值`
buff	const uint8_t *	存放升级包数据的buffer	非 NULL
len	uint16_t	升级包数据buffer的长度	`1 ~ 65535`
callback	uapi_upg_write_done_cb	写入完成的回调函数	NULL 或有效的回调函数指针

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据写入成功
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
ERRCODE_UPG_NULL_POINTER(0x80003045)	空指针	buff 为 NULL
ERRCODE_UPG_INVALID_BUFF_LEN(0x80003055)	buffer长度无效	len 为0
ERRCODE_UPG_NOT_PREPARED(0x80003054)	存储区未准备	未调用 uapi_upg_prepare()

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_init() 初始化完成
已通过 uapi_upg_prepare() 完成存储区准备工作

入参

名称	参数类型	详细说明	约束取值范围
offset	uint32_t	相对升级包开头的偏移	`0 ~ 存储空间最大值`
buff	const uint8_t *	存放升级包数据的buffer	非 NULL
len	uint16_t	升级包数据buffer的长度	`1 ~ 65535`

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据写入成功
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
ERRCODE_UPG_NULL_POINTER(0x80003045)	空指针	buff 为 NULL
ERRCODE_UPG_INVALID_BUFF_LEN(0x80003055)	buffer长度无效	len 为0
ERRCODE_UPG_NOT_PREPARED(0x80003054)	存储区未准备	未调用 uapi_upg_prepare()

uapi_upg_read_package

函数声明

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

头文件清单

#include "middleware/utils/upg.h"

功能说明

从本地存储器读取升级包数据到指定buffer
读取偏移和长度由调用者指定

前置条件

升级模块已通过 uapi_upg_init() 初始化完成
buff 指向的内存空间已分配，大小不小于 len

入参

名称	参数类型	详细说明	约束取值范围
offset	uint32_t	相对升级包开头的偏移	`0 ~ 存储空间最大值`
len	uint32_t	升级包数据的长度	`1 ~ 4294967295`

出参

名称	数据类型	输出说明
buff	uint8_t *	读取到的升级包数据

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据读取成功
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
ERRCODE_UPG_NULL_POINTER(0x80003045)	空指针	buff 为 NULL
ERRCODE_UPG_INVALID_BUFF_LEN(0x80003055)	buffer长度无效	len 为0

uapi_upg_get_storage_size

函数声明

uint32_t uapi_upg_get_storage_size(void)

头文件清单

#include "middleware/utils/upg.h"

功能说明

获取本地存储空间可存放升级包的最大空间大小
返回0表示获取失败或模块未初始化
用于在调用 uapi_upg_prepare() 之前判断升级包是否超出存储空间限制

前置条件

升级模块已通过 uapi_upg_init() 初始化完成，否则返回0

返回值

返回值	文字含义	触发场景
0	获取失败	模块未初始化或获取存储空间信息失败
Others	空间大小	可用存储空间大小（单位：字节）

uapi_upg_request_upgrade

函数声明

errcode_t uapi_upg_request_upgrade(bool reset)

头文件清单

#include "middleware/utils/upg.h"

功能说明

申请开始进行本地升级，读取升级包头并获取固件数量后写入升级标记
若配置 UPG_CFG_VERIFICATION_SUPPORT 和 UPG_CFG_SUPPORT_VERIFICATION_IN_REQUEST 均为 YES，则在申请流程中执行整包校验
reset 为 true 时，升级申请流程完成后系统将重启

前置条件

升级模块已通过 uapi_upg_init() 初始化完成
升级包已写入本地存储器

入参

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

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	升级申请成功
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
Other	其他错误码	升级包校验失败或标记写入失败

uapi_upg_verify_file_head

函数声明

errcode_t uapi_upg_verify_file_head(const upg_package_header_t *pkg_header)

头文件清单

#include "middleware/utils/upg.h"

功能说明

校验升级包头结构，依次执行Key Area签名校验、FOTA Info区签名校验及自定义字段校验
若注册了用户自定义字段校验函数，则在签名校验通过后调用自定义校验函数

前置条件

依赖关系：签名校验依赖于配置项 UPG_CFG_SIGNATURE_VERIFICATION_ENABLED 控制是否执行
升级模块已通过 uapi_upg_init() 初始化完成
pkg_header 指向有效的升级包头结构

入参

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

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	包头校验通过
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
ERRCODE_UPG_VERIFICATION_KEY_ERROR(0x80003063)	校验密钥错误	根公钥获取失败
Other	其他错误码	签名校验失败或自定义字段校验失败

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"

功能说明

校验升级包中的升级镜像，包括镜像头HASH校验和新镜像数据校验
verify_old 适用于差分升级场景，用于判断当前使用的旧镜像与做差分镜像时的旧镜像是否一致

前置条件

依赖关系：差分校验依赖于配置项 UPG_CFG_DIFF_UPGRADE_SUPPORT
升级模块已通过 uapi_upg_init() 初始化完成
img_header 指向有效的镜像头结构，hash 指向有效的哈希值

入参

名称	参数类型	详细说明	约束取值范围
img_header	const upg_image_header_t *	指向升级镜像头结构的指针	非 NULL
hash	const uint8_t *	升级镜像的HASH值	非 NULL，长度为 hash_len
hash_len	uint32_t	HASH的长度（单位：字节）	`32`（SHA_256_LENGTH）
verify_old	bool	是否校验旧镜像	true / false

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	镜像校验通过
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	header_magic 不匹配或HASH校验失败

uapi_upg_verify_file

函数声明

errcode_t uapi_upg_verify_file(const upg_package_header_t *pkg_header)

头文件清单

#include "middleware/utils/upg.h"

功能说明

校验整个升级包，依次执行包头校验、Hash Table校验及所有镜像的逐个校验
内部调用 uapi_upg_verify_file_head 完成包头校验，再遍历每个镜像调用 uapi_upg_verify_file_image
若支持防回滚，还会校验镜像版本号是否满足防回滚要求

前置条件

升级模块已通过 uapi_upg_init() 初始化完成
pkg_header 指向有效的升级包头结构

入参

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

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	整包校验通过
ERRCODE_UPG_NOT_INIT(0x80003040)	模块未初始化	升级模块未初始化
Other	其他错误码	包头校验、Hash Table校验或镜像校验失败

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 时校验函数会被调用
param 为传递给校验函数的注册参数
无返回值，该接口始终执行成功

前置条件

升级模块已通过 uapi_upg_init() 初始化完成

入参

名称	参数类型	详细说明	约束取值范围
func	uapi_upg_user_defined_check	用于校验用户自定义字段的校验函数	NULL 或有效的回调函数指针
param	uintptr_t	注册参数	`0 ~ UINTPTR_MAX`

Type definitions

uapi_upg_write_done_cb

typedef void (*uapi_upg_write_done_cb)(errcode_t result);

调用时机

异步写入升级包数据完成后被调用，result参数指示写入操作结果

使用说明

作为 uapi_upg_write_package_async 接口的 callback 参数使用

uapi_upg_progress_cb

typedef void (*uapi_upg_progress_cb)(uint32_t percent);

调用时机

升级过程中每完成一定比例时被调用，percent参数指示当前升级进度百分比

使用说明

作为 uapi_upg_register_progress_callback 接口的 func 参数使用

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_verify_file_head 和 uapi_upg_verify_file 校验包头签名通过后被调用，用于校验用户自定义字段

使用说明

作为 uapi_upg_register_user_defined_verify_func 接口的 func 参数使用

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_t

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	校验Hash Table失败
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_t

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_t

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 key区域的标识
struct_version	uint32_t	FOTA key区域结构版本
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[16]	芯片组芯片ID，在启用维护模式时有效
fota_info_addr	uint32_t	FOTA info区域的偏移地址
reserved	uint8_t[52]	为字节对齐而保留的字段
fota_external_public_key	uint8_t[64]	FOTA二级公钥
sig_fota_key_area	uint8_t[64]	FOTA key区域签名

upg_fota_info_data_t

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[32]	镜像哈希表的哈希
image_num	uint32_t	FOTA镜像的总数
hardware_id	uint32_t	硬件ID
user_defined	uint8_t[112]	预留字节供用户自定义使用
sign_fota_info	uint8_t[64]	FOTA信息签名

upg_image_hash_node_t

typedef struct upg_image_hash_node {
    uint32_t image_id;
    uint32_t image_addr;
    uint32_t image_length;
    uint8_t image_hash[SHA_256_LENGTH];
} upg_image_hash_node_t;

成员说明

成员名称	数据类型	描述
image_id	uint32_t	镜像的标识
image_addr	uint32_t	镜像头偏移量
image_length	uint32_t	镜像长度
image_hash	uint8_t[32]	镜像头的哈希

upg_package_header_t

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 info区数据

upg_image_header_t

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	镜像的标识
image_offset	uint32_t	要更新的镜像数据的偏移地址
image_len	uint32_t	更新的镜像数据的长度（实际数据长度，不包括填充字段）
image_hash	uint8_t[32]	更新镜像数据的哈希
old_image_len	uint32_t	旧镜像长度
old_image_hash	uint8_t[32]	旧镜像的哈希值
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[16]	用于解密更新镜像的一级加密保护密钥
enc_pk_l2	uint8_t[16]	用于解密更新镜像的二级加密保护密钥
iv	uint8_t[16]	用于解密升级镜像的IV
padding	uint8_t[4]	保留字段，以保证整个结构16字节对齐

upg_func_t

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串口输出函数（可选函数）

upg_prepare_info_t

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

芯片ID长度

PROTECT_KEY_LEN

#define PROTECT_KEY_LEN 16

加密秘钥长度

IV_LEN

#define IV_LEN          16

IV长度

SSB_IMAGE_ID

#define SSB_IMAGE_ID                           0x4B1E3C2D

SSB镜像ID

SELITEOS_IMAGE_ID

#define SELITEOS_IMAGE_ID                      0x4BE10F2D

SELITEOS镜像ID

ROOT_PUBLIC_KEY_ID

#define ROOT_PUBLIC_KEY_ID                     0x4B96B41E

根公钥ID

OEM_ROOT_PUBLIC_KEY_ID

#define OEM_ROOT_PUBLIC_KEY_ID                 0x4BA5C31E

客户根公钥ID

RECOVERY_IMAGE_ID

#define RECOVERY_IMAGE_ID                      0x4B69872D

Recovery镜像ID

APPLICATION_IMAGE_ID

#define APPLICATION_IMAGE_ID                   0x4B0F2D2D

Application镜像ID

BT_IMAGE_ID

#define BT_IMAGE_ID                            0x4BF01E2D

BT镜像ID

DSP_MAIN_IMAGE_ID

#define DSP_MAIN_IMAGE_ID                      0x5A87A52D

DSP主镜像ID

DSP_OVERLAY_IMAGE_ID

#define DSP_OVERLAY_IMAGE_ID                   0x5A87A54B

DSP覆盖镜像ID

KEY_AREA_RESERVED_LEN

#define KEY_AREA_RESERVED_LEN 52

key区保留字段长度

INFO_AREA_USER_LEN

#define INFO_AREA_USER_LEN 112

info区用户字段长度

SIG_LEN

#define SIG_LEN         64

签名字段长度

PUBLIC_KEY_LEN

#define PUBLIC_KEY_LEN 64

FOTA二级公钥长度