1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License.\n 14 * Description: NV STORAGE INTERFACE \n 15 * 16 * History: \n 17 * 2022-02-25, fix comments. \n 18 * 2018-08-08, Create file. \n 19 */ 20 21 #ifndef NV_H 22 #define NV_H 23 24 #include <stdint.h> 25 #include <stdbool.h> 26 #include "errcode.h" 27 #include "key_id.h" 28 29 #ifdef __cplusplus 30 #if __cplusplus 31 extern "C" { 32 #endif /* __cplusplus */ 33 #endif /* __cplusplus */ 34 35 /** 36 * @defgroup middleware_utils_nv_api NV 37 * @ingroup middleware_utils 38 * @{ 39 */ 40 41 /** 42 * @if Eng 43 * @brief nv storage callback. 44 * @else 45 * @brief nv存储回调函数。 46 * @endif 47 */ 48 typedef void (*nv_storage_completed_callback)(errcode_t result); 49 50 /** 51 * @if Eng 52 * @brief nv changed notify callback. 53 * @else 54 * @brief nv值更改回调函数。 55 * @endif 56 */ 57 typedef void (*nv_changed_notify_func)(uint16_t key); 58 59 /** 60 * @if Eng 61 * @brief nv key Properties. 62 * @else 63 * @brief NV属性 64 * @endif 65 */ 66 typedef struct { 67 bool permanent; /*!< @if Eng Indicates whether the key is a permanent key. 68 @else 是否为永久NV @endif */ 69 bool encrypted; /*!< @if Eng Indicates whether to store ciphertext. 70 @else 是否为密文存储 @endif */ 71 bool non_upgrade; /*!< @if Eng Indicates whether upgradeable. 72 @else 是否不可升级 @endif */ 73 uint8_t reserve; /*!< @if Eng Reserved field for the future 74 @else 保留字段 @endif */ 75 } nv_key_attr_t; 76 77 /** 78 * @if Eng 79 * @brief nv storage Status. 80 * @else 81 * @brief nv存储状态 82 * @endif 83 */ 84 typedef struct { 85 uint32_t total_space; /*!< @if Eng Total NV space of the current core 86 @else 当前核的总NV空间 @endif */ 87 uint32_t used_space; /*!< @if Eng Used NV space of the current core 88 @else 当前核已使用的NV空间 @endif */ 89 uint32_t reclaimable_space; /*!< @if Eng NV recyclable space of the current core, 90 can be reused after erasing 91 @else 当前核的NV可回收空间 @endif */ 92 uint32_t corrupted_space; /*!< @if Eng NV corrupted space of the current core, 93 It's a valid data,but the data is abnormal. 94 It can be reused after erasing 95 @else 当前核已损坏了的NV空间 @endif */ 96 uint32_t max_key_space; /*!< @if Eng Maximum single NV space that can be stored 97 @else 可存储的最大单NV项空间 @endif */ 98 } nv_store_status_t; 99 100 /** 101 * @if Eng 102 * @brief region of of key_id value. 103 * @else 104 * @brief key_id取值区域 105 * @endif 106 */ 107 typedef enum { 108 KEY_ID_REGION0, /*!< @if Eng The region 0 of value range of key_id: [0x0001,0x1000). 109 @else key_id的取值区域0：[0x0001,0x1000)。 @endif */ 110 KEY_ID_REGION1, /*!< @if Eng The region 1 of value range of key_id: [0x1000,0x2000). 111 @else key_id的取值区域1：[0x1000,0x2000)。 @endif */ 112 KEY_ID_REGION2, /*!< @if Eng The region 2 of value range of key_id: [0x2000,0x3000). 113 @else key_id的取值区域2：[0x2000,0x3000)。 @endif */ 114 KEY_ID_REGION3, /*!< @if Eng The region 3 of value range of key_id: [0x3000,0x4000). 115 @else key_id的取值区域3：[0x3000,0x4000)。 @endif */ 116 KEY_ID_REGION4, /*!< @if Eng The region 4 of value range of key_id: [0x4000,0x5000). 117 @else key_id的取值区域4：[0x4000,0x5000)。 @endif */ 118 KEY_ID_REGION5, /*!< @if Eng The region 5 of value range of key_id: [0x5000,0x6000). 119 @else key_id的取值区域5：[0x5000,0x6000)。 @endif */ 120 KEY_ID_REGION6, /*!< @if Eng The region 6 of value range of key_id: [0x6000,0x7000). 121 @else key_id的取值区域6：[0x6000,0x7000)。 @endif */ 122 KEY_ID_REGION7, /*!< @if Eng The region 7 of value range of key_id: [0x7000,0x8000). 123 @else key_id的取值区域7：[0x7000,0x8000)。 @endif */ 124 KEY_ID_REGION8, /*!< @if Eng The region 8 of value range of key_id: [0x8000,0x9000). 125 @else key_id的取值区域8：[0x8000,0x9000)。 @endif */ 126 KEY_ID_REGION9, /*!< @if Eng The region 9 of value range of key_id: [0x9000,0xA000). 127 @else key_id的取值区域9：[0x9000,0xA000)。 @endif */ 128 KEY_ID_REGION10, /*!< @if Eng The region 10 of value range of key_id: [0xA000,0xB000). 129 @else key_id的取值区域10：[0xA000,0xB000)。 @endif */ 130 KEY_ID_REGION11, /*!< @if Eng The region 11 of value range of key_id: [0xB000,0xC000). 131 @else key_id的取值区域11：[0xB000,0xC000)。 @endif */ 132 KEY_ID_REGION12, /*!< @if Eng The region 12 of value range of key_id: [0xC000,0xD000). 133 @else key_id的取值区域12：[0xC000,0xD000)。 @endif */ 134 KEY_ID_REGION13, /*!< @if Eng The region 13 of value range of key_id: [0xD000,0xE000). 135 @else key_id的取值区域13：[0xD000,0xE000)。 @endif */ 136 KEY_ID_REGION14, /*!< @if Eng The region 14 of value range of key_id: [0xE000,0xF000). 137 @else key_id的取值区域14：[0xE000,0xF000)。 @endif */ 138 KEY_ID_REGION15, /*!< @if Eng The region 15 of value range of key_id: [0xF000,0xFFFF]. 139 @else key_id的取值区域15：[0xF000,0xFFFF]。 @endif */ 140 KEY_ID_REGION_MAX_NUM, /*!< @if Eng The Number of the regions. 141 @else key_id的取值区域数量 @endif */ 142 } nv_key_id_region_t; 143 144 /** 145 * @if Eng 146 * @brief Mode selection of Restoring factory settings.The value true indicates that the data is to be restored. 147 * @else 148 * @brief 恢复出厂区域配置，true代表要恢复 149 * @endif 150 */ 151 typedef struct { 152 bool region_mode[KEY_ID_REGION_MAX_NUM]; /*!< @if Eng Recovery region flag configuration 153 @else 恢复出厂区域标志配置 @endif */ 154 } nv_restore_mode_t; 155 156 /** 157 * @if Eng 158 * @brief Backup region flag configuration.The value true indicates that the data is backed up. 159 * @else 160 * @brief 备份区域配置，true代表要备份 161 * @endif 162 */ 163 typedef struct { 164 bool region_mode[KEY_ID_REGION_MAX_NUM]; /*!< @if Eng Backup region flag configuration 165 @else 备份区域标志配置 @endif */ 166 } nv_backup_mode_t; 167 168 /** 169 * @if Eng 170 * @brief Init the nv module, it must be called before using nv function. 171 * @retval EXT_ERR_SUCCESS Success. 172 * @retval Other ERRCODE_FAIL or other error num. 173 * @par Depends: 174 * @li nv.h 175 * @else 176 * @brief 初始化nv模块，必须在使用nv函数之前调用。 177 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 178 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 179 * @par 依赖: 180 * @li nv.h 181 * @endif 182 */ 183 void uapi_nv_init(void); 184 185 /** 186 * @if Eng 187 * @brief Store a key value pair. 188 * @par Description: Writes NV data item. The default attribute is Normal and no callback function is available. 189 * @param [in] key The key ID to which the kvalue is associated. 190 * @param [in] kvalue The value to store. 191 * @param [in] kvalue_length Length of kvalue in bytes. 192 * @retval EXT_ERR_SUCCESS Success. 193 * @retval Other ERRCODE_FAIL or other error num. 194 * @par Depends: 195 * @li nv.h 196 * @else 197 * @brief 写入NV数据项 198 * @par 说明: 默认属性为Normal，没有回调函数。 199 * @param [in] key 要写入的NV项的key ID，用于索引 200 * @param [in] kvalue 指向要写入的NV项的值的指针 201 * @param [in] kvalue_length 写入数据的长度（以字节为单位） 202 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 203 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 204 * @par 依赖: 205 * @li nv.h 206 * @endif 207 */ 208 errcode_t uapi_nv_write(uint16_t key, const uint8_t *kvalue, uint16_t kvalue_length); 209 210 211 /** 212 * @if Eng 213 * @brief set a value associated with a specific key. 214 * @par Description: Write the NV data associated with a particular key. 215 * @attention The encryption attribute and permanent attribute of a key cannot be modified, 216 * and the kvalue of the permanent attribute cannot be modified. 217 * @param [in] key The key to which the kvalue is associated. 218 * @param [in] kvalue The value to store. 219 * @param [in] kvalue_length Length of kvalue in bytes. 220 * @param [in] attr Set the storage properties of the key. 221 * @param [in] func Callback function invoked after kvalue is written to the flash memory. 222 * @retval EXT_ERR_SUCCESS Success. 223 * @retval Other ERRCODE_FAIL or other error num. 224 * @par Depends: 225 * @li nv.h 226 * @else 227 * @brief 写入NV数据项，并根据业务需求配置属性及回调函数 228 * @par 说明: 写入NV数据项，并根据业务需求配置属性及回调函数 229 * @attention NV的加密属性和永久属性不能修改，永久属性的kvalue不能修改 230 * @param [in] key 要写入的NV项的key ID，用于索引 231 * @param [in] kvalue 指向要写入的NV项的值的指针 232 * @param [in] kvalue_length 写入数据的长度（以字节为单位） 233 * @param [in] attr 要配置的NV项的属性 234 * @param [in] func kvalue写入flash后调用的回调函数 235 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 236 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 237 * @par 依赖: 238 * @li nv.h 239 * @endif 240 */ 241 errcode_t uapi_nv_write_with_attr(uint16_t key, const uint8_t *kvalue, uint16_t kvalue_length, nv_key_attr_t *attr, 242 nv_storage_completed_callback func); 243 244 /** 245 * @if Eng 246 * @brief Get a value associated with a specific key. 247 * @par Description: Reads NV data. 248 * @attention By default, the key attribute value is not obtained. 249 * @param [in] key The key to which the kvalue is associated. 250 * @param [in] kvalue_max_length The maximum length, in bytes, 251 * that is allowed to be copied in the kvalue buffer if the key is found. 252 * @param [out] kvalue_length Length of kvalue in bytes. 253 * @param [out] kvalue The value to store. 254 * @retval EXT_ERR_SUCCESS Success. 255 * @retval Other ERRCODE_FAIL or other error num. 256 * @par Depends: 257 * @li nv.h 258 * @else 259 * @brief 读取指定NV数据项的值 260 * @par 说明: 读取指定NV数据项的值 261 * @attention 默认情况下，不获取NV属性值 262 * @param [in] key 要读取的NV项的key ID，用于索引 263 * @param [in] kvalue_max_length 允许存储数据的最大长度（以字节为单位） 264 * @param [out] kvalue_length 实际读取到的数据长度 265 * @param [out] kvalue 指向保存读取数据的buffer的指针 266 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 267 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 268 * @par 依赖: 269 * @li nv.h 270 * @endif 271 */ 272 errcode_t uapi_nv_read(uint16_t key, uint16_t kvalue_max_length, uint16_t *kvalue_length, uint8_t *kvalue); 273 274 /** 275 * @if Eng 276 * @brief Get a value associated with a specific key. 277 * @par Description: Reads NV data and obtains the attribute value of the key. 278 * @param [in] key The key to which the kvalue is associated. 279 * @param [in] kvalue_max_length The maximum length, in bytes, 280 * that is allowed to be copied in the kvalue buffer if the key is found. 281 * @param [out] kvalue_length Length of kvalue in bytes. 282 * @param [out] kvalue The value to store. 283 * @param [out] attr Attribute value of the key. 284 * @retval EXT_ERR_SUCCESS Success. 285 * @retval Other ERRCODE_FAIL or other error num. 286 * @par Depends: 287 * @li nv.h 288 * @else 289 * @brief 读取指定NV数据项的值，同时获取key的属性值 290 * @par 说明: 读取指定NV数据项的值，同时获取key的属性值 291 * @param [in] key 要读取的NV项的key ID，用于索引。 292 * @param [in] kvalue_max_length 允许存储数据的最大长度（以字节为单位） 293 * @param [out] kvalue_length 实际读取到的数据长度 294 * @param [out] kvalue 指向保存读取数据的buffer的指针 295 * @param [out] attr 获取到的NV项的属性 296 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 297 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 298 * @par 依赖: 299 * @li nv.h 300 * @endif 301 */ 302 errcode_t uapi_nv_read_with_attr(uint16_t key, uint16_t kvalue_max_length, uint16_t *kvalue_length, uint8_t *kvalue, 303 nv_key_attr_t *attr); 304 305 /** 306 * @if Eng 307 * @brief Get the space usage of NV storage. 308 * @par Description: Query the NV space status. 309 * @param [out] status pointer to NV status . 310 * @retval EXT_ERR_SUCCESS Success. 311 * @retval Other ERRCODE_FAIL or other error num. 312 * @par Depends: 313 * @li nv.h 314 * @else 315 * @brief 获取NV存储的空间使用情况 316 * @par 说明: 查询NV空间状态 317 * @param [out] status 指向保存NV状态数据的指针 318 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 319 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 320 * @par 依赖: 321 * @li nv.h 322 * @endif 323 */ 324 errcode_t uapi_nv_get_store_status(nv_store_status_t *status); 325 326 /** 327 * @if Eng 328 * @brief NV backup. 329 * @par Description: NV backup. 330 * @param [in] backup_mode pointer to NV backup region flag. 331 * @retval EXT_ERR_SUCCESS Success. 332 * @retval Other ERRCODE_FAIL or other error num. 333 * @par Depends: 334 * @li nv.h 335 * @else 336 * @brief 执行NV备份 337 * @par 说明: 执行NV备份 338 * @param [in] backup_mode 指向保存NV备份区域选择的指针 339 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 340 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 341 * @par 依赖: 342 * @li nv.h 343 * @endif 344 */ 345 errcode_t uapi_nv_backup(const nv_backup_mode_t *backup_mode); 346 347 /** 348 * @if Eng 349 * @brief Set NV all restore flag. 350 * @retval EXT_ERR_SUCCESS Success. 351 * @retval Other ERRCODE_FAIL or other error num. 352 * @par Depends: 353 * @li nv.h 354 * @else 355 * @brief 设置NV全量恢复标志 356 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 357 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 358 * @par 依赖: 359 * @li nv.h 360 * @endif 361 */ 362 errcode_t uapi_nv_set_restore_mode_all(void); 363 364 /** 365 * @if Eng 366 * @brief Set NV partitial restore flag. 367 * @par Description: Set NV partitial restore flag. 368 * @param [in] restore_mode pointer to NV restore region flag. 369 * @retval EXT_ERR_SUCCESS Success. 370 * @retval Other ERRCODE_FAIL or other error num. 371 * @par Depends: 372 * @li nv.h 373 * @else 374 * @brief 设置NV部分恢复标志 375 * @par 说明: 设置NV部分恢复标志 376 * @param [in] restore_mode 指向保存NV各区域是否恢复标志的指针 377 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 378 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 379 * @par 依赖: 380 * @li nv.h 381 * @endif 382 */ 383 errcode_t uapi_nv_set_restore_mode_partitial(const nv_restore_mode_t *restore_mode); 384 385 386 /** 387 * @if Eng 388 * @brief Ensure NV data from ram flush to flash. 389 * @par Description: Only when nv open the CONFIG NV SUPPORT ASYNCHRONOUS STORE valid. 390 * @retval EXT_ERR_SUCCESS Success. 391 * @retval Other ERRCODE_FAIL or other error num. 392 * @par Depends: 393 * @li nv.h 394 * @else 395 * @brief 确保NV数据从Ram上同步到Falsh 396 * @par 说明: 仅NV支持异步存储时调用有效。 397 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 398 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 399 * @par 依赖: 400 * @li nv.h 401 * @endif 402 */ 403 errcode_t uapi_nv_flush(void); 404 405 /** 406 * @if Eng 407 * @brief register callback function of nv key value changed notification. 408 * @param min_key Minimum key-ID supported by registration callback. 409 * @param max_key Maximum key-ID supported by registration callback. 410 * @param func callback function. 411 * @retval EXT_ERR_SUCCESS Success. 412 * @retval Other ERRCODE_FAIL or other error num. 413 * @par Depends: 414 * @li nv.h 415 * @else 416 * @brief 注册nv键值改变通知的回调函数 417 * @param min_key 注册回调支持的最小key-ID 418 * @param max_key 注册回调支持的最大key-ID 419 * @param func 回调函数. 420 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 421 * @retval Other 失败返回#ERRCODE_FAIL或其他返回值 422 * @par 依赖: 423 * @li nv.h 424 * @endif 425 */ 426 errcode_t uapi_nv_register_change_notify_proc(uint16_t min_key, uint16_t max_key, nv_changed_notify_func func); 427 428 /** 429 * @} 430 */ 431 432 #ifdef __cplusplus 433 #if __cplusplus 434 } 435 #endif /* __cplusplus */ 436 #endif /* __cplusplus */ 437 438 #endif /* NV_H */