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 * @since 1.12 23 * @version 1.0.0 24 * @ingroup file_system_storage 25 * @{ 26 * @} 27 */ 28 29 /** 30 * @brief Non-volatile Storage Data Structures 31 * @defgroup nvs_data_structures Non-volatile Storage Data Structures 32 * @ingroup nvs 33 * @{ 34 */ 35 36 /** 37 * @brief Non-volatile Storage File system structure 38 */ 39 struct nvs_fs { 40 /** File system offset in flash **/ 41 off_t offset; 42 /** Allocation table entry write address. 43 * Addresses are stored as uint32_t: 44 * - high 2 bytes correspond to the sector 45 * - low 2 bytes are the offset in the sector 46 */ 47 uint32_t ate_wra; 48 /** Data write address */ 49 uint32_t data_wra; 50 /** File system is split into sectors, each sector must be multiple of erase-block-size */ 51 uint16_t sector_size; 52 /** Number of sectors in the file system */ 53 uint16_t sector_count; 54 /** Flag indicating if the file system is initialized */ 55 bool ready; 56 /** Mutex */ 57 struct k_mutex nvs_lock; 58 /** Flash device runtime structure */ 59 const struct device *flash_device; 60 /** Flash memory parameters structure */ 61 const struct flash_parameters *flash_parameters; 62 #if CONFIG_NVS_LOOKUP_CACHE 63 uint32_t lookup_cache[CONFIG_NVS_LOOKUP_CACHE_SIZE]; 64 #endif 65 }; 66 67 /** 68 * @} 69 */ 70 71 /** 72 * @brief Non-volatile Storage APIs 73 * @defgroup nvs_high_level_api Non-volatile Storage APIs 74 * @ingroup nvs 75 * @{ 76 */ 77 78 /** 79 * @brief Mount an NVS file system onto the flash device specified in @p fs. 80 * 81 * @param fs Pointer to file system 82 * @retval 0 Success 83 * @retval -ERRNO errno code if error 84 */ 85 int nvs_mount(struct nvs_fs *fs); 86 87 /** 88 * @brief Clear the NVS file system from flash. 89 * 90 * @param fs Pointer to file system 91 * @retval 0 Success 92 * @retval -ERRNO errno code if error 93 */ 94 int nvs_clear(struct nvs_fs *fs); 95 96 /** 97 * @brief Write an entry to the file system. 98 * 99 * @note When @p len parameter is equal to @p 0 then entry is effectively removed (it is 100 * equivalent to calling of nvs_delete). Any calls to nvs_read for entries with data of length 101 * @p 0 will return error.@n It is not possible to distinguish between deleted entry and entry 102 * with data of length 0. 103 * 104 * @param fs Pointer to file system 105 * @param id Id of the entry to be written 106 * @param data Pointer to the data to be written 107 * @param len Number of bytes to be written 108 * 109 * @return Number of bytes written. On success, it will be equal to the number of bytes requested 110 * to be written. When a rewrite of the same data already stored is attempted, nothing is written 111 * to flash, thus 0 is returned. On error, returns negative value of errno.h defined error codes. 112 */ 113 ssize_t nvs_write(struct nvs_fs *fs, uint16_t id, const void *data, size_t len); 114 115 /** 116 * @brief Delete an entry from the file system 117 * 118 * @param fs Pointer to file system 119 * @param id Id of the entry to be deleted 120 * @retval 0 Success 121 * @retval -ERRNO errno code if error 122 */ 123 int nvs_delete(struct nvs_fs *fs, uint16_t id); 124 125 /** 126 * @brief Read an entry from the file system. 127 * 128 * @param fs Pointer to file system 129 * @param id Id of the entry to be read 130 * @param data Pointer to data buffer 131 * @param len Number of bytes to be read 132 * 133 * @return Number of bytes read. On success, it will be equal to the number of bytes requested 134 * to be read. When the return value is larger than the number of bytes requested to read this 135 * indicates not all bytes were read, and more data is available. On error, returns negative 136 * value of errno.h defined error codes. 137 */ 138 ssize_t nvs_read(struct nvs_fs *fs, uint16_t id, void *data, size_t len); 139 140 /** 141 * @brief Read a history entry from the file system. 142 * 143 * @param fs Pointer to file system 144 * @param id Id of the entry to be read 145 * @param data Pointer to data buffer 146 * @param len Number of bytes to be read 147 * @param cnt History counter: 0: latest entry, 1: one before latest ... 148 * 149 * @return Number of bytes read. On success, it will be equal to the number of bytes requested 150 * to be read. When the return value is larger than the number of bytes requested to read this 151 * indicates not all bytes were read, and more data is available. On error, returns negative 152 * value of errno.h defined error codes. 153 */ 154 ssize_t nvs_read_hist(struct nvs_fs *fs, uint16_t id, void *data, size_t len, uint16_t cnt); 155 156 /** 157 * @brief Calculate the available free space in the file system. 158 * 159 * @param fs Pointer to file system 160 * 161 * @return Number of bytes free. On success, it will be equal to the number of bytes that can 162 * still be written to the file system. Calculating the free space is a time consuming operation, 163 * especially on spi flash. On error, returns negative value of errno.h defined error codes. 164 */ 165 ssize_t nvs_calc_free_space(struct nvs_fs *fs); 166 167 /** 168 * @brief Tell how many contiguous free space remains in the currently active NVS sector. 169 * 170 * @param fs Pointer to the file system. 171 * 172 * @return Number of free bytes. 173 */ 174 size_t nvs_sector_max_data_size(struct nvs_fs *fs); 175 176 /** 177 * @brief Close the currently active sector and switch to the next one. 178 * 179 * @note The garbage collector is called on the new sector. 180 * 181 * @warning This routine is made available for specific use cases. 182 * It breaks the aim of the NVS to avoid any unnecessary flash erases. 183 * Using this routine extensively can result in premature failure of the flash device. 184 * 185 * @param fs Pointer to the file system. 186 * 187 * @return 0 on success. On error, returns negative value of errno.h defined error codes. 188 */ 189 int nvs_sector_use_next(struct nvs_fs *fs); 190 191 /** 192 * @} 193 */ 194 195 #ifdef __cplusplus 196 } 197 #endif 198 199 #endif /* ZEPHYR_INCLUDE_FS_NVS_H_ */ 200
