1/*
2 * @file hi_flash.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/** @defgroup iot_flash  Flash
19 *  @ingroup drivers
20 */
21#ifndef __HI_FLASH_H__
22#define __HI_FLASH_H__
23
24#include <hi_types.h>
25#include <hi_flash_base.h>
26/**
27* @ingroup  iot_flash
28* @brief  Reads the flash data to the specified cache. CNcomment:读出Flash数据到指定缓存区域。CNend
29*
30* @par 描述:
31*           Reads the flash data to the specified cache. CNcomment:读出Flash数据到指定缓存区域。CNend
32*
33* @attention None
34* @param  flash_offset      [IN] type #const hi_u32，Offset of the flash address.CNcomment:指定的Flash地址偏移。CNend
35* @param  size              [IN] type #const hi_u32，Read length (unit: byte).
36CNcomment:指定读取的长度（单位：byte）。CNend
37* @param  ram_data          [OUT] type #hi_u8*，Destination cache address.CNcomment:目的缓存地址。CNend
38*
39* @retval #HI_ERR_SUCCESS  Success.
40* @retval #Other           Failure. For details, see hi_errno.h.
41* @par 依赖:
42*            @li hi_flash.h：FLASH driver APIs.CNcomment:该接口声明所在的头文件。CNend
43* @see  None
44*/
45hi_u32 hi_flash_read(const hi_u32 flash_offset, const hi_u32 size, hi_u8 *ram_data);
46
47/**
48* @ingroup  iot_flash
49* @brief  Writes data to the specified flash partition.CNcomment:把数据写入指定的Flash区。CNend
50*
51* @par 描述:
52*           Writes data to the specified flash partition.CNcomment:把数据写入指定的Flash区域。CNend
53*
54* @attention
55*           @li Restriction protection for the relative address of the flash memory.
56CNcomment:Flash相对地址的限制保护。CNend
57*           @li The number of flash erase times must comply with the device data sheet.
58CNcomment:Flash擦写次数限制。CNend
59*           @li Determine whether to erase the flash before the write based on the actual control scenario.
60CNcomment:根据用户实际控制场景决定是否先擦后写。CNend
61* @param  flash_offset    [IN] type #const hi_u32，Offset address for writing data to the flash memory.
62CNcomment:指定写入Flash偏移地址。CNend
63* @param  size            [IN] type #hi_u32，Length of the data to be written (unit: byte).
64CNcomment:需要写入的长度（单位：byte）。CNend
65* @param  ram_data        [IN] type #const hi_u8*，Cache address of the data to be written.
66CNcomment:需要写入的数据的缓存地址。CNend
67* @param  do_erase        [IN] type #hi_bool，HI_FALSE: Write data to the flash memory directly.
68*                                             HI_TRUE:  Erase the sector space before write.
69*                         The user data is written to the user operation space and the historical
70*                         data is written back to other spaces.CNcomment:表示是否自动擦除并覆盖写入。
71*                         @li HI_TRUE：本接口中先擦后写。
72*                         @li HI_FALSE：用户已经擦除本接口，可直接写入。CNend
73*
74* @retval #HI_ERR_SUCCESS  Success.
75* @retval #Other           Failure. For details, see hi_errno.h.
76* @par 依赖:
77*            @li hi_flash.h：FLASH driver APIs.CNcomment:该接口声明所在的头文件。CNend
78* @see  None
79*/
80hi_u32 hi_flash_write(const hi_u32 flash_offset, hi_u32 size, const hi_u8 *ram_data, hi_bool do_erase);
81
82/**
83* @ingroup  iot_flash
84* @brief  Erases the data in the specified flash partition.CNcomment:把指定的Flash区域数据擦除。CNend
85*
86* @par 描述:
87*           Erases the data in the specified flash partition.CNcomment:把指定的Flash区域数据擦除。CNend
88*
89* @attention
90*           @li Restriction protection for the relative address of the flash memory.
91CNcomment:Flash相对地址的限制保护。CNend
92*           @li The number of flash erase times must comply with the device data sheet.
93CNcomment:Flash擦写次数限制。CNend
94*
95* @param  flash_offset    [IN] type #const hi_u32，Address offset of the flash memory to be erased.
96CNcomment:指定要擦除Flash的地址偏移。CNend
97* @param  size            [IN] type #const hi_u32，Length of the data to be erased (unit: byte).
98*                         The value must be a multiple of 4 KB.
99CNcomment:需要擦除的长度（单位：byte），必须是4K的倍数。CNend
100*
101* @retval #HI_ERR_SUCCESS  Success.
102* @retval #Other           Failure. For details, see hi_errno.h.
103* @par 依赖:
104*            @li hi_flash.h：FLASH driver APIs.CNcomment:该接口声明所在的头文件。CNend
105* @see  None
106*/
107hi_u32 hi_flash_erase(const hi_u32 flash_offset, const hi_u32 size);
108
109/**
110* @ingroup  iot_flash
111* @brief   Initializes the flash device. CNcomment:初始化Flash设备。CNend
112*
113* @par 描述:
114*           Initializes the flash device. CNcomment:初始化Flash设备。CNend
115*
116* @attention Initialize the flash module during system boot.
117CNcomment:Flash模块初始化，一般在系统启动时调用。CNend
118* @param  None
119*
120* @retval #HI_ERR_SUCCESS  Success.
121* @retval #Other           Failure. For details, see hi_errno.h.
122* @par 依赖:
123*            @li hi_flash.h：FLASH driver APIs.CNcomment:该接口声明所在的头文件。CNend
124* @see  None
125*/
126hi_u32 hi_flash_init(hi_void);
127
128/**
129* @ingroup  iot_flash
130* @brief  Deinitializes the flash device.CNcomment:去初始化Flash设备。CNend
131*
132* @par 描述:
133*           Deinitializes the flash device.CNcomment:去初始化Flash设备。CNend
134*
135* @attention None
136* @param  None
137*
138* @retval #HI_ERR_SUCCESS  Success.
139* @retval #Other           Failure. For details, see hi_errno.h.
140* @par 依赖:
141*            @li hi_flash.h：FLASH driver APIs.CNcomment:该接口声明所在的头文件。CNend
142* @see  None
143*/
144hi_u32 hi_flash_deinit(hi_void);
145/**
146* @ingroup  iot_flash
147* @brief  Sets or reads flash information.CNcomment:获取Flash信息。CNend
148*
149* @par 描述:
150*          Sets or reads flash information.CNcomment:获取Flash信息。CNend
151*
152* @attention None
153* @param  cmd             [IN]     type #hi_u16，Command ID, currently supports HI_FLASH_CMD_GET_INFO and
154*                         HI_FLASHI_FLASH_CMD_IS_BUSY.
155CNcomment:命令ID，当前支持HI_FLASH_CMD_GET_INFO 和 HI_FLASH_CMD_IS_BUSY。CNend
156* @param  data            [IN/OUT] type #hi_void*, Information set or obtained. cmd is HI_FLASH_CMD_GET_INFO, data is
157*                         a pointer of hi_flash_info struct; cmd is HI_FLASH_CMD_IS_BUSY, data is a pointer of type
158*                         hi_bool.CNcomment:数据信息，cmd参数为HI_FLASH_CMD_GET_INFO，data为hi_flash_info结构指针；
159*                         cmd为HI_FLASH_CMD_IS_BUSY，data为hi_bool类型指针。CNend
160*
161* @retval #HI_ERR_SUCCESS  Success.
162* @retval #Other           Failure. For details, see hi_errno.h.
163* @par 依赖:
164*            @li hi_flash.h：FLASH driver APIs.CNcomment:该接口声明所在的头文件。CNend
165* @see  None
166*/
167hi_u32 hi_flash_ioctl(HI_IN hi_u16 cmd, HI_INOUT hi_void *data);
168
169#endif
170
171