1 /*
2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 * Description: UPG common functions header file
15 */
16
17 #ifndef UPG_COMMON_H
18 #define UPG_COMMON_H
19
20 #include <stdint.h>
21 #include <stdbool.h>
22 #include "errcode.h"
23 #include "common_def.h"
24 #include "partition.h"
25 #include "upg.h"
26 #include "upg_definitions.h"
27
28 #ifdef __cplusplus
29 #if __cplusplus
30 extern "C" {
31 #endif
32 #endif
33
upg_aligned(uint32_t len,uint32_t align)34 static inline uint32_t upg_aligned(uint32_t len, uint32_t align)
35 {
36 return ((uint32_t)(len) + ((align) - 1)) & ~((align) - 1);
37 }
38
39 /**** upg_commom ****/
40 upg_storage_ctx_t *upg_get_ctx(void);
41
42 /*
43 * 获取在当前Flash上指定固件镜像的地址信息。该地址为flash上的相对地址，是相对flash基地址的偏移
44 * image_id 固件的镜像ID
45 * start_address 返回该镜像的起始地址
46 * size 返回该镜像区域的大小
47 */
48 errcode_t upg_get_partition_info(uint32_t image_id, uint32_t *start_address, uint32_t *size);
49
50 /*
51 * 获取指定固件镜像的地址信息。
52 * image_id 固件的镜像ID
53 * image_info 返回该镜像的信息
54 */
55 errcode_t upg_get_image_info(uint32_t image_id, partition_information_t *image_info);
56
57 /*
58 * 读取升级包中的数据到buffer中
59 * read_offset 相对升级包起始的偏移
60 * buffer 读取数据buffer指针
61 * read_len 输入buffer的长度，输出实际读到的数据长度
62 */
63 errcode_t upg_read_fota_pkg_data(uint32_t read_offset, uint8_t *buffer, uint32_t *read_len);
64
65 /* 获取升级标记结构到RAM中 */
66 errcode_t upg_alloc_and_get_upgrade_flag(fota_upgrade_flag_area_t **upg_flag);
67
68 /*
69 * 获取升级包包头结构指针
70 * pkg_header 返回升级包头结构指针，指针指向的空间在函数内分配，需要使用者使用完后调用upg_free释放。
71 * (如果采用直接访问flash的方式，返回升级包头所在的flash地址)
72 */
73 errcode_t upg_get_package_header(upg_package_header_t **pkg_header);
74
75 /*
76 * 获取镜像哈希表结构指针
77 * pkg_header 升级包头结构指针
78 * img_hash_table 返回对应的升级镜像HASH表头指针，指针指向的空间在函数内分配，需要使用者使用完后调用upg_free释放。
79 * (如果采用直接访问flash的方式，返回升级镜像哈希表所在的flash地址)
80 */
81 errcode_t upg_get_pkg_image_hash_table(const upg_package_header_t *pkg_header,
82 upg_image_hash_node_t **img_hash_table);
83
84 /*
85 * 获取升级镜像的头结构指针
86 * img_hash_table 升级镜像HASH表节点指针
87 * img_header 返回对应的升级镜像头指针，指针指向的空间在函数内分配，需要使用者使用完后调用upg_free释放。
88 * (如果采用直接访问flash的方式，返回镜像头所在的flash地址)
89 */
90 errcode_t upg_get_pkg_image_header(const upg_image_hash_node_t *img_hash_table, upg_image_header_t **img_header);
91
92 /*
93 * 获取升级镜像的数据指针
94 * img_header 升级镜像头结构指针
95 * data_offset 相对升级镜像数据开头的偏移
96 * data_len 输出要获取数据的长度，输出实际获取到的数据长度
97 * img_data 返回升级镜像数据的指针，指针指向的空间在函数内分配，需要使用者使用完后调用upg_free释放。
98 * (如果采用直接访问flash的方式，返回数据所在的flash地址)
99 */
100 errcode_t upg_get_pkg_image_data(const upg_image_header_t *img_header,
101 uint32_t data_offset, uint32_t *data_len, uint8_t **img_data);
102
103 /*
104 * 拷贝升级镜像指定范围的数据至buffer中
105 * img_header 升级镜像头结构指针
106 * data_offset 相对升级镜像数据开头的偏移
107 * data_len 输入要拷贝的数据的长度，输出实际拷贝的数据长度
108 * img_data 保存数据的buffer指针，buffer的空间需要使用者分配
109 */
110 errcode_t upg_copy_pkg_image_data(const upg_image_header_t *img_header,
111 uint32_t data_offset, uint32_t *data_len, uint8_t *img_data);
112
113 /*
114 * 将buffer中的数据写入指定image_id的镜像所在的地址上
115 * write_offset 相对镜像起始地址的偏移
116 * buffer 写入数据的buffer指针
117 * write_len 输入buffer的长度，输出实际写入的数据长度
118 * image_id 镜像的ID
119 * do_erase 是否执行写前擦
120 */
121 errcode_t upg_write_new_image_data(uint32_t write_offset, uint8_t *buffer, uint32_t *write_len, uint32_t image_id,
122 bool do_erase);
123
124 /*
125 * 从指定image_id的镜像所在的地址上读取数据到buffer中
126 * write_offset 相对镜像起始地址的偏移
127 * buffer 存储数据的buffer指针
128 * write_len buffer的长度
129 * image_id 镜像的ID
130 */
131 errcode_t upg_read_old_image_data(uint32_t read_offset, uint8_t *buffer, uint32_t *read_len, uint32_t image_id);
132
133 /*
134 * 获取升级包中的升级镜像的升级标记状态(NOT_STARTED/STARTED/RETRY/FINISHED)
135 * firmware_index为升级包中的固件（除NV之外的镜像）的序号
136 * 如升级包中包含 固件0、固件1、固件2、NV、固件3，其中固件3的序号为3而不是4
137 * 如为NV镜像，firmware_index参数可忽略
138 */
139 upg_image_status_t upg_get_image_update_status(fota_upgrade_flag_area_t *upg_flag,
140 uint32_t firmware_index, uint32_t image_id);
141
142 /*
143 * 设置指定固件（不包含NV）的升级标记(STARTED/RETRY/FINISHED)
144 * firmware_index为升级包中的固件（除NV之外的镜像）的序号
145 * 如升级包中包含 固件0、固件1、固件2、NV、固件3，其中固件3的序号为3而不是4
146 */
147 errcode_t upg_set_firmware_update_status(fota_upgrade_flag_area_t *upg_flag,
148 uint32_t firmware_index, upg_image_status_switch_t switch_status);
149 errcode_t upg_set_nv_update_flag(fota_upgrade_flag_area_t *upg_flag, upg_image_status_t status);
150
151 /* 擦除metadata数据区 */
152 errcode_t upg_flash_erase_metadata_pages(void);
153
154 /* 设置升级结果(临时保存) */
155 void upg_set_temporary_result(upg_result_t result);
156
157 /* 获取临时保存的升级结果 */
158 upg_result_t upg_get_temporary_result(void);
159
160 /* 检查是否所有镜像都已完成升级（包括升级失败但是已尝试最大次数） */
161 bool upg_check_image_update_complete(const fota_upgrade_flag_area_t *upg_flag, uint32_t image_num);
162
163 /* 将升级结果保存至Flash升级标记区 */
164 void upg_set_update_result(upg_result_t result);
165
166 /* 设置升级完成标记 */
167 void upg_set_complete_flag(uint32_t image_num, errcode_t result, bool direct_finish);
168
169 /* 获取注册函数列表 */
170 upg_func_t *upg_get_func_list(void);
171
172 /* update模块是否已经初始化 */
173 bool upg_is_inited(void);
174
175 /* 镜像是否在当前程序支持升级 */
176 bool upg_img_in_set(uint32_t img_id);
177
178 /**** upg_process ****/
179 /* 计算升级进度并通知上层 */
180 void upg_calculate_and_notify_process(uint32_t current_size);
181
182
183 /**** upg_upgrade ****/
184 /* FOTA压缩升级 */
185 errcode_t uapi_upg_compress_image_update(const upg_image_header_t *image);
186
187 /* FOTA差分升级 */
188 errcode_t uapi_upg_diff_image_update(const upg_image_header_t *image);
189
190 /* FOTA全镜像升级 */
191 errcode_t uapi_upg_full_image_update(const upg_image_header_t *image);
192
193 /* 防回滚号校验 */
194 errcode_t upg_anti_rollback_version_verify(
195 const upg_package_header_t *pkg_header, const upg_image_header_t *img_header);
196
197 /* 更新防回滚版本号 */
198 errcode_t upg_anti_rollback_version_update(const upg_image_header_t *img_header);
199
200 /* 判断升级包是否为第一次启动后验签 */
201 #if (UPG_CFG_VERIFICATION_SUPPORT == YES)
202 bool upg_check_first_entry(const fota_upgrade_flag_area_t *upg_flag_info);
203 #endif
204
205 /**** upg_resource ****/
206 /* 处理资源文件 */
207 errcode_t uapi_upg_resource_index_process(const upg_image_header_t *image);
208 errcode_t uapi_upg_resource_data_process(const upg_image_header_t *image);
209
210 #ifdef __cplusplus
211 #if __cplusplus
212 }
213 #endif
214 #endif
215 #endif /* UPG_COMMON_H */
216