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 21 * @defgroup nvs Non-volatile Storage 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 * @param offset File system offset in flash 38 * @param ate_wra Allocation table entry write address. Addresses are stored as uint32_t: 39 * high 2 bytes correspond to the sector, low 2 bytes are the offset in the sector 40 * @param data_wra Data write address 41 * @param sector_size File system is split into sectors, each sector must be multiple of pagesize 42 * @param sector_count Number of sectors in the file systems 43 * @param ready Flag indicating if the filesystem is initialized 44 * @param nvs_lock Mutex 45 * @param flash_device Flash Device runtime structure 46 * @param flash_parameters Flash memory parameters structure 47 */ 48 struct nvs_fs { 49 off_t offset; 50 uint32_t ate_wra; 51 uint32_t data_wra; 52 uint16_t sector_size; 53 uint16_t sector_count; 54 bool ready; 55 struct k_mutex nvs_lock; 56 const struct device *flash_device; 57 const struct flash_parameters *flash_parameters; 58 #if CONFIG_NVS_LOOKUP_CACHE 59 uint32_t lookup_cache[CONFIG_NVS_LOOKUP_CACHE_SIZE]; 60 #endif 61 }; 62 63 /** 64 * @} 65 */ 66 67 /** 68 * @brief Non-volatile Storage APIs 69 * @defgroup nvs_high_level_api Non-volatile Storage APIs 70 * @ingroup nvs 71 * @{ 72 */ 73 74 /** 75 * @brief nvs_mount 76 * 77 * Mount a 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 nvs_clear 87 * 88 * Clears the NVS file system from flash. 89 * @param fs Pointer to file system 90 * @retval 0 Success 91 * @retval -ERRNO errno code if error 92 */ 93 int nvs_clear(struct nvs_fs *fs); 94 95 /** 96 * @brief nvs_write 97 * 98 * Write an entry to the file system. 99 * 100 * @param fs Pointer to file system 101 * @param id Id of the entry to be written 102 * @param data Pointer to the data to be written 103 * @param len Number of bytes to be written 104 * 105 * @return Number of bytes written. On success, it will be equal to the number of bytes requested 106 * to be written. When a rewrite of the same data already stored is attempted, nothing is written 107 * to flash, thus 0 is returned. On error, returns negative value of errno.h defined error codes. 108 */ 109 ssize_t nvs_write(struct nvs_fs *fs, uint16_t id, const void *data, size_t len); 110 111 /** 112 * @brief nvs_delete 113 * 114 * 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 nvs_read 125 * 126 * 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 nvs_read_hist 142 * 143 * Read a history entry from the file system. 144 * 145 * @param fs Pointer to file system 146 * @param id Id of the entry to be read 147 * @param data Pointer to data buffer 148 * @param len Number of bytes to be read 149 * @param cnt History counter: 0: latest entry, 1: one before latest ... 150 * 151 * @return Number of bytes read. On success, it will be equal to the number of bytes requested 152 * to be read. When the return value is larger than the number of bytes requested to read this 153 * indicates not all bytes were read, and more data is available. On error, returns negative 154 * value of errno.h defined error codes. 155 */ 156 ssize_t nvs_read_hist(struct nvs_fs *fs, uint16_t id, void *data, size_t len, uint16_t cnt); 157 158 /** 159 * @brief nvs_calc_free_space 160 * 161 * Calculate the available free space in the file system. 162 * 163 * @param fs Pointer to file system 164 * 165 * @return Number of bytes free. On success, it will be equal to the number of bytes that can 166 * still be written to the file system. Calculating the free space is a time consuming operation, 167 * especially on spi flash. On error, returns negative value of errno.h defined error codes. 168 */ 169 ssize_t nvs_calc_free_space(struct nvs_fs *fs); 170 171 /** 172 * @} 173 */ 174 175 #ifdef __cplusplus 176 } 177 #endif 178 179 #endif /* ZEPHYR_INCLUDE_FS_NVS_H_ */ 180
