gr55xx_nvds.h
Go to the documentation of this file.
1 /**
2 ******************************************************************************
3 *
4 * @file gr55xx_nvds.h
5 *
6 * @brief NVDS API
7 *
8 ******************************************************************************
9 * @attention
10 #####Copyright (c) 2019 GOODIX
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15 * Redistributions of source code must retain the above copyright
16 notice, this list of conditions and the following disclaimer.
17 * Redistributions in binary form must reproduce the above copyright
18 notice, this list of conditions and the following disclaimer in the
19 documentation and/or other materials provided with the distribution.
20 * Neither the name of GOODIX nor the names of its contributors may be used
21 to endorse or promote products derived from this software without
22 specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35 *****************************************************************************************
36 */
37
38 /**
39 * @addtogroup SYSTEM
40 * @{
41 */
42 /**
43 @addtogroup NVDS Non-Volatile Data Storage
44 @{
45 @brief Definitions and prototypes for the NVDS interface.
46 */
47
48 #ifndef __GR55XX_NVDS_H__
49 #define __GR55XX_NVDS_H__
50
51 #include <stdint.h>
52 #include <stdbool.h>
53
54 /** @addtogroup NVDS_DEFINES Defines
55 * @{ */
56 #define NV_TAGCAT_APP 0x4000 /**< NVDS tag mask for user application. */
57
58 /**@brief Get NVDS tag for user application.
59 * The values of Tag 0x0000 and 0xFFFF are invalid. idx should not be used
60 * as the parameter of NVDS APIs directly. The range of idx is 0x0001~0x3FFF.
61 */
62 #define NV_TAG_APP(idx) (NV_TAGCAT_APP | ((idx) & 0x3FFF))
63 /** @} */
64
65 /**@addtogroup NVDS_ENUMERATIONS Enumerations
66 * @{ */
67 /**@brief NVDS Returned Status. */
68 enum NVDS_STATUS
69 {
70 NVDS_SUCCESS, /**< NVDS succeeds. */
71 NVDS_FAIL, /**< NVDS failed. */
72 NVDS_TAG_NOT_EXISTED, /**< NVDS tag does not exist. */
73 NVDS_SPACE_NOT_ENOUGH, /**< NVDS space is not enough. */
74 NVDS_LENGTH_OUT_OF_RANGE, /**< NVDS length out of range. */
75 NVDS_INVALID_PARA, /**< NVDS invalid params. */
76 NVDS_INVALID_START_ADDR, /**< NVDS invalid start address. */
77 NVDS_INVALID_SECTORS, /**< NVDS invalid sector. */
78 NVDS_COMPACT_FAILED, /**< NVDS failed to compact sectors. */
79 NVDS_STORAGE_ACCESS_FAILED , /**< NVDS failed to access storage. */
80 NVDS_GC_COMPLETE, /**< NVDS garbage collection complete. */
81 NVDS_NOT_INIT, /**< NVDS not initialize. */
82 NVDS_POINTER_NULL /**< NVDS or driver function repalce error: NULL. */
83 };
84 /** @} */
85
86 /**@addtogroup NVDS_STRUCTURES Structures
87 * @{ */
88 /**@brief NVDS Item tag. */
89 typedef uint16_t NvdsTag_t;
90 /** @} */
91
92 /** @addtogroup NVDS_FUNCTIONS Functions
93 * @{ */
94 /**
95 ****************************************************************************************
96 * @brief Initialize the sectors for NVDS.
97 *
98 * @note NVDS locates in the last sector of Flash.
99 *
100 * @param[in] start_addr: Start address of NVDS area. If the value equals zero,
101 NVDS area will locate in the last sector(s) in flash
102 memory. If the value does not equal zero, it must be
103 sector-aligned.
104 * @param[in] sectors: The number of sectors.
105 *
106 * @return ::NVDS_SUCCESS if successful.
107 * @return error code in ::NVDS_STATUS if not successful.
108 ****************************************************************************************
109 */
110 uint8_t nvds_init(uint32_t start_addr, uint8_t sectors);
111
112 /** @addtogroup NVDS_FUNCTIONS Functions
113 * @{ */
114 /**
115 ****************************************************************************************
116 * @brief De-initialize the sectors for NVDS.
117 *
118 * @note nvds_deinit will erase the flash sectors.
119 *
120 * @param[in] start_addr: Start address of NVDS area. If the value does not equal zero,
121 it must be sector-aligned. If the value equals zero,
122 NVDS area will locate in the last sector(s) in flash memory.
123 * @param[in] sectors: The number of sectors.
124 *
125 * @return Result of nvds deinit.
126 ****************************************************************************************
127 */
128 uint8_t nvds_deinit(uint32_t start_addr, uint8_t sectors);
129
130 /**
131 ****************************************************************************************
132 * @brief Read data from NVDS.
133 *
134 * @param[in] tag: Valid NVDS item tag.
135 * @param[in,out] p_len: Pointer to the length of data.
136 * @param[out] p_buf: Data is read into the buffer.
137 *
138 * @return ::NVDS_SUCCESS if successful.
139 * @return error code in ::NVDS_STATUS if not successful.
140 ****************************************************************************************
141 */
142 uint8_t nvds_get(NvdsTag_t tag, uint16_t *p_len, uint8_t *p_buf);
143
144 /**
145 ****************************************************************************************
146 * @brief Write data to NVDS. If the tag does not exist, create one.
147 *
148 * @param[in] tag: Valid NVDS item tag.
149 * @param[in] len: Length of data to be written, the max length of data is 1024 bytes.
150 * @param[in] p_buf: Data to be written.
151 *
152 * @return ::NVDS_SUCCESS: if successful.
153 * @return error code in ::NVDS_STATUS if not successful.
154 ****************************************************************************************
155 */
156 uint8_t nvds_put(NvdsTag_t tag, uint16_t len, const uint8_t *p_buf);
157
158 /**
159 ****************************************************************************************
160 * @brief Delete a tag in NVDS
161 *
162 * @param[in] tag: The tag to be deleted.
163 *
164 * @return NVDS_SUCCESS: If the deletion is successful.
165 * @return Error code in ::NVDS_STATUS if not successful.
166 ****************************************************************************************
167 */
168 uint8_t nvds_del(NvdsTag_t tag);
169
170 /**
171 ****************************************************************************************
172 * @brief Get the length of a tag in NVDS
173 *
174 * @param[in] tag: The tag to get the length.
175 *
176 * @return length: if tag exists.
177 * @return 0: if tag does not exist.
178 ****************************************************************************************
179 */
180 uint16_t nvds_tag_length(NvdsTag_t tag);
181
182
183 /** @addtogroup LOCAL_FLASH_FUNCTIONS Local Flash Functions
184 * @{ */
185 /**@brief Flash operation API based on hal flash.*/
186 /**
187 ****************************************************************************************
188 * @brief Erase flash chip.
189 *
190 * @return true if successful.
191 * @return false if not successful.
192 ****************************************************************************************
193 */
194 bool local_hal_flash_erase_chip(void);
195
196 /**
197 ****************************************************************************************
198 * @brief Erase flash region.
199 *
200 * @note All sectors that have address in range of [addr, addr+len]
201 * will be erased. If addr is not sector aligned, preceding data
202 * on the sector that addr belongs to will also be erased.
203 * If (addr + size) is not sector aligned, the whole sector
204 * will also be erased.
205 *
206 * @param[in] addr start address in flash to write data to.
207 * @param[in] size number of bytes to write.
208 *
209 * @return true if successful.
210 * @return false if not successful.
211 ****************************************************************************************
212 */
213 bool local_hal_flash_erase(const uint32_t addr, const uint32_t size);
214
215 /**
216 *******************************************************************************
217 * @brief Write flash Memory.
218 *
219 * @param[in] addr start address in flash to write data to.
220 * @param[in,out] buf buffer of data to write.
221 * @param[in] size number of bytes to write.
222 *
223 * @return number of bytes written
224 *******************************************************************************
225 */
226 uint32_t local_hal_flash_write(const uint32_t addr, const uint8_t *buf, const uint32_t size);
227
228 /**
229 *******************************************************************************
230 * @brief Read flash Memory.
231 *
232 * @param[in] addr start address in flash to read data.
233 * @param[in,out] buf buffer to read data to.
234 * @param[in] size number of bytes to read.
235 *
236 * @return number of bytes read
237 *******************************************************************************
238 */
239 uint32_t local_hal_flash_read(const uint32_t addr, uint8_t *buf, const uint32_t size);
240
241 /**
242 *******************************************************************************
243 * @brief Get Flash information.
244 *
245 * @param[in,out] id Pointer to flash id.
246 * @param[in,out] size Pointer to flash size.
247 *
248 *******************************************************************************
249 */
250 void local_hal_flash_get_info(uint32_t *id, uint32_t *size);
251
252 /**
253 *******************************************************************************
254 * @brief Get encrypted and decrypted status in write-read operations.
255 *
256 * @return true Enable encrypted and decrypted.
257 * @return false Disable encrypted and decrypted.
258 *******************************************************************************
259 */
260 bool local_hal_flash_get_security(void);
261
262 /**
263 *******************************************************************************
264 * @brief Enable encrypted and decrypted in write-read operations.
265 *
266 * @param[in] enable control encrypted and decrypte.
267 *
268 *******************************************************************************
269 */
270 void local_hal_flash_set_security(bool enable);
271
272 /**
273 *******************************************************************************
274 * @brief Write flash Memory reliably.
275 *
276 * @note It's possible that the data was not written into Flash Memory
277 * successfully. This function reads the data from Flash Memory to check
278 * the reliability of programming Flash Memory.
279 * @param[in] addr start address in flash to write data to.
280 * @param[in,out] buf buffer of data to write.
281 * @param[in] size number of bytes to write.
282 *
283 * @return number of bytes written
284 *******************************************************************************
285 */
286 uint32_t local_hal_flash_write_r(const uint32_t addr, const uint8_t *buf, const uint32_t size);
287
288 /** @} */
289
290 /** @} */
291
292 #endif
293
294 /** @} */
295 /** @} */
296
nvds_del
uint8_t nvds_del(NvdsTag_t tag)
Delete a tag in NVDS.
NVDS_SPACE_NOT_ENOUGH
@ NVDS_SPACE_NOT_ENOUGH
NVDS space is not enough.
Definition: gr55xx_nvds.h:73
local_hal_flash_write
uint32_t local_hal_flash_write(const uint32_t addr, const uint8_t *buf, const uint32_t size)
Write flash Memory.
local_hal_flash_read
uint32_t local_hal_flash_read(const uint32_t addr, uint8_t *buf, const uint32_t size)
Read flash Memory.
NVDS_POINTER_NULL
@ NVDS_POINTER_NULL
NVDS or driver function repalce error: NULL.
Definition: gr55xx_nvds.h:82
NVDS_COMPACT_FAILED
@ NVDS_COMPACT_FAILED
NVDS failed to compact sectors.
Definition: gr55xx_nvds.h:78
NVDS_NOT_INIT
@ NVDS_NOT_INIT
NVDS not initialize.
Definition: gr55xx_nvds.h:81
local_hal_flash_set_security
void local_hal_flash_set_security(bool enable)
Enable encrypted and decrypted in write-read operations.
local_hal_flash_get_security
bool local_hal_flash_get_security(void)
Get encrypted and decrypted status in write-read operations.
NVDS_LENGTH_OUT_OF_RANGE
@ NVDS_LENGTH_OUT_OF_RANGE
NVDS length out of range.
Definition: gr55xx_nvds.h:74
NVDS_GC_COMPLETE
@ NVDS_GC_COMPLETE
NVDS garbage collection complete.
Definition: gr55xx_nvds.h:80
NVDS_INVALID_PARA
@ NVDS_INVALID_PARA
NVDS invalid params.
Definition: gr55xx_nvds.h:75
NVDS_STORAGE_ACCESS_FAILED
@ NVDS_STORAGE_ACCESS_FAILED
NVDS failed to access storage.
Definition: gr55xx_nvds.h:79
local_hal_flash_erase
bool local_hal_flash_erase(const uint32_t addr, const uint32_t size)
Erase flash region.
local_hal_flash_get_info
void local_hal_flash_get_info(uint32_t *id, uint32_t *size)
Get Flash information.
nvds_deinit
uint8_t nvds_deinit(uint32_t start_addr, uint8_t sectors)
De-initialize the sectors for NVDS.
NVDS_INVALID_SECTORS
@ NVDS_INVALID_SECTORS
NVDS invalid sector.
Definition: gr55xx_nvds.h:77
NVDS_FAIL
@ NVDS_FAIL
NVDS failed.
Definition: gr55xx_nvds.h:71
nvds_put
uint8_t nvds_put(NvdsTag_t tag, uint16_t len, const uint8_t *p_buf)
Write data to NVDS.
nvds_tag_length
uint16_t nvds_tag_length(NvdsTag_t tag)
Get the length of a tag in NVDS.
local_hal_flash_erase_chip
bool local_hal_flash_erase_chip(void)
Flash operation API based on hal flash.
NVDS_STATUS
NVDS_STATUS
NVDS Returned Status.
Definition: gr55xx_nvds.h:69
NVDS_SUCCESS
@ NVDS_SUCCESS
NVDS succeeds.
Definition: gr55xx_nvds.h:70
local_hal_flash_write_r
uint32_t local_hal_flash_write_r(const uint32_t addr, const uint8_t *buf, const uint32_t size)
Write flash Memory reliably.
NVDS_TAG_NOT_EXISTED
@ NVDS_TAG_NOT_EXISTED
NVDS tag does not exist.
Definition: gr55xx_nvds.h:72
nvds_init
uint8_t nvds_init(uint32_t start_addr, uint8_t sectors)
Initialize the sectors for NVDS.
nvds_get
uint8_t nvds_get(NvdsTag_t tag, uint16_t *p_len, uint8_t *p_buf)
Read data from NVDS.
NVDS_INVALID_START_ADDR
@ NVDS_INVALID_START_ADDR
NVDS invalid start address.
Definition: gr55xx_nvds.h:76
NvdsTag_t
uint16_t NvdsTag_t
NVDS Item tag.
Definition: gr55xx_nvds.h:89