gr533x_nvds.h
Go to the documentation of this file.
1 /**
2 ******************************************************************************
3 *
4 * @file gr533x_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 __GR533X_NVDS_H__
49 #define __GR533X_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 #define NV_TAG_APP(idx) (NV_TAGCAT_APP | ((idx) & 0x3FFF)) /**< Get NVDS tag for user application.
58 The values of Tag 0x0000 and 0xFFFF are invalid.
59 Idx should not be used as the parameter of NVDS APIs directly.
60 The range of idx is 0x0000~0x3FFF. */
61 /** @} */
62
63 /**@addtogroup NVDS_ENUMERATIONS Enumerations
64 * @{ */
65 /**@brief NVDS Returned Status. */
66 enum NVDS_STATUS
67 {
68 NVDS_SUCCESS, /**< NVDS succeeds. */
69 NVDS_GC_COMPLETE, /**< NVDS garbage collection complete. */
70 NVDS_FAIL, /**< NVDS failed. */
71 NVDS_NOT_INIT, /**< NVDS not initialize. */
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_POINTER_NULL /**< NVDS or driver function repalce error: NULL. */
81 };
82
83 /**@brief NVDS initialization Return error code. */
84 enum NVDS_INIT_ERR_CODE
85 {
86 NVDS_INIT_SUCCESS, /**< NVDS initialization succeeds. */
87 NVDS_INIT_MULT_SECTOR_NUM_ERR, /**< NVDS_INIT input parameter sectors is 0, when enable ENABLE_MULT_SECTOR. */
88 NVDS_INIT_SING_SECTOR_NUM_ERR, /**< NVDS_INIT input parameter sectors is not 1, when disable ENABLE_MULT_SECTOR. */
89 NVDS_INIT_START_ADDR_NO_ALIGN, /**< NVDS_INIT input parameter start addr is not 4K aligned. */
90 NVDS_INIT_AREA_SLOP_OVER, /**< NVDS_INIT input parameters cause nvds to out of range. */
91 NVDS_INIT_CHECKSUM_FAIL, /**< When nvds has been initialized and read tag, verification fail. */
92 NVDS_INIT_TAG_LEN_ERR, /**< When nvds has been initialized and read tag, the tag length is 0. */
93 NVDS_INIT_READ_TAG_NOT_COMPLETE, /**< When nvds has been initialized read tag not complate. */
94 NVDS_INIT_MGR_ERR, /**< When nvds has been initialized and read tag complate, avail size is error. */
95 };
96 /** @} */
97
98 /**@addtogroup NVDS_TYPEDEFS Type Typedefs
99 * @{ */
100 /**@brief NVDS Item tag. */
101 typedef uint16_t NvdsTag_t;
102 /** @} */
103
104
105 /**@addtogroup NVDS_STRUCTURES Enumerations
106 * @{ */
107 /**@brief NVDS drive function struct. */
108 typedef struct
109 {
110 uint32_t (*p_nvds_flash_read)(const uint32_t addr, uint8_t *buf, const uint32_t size); /**< NVDS flash read function. */
111 uint32_t (*p_nvds_flash_write_r)(const uint32_t addr, const uint8_t *buf, const uint32_t size); /**< NVDS flash write_r function. */
112 void (*p_nvds_flash_set_security)(bool enable); /**< NVDS flash security set function. */
113 bool (*p_nvds_flash_get_security)(void); /**< NVDS flash security get function. */
114 bool (*p_nvds_flash_erase)(const uint32_t addr, const uint32_t size); /**< NVDS flash erase function. */
115 void (*p_nvds_flash_get_info)(uint32_t *id, uint32_t *size); /**< NVDS flash information get function. */
116 }nvds_drv_func_t;
117
118 /**@brief NVDS function struct. */
119 typedef struct
120 {
121 uint8_t (*p_nvds_init)(uint32_t start_addr, uint8_t sectors); /**< NVDS init function */
122 uint8_t (*p_nvds_get)(uint16_t tag, uint16_t *p_len, uint8_t *p_buf); /**< NVDS get function */
123 uint8_t (*p_nvds_put)(uint16_t tag, uint16_t len, const uint8_t *p_buf); /**< NVDS put function */
124 uint8_t (*p_nvds_del)(uint16_t tag); /**< NVDS delete function */
125 uint16_t (*p_nvds_tag_length)(uint16_t tag); /**< NVDS tag length get function */
126 }nvds_func_t;
127
128 /* Mesh max number of devices supported structure*/
129 typedef struct
130 {
131 uint8_t mesh_net_key_list_num;
132 uint8_t mesh_app_key_list_num;
133 uint8_t mesh_piblic_subscr_list_num;
134 uint8_t mesh_friend_num;
135 uint8_t mesh_LPN_num;
136 }mesh_config_dev_num_t;
137 /** @} */
138
139 /** @addtogroup NVDS_FUNCTIONS Functions
140 * @{ */
141 /**
142 ****************************************************************************************
143 * @brief Initialize the sectors for NVDS.
144 *
145 * @note NVDS module will use one more sector flash for garbage collection.
146 * For example, sectors=1, NVDS area actually use 2 sector(one sector for garbage collection)
147 *
148 * @param[in] start_addr: Start address of NVDS area. If the value does not equal zero, it must be sector-aligned.
149 If the value equals zero, NVDS area will locate in the last two sector(s) in flash memory.
150 * @param[in] sectors: The number of sectors.
151 *
152 * @return Result of nvds init.
153 ****************************************************************************************
154 */
155 uint8_t nvds_init(uint32_t start_addr, uint8_t sectors);
156
157 /**
158 ****************************************************************************************
159 * @brief De-initialize the sectors for NVDS.
160 *
161 * @note nvds_deinit will erase the flash sectors.
162 *
163 * @param[in] start_addr: Start address of NVDS area. If the value does not equal zero, it must be sector-aligned.
164 If the value equals zero, NVDS area will locate in the last two sector(s) in flash memory.
165 * @param[in] sectors: The number of sectors.
166 *
167 * @return Result of nvds deinit.
168 ****************************************************************************************
169 */
170 uint8_t nvds_deinit(uint32_t start_addr, uint8_t sectors);
171
172 /**
173 ****************************************************************************************
174 * @brief Read data from NVDS.
175 *
176 * @param[in] tag: Valid NVDS item tag.
177 * @param[in,out] p_len: Pointer to the length of data.
178 * @param[out] p_buf: Data is read into the buffer.
179 *
180 * @return Result of nvds get.
181 ****************************************************************************************
182 */
183 uint8_t nvds_get(NvdsTag_t tag, uint16_t *p_len, uint8_t *p_buf);
184
185 /**
186 ****************************************************************************************
187 * @brief Write data to NVDS. If the tag does not exist, create one.
188 *
189 * @param[in] tag: Valid NVDS item tag.
190 * @param[in] len: Length of data to be written.
191 * @param[in] p_buf: Data to be written.
192 *
193 * @return Result of nvds put.
194 ****************************************************************************************
195 */
196 uint8_t nvds_put(NvdsTag_t tag, uint16_t len, const uint8_t *p_buf);
197
198 /**
199 ****************************************************************************************
200 * @brief Delete a tag in NVDS
201 *
202 * @param[in] tag: The tag to be deleted.
203 *
204 * @return Result of nvds delete.
205 ****************************************************************************************
206 */
207 uint8_t nvds_del(NvdsTag_t tag);
208
209 /**
210 ****************************************************************************************
211 * @brief Get the length of a tag in NVDS
212 *
213 * @param[in] tag: The tag to get the length.
214 *
215 * @return Length of tag data.
216 ****************************************************************************************
217 */
218 uint16_t nvds_tag_length(NvdsTag_t tag);
219
220 /**
221 ****************************************************************************************
222 * @brief Replace the drive function.
223 *
224 * @param[in] p_nvds_drv_func: Pointer to drive functions.
225 *
226 * @return Result of drive function replace.
227 ****************************************************************************************
228 */
229 uint8_t nvds_drv_func_replace(nvds_drv_func_t *p_nvds_drv_func);
230
231 /**
232 ****************************************************************************************
233 * @brief Replace the function in NVDS.
234 *
235 * @param[in] p_nvds_func: Pointer to nvds functions.
236 *
237 * @return Result nvds function replace.
238 ****************************************************************************************
239 */
240 uint8_t nvds_func_replace(nvds_func_t *p_nvds_func);
241
242 /**
243 ****************************************************************************************
244 * @brief Calculate the space reserved for system.
245 *
246 * @param[in] bond_dev_num: The number of bond device.
247 * @param[in] mesh_config_dev_num: The number of mesh config device.
248 *
249 * @return System retention size.
250 ****************************************************************************************
251 */
252 void nvds_retention_size(uint8_t bond_dev_num, mesh_config_dev_num_t mesh_config_dev_num);
253 /** @} */
254 #endif
255
256 /** @} */
257 /** @} */
258
nvds_del
uint8_t nvds_del(NvdsTag_t tag)
Delete a tag in NVDS.
NVDS_SPACE_NOT_ENOUGH
@ NVDS_SPACE_NOT_ENOUGH
Definition: gr533x_nvds.h:73
NVDS_INIT_TAG_LEN_ERR
@ NVDS_INIT_TAG_LEN_ERR
Definition: gr533x_nvds.h:92
nvds_retention_size
void nvds_retention_size(uint8_t bond_dev_num, mesh_config_dev_num_t mesh_config_dev_num)
Calculate the space reserved for system.
NVDS_POINTER_NULL
@ NVDS_POINTER_NULL
Definition: gr533x_nvds.h:80
mesh_config_dev_num_t::mesh_friend_num
uint8_t mesh_friend_num
Definition: gr533x_nvds.h:134
NVDS_INIT_AREA_SLOP_OVER
@ NVDS_INIT_AREA_SLOP_OVER
Definition: gr533x_nvds.h:90
NVDS_COMPACT_FAILED
@ NVDS_COMPACT_FAILED
Definition: gr533x_nvds.h:78
nvds_drv_func_t
NVDS drive function struct.
Definition: gr533x_nvds.h:109
mesh_config_dev_num_t::mesh_app_key_list_num
uint8_t mesh_app_key_list_num
Definition: gr533x_nvds.h:132
NVDS_NOT_INIT
@ NVDS_NOT_INIT
Definition: gr533x_nvds.h:71
NVDS_INIT_MULT_SECTOR_NUM_ERR
@ NVDS_INIT_MULT_SECTOR_NUM_ERR
Definition: gr533x_nvds.h:87
NVDS_INIT_READ_TAG_NOT_COMPLETE
@ NVDS_INIT_READ_TAG_NOT_COMPLETE
Definition: gr533x_nvds.h:93
NVDS_LENGTH_OUT_OF_RANGE
@ NVDS_LENGTH_OUT_OF_RANGE
Definition: gr533x_nvds.h:74
NVDS_GC_COMPLETE
@ NVDS_GC_COMPLETE
Definition: gr533x_nvds.h:69
nvds_drv_func_replace
uint8_t nvds_drv_func_replace(nvds_drv_func_t *p_nvds_drv_func)
Replace the drive function.
NVDS_INIT_CHECKSUM_FAIL
@ NVDS_INIT_CHECKSUM_FAIL
Definition: gr533x_nvds.h:91
NVDS_INVALID_PARA
@ NVDS_INVALID_PARA
Definition: gr533x_nvds.h:75
NVDS_STORAGE_ACCESS_FAILED
@ NVDS_STORAGE_ACCESS_FAILED
Definition: gr533x_nvds.h:79
nvds_deinit
uint8_t nvds_deinit(uint32_t start_addr, uint8_t sectors)
De-initialize the sectors for NVDS.
NVDS_INIT_START_ADDR_NO_ALIGN
@ NVDS_INIT_START_ADDR_NO_ALIGN
Definition: gr533x_nvds.h:89
NVDS_INVALID_SECTORS
@ NVDS_INVALID_SECTORS
Definition: gr533x_nvds.h:77
NVDS_FAIL
@ NVDS_FAIL
Definition: gr533x_nvds.h:70
mesh_config_dev_num_t
Definition: gr533x_nvds.h:130
NVDS_INIT_SING_SECTOR_NUM_ERR
@ NVDS_INIT_SING_SECTOR_NUM_ERR
Definition: gr533x_nvds.h:88
nvds_put
uint8_t nvds_put(NvdsTag_t tag, uint16_t len, const uint8_t *p_buf)
Write data to NVDS. If the tag does not exist, create one.
nvds_tag_length
uint16_t nvds_tag_length(NvdsTag_t tag)
Get the length of a tag in NVDS.
nvds_func_t
NVDS function struct.
Definition: gr533x_nvds.h:120
NvdsTag_t
uint16_t NvdsTag_t
NVDS Item tag.
Definition: gr533x_nvds.h:101
NVDS_INIT_ERR_CODE
NVDS_INIT_ERR_CODE
NVDS initialization Return error code.
Definition: gr533x_nvds.h:85
mesh_config_dev_num_t::mesh_piblic_subscr_list_num
uint8_t mesh_piblic_subscr_list_num
Definition: gr533x_nvds.h:133
nvds_func_replace
uint8_t nvds_func_replace(nvds_func_t *p_nvds_func)
Replace the function in NVDS.
mesh_config_dev_num_t::mesh_net_key_list_num
uint8_t mesh_net_key_list_num
Definition: gr533x_nvds.h:131
NVDS_INIT_MGR_ERR
@ NVDS_INIT_MGR_ERR
Definition: gr533x_nvds.h:94
NVDS_STATUS
NVDS_STATUS
NVDS Returned Status.
Definition: gr533x_nvds.h:67
NVDS_SUCCESS
@ NVDS_SUCCESS
Definition: gr533x_nvds.h:68
mesh_config_dev_num_t::mesh_LPN_num
uint8_t mesh_LPN_num
Definition: gr533x_nvds.h:135
NVDS_TAG_NOT_EXISTED
@ NVDS_TAG_NOT_EXISTED
Definition: gr533x_nvds.h:72
NVDS_INIT_SUCCESS
@ NVDS_INIT_SUCCESS
Definition: gr533x_nvds.h:86
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
Definition: gr533x_nvds.h:76