yu.dong | c33b307 | 2024-08-21 23:14:49 -0700 | [diff] [blame^] | 1 | /***************************************************************************** |
| 2 | * Copyright Statement: |
| 3 | * -------------------- |
| 4 | * This software is protected by Copyright and the information contained |
| 5 | * herein is confidential. The software may not be copied and the information |
| 6 | * contained herein may not be used or disclosed except with the written |
| 7 | * permission of MediaTek Inc. (C) 2006 |
| 8 | * |
| 9 | * BY OPENING THIS FILE, BUYER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES |
| 10 | * THAT THE SOFTWARE/FIRMWARE AND ITS DOCUMENTATIONS ("MEDIATEK SOFTWARE") |
| 11 | * RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES ARE PROVIDED TO BUYER ON |
| 12 | * AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES, |
| 13 | * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF |
| 14 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. |
| 15 | * NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE |
| 16 | * SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR |
| 17 | * SUPPLIED WITH THE MEDIATEK SOFTWARE, AND BUYER AGREES TO LOOK ONLY TO SUCH |
| 18 | * THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. MEDIATEK SHALL ALSO |
| 19 | * NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO BUYER'S |
| 20 | * SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM. |
| 21 | * |
| 22 | * BUYER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND CUMULATIVE |
| 23 | * LIABILITY WITH RESPECT TO THE MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE, |
| 24 | * AT MEDIATEK'S OPTION, TO REVISE OR REPLACE THE MEDIATEK SOFTWARE AT ISSUE, |
| 25 | * OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY BUYER TO |
| 26 | * MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE. |
| 27 | * |
| 28 | * THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED IN ACCORDANCE |
| 29 | * WITH THE LAWS OF THE STATE OF CALIFORNIA, USA, EXCLUDING ITS CONFLICT OF |
| 30 | * LAWS PRINCIPLES. ANY DISPUTES, CONTROVERSIES OR CLAIMS ARISING THEREOF AND |
| 31 | * RELATED THERETO SHALL BE SETTLED BY ARBITRATION IN SAN FRANCISCO, CA, UNDER |
| 32 | * THE RULES OF THE INTERNATIONAL CHAMBER OF COMMERCE (ICC). |
| 33 | * |
| 34 | *****************************************************************************/ |
| 35 | |
| 36 | /***************************************************************************** |
| 37 | * |
| 38 | * Filename: |
| 39 | * --------- |
| 40 | * fota.h |
| 41 | * |
| 42 | * Project: |
| 43 | * -------- |
| 44 | * Maui_Software |
| 45 | * |
| 46 | * Description: |
| 47 | * ------------ |
| 48 | * This is the header of FOTA firmware update download module |
| 49 | * |
| 50 | * Author: |
| 51 | * ------- |
| 52 | * ------- |
| 53 | * |
| 54 | *============================================================================ |
| 55 | * HISTORY |
| 56 | * Below this line, this part is controlled by PVCS VM. DO NOT MODIFY!! |
| 57 | *------------------------------------------------------------------------------ |
| 58 | * removed! |
| 59 | * removed! |
| 60 | * removed! |
| 61 | * |
| 62 | * removed! |
| 63 | * removed! |
| 64 | * removed! |
| 65 | * |
| 66 | * removed! |
| 67 | * removed! |
| 68 | * removed! |
| 69 | * |
| 70 | * removed! |
| 71 | * removed! |
| 72 | * removed! |
| 73 | * |
| 74 | * removed! |
| 75 | * removed! |
| 76 | * removed! |
| 77 | * |
| 78 | * removed! |
| 79 | * removed! |
| 80 | * removed! |
| 81 | * |
| 82 | * removed! |
| 83 | * removed! |
| 84 | * removed! |
| 85 | * |
| 86 | * removed! |
| 87 | * removed! |
| 88 | * removed! |
| 89 | * |
| 90 | *------------------------------------------------------------------------------ |
| 91 | * Upper this line, this part is controlled by PVCS VM. DO NOT MODIFY!! |
| 92 | *============================================================================ |
| 93 | ****************************************************************************/ |
| 94 | |
| 95 | #ifndef __FOTA_H__ |
| 96 | #define __FOTA_H__ |
| 97 | |
| 98 | /******************************************* |
| 99 | * Include File |
| 100 | ********************************************/ |
| 101 | |
| 102 | #include "kal_public_api.h" //MSBB change #include "kal_release.h" |
| 103 | #include "fat_fs.h" |
| 104 | #include "DrvFlash.h" |
| 105 | #include "fota_error.h" |
| 106 | #include "custom_img_config.h" |
| 107 | |
| 108 | /******************************************* |
| 109 | * Structure and Macro Definition |
| 110 | ********************************************/ |
| 111 | #define FOTA_BUFFER_SIZE FOTA_FLASH_MAX_PAGE_SIZE |
| 112 | #define FOTA_FRAME_TICK 70 |
| 113 | |
| 114 | typedef kal_int32 (*CALLBACK_Auth_FUNC)(void* Header); |
| 115 | typedef kal_int32 (*CALLBACK_Decrypt_FUNC)(void* EncryptBuffer); |
| 116 | |
| 117 | //#if !defined(_NAND_FLASH_BOOTING_) |
| 118 | #if !defined(__FOTA_DM__) |
| 119 | |
| 120 | typedef struct { |
| 121 | kal_int32 Status; |
| 122 | kal_uint32 FlashBaseAddr; |
| 123 | kal_uint32 OriginalBaseAddr; |
| 124 | kal_uint32 SpareBaseAddr; |
| 125 | kal_uint32 SpareStartBlkIndex; |
| 126 | kal_uint32 TotalFOTALength; |
| 127 | kal_uint32 SpareCurrAddr; |
| 128 | kal_uint32 NextBlockAddr; |
| 129 | kal_uint32 NextBlkOffset; |
| 130 | FlashRegionInfo* NORRegionInfo; |
| 131 | kal_uint32 ImageChecksum; |
| 132 | kal_uint32 ImageStartAddr; |
| 133 | kal_uint32 ImageLength; |
| 134 | kal_uint32 BufferIndex; |
| 135 | CALLBACK_Auth_FUNC Auth; |
| 136 | CALLBACK_Decrypt_FUNC Decrypt; |
| 137 | kal_uint32 FOTABuffer[FOTA_BUFFER_SIZE>>2]; |
| 138 | } FOTA_DATA; |
| 139 | |
| 140 | #else /* defined(_NAND_FLASH_BOOTING_) */ |
| 141 | |
| 142 | typedef struct { |
| 143 | kal_int32 Status; |
| 144 | kal_uint32 SpareCurrWriteAddr; |
| 145 | kal_uint32 SpareNextWriteBlockAddr; |
| 146 | kal_uint32 SpareCurrReadAddr; |
| 147 | kal_uint32 SpareNextReadBlockAddr; |
| 148 | kal_uint32 BufferIndex; |
| 149 | kal_uint32 FOTAWriteBuffer[FOTA_BUFFER_SIZE>>2]; |
| 150 | kal_uint32 FOTAReadBuffer[FOTA_BUFFER_SIZE>>2]; |
| 151 | } FOTA_DATA; |
| 152 | |
| 153 | #endif /* !defined(_NAND_FLASH_BOOTING_) */ |
| 154 | |
| 155 | typedef struct { |
| 156 | kal_uint32 UpdateFlag; |
| 157 | kal_uint32 StartAddr; |
| 158 | kal_uint32 ImageLen; |
| 159 | } FUE_FLAG; |
| 160 | |
| 161 | typedef struct { |
| 162 | kal_char PlatformID[128]; |
| 163 | kal_uint32 FATBeginAddr; |
| 164 | kal_uint32 FATLength; |
| 165 | kal_uint32 ImageLength; |
| 166 | kal_uint32 ImageCheckSum; |
| 167 | kal_uint32 StartAddr; |
| 168 | kal_uint32 HeaderCheckSum; |
| 169 | } CompressImageHeader; |
| 170 | |
| 171 | |
| 172 | typedef enum { |
| 173 | FOTA_UPDATE_SUCCEEDED, |
| 174 | FOTA_UPDATE_FAILED, |
| 175 | FOTA_UPDATE_NONE, |
| 176 | FOTA_UPDATE_END |
| 177 | } FOTA_update_result; |
| 178 | |
| 179 | /******************************************* |
| 180 | * Function and Variable Definition |
| 181 | ********************************************/ |
| 182 | |
| 183 | /* --------------------------------------------------------------------------------- |
| 184 | FUNCTION |
| 185 | FOTA_Initialize |
| 186 | DESCRIPTION |
| 187 | FOTA Initialization API |
| 188 | 1. Initialize data structure and progress initial step |
| 189 | 2. Register customized authentication function or encryption function |
| 190 | PARAMETER |
| 191 | NULL |
| 192 | RETURN |
| 193 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 194 | < 0: means fail |
| 195 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 196 | --------------------------------------------------------------------------------- */ |
| 197 | extern kal_int32 FOTA_Initialize(void); |
| 198 | |
| 199 | /* --------------------------------------------------------------------------------- |
| 200 | FUNCTION |
| 201 | FOTA_WriteData |
| 202 | DESCRIPTION |
| 203 | FOTA write data API |
| 204 | 1. This function is used to write data to spare image pool |
| 205 | 2. This API only allow sequentially writing mechanism |
| 206 | 3. Authentication mechanism is executed during writing |
| 207 | PARAMETER |
| 208 | Length: the length of writing (Unit: Bytes) |
| 209 | Buffer: the start address of buffer |
| 210 | RETURN |
| 211 | 0: means pass write success (ERROR_FOTA_SUCCESS) |
| 212 | < 0: writing action is fail |
| 213 | ERROR_FOTA_AUTH_ROMINFO: authentication fail, can't find rom info |
| 214 | ERROR_FOTA_AUTH_FATBEGIN: authentication fail, fat begin address is different |
| 215 | ERROR_FOTA_AUTH_FATLEN: authentication fail, fat length is different |
| 216 | ERROR_FOTA_AUTH_HCHECKSUM: authentication fail, header checksum fail |
| 217 | ERROR_FOTA_AUTH_ID: authentication fail, platform id is different |
| 218 | ERROR_FOTA_AUTH_VERSION: authentication fail, downgrade is not allowed |
| 219 | ERROR_FOTA_AUTH_IMAGELEN: authentication fail, image length too large |
| 220 | ERROR_FOTA_AUTH_FAIL: authentication fail before |
| 221 | ERROR_FOTA_OVERRANGE: write over the spare image pool range |
| 222 | ERROR_FOTA_NOT_INITIALIZED: not call FOTA_Initialize before |
| 223 | --------------------------------------------------------------------------------- */ |
| 224 | extern kal_int32 FOTA_WriteData(kal_uint32 Length, void* Buffer); |
| 225 | |
| 226 | /* --------------------------------------------------------------------------------- |
| 227 | FUNCTION |
| 228 | FOTA_ReadData |
| 229 | DESCRIPTION |
| 230 | FOTA read data API |
| 231 | 1. This function is used to read data from spare image pool |
| 232 | 2. This API only support sequentially read operation, i.e. from low address to high address |
| 233 | PARAMETER |
| 234 | Length: the length of writing (Unit: Bytes) |
| 235 | Buffer: the start address of buffer |
| 236 | RETURN |
| 237 | 0: means pass write success (ERROR_FOTA_SUCCESS) |
| 238 | < 0: writing action is fail |
| 239 | ERROR_FOTA_AUTH_ROMINFO: authentication fail, can't find rom info |
| 240 | ERROR_FOTA_AUTH_FATBEGIN: authentication fail, fat begin address is different |
| 241 | ERROR_FOTA_AUTH_FATLEN: authentication fail, fat length is different |
| 242 | ERROR_FOTA_AUTH_HCHECKSUM: authentication fail, header checksum fail |
| 243 | ERROR_FOTA_AUTH_ID: authentication fail, platform id is different |
| 244 | ERROR_FOTA_AUTH_VERSION: authentication fail, downgrade is not allowed |
| 245 | ERROR_FOTA_AUTH_IMAGELEN: authentication fail, image length too large |
| 246 | ERROR_FOTA_AUTH_FAIL: authentication fail before |
| 247 | ERROR_FOTA_OVERRANGE: write over the spare image pool range |
| 248 | ERROR_FOTA_NOT_INITIALIZED: not call FOTA_Initialize before |
| 249 | --------------------------------------------------------------------------------- */ |
| 250 | extern kal_int32 FOTA_ReadData(kal_uint32 Length, void* Buffer); |
| 251 | |
| 252 | /* --------------------------------------------------------------------------------- |
| 253 | FUNCTION |
| 254 | FOTA_Get_DownloadedPackageSize |
| 255 | DESCRIPTION |
| 256 | return currently downloaded package size |
| 257 | PARAMETER |
| 258 | NULL |
| 259 | RETURN |
| 260 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 261 | < 0: means fail |
| 262 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 263 | --------------------------------------------------------------------------------- */ |
| 264 | kal_int32 FOTA_Get_DownloadedPackageSize(kal_uint32 *curr_size); |
| 265 | |
| 266 | /* --------------------------------------------------------------------------------- |
| 267 | FUNCTION |
| 268 | FOTA_ClearPackageReservoir |
| 269 | DESCRIPTION |
| 270 | clear downloaded update package |
| 271 | PARAMETER |
| 272 | NULL |
| 273 | RETURN |
| 274 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 275 | < 0: means fail |
| 276 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 277 | --------------------------------------------------------------------------------- */ |
| 278 | kal_int32 FOTA_ClearPackageReservoir(void); |
| 279 | |
| 280 | /* --------------------------------------------------------------------------------- |
| 281 | FUNCTION |
| 282 | FOTA_Get_AvailablePackageSpace |
| 283 | DESCRIPTION |
| 284 | return currently downloaded package size |
| 285 | PARAMETER |
| 286 | NULL |
| 287 | RETURN |
| 288 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 289 | < 0: means fail |
| 290 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 291 | --------------------------------------------------------------------------------- */ |
| 292 | kal_int32 FOTA_Get_AvailablePackageSpace(kal_uint32 *avail_size); |
| 293 | |
| 294 | /* --------------------------------------------------------------------------------- |
| 295 | FUNCTION |
| 296 | FOTA_Get_TotalPackageSpace |
| 297 | DESCRIPTION |
| 298 | return currently downloaded package size |
| 299 | PARAMETER |
| 300 | NULL |
| 301 | RETURN |
| 302 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 303 | < 0: means fail |
| 304 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 305 | --------------------------------------------------------------------------------- */ |
| 306 | kal_int32 FOTA_Get_TotalPackageSpace(kal_uint32 *avail_size); |
| 307 | |
| 308 | /* --------------------------------------------------------------------------------- |
| 309 | FUNCTION |
| 310 | FOTA_WriteUpdateRecord |
| 311 | DESCRIPTION |
| 312 | FOTA update state information write API |
| 313 | download client and update agent use this information to communicate with each other |
| 314 | PARAMETER |
| 315 | NULL |
| 316 | RETURN |
| 317 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 318 | < 0: means fail |
| 319 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 320 | --------------------------------------------------------------------------------- */ |
| 321 | extern kal_int32 FOTA_WriteUpdateRecord(FOTA_Custom_Update_Info* record); |
| 322 | |
| 323 | /* --------------------------------------------------------------------------------- |
| 324 | FUNCTION |
| 325 | FOTA_ReadUpdateRecord |
| 326 | DESCRIPTION |
| 327 | FOTA update state information read API |
| 328 | download client and update agent use this information to communicate with each other |
| 329 | PARAMETER |
| 330 | NULL |
| 331 | RETURN |
| 332 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 333 | < 0: means fail |
| 334 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 335 | --------------------------------------------------------------------------------- */ |
| 336 | extern kal_int32 FOTA_ReadUpdateRecord(FOTA_Custom_Update_Info* record); |
| 337 | |
| 338 | /* --------------------------------------------------------------------------------- |
| 339 | FUNCTION |
| 340 | FOTA_Finalize |
| 341 | DESCRIPTION |
| 342 | FOTA finalization API |
| 343 | 1. compare calculated checksum with image checksum in the header after |
| 344 | whole image is written |
| 345 | 2. mark the status to UPDATE_NEEDED |
| 346 | PARAMETER |
| 347 | void |
| 348 | RETURN |
| 349 | 0: means pass error check step (ERROR_FOTA_SUCCESS) |
| 350 | < 0: means fail |
| 351 | ERROR_FOTA_AUTH_FAIL: authentication fail, final step is not allowed |
| 352 | ERROR_FOTA_IMAGE_CHECKSUM: image checksum error |
| 353 | --------------------------------------------------------------------------------- */ |
| 354 | extern kal_int32 FOTA_Finalize(void); |
| 355 | |
| 356 | /* --------------------------------------------------------------------------------- |
| 357 | FUNCTION |
| 358 | FOTA_FOTA_Reg_Auth |
| 359 | DESCRIPTION |
| 360 | FOTA register function of authentication |
| 361 | register the authentication function if needed |
| 362 | PARAMETER |
| 363 | Auth: the call back decrypt function which want to register |
| 364 | RETURN |
| 365 | NULL |
| 366 | --------------------------------------------------------------------------------- */ |
| 367 | extern void FOTA_Reg_Auth(CALLBACK_Auth_FUNC Auth); |
| 368 | |
| 369 | /* --------------------------------------------------------------------------------- |
| 370 | FUNCTION |
| 371 | FOTA_Reg_Decrypt |
| 372 | DESCRIPTION |
| 373 | FOTA register function of decryption, only allow symmetric encryption algorithm |
| 374 | register the decryption function if needed |
| 375 | PARAMETER |
| 376 | Decrypt: the call back decrypt function which want to register |
| 377 | RETURN |
| 378 | NULL |
| 379 | --------------------------------------------------------------------------------- */ |
| 380 | extern void FOTA_Reg_Decrypt(CALLBACK_Decrypt_FUNC Decrypt); |
| 381 | |
| 382 | /* --------------------------------------------------------------------------------- |
| 383 | FUNCTION |
| 384 | FOTA_InitializeUpdateRecord |
| 385 | DESCRIPTION |
| 386 | create an update record block or find out the existing update record block |
| 387 | PARAMETER |
| 388 | NULL |
| 389 | RETURN |
| 390 | 0: means pass initialization step (ERROR_FOTA_SUCCESS) |
| 391 | < 0: means fail |
| 392 | ERROR_FOTA_CUSTOMIZATION: wrong customization |
| 393 | --------------------------------------------------------------------------------- */ |
| 394 | kal_int32 FOTA_InitializeUpdateRecord(void); |
| 395 | |
| 396 | /* --------------------------------------------------------------------------------- |
| 397 | FUNCTION |
| 398 | FOTA_Inform_Update_State |
| 399 | DESCRIPTION |
| 400 | Query the status of triggered update process |
| 401 | PARAMETER |
| 402 | NONE |
| 403 | RETURN |
| 404 | NULL |
| 405 | --------------------------------------------------------------------------------- */ |
| 406 | FOTA_update_result FOTA_Inform_Update_State(void); |
| 407 | |
| 408 | /* --------------------------------------------------------------------------------- |
| 409 | FUNCTION |
| 410 | FOTA_Start_Download_State |
| 411 | DESCRIPTION |
| 412 | Download client use this function to query the result of update process |
| 413 | PARAMETER |
| 414 | NULL |
| 415 | RETURN |
| 416 | --------------------------------------------------------------------------------- */ |
| 417 | kal_int32 FOTA_Start_Download_State(void); |
| 418 | |
| 419 | /* --------------------------------------------------------------------------------- |
| 420 | FUNCTION |
| 421 | FOTA_Start_Update_State |
| 422 | DESCRIPTION |
| 423 | Download client use this function to query the result of update process |
| 424 | PARAMETER |
| 425 | NULL |
| 426 | RETURN |
| 427 | --------------------------------------------------------------------------------- */ |
| 428 | kal_int32 FOTA_Start_Update_State(void); |
| 429 | |
| 430 | extern FOTA_DATA FOTAData; |
| 431 | |
| 432 | #endif //__FOTA_H__ |