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