1 /* 2 * @file hi_upg_api.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /** 19 * @defgroup upg Upgrade 20 * @ingroup system 21 */ 22 23 #ifndef __HI_UPG_API_H__ 24 #define __HI_UPG_API_H__ 25 #include "hi_upg_file.h" 26 #include <hi_types.h> 27 28 /** 29 * @ingroup upg 30 * Kernel upgrade file. CNcomment:Kernel升级文件。CNend 31 */ 32 #define HI_UPG_FILE_KERNEL 0xF0 33 34 /** 35 * @ingroup upg 36 * FlashBoot upgrade file. CNcomment:FlashBoot升级文件。CNend 37 */ 38 #define HI_UPG_FILE_BOOT 0xE1 39 40 /** 41 * @ingroup upg 42 * Kernel upgrade file of area A. CNcomment:A区升级文件。CNend 43 */ 44 #define HI_UPG_FILE_FOR_AREA_A 1 45 46 /** 47 * @ingroup upg 48 * Kernel upgrade file of area B/Compress kernel upgrade file. CNcomment:B区升级文件/压缩升级文件。CNend 49 */ 50 #define HI_UPG_FILE_FOR_AREA_B 2 51 52 /** 53 * @ingroup upg 54 * Kernel upgrade file magic number. CNcomment:Kernel升级文件魔术字。CNend 55 */ 56 #define HI_UPG_FILE_IMAGE_ID 0x3C78961E 57 58 /** 59 * @ingroup upg 60 * @brief Upgrade module initialization.CNcomment:升级模块初始化。CNend 61 * 62 * @par 描述: 63 Upgrade module initialization.CNcomment:升级模块初始化。CNend 64 * @attention 65 * @li Must be called immediately after NV initialization. CNcomment:必须紧跟NV初始化后调用。CNend 66 * @li This interface does not support multiple calls. CNcomment:该接口不支持多次调用。CNend 67 * @param None. 68 * @retval #HI_ERR_SUCCESS Success.CNcomment:升级模块初始化成功。CNend 69 * @retval #Other Failure.CNcomment:其他值 升级模块初始化失败。CNend 70 * @par 依赖: 71 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 72 * @see None.CNcomment:无。CNend 73 */ 74 hi_u32 hi_upg_init(hi_void); 75 76 /** 77 * @ingroup upg 78 * @brief Get upgrade file from the backup flash.CNcomment:从备份区读取升级文件。CNend 79 * 80 * @par 描述: 81 Used to get upgrade data from the backup flash.CNcomment:该函数从备份区读升级文件。CNend 82 * @attention 83 * @li Ensure that the actual buffer size is the same as the value of buf_len. 84 * CNcomment:用户需保证buf实际大小与buf_len相等。CNend 85 * @li Must be called after calling interface hi_upg_transmit or hi_upg_transmit_finish_save_cache. 86 CNcomment:必须在调用升级文件传输接口之后调用。CNend 87 * @li Must be called before calling interface hi_upg_transmit_finish in non-power-off upgrade scenario. 88 CNcomment:非断电升级场景必须在调用升级文件传输完成之前调用。CNend 89 * @li Must be called before calling interface hi_upg_finish_with_cache in power-off upgrade scenario. 90 CNcomment:断电升级场景必须在调用升级结束完成之前调用。CNend 91 * @param offset [IN] type #hi_u32 Offset relative to the start address of the upgrade cache. 92 * CNcomment:相对升级备份区起始地址的偏移地址。CNend 93 * @param buf [IN/OUT] type #hi_u8* Pointer to the upgrade data package.CNcomment:升级数据包指针。CNend 94 * @param buf_len [IN] type #hi_u32 Length of the upgrade data package.Unit: byte. 95 * CNcomment:升级数据包长度，单位：byte。CNend 96 * @retval #HI_ERR_SUCCESS Success.CNcomment:读成功。CNend 97 * @retval #Other Failure.CNcomment:其他值 读失败。CNend 98 * @par 依赖: 99 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 100 * @see hi_upg_transmit_finish_save_cache; hi_upg_finish_with_cache; hi_upg_transmit; hi_upg_transmit_finish. 101 */ 102 hi_u32 hi_upg_get_content(hi_u32 offset, hi_u8* buf, hi_u32 buf_len); 103 104 /** 105 * @ingroup upg 106 * @brief Transmit upgrade file.CNcomment:传输升级文件。CNend 107 * 108 * @par 描述: 109 Transmit upgrade file.CNcomment:传输升级文件。CNend 110 * @attention 111 * @li The first packet transmitted is not less than 96 bytes.CNcomment:传输的第1包不小于96字节。CNend 112 * @param offset [IN] type #hi_u32 Offset relative to the head of the upgrade file.CNcomment:相对升级文件头的偏移地址。CNend 113 * @param buf [IN] type #hi_u8* Upgrade file data.CNcomment:升级数据包。CNend 114 * @param buf_len [IN] type #hi_u32 Length of the upgrade file data.Unit:byte.CNcomment:升级数据包长度，单位：byte。CNend 115 * @retval #HI_ERR_SUCCESS Success.CNcomment:成功。CNend 116 * @retval #Other Failure.CNcomment:其他值 失败。CNend 117 * @par 依赖: 118 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 119 * @see None.CNcomment:无。CNend 120 */ 121 hi_u32 hi_upg_transmit(hi_u32 offset, hi_u8* buf, hi_u32 buf_len); 122 123 /** 124 * @ingroup upg 125 * @brief Upgrade restart.CNcomment:升级重启。CNend 126 * 127 * @par 描述: 128 This interface is used to restart.CNcomment:该接口实现升级重启。CNend 129 * @attention None. 130 * @param None. 131 * @retval None. 132 * @par 依赖: 133 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 134 * @see None.CNcomment:无。CNend 135 */ 136 hi_void hi_upg_finish(hi_void); 137 138 /** 139 * @ingroup upg 140 * @brief Notify file transfer end.CNcomment:文件传输结束。CNend 141 * 142 * @par 描述: 143 Used to notify file transfer end.CNcomment:文件传输结束。CNend 144 * @attention None. 145 * @param None. 146 * @retval #HI_ERR_SUCCESS Success.CNcomment:成功。CNend 147 * @retval #Other Failure.CNcomment:其他值 失败。CNend 148 * @par 依赖: 149 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 150 * @see None.CNcomment:无。CNend 151 */ 152 hi_u32 hi_upg_transmit_finish(hi_void); 153 154 /** 155 * @ingroup upg 156 * @brief Upgrade restart. The power-off or restart operation is allowed before upgrade restart. 157 CNcomment:升级重启，支持断电后执行升级重启操作。CNend 158 * 159 * @par 描述: 160 This interface is used to restart. It works with hi_upg_transmit_finish_save_cache and applies to scenarios 161 where the upgrade is not required immediately. 162 CNcomment:该接口实现升级重启，与hi_upg_transmit_finish_save_cache配合使用，适用于不需要立即进行升级的场景。CNend 163 * @attention 164 * @li The power-off or restart operation is allowed between hi_upg_transmit_finish_save_cache and 165 hi_upg_finish_with_cache. 166 CNcomment:允许在hi_upg_transmit_finish_save_cache和hi_upg_finish_with_cache的调用之间存在掉电或重启操作。CNend. 167 * @param None. 168 * @retval #HI_ERR_SUCCESS Success.CNcomment:成功。CNend 169 * @retval #Other Failure.CNcomment:其他值 失败。CNend 170 * @par 依赖: 171 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 172 * @see None.CNcomment:无。CNend 173 */ 174 hi_u32 hi_upg_finish_with_cache(hi_void); 175 176 /** 177 * @ingroup upg 178 * @brief Notify file transfer is complete and save some key parameters of the transfer process. 179 CNcomment:文件传输结束，保存传输流程的关键参数。CNend 180 * 181 * @par 描述: 182 Used to notify file transfer end and save some key parameters of the transfer process. It works with 183 hi_upg_finish_with_cache and applies to scenarios where the upgrade is not required immediately. 184 CNcomment:文件传输结束，保存传输流程的关键参数。与hi_upg_finish_with_cache配合使用，适用于不需要立即 185 进行升级的场景。CNend 186 * @attention 187 * @li The power-off or restart operation is allowed between hi_upg_transmit_finish_save_cache and 188 hi_upg_finish_with_cache. 189 CNcomment:允许在hi_upg_transmit_finish_save_cache和hi_upg_finish_with_cache的调用之间存在掉电或重启操作。CNend. 190 * @param None. 191 * @retval #HI_ERR_SUCCESS Success.CNcomment:成功。CNend 192 * @retval #Other Failure.CNcomment:其他值 失败。CNend 193 * @par 依赖: 194 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 195 * @see None.CNcomment:无。CNend 196 */ 197 hi_u32 hi_upg_transmit_finish_save_cache(hi_void); 198 199 /** 200 * @ingroup upg 201 * @brief Get the maximum upgrade file length.CNcomment:获取最大升级文件长度。CNend 202 * 203 * @par 描述: 204 Used to get the maximum upgrade file length.CNcomment:获取最大升级文件长度。CNend 205 * @attention None. 206 * @param file_type [IN] type #hi_u8 Upgrade file type.CNcomment:升级文件类型。CNend 207 * @param file_len [IN/OUT] type #hi_u32* Max file length.CNcomment:最大升级文件大小。CNend 208 * @retval #HI_ERR_SUCCESS Success.CNcomment:成功。CNend 209 * @retval #Other Failure.CNcomment:其他值 失败。CNend 210 * @par 依赖: 211 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 212 * @see None.CNcomment:无。CNend 213 */ 214 hi_u32 hi_upg_get_max_file_len(hi_u8 file_type, hi_u32 *file_len); 215 216 /** 217 * @ingroup upg 218 * @brief Get the upgrade file index.CNcomment:获取升级文件编号。CNend 219 * 220 * @par 描述: 221 Get the upgrade file index.CNcomment:获取升级文件编号。CNend 222 * @attention None.CNcomment:无。CNend 223 * @param index [IN/OUT] type #hi_u8* Upgrade file index.CNcomment:升级文件编号。CNend 224 * @retval #1 Upg file for area A.CNcomment:1 A区升级文件。CNend 225 * @retval #2 Upg file for area B.CNcomment:2 B区升级文件。CNend 226 * @par 依赖: 227 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 228 * @see None.CNcomment:无。CNend 229 */ 230 hi_u32 hi_upg_get_file_index(hi_u8 *index); 231 232 /** 233 * @ingroup upg 234 * @brief Stop the upgrade process.CNcomment:停止升级。CNend 235 * 236 * @par 描述: 237 Used to stop the upgrade process.CNcomment:停止升级。CNend 238 * @attention None. 239 * @param None. 240 * @retval #HI_ERR_SUCCESS Success.CNcomment:成功。CNend 241 * @retval #Other Failure.CNcomment:其他值 失败。CNend 242 * @par 依赖: 243 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 244 * @see None.CNcomment:无。CNend 245 */ 246 hi_u32 hi_upg_stop(hi_void); 247 248 /** 249 * @ingroup upg 250 * @brief Register upgrade file validity check interface.CNcomment:注册升级文件合法性校验接口。CNend 251 * 252 * @par 描述: 253 Register upgrade file validity check interface.CNcomment:注册升级文件合法性校验接口。CNend 254 * @attention Called during the initialization process.CNcomment:初始化流程中调用。CNend 255 * @param upg_file_check_fn [IN]User-defined upgrade file verification interface.CNcomment:用户自定义接口。CNend 256 * @param param [IN]Passed back to callback function when callback.CNcomment:用户自定义接口参数。CNend 257 * @retval #HI_ERR_SUCCESS Success.CNcomment:成功。CNend 258 * @retval #Other Failure.CNcomment:其他值 失败。CNend 259 * @par 依赖: 260 * @li hi_upg_api.h：Describe Upgrade usage APIs.CNcomment:文件用于描述升级对外接口。CNend 261 * @see None.CNcomment:无。CNend 262 */ 263 hi_u32 hi_upg_register_file_verify_fn( 264 hi_u32 (*upg_file_check_fn)(const hi_upg_user_info *info, hi_void *param), 265 hi_void *param); 266 267 #endif