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.\n 14 * Description: UPG Interface Header \n 15 * 16 * History: \n 17 * 2022-09-01, Create file. \n 18 */ 19 20 #ifndef UPG_INTERFACE_H 21 #define UPG_INTERFACE_H 22 23 #include <stdint.h> 24 #include <stdbool.h> 25 #include "errcode.h" 26 #include "upg_definitions_porting.h" 27 28 #ifdef __cplusplus 29 #if __cplusplus 30 extern "C" { 31 #endif 32 #endif 33 34 /** 35 * @defgroup middleware_utils_update_api Update 36 * @ingroup middleware_utils 37 * @{ 38 */ 39 40 /** 41 * @if Eng 42 * @brief SHA 256 length. 43 * @else 44 * @brief 哈希长度。 45 * @endif 46 */ 47 #define SHA_256_LENGTH 32 48 49 /** 50 * @if Eng 51 * @brief Indicates the length of the chip ID. 52 * @else 53 * @brief 芯片ID长度。 54 * @endif 55 */ 56 #define DIE_ID_LEN 16 57 58 /** 59 * @if Eng 60 * @brief Key protection length. 61 * @else 62 * @brief 加密秘钥长度。 63 * @endif 64 */ 65 #define PROTECT_KEY_LEN 16 66 67 /** 68 * @if Eng 69 * @brief IV length. 70 * @else 71 * @brief IV 长度。 72 * @endif 73 */ 74 #define IV_LEN 16 75 76 /** 77 * @if Eng 78 * @brief partition type enumeration. 79 * @else 80 * @brief 分区枚举类型。 81 * @endif 82 */ 83 typedef enum upg_result { 84 UPG_RESULT_UPDATE_SUCCESS, /*!< @if Eng The upgrade is successful. 85 @else 升级成功。 @endif */ 86 UPG_RESULT_VERIFY_HEAD_FAILED, /*!< @if Eng Failed to verify the upgrade header. 87 @else 校验升级包头失败。 @endif */ 88 UPG_RESULT_VERIFY_HASH_TABLE_FAILED, /*!< @if Eng Failed to verify the hash table. 89 @else 校验Hash Table失败。 @endif */ 90 UPG_RESULT_VERIFY_IMAGE_FAILED, /*!< @if Eng Failed to verify the image. 91 @else 校验镜像失败。 @endif */ 92 UPG_RESULT_VERIFY_OLD_IMAGE_FAILED, /*!< @if Eng Failed to verify the old image. 93 @else 校验旧镜像失败。 @endif */ 94 UPG_RESULT_DECOMPRESS_IMAGE_FAILED, /*!< @if Eng Decompression failed. 95 @else 解压缩失败。 @endif */ 96 UPG_RESULT_DECRYPT_IMAGE_FAILED, /*!< @if Eng Decryption failed. 97 @else 解密失败。 @endif */ 98 UPG_RESULT_RECRYPT_IMAGE_FAILED, /*!< @if Eng Re-encryption failed. 99 @else 重加密失败。 @endif */ 100 UPG_RESULT_DIFF_IMAGE_FAILED, /*!< @if Eng Differential restoration failed. 101 @else 差分恢复失败。 @endif */ 102 UPG_RESULT_UPDATE_IMAGE_FAILED, /*!< @if Eng Failed to update the image to the flash memory. 103 @else 更新镜像到Flash失败。 @endif */ 104 UPG_RESULT_PROCESS_NV_FAILED, /*!< @if Eng Failed to process the NV image. 105 @else 处理NV镜像失败。 @endif */ 106 UPG_RESULT_VERIFY_VERSION_FAILED, /*!< @if Eng Failed to verify the anti-rollback number. 107 @else 防回滚校验失败。 @endif */ 108 UPG_RESULT_IMAGE_ID_FAILED, /*!< @if Eng Failed to verify the Image ID. 109 @else 镜像ID校验失败。 @endif */ 110 UPG_RESULT_RETRY_ALL_FAILED, /*!< @if Eng All failed to retry to update the image. 111 @else 所有升级尝试均失败。 @endif */ 112 UPG_RESULT_MAX, /*!< @if Eng result_max. 113 @else 升级结果最大值。 @endif */ 114 } upg_result_t; 115 116 /** 117 * @if Eng 118 * @brief update status type enumeration. 119 * @else 120 * @brief 升级状态枚举类型。 121 * @endif 122 */ 123 typedef enum upg_status { 124 UPG_STATUS_SUCC, /*!< @if Eng The upgrade is successful. 125 @else 升级成功。 @endif */ 126 UPG_STATUS_FAIL, /*!< @if Eng The upgrade is failed. 127 @else 升级失败。 @endif */ 128 UPG_STATUS_UPDATING, /*!< @if Eng The upgrade in progress. 129 @else 正在进行升级。 @endif */ 130 UPG_STATUS_NONE /*!< @if Eng Non-upgrade status. 131 @else 非升级状态。 @endif */ 132 } upg_status_t; 133 134 /** 135 * @if Eng 136 * @brief upg key area data type. 137 * @else 138 * @brief 升级key区域数据类型。 139 * @endif 140 */ 141 typedef struct upg_key_area_data { 142 uint32_t image_id; /*!< @if Eng Identity of FOTA Key Area. 143 @else FOTA key区域的标识。 @endif */ 144 uint32_t struct_version; /*!< @if Eng The Structure Version of FOTA Key Area. 145 @else FOTA key区域结构版本。 @endif */ 146 uint32_t struct_length; /*!< @if Eng The Structure Length. 147 @else 结构长度。 @endif */ 148 uint32_t signature_length; /*!< @if Eng The signature Length. 149 @else 签名长度。 @endif */ 150 uint32_t key_owner_id; /*!< @if Eng OwnerID of the FOTA external public key. 151 @else FOTA二级公钥的所有者ID。 @endif */ 152 uint32_t key_id; /*!< @if Eng Key ID of FOTA_External_Public_Key. 153 @else FOTA二级公共密钥的密钥ID。 @endif */ 154 uint32_t key_alg; /*!< @if Eng Algorithm of the external public key. 155 @else 二级公钥算法。 @endif */ 156 uint32_t ecc_curve_type; /*!< @if Eng ecc curve type. 157 @else ecc 曲线类型。 @endif */ 158 uint32_t key_length; /*!< @if Eng The length of FOTA_External_Public_Key. 159 @else FOTA二级公共密钥的长度。 @endif */ 160 uint32_t fota_key_version_ext;/*!< @if Eng Version of FOTA_External_Public_Key. 161 @else FOTA二级公共密钥的版本。 @endif */ 162 uint32_t mask_fota_key_version_ext;/*!< @if Eng Mask of FOTA_Key_Version_Ext. 163 @else FOTA密钥版本扩展的掩码。 @endif */ 164 uint32_t msid_ext; /*!< @if Eng Market segment ID. 165 @else 细分市场ID。 @endif */ 166 uint32_t mask_msid_ext; /*!< @if Eng Mask of MSID. 167 @else MSID掩码。 @endif */ 168 uint32_t maintenance_mode; /*!< @if Eng Maintenance Mode. 169 @else 维护模式。 @endif */ 170 uint8_t die_id[DIE_ID_LEN]; /*!< @if Eng Chipset DIE ID, valid when maintenance mode is enabled. 171 @else 芯片组芯片ID，在启用维护模式时有效。 @endif */ 172 uint32_t fota_info_addr; /*!< @if Eng Address of FOTA Info. 173 @else FOTA info区域的偏移地址。 @endif */ 174 uint8_t reserved[KEY_AREA_RESERVED_LEN]; /*!< @if Eng reserve bytes for aligned. 175 @else 为字节对齐而保留的字段。 @endif */ 176 uint8_t fota_external_public_key[PUBLIC_KEY_LEN];/*!< @if Eng FOTA_External_Public_Key. 177 @else FOTA二级公钥。 @endif */ 178 uint8_t sig_fota_key_area[SIG_LEN];/*!< @if Eng Signature of the FOTA Key Area. 179 @else FOTA key区域签名。 @endif */ 180 } upg_key_area_data_t; 181 182 /** 183 * @if Eng 184 * @brief upg fota info data type. 185 * @else 186 * @brief 升级fota信息数据类型。 187 * @endif 188 */ 189 typedef struct upg_fota_info_data { 190 uint32_t image_id; /*!< @if Eng Identity of FOTA Info Area. 191 @else FOTA信息区标识。 @endif */ 192 uint32_t struct_version; /*!< @if Eng The Structure Version of FOTA info Area. 193 @else FOTA key区域结构版本。 @endif */ 194 uint32_t struct_length; /*!< @if Eng The Structure Length. 195 @else 结构长度。 @endif */ 196 uint32_t signature_length; /*!< @if Eng The signature Length. 197 @else 签名长度。 @endif */ 198 uint32_t fota_version_ext; /*!< @if Eng Version of FOTA Info Area. 199 @else FOTA信息区的版本。 @endif */ 200 uint32_t mask_fota_version_ext;/*!< @if Eng Version of FOTA_External_Public_Key. 201 @else FOTA二级公共密钥的版本。 @endif */ 202 uint32_t msid_ext; /*!< @if Eng Market segment ID. 203 @else 细分市场ID。 @endif */ 204 uint32_t mask_msid_ext; /*!< @if Eng Mask of MSID. 205 @else MSID掩码。 @endif */ 206 uint32_t image_hash_table_addr;/*!< @if Eng Address of Image_Hash_Table In FOTA Package. 207 @else FOTA包中镜像哈希表的地址。 @endif */ 208 uint32_t image_hash_table_length;/*!< @if Eng Length of Image_Hash_Table. 209 @else 镜像哈希表的长度。 @endif */ 210 uint8_t image_hash_table_hash[SHA_256_LENGTH];/*!< @if Eng Hash of Image_Hash_Table. 211 @else 镜像哈希表的哈希。 @endif */ 212 uint32_t image_num; /*!< @if Eng The total numbers of FOTA images. 213 @else FOTA镜像的总数。 @endif */ 214 uint32_t hardware_id; /*!< @if Eng Hardware ID. 215 @else 硬件ID。 @endif */ 216 uint8_t user_defined[INFO_AREA_USER_LEN]; /*!< @if Eng Reserve 48 bytes for user customization. 217 @else 预留字节供用户自定义使用。 @endif */ 218 uint8_t sign_fota_info[SIG_LEN];/*!< @if Eng Signature of FOTA Info. 219 @else FOTA信息签名。 @endif */ 220 } upg_fota_info_data_t; 221 222 /** 223 * @if Eng 224 * @brief upg image hash node type. 225 * @else 226 * @brief 升级镜像哈希节点类型。 227 * @endif 228 */ 229 typedef struct upg_image_hash_node { 230 uint32_t image_id; /*!< @if Eng Identity of FOTA Key Area. 231 @else FOTA key区域的标识。 @endif */ 232 uint32_t image_addr; /*!< @if Eng Offset of Image Header. 233 @else 镜像头偏移量。 @endif */ 234 uint32_t image_length; /*!< @if Eng Length of Image. 235 @else 镜像长度。 @endif */ 236 uint8_t image_hash[SHA_256_LENGTH]; /*!< @if Eng Hash Of Image Header. 237 @else 镜像头的哈希。 @endif */ 238 } upg_image_hash_node_t; 239 240 /** 241 * @if Eng 242 * @brief upg package header type. 243 * @else 244 * @brief 升级包头类型 245 * @endif 246 */ 247 typedef struct upg_package_header { 248 upg_key_area_data_t key_area;/*!< @if Eng upg key area data. 249 @else 升级密钥区域数据。 @endif */ 250 upg_fota_info_data_t info_area;/*!< @if Eng fota info data. 251 @else FOTA info区数据。 @endif */ 252 } upg_package_header_t; 253 254 /** 255 * @if Eng 256 * @brief upg image header type. 257 * @else 258 * @brief 升级包镜像头类型 259 * @endif 260 */ 261 typedef struct upg_image_header { 262 uint32_t header_magic; /*!< @if Eng header magic. 263 @else 镜像头魔术字。 @endif */ 264 uint32_t image_id; /*!< @if Eng Identity of FOTA Key Area. 265 @else FOTA key区域的标识。 @endif */ 266 uint32_t image_offset; /*!< @if Eng Offset of update Image data. 267 @else 要更新的镜像数据的偏移地址。 @endif */ 268 uint32_t image_len; /*!< @if Eng Length of update image data, actual data length, NOT including padding. 269 @else 更新的镜像数据的长度（实际数据长度，不包括填充字段）。 @endif */ 270 uint8_t image_hash[SHA_256_LENGTH]; /*!< @if Eng Hash of update image data. 271 @else 更新镜像数据的哈希。 @endif */ 272 uint32_t old_image_len; /*!< @if Eng Length of old image. 273 @else 旧镜像长度。 @endif */ 274 uint8_t old_image_hash[SHA_256_LENGTH]; /*!< @if Eng Hash value of old image. 275 @else 旧镜像的哈希值。 @endif */ 276 uint32_t new_image_len; /*!< @if Eng length of new image. 277 @else 新镜像长度。 @endif */ 278 uint32_t version_ext; /*!< @if Eng Version of the new image. 279 @else 新镜像版本。 @endif */ 280 uint32_t version_mask; /*!< @if Eng The version mask. 281 @else 版本掩码。 @endif */ 282 uint32_t decompress_flag; /*!< @if Eng Decompress flag. 283 @else 解压标志。 @endif */ 284 uint32_t re_enc_flag; /*!< @if Eng Re-Encryption flag. 285 @else 重新加密标志。 @endif */ 286 uint32_t root_key_type; /*!< @if Eng Root key which is used to encrypt the image. 287 @else 用于加密镜像的密钥。 @endif */ 288 uint8_t enc_pk_l1[PROTECT_KEY_LEN]; /*!< @if Eng The level 1 encrypted protection key 289 for decrypting update image. 290 @else 用于解密更新镜像的一级加密保护密钥。 @endif */ 291 uint8_t enc_pk_l2[PROTECT_KEY_LEN]; /*!< @if Eng level 2 encrypted protection key 292 for decrypting update image. 293 @else 用于解密更新镜像的二级加密保护密钥。 @endif */ 294 uint8_t iv[IV_LEN]; /*!< @if Eng The IV for decrypt update image. 295 @else 用于解密升级镜像的IV。 @endif */ 296 uint8_t padding[4]; /*!< @if Eng reserve bytes for 16-byte aligned. 297 @else 保留字段，以保证整个结构16字节对齐。 @endif */ 298 } upg_image_header_t; 299 300 /** 301 * @if Eng 302 * @brief The callback function after writting type. 303 * @else 304 * @brief 写类型后的回调函数。 305 * @endif 306 */ 307 typedef void (*uapi_upg_write_done_cb)(errcode_t result); 308 309 /** 310 * @if Eng 311 * @brief The progress notification callback function type. 312 * @else 313 * @brief 进度通知回调函数类型。 314 * @endif 315 */ 316 typedef void (*uapi_upg_progress_cb)(uint32_t percent); 317 318 /** 319 * @if Eng 320 * @brief The function for verifying user-defined field type. 321 * @else 322 * @brief 自定义字段类型校验函数。 323 * @endif 324 */ 325 typedef errcode_t (*uapi_upg_user_defined_check)(uint8_t *user_info, uint32_t info_len, uintptr_t param); 326 327 /** 328 * @if Eng 329 * @brief upg malloc function. 330 * @else 331 * @brief 升级使用内存分配函数。 332 * @endif 333 */ 334 typedef void *(*upg_func_malloc)(const uint32_t size); 335 336 /** 337 * @if Eng 338 * @brief upg free mandatory function. 339 * @else 340 * @brief 升级释放内存函数。 341 * @endif 342 */ 343 typedef void (*upg_func_free)(void *ptr); 344 345 /** 346 * @if Eng 347 * @brief upg serial putc mandatory function. 348 * @else 349 * @brief upg串口输出函数。 350 * @endif 351 */ 352 typedef void (*upg_func_serial_putc)(const char c); 353 354 /** 355 * @if Eng 356 * @brief struct of optional function. 357 * @else 358 * @brief 可选函数结构。 359 * @endif 360 */ 361 typedef struct upg_func { 362 upg_func_malloc malloc; /*!< @if Eng upg malloc function.(Mandatory Function) 363 @else 升级使用内存分配函数（必选函数）。 @endif */ 364 upg_func_free free; /*!< @if Eng upg free mandatory function.(Mandatory Function) 365 @else 升级释放内存函数 （必选函数）。 @endif */ 366 upg_func_serial_putc serial_putc; /*!< @if Eng upg serial putc mandatory function.（Optional Functions） 367 @else upg串口输出函数。 @endif */ 368 } upg_func_t; 369 370 /** 371 * @if Eng 372 * @brief struct of upg prepare info. 373 * @else 374 * @brief 升级准备信息结构。 375 * @endif 376 */ 377 typedef struct upg_prepare_info { 378 uint32_t package_len; /*!< @if Eng package length. 379 @else 升级包的大小。 @endif */ 380 } upg_prepare_info_t; 381 382 /** 383 * @if Eng 384 * @brief Initializing the update module. 385 * @par Description: Initializing the update module. 386 * @param [in] func_list Register functions list for update code usage. see @ref upg_func_t 387 * @retval ERRCODE_SUCC Success. 388 * @retval Others ERRCODE_FAIL or other error num. 389 * @else 390 * @brief 初始化升级模块。 391 * @par 说明: 初始化升级模块。 392 * @param [in] func_list 升级模块使用的注册函数列表。 参考 @ref upg_func_t 393 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 394 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 395 * @endif 396 */ 397 errcode_t uapi_upg_init(const upg_func_t *func_list); 398 399 /** 400 * @if Eng 401 * @brief Start local update. 402 * @par Description: Start local update. 403 * @retval ERRCODE_SUCC Success. 404 * @retval Others ERRCODE_FAIL or other error num. 405 * @else 406 * @brief 开始本地升级。 407 * @par 说明: 开始本地升级。 408 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 409 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 410 * @endif 411 */ 412 errcode_t uapi_upg_start(void); 413 414 /** 415 * @if Eng 416 * @brief Register the progress notification callback function. 417 * @par Description: Register the progress notification callback function. 418 * @param [in] func The progress notification callback function. see @ref uapi_upg_progress_cb 419 * @retval ERRCODE_SUCC Success. 420 * @retval Others ERRCODE_FAIL or other error num. 421 * @else 422 * @brief 注册升级进度通知回调函数。 423 * @par 说明: 注册升级进度通知回调函数。 424 * @param [in] func 进度通知的回调函数。 参考 @ref uapi_upg_progress_cb 425 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 426 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 427 * @endif 428 */ 429 errcode_t uapi_upg_register_progress_callback(uapi_upg_progress_cb func); 430 431 /** 432 * @if Eng 433 * @brief Obtain the update result. 434 * @par Description: Obtain the update result. 435 * @param [out] result Address for saving the update result. see @ref upg_result_t 436 * @param [out] last_image_index Address for saving the last image index. 437 * @retval ERRCODE_SUCC Success. 438 * @retval Others ERRCODE_FAIL or other error num. 439 * @else 440 * @brief 获取升级结果。 441 * @par 说明: 获取升级结果。 442 * @param [out] result 保存获取的升级结果。 参考 @ref upg_result_t 443 * @param [out] last_image_index 保存获取的最后一个处理的升级镜像的序号。 444 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 445 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 446 * @endif 447 */ 448 errcode_t uapi_upg_get_result(upg_result_t *result, uint32_t *last_image_index); 449 450 /** 451 * @if Eng 452 * @brief Obtain the update status. 453 * @par Description: Obtain the update status. 454 * @retval see @ref upg_status_t. 455 * @else 456 * @brief 获取升级状态。 457 * @par 说明: 获取升级状态。 458 * @retval 参考 @ref upg_status_t 459 * @endif 460 */ 461 upg_status_t uapi_upg_get_status(void); 462 463 /** 464 * @if Eng 465 * @brief Preparing the local storage for storing the upgrade package. 466 * @par Description: This function is blocked and waits for the return value after execution. 467 * @param [in] prepare_info The pointer of prepare info. see @ref upg_prepare_info_t 468 * @retval ERRCODE_SUCC Success. 469 * @retval Others ERRCODE_FAIL or other error num. 470 * @else 471 * @brief 用来保存升级包的本地存储器的准备工作。 472 * @par 说明: 该函数阻塞等待执行完返回。 473 * @param [in] prepare_info 准备信息的指针。 参考 @ref upg_prepare_info_t 474 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 475 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 476 * @endif 477 */ 478 errcode_t uapi_upg_prepare(upg_prepare_info_t *prepare_info); 479 480 /** 481 * @if Eng 482 * @brief Reset upgrade flag 483 * @par Description: This function is blocked and waits for the return value after execution. 484 * @retval ERRCODE_SUCC Success. 485 * @retval Others ERRCODE_FAIL or other error num. 486 * @else 487 * @brief 重置升级标记 488 * @par 说明: 该函数阻塞等待执行完返回。 489 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 490 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 491 * @endif 492 */ 493 errcode_t uapi_upg_reset_upgrade_flag(void); 494 495 /** 496 * @if Eng 497 * @brief Write the update package data to the local storage. 498 * @par Description: This function is asynchronous and returns immediately. 499 * After the actual operation is complete, 500 * the callback function is invoked. 501 * @attention The next packet can be written only after the callback function 502 * is called and the write success is returned. 503 * Before that, this interface cannot be called again to write the next packet. 504 * @param [in] offset Offset from the start of the package. 505 * @param [in] buff Buffer for storing package section data. 506 * The callback function for completing preparations. 507 * @param [in] len The length of package section data. 508 * @param [in] callback The callback function after writting. see @ref uapi_upg_write_done_cb 509 * @retval ERRCODE_SUCC Success. 510 * @retval Others ERRCODE_FAIL or other error num. 511 * @else 512 * @brief 将升级包数据写入本地存储器。 513 * @par 说明: 该函数异步执行立即返回，实际操作完成后调用回调函数。 514 * @attention 当前接口的回调函数被调用且返回写成功才能继续写下一个数据包，在此之前禁止再次调用该接口写下一个数据包。 515 * @param [in] offset 相对升级包开头的偏移。 516 * @param [in] buff 存放升级包数据的buffer。 517 * @param [in] len 升级包数据buffer的长度。 518 * @param [in] callback 写入完成的回调函数。 参考 @ref uapi_upg_write_done_cb 519 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 520 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 521 * @endif 522 */ 523 errcode_t uapi_upg_write_package_async(uint32_t offset, const uint8_t *buff, uint16_t len, 524 uapi_upg_write_done_cb callback); 525 526 /** 527 * @if Eng 528 * @brief Write the update package data to the local storage. 529 * @par Description: This function is synchronous and returns immediately. 530 * @param [in] offset Offset from the start of the package. 531 * @param [in] buff Buffer for storing package section data. 532 * The callback function for completing preparations. 533 * @param [in] len The length of package section data. 534 * @retval ERRCODE_SUCC Success. 535 * @retval Others ERRCODE_FAIL or other error num. 536 * @else 537 * @brief 将升级包数据写入本地存储器。 538 * @par 说明: 该函数同步执行立即返回。 539 * @param [in] offset 相对升级包开头的偏移。 540 * @param [in] buff 存放升级包数据的buffer。 541 * @param [in] len 升级包数据buffer的长度。 542 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 543 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 544 * @endif 545 */ 546 errcode_t uapi_upg_write_package_sync(uint32_t offset, const uint8_t *buff, uint16_t len); 547 548 /** 549 * @if Eng 550 * @brief Read the package data from the local storage. 551 * @par Description: Read the package data from the local storage. 552 * @param [in] offset Offset from the start of the package. 553 * @param [in] buff Buffer for storing package section data. 554 * The callback function for completing preparations. 555 * @param [in] len The length of package section data. 556 * @retval ERRCODE_SUCC Success. 557 * @retval Others ERRCODE_FAIL or other error num. 558 * @else 559 * @brief 从本地存储器读取升级包数据。 560 * @par 说明: 从本地存储器读取升级包数据。 561 * @param [in] offset 相对升级包开头的偏移。 562 * @param [in] buff 存放升级包数据的buffer。 563 * @param [in] len 升级包数据的长度buffer。 564 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 565 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 566 * @endif 567 */ 568 errcode_t uapi_upg_read_package(uint32_t offset, uint8_t *buff, uint32_t len); 569 570 /** 571 * @if Eng 572 * @brief Obtain the size for the package. 573 * @par Description: Obtain the size for the package. 574 * @retval 0 Obtain the size failed. 575 * @retval Others The size obtained. 576 * @else 577 * @brief 获取可存放升级包的空间大小。 578 * @par 说明: 获取可存放升级包的空间大小。 579 * @retval 0 失败返回0。 580 * @retval Others 其他值：成功返回空间大小。 581 * @endif 582 */ 583 uint32_t uapi_upg_get_storage_size(void); 584 585 /** 586 * @if Eng 587 * @brief Request local update. 588 * @par Description: Request local update. 589 * @param [in] reset Whether to restart the system after the function process is complete. 590 * @retval ERRCODE_SUCC Success. 591 * @retval Others ERRCODE_FAIL or other error num. 592 * @else 593 * @brief 申请开始进行本地升级。 594 * @par 说明: 申请开始进行本地升级。 595 * @param [in] reset 申请流程结束后是否重启系统。 596 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 597 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 598 * @endif 599 */ 600 errcode_t uapi_upg_request_upgrade(bool reset); 601 602 /** 603 * @if Eng 604 * @brief verify the Header of the update package. 605 * @par Description: verify the Header of the update package. 606 * @param [in] pkg_header Pointer to the package header. see @ref upg_package_header_t 607 * @retval ERRCODE_SUCC Success. 608 * @retval Others ERRCODE_FAIL or other error num. 609 * @else 610 * @brief 校验升级包头结构。 611 * @par 说明: 校验升级包头结构。 612 * @param [in] pkg_header 指向升级包头结构的指针。 参考 @ref upg_package_header_t 613 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 614 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 615 * @endif 616 */ 617 errcode_t uapi_upg_verify_file_head(const upg_package_header_t *pkg_header); 618 619 /** 620 * @if Eng 621 * @brief verify the image in the upgrade package. 622 * @par Description: verify_old applies to differential update, used to determine whether the old image 623 in use is the same as the old image used for differential mirroring. 624 * @param [in] img_header Pointer to the image header. see @ref upg_image_header_t 625 * @param [in] hash The hash of image. 626 * The callback function for completing preparations. 627 * @param [in] hash_len The length of hash(unit: byte). 628 * @param [in] verify_old Whether to verify the old image. 629 * @retval ERRCODE_SUCC Success. 630 * @retval Others ERRCODE_FAIL or other error num. 631 * @else 632 * @brief 校验升级包中的升级镜像。 633 * @par 说明: verify_old一般适用于差分升级场景下，用于判断当前使用的旧镜像与做差分镜像时的旧镜像是否一致。 634 * @param [in] img_header 指向升级包中升级镜像头结构的指针。 参考 @ref upg_image_header_t 635 * @param [in] hash 升级镜像的HASH值。 636 * @param [in] hash_len HASH的长度(单位：字节)。 637 * @param [in] verify_old 是否校验旧镜像。 638 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 639 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 640 * @endif 641 */ 642 errcode_t uapi_upg_verify_file_image(const upg_image_header_t *img_header, 643 const uint8_t *hash, uint32_t hash_len, bool verify_old); 644 645 /** 646 * @if Eng 647 * @brief verify the whole update package. 648 * @par Description: verify the whole update package. 649 * @param [in] pkg_header Pointer to the package header. see @ref upg_package_header_t 650 * @retval ERRCODE_SUCC Success. 651 * @retval Others ERRCODE_FAIL or other error num. 652 * @else 653 * @brief 校验整个升级包。 654 * @par 说明: 校验整个升级包。 655 * @param [in] pkg_header 指向升级包头结构的指针。 参考 @ref upg_package_header_t 656 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 657 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 658 * @endif 659 */ 660 errcode_t uapi_upg_verify_file(const upg_package_header_t *pkg_header); 661 662 /** 663 * @if Eng 664 * @brief Register a user-defined field verification function. 665 * @par Description: After the user-defined verification function is registered. 666 * When the uapi_upg_verify_file_head and uapi_upg_verify_file functions are invoked, 667 * the verification function is invoked. 668 * @param [in] func The function for verifying user-defined field. see @ref uapi_upg_user_defined_check 669 * @param [in] param Registration parameters . 670 * @retval ERRCODE_SUCC Success. 671 * @retval Others ERRCODE_FAIL or other error num. 672 * @else 673 * @brief 注册用户自定义字段的校验函数。 674 * @par 说明: 注册后，调用uapi_upg_verify_file_head和uapi_upg_verify_file函数时，校验函数会被调用到。 675 * @param [in] func 用于校验用户自定义字段的校验函数。 参考 @ref uapi_upg_user_defined_check 676 * @param [in] param 注册参数。 677 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC。 678 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值。 679 * @endif 680 */ 681 void uapi_upg_register_user_defined_verify_func(uapi_upg_user_defined_check func, uintptr_t param); 682 683 /** 684 * @} 685 */ 686 687 #ifdef __cplusplus 688 #if __cplusplus 689 } 690 #endif 691 #endif 692 693 #endif /* UPG_INTERFACE_H */