1 /* NVS: non volatile storage in flash 2 * 3 * Copyright (c) 2018 Laczen 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 #ifndef ZEPHYR_INCLUDE_FS_NVS_H_ 8 #define ZEPHYR_INCLUDE_FS_NVS_H_ 9 10 #include <sys/types.h> 11 #include <zephyr/kernel.h> 12 #include <zephyr/device.h> 13 #include <zephyr/toolchain.h> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * @brief Non-volatile Storage (NVS) 21 * @defgroup nvs Non-volatile Storage (NVS) 22 * @ingroup file_system_storage 23 * @{ 24 * @} 25 */ 26 27 /** 28 * @brief Non-volatile Storage Data Structures 29 * @defgroup nvs_data_structures Non-volatile Storage Data Structures 30 * @ingroup nvs 31 * @{ 32 */ 33 34 /** 35 * @brief Non-volatile Storage File system structure 36 */ 37 struct nvs_fs { 38 /** File system offset in flash **/ 39 off_t offset; 40 /** Allocation table entry write address. 41 * Addresses are stored as uint32_t: 42 * - high 2 bytes correspond to the sector 43 * - low 2 bytes are the offset in the sector 44 */ 45 uint32_t ate_wra; 46 /** Data write address */ 47 uint32_t data_wra; 48 /** File system is split into sectors, each sector must be multiple of erase-block-size */ 49 uint16_t sector_size; 50 /** Number of sectors in the file system */ 51 uint16_t sector_count; 52 /** Flag indicating if the file system is initialized */ 53 bool ready; 54 /** Mutex */ 55 struct k_mutex nvs_lock; 56 /** Flash device runtime structure */ 57 const struct device *flash_device; 58 /** Flash memory parameters structure */ 59 const struct flash_parameters *flash_parameters; 60 #if CONFIG_NVS_LOOKUP_CACHE 61 uint32_t lookup_cache[CONFIG_NVS_LOOKUP_CACHE_SIZE]; 62 #endif 63 }; 64 65 /** 66 * @} 67 */ 68 69 /** 70 * @brief Non-volatile Storage APIs 71 * @defgroup nvs_high_level_api Non-volatile Storage APIs 72 * @ingroup nvs 73 * @{ 74 */ 75 76 /** 77 * @brief Mount an NVS file system onto the flash device specified in @p fs. 78 * 79 * @param fs Pointer to file system 80 * @retval 0 Success 81 * @retval -ERRNO errno code if error 82 */ 83 int nvs_mount(struct nvs_fs *fs); 84 85 /** 86 * @brief Clear the NVS file system from flash. 87 * 88 * @param fs Pointer to file system 89 * @retval 0 Success 90 * @retval -ERRNO errno code if error 91 */ 92 int nvs_clear(struct nvs_fs *fs); 93 94 /** 95 * @brief Write an entry to the file system. 96 * 97 * @note When @p len parameter is equal to @p 0 then entry is effectively removed (it is 98 * equivalent to calling of nvs_delete). Any calls to nvs_read for entries with data of length 99 * @p 0 will return error.@n It is not possible to distinguish between deleted entry and entry 100 * with data of length 0. 101 * 102 * @param fs Pointer to file system 103 * @param id Id of the entry to be written 104 * @param data Pointer to the data to be written 105 * @param len Number of bytes to be written 106 * 107 * @return Number of bytes written. On success, it will be equal to the number of bytes requested 108 * to be written. When a rewrite of the same data already stored is attempted, nothing is written 109 * to flash, thus 0 is returned. On error, returns negative value of errno.h defined error codes. 110 */ 111 ssize_t nvs_write(struct nvs_fs *fs, uint16_t id, const void *data, size_t len); 112 113 /** 114 * @brief Delete an entry from the file system 115 * 116 * @param fs Pointer to file system 117 * @param id Id of the entry to be deleted 118 * @retval 0 Success 119 * @retval -ERRNO errno code if error 120 */ 121 int nvs_delete(struct nvs_fs *fs, uint16_t id); 122 123 /** 124 * @brief Read an entry from the file system. 125 * 126 * @param fs Pointer to file system 127 * @param id Id of the entry to be read 128 * @param data Pointer to data buffer 129 * @param len Number of bytes to be read 130 * 131 * @return Number of bytes read. On success, it will be equal to the number of bytes requested 132 * to be read. When the return value is larger than the number of bytes requested to read this 133 * indicates not all bytes were read, and more data is available. On error, returns negative 134 * value of errno.h defined error codes. 135 */ 136 ssize_t nvs_read(struct nvs_fs *fs, uint16_t id, void *data, size_t len); 137 138 /** 139 * @brief Read a history entry from the file system. 140 * 141 * @param fs Pointer to file system 142 * @param id Id of the entry to be read 143 * @param data Pointer to data buffer 144 * @param len Number of bytes to be read 145 * @param cnt History counter: 0: latest entry, 1: one before latest ... 146 * 147 * @return Number of bytes read. On success, it will be equal to the number of bytes requested 148 * to be read. When the return value is larger than the number of bytes requested to read this 149 * indicates not all bytes were read, and more data is available. On error, returns negative 150 * value of errno.h defined error codes. 151 */ 152 ssize_t nvs_read_hist(struct nvs_fs *fs, uint16_t id, void *data, size_t len, uint16_t cnt); 153 154 /** 155 * @brief Calculate the available free space in the file system. 156 * 157 * @param fs Pointer to file system 158 * 159 * @return Number of bytes free. On success, it will be equal to the number of bytes that can 160 * still be written to the file system. Calculating the free space is a time consuming operation, 161 * especially on spi flash. On error, returns negative value of errno.h defined error codes. 162 */ 163 ssize_t nvs_calc_free_space(struct nvs_fs *fs); 164 165 /** 166 * @} 167 */ 168 169 #ifdef __cplusplus 170 } 171 #endif 172 173 #endif /* ZEPHYR_INCLUDE_FS_NVS_H_ */ 174
