blob: 564b4a1a84f224966425a3dd162491246502f15a [file] [log] [blame]
yu.dongc33b3072024-08-21 23:14:49 -07001/*****************************************************************************
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
114typedef kal_int32 (*CALLBACK_Auth_FUNC)(void* Header);
115typedef kal_int32 (*CALLBACK_Decrypt_FUNC)(void* EncryptBuffer);
116
117//#if !defined(_NAND_FLASH_BOOTING_)
118#if !defined(__FOTA_DM__)
119
120typedef 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
142typedef 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
155typedef struct {
156 kal_uint32 UpdateFlag;
157 kal_uint32 StartAddr;
158 kal_uint32 ImageLen;
159} FUE_FLAG;
160
161typedef 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
172typedef 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/* ---------------------------------------------------------------------------------
184FUNCTION
185 FOTA_Initialize
186DESCRIPTION
187 FOTA Initialization API
188 1. Initialize data structure and progress initial step
189 2. Register customized authentication function or encryption function
190PARAMETER
191 NULL
192RETURN
193 0: means pass initialization step (ERROR_FOTA_SUCCESS)
194 < 0: means fail
195 ERROR_FOTA_CUSTOMIZATION: wrong customization
196--------------------------------------------------------------------------------- */
197extern kal_int32 FOTA_Initialize(void);
198
199/* ---------------------------------------------------------------------------------
200FUNCTION
201 FOTA_WriteData
202DESCRIPTION
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
207PARAMETER
208 Length: the length of writing (Unit: Bytes)
209 Buffer: the start address of buffer
210RETURN
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--------------------------------------------------------------------------------- */
224extern kal_int32 FOTA_WriteData(kal_uint32 Length, void* Buffer);
225
226/* ---------------------------------------------------------------------------------
227FUNCTION
228 FOTA_ReadData
229DESCRIPTION
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
233PARAMETER
234 Length: the length of writing (Unit: Bytes)
235 Buffer: the start address of buffer
236RETURN
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--------------------------------------------------------------------------------- */
250extern kal_int32 FOTA_ReadData(kal_uint32 Length, void* Buffer);
251
252/* ---------------------------------------------------------------------------------
253FUNCTION
254 FOTA_Get_DownloadedPackageSize
255DESCRIPTION
256 return currently downloaded package size
257PARAMETER
258 NULL
259RETURN
260 0: means pass initialization step (ERROR_FOTA_SUCCESS)
261 < 0: means fail
262 ERROR_FOTA_CUSTOMIZATION: wrong customization
263--------------------------------------------------------------------------------- */
264kal_int32 FOTA_Get_DownloadedPackageSize(kal_uint32 *curr_size);
265
266/* ---------------------------------------------------------------------------------
267FUNCTION
268 FOTA_ClearPackageReservoir
269DESCRIPTION
270 clear downloaded update package
271PARAMETER
272 NULL
273RETURN
274 0: means pass initialization step (ERROR_FOTA_SUCCESS)
275 < 0: means fail
276 ERROR_FOTA_CUSTOMIZATION: wrong customization
277--------------------------------------------------------------------------------- */
278kal_int32 FOTA_ClearPackageReservoir(void);
279
280/* ---------------------------------------------------------------------------------
281FUNCTION
282 FOTA_Get_AvailablePackageSpace
283DESCRIPTION
284 return currently downloaded package size
285PARAMETER
286 NULL
287RETURN
288 0: means pass initialization step (ERROR_FOTA_SUCCESS)
289 < 0: means fail
290 ERROR_FOTA_CUSTOMIZATION: wrong customization
291--------------------------------------------------------------------------------- */
292kal_int32 FOTA_Get_AvailablePackageSpace(kal_uint32 *avail_size);
293
294/* ---------------------------------------------------------------------------------
295FUNCTION
296 FOTA_Get_TotalPackageSpace
297DESCRIPTION
298 return currently downloaded package size
299PARAMETER
300 NULL
301RETURN
302 0: means pass initialization step (ERROR_FOTA_SUCCESS)
303 < 0: means fail
304 ERROR_FOTA_CUSTOMIZATION: wrong customization
305--------------------------------------------------------------------------------- */
306kal_int32 FOTA_Get_TotalPackageSpace(kal_uint32 *avail_size);
307
308/* ---------------------------------------------------------------------------------
309FUNCTION
310 FOTA_WriteUpdateRecord
311DESCRIPTION
312 FOTA update state information write API
313 download client and update agent use this information to communicate with each other
314PARAMETER
315 NULL
316RETURN
317 0: means pass initialization step (ERROR_FOTA_SUCCESS)
318 < 0: means fail
319 ERROR_FOTA_CUSTOMIZATION: wrong customization
320--------------------------------------------------------------------------------- */
321extern kal_int32 FOTA_WriteUpdateRecord(FOTA_Custom_Update_Info* record);
322
323/* ---------------------------------------------------------------------------------
324FUNCTION
325 FOTA_ReadUpdateRecord
326DESCRIPTION
327 FOTA update state information read API
328 download client and update agent use this information to communicate with each other
329PARAMETER
330 NULL
331RETURN
332 0: means pass initialization step (ERROR_FOTA_SUCCESS)
333 < 0: means fail
334 ERROR_FOTA_CUSTOMIZATION: wrong customization
335--------------------------------------------------------------------------------- */
336extern kal_int32 FOTA_ReadUpdateRecord(FOTA_Custom_Update_Info* record);
337
338/* ---------------------------------------------------------------------------------
339FUNCTION
340 FOTA_Finalize
341DESCRIPTION
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
346PARAMETER
347 void
348RETURN
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--------------------------------------------------------------------------------- */
354extern kal_int32 FOTA_Finalize(void);
355
356/* ---------------------------------------------------------------------------------
357FUNCTION
358 FOTA_FOTA_Reg_Auth
359DESCRIPTION
360 FOTA register function of authentication
361 register the authentication function if needed
362PARAMETER
363 Auth: the call back decrypt function which want to register
364RETURN
365 NULL
366--------------------------------------------------------------------------------- */
367extern void FOTA_Reg_Auth(CALLBACK_Auth_FUNC Auth);
368
369/* ---------------------------------------------------------------------------------
370FUNCTION
371 FOTA_Reg_Decrypt
372DESCRIPTION
373 FOTA register function of decryption, only allow symmetric encryption algorithm
374 register the decryption function if needed
375PARAMETER
376 Decrypt: the call back decrypt function which want to register
377RETURN
378 NULL
379--------------------------------------------------------------------------------- */
380extern void FOTA_Reg_Decrypt(CALLBACK_Decrypt_FUNC Decrypt);
381
382/* ---------------------------------------------------------------------------------
383FUNCTION
384 FOTA_InitializeUpdateRecord
385DESCRIPTION
386 create an update record block or find out the existing update record block
387PARAMETER
388 NULL
389RETURN
390 0: means pass initialization step (ERROR_FOTA_SUCCESS)
391 < 0: means fail
392 ERROR_FOTA_CUSTOMIZATION: wrong customization
393--------------------------------------------------------------------------------- */
394kal_int32 FOTA_InitializeUpdateRecord(void);
395
396/* ---------------------------------------------------------------------------------
397FUNCTION
398 FOTA_Inform_Update_State
399DESCRIPTION
400 Query the status of triggered update process
401PARAMETER
402 NONE
403RETURN
404 NULL
405--------------------------------------------------------------------------------- */
406FOTA_update_result FOTA_Inform_Update_State(void);
407
408/* ---------------------------------------------------------------------------------
409FUNCTION
410 FOTA_Start_Download_State
411DESCRIPTION
412 Download client use this function to query the result of update process
413PARAMETER
414 NULL
415RETURN
416--------------------------------------------------------------------------------- */
417kal_int32 FOTA_Start_Download_State(void);
418
419/* ---------------------------------------------------------------------------------
420FUNCTION
421 FOTA_Start_Update_State
422DESCRIPTION
423 Download client use this function to query the result of update process
424PARAMETER
425 NULL
426RETURN
427--------------------------------------------------------------------------------- */
428kal_int32 FOTA_Start_Update_State(void);
429
430extern FOTA_DATA FOTAData;
431
432#endif //__FOTA_H__