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*/
74hi_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.
86CNcomment:必须在调用升级文件传输接口之后调用。CNend
87* @li Must be called before calling interface hi_upg_transmit_finish in non-power-off upgrade scenario.
88CNcomment:非断电升级场景必须在调用升级文件传输完成之前调用。CNend
89* @li Must be called before calling interface hi_upg_finish_with_cache in power-off upgrade scenario.
90CNcomment:断电升级场景必须在调用升级结束完成之前调用。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*/
102hi_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*/
121hi_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*/
136hi_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*/
152hi_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.
166CNcomment:允许在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*/
174hi_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.
189CNcomment:允许在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*/
197hi_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*/
214hi_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*/
230hi_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*/
246hi_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*/
263hi_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