Line data Source code
1 0 : /* 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 1 : struct nvs_fs {
40 : /** File system offset in flash **/
41 1 : 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 1 : uint32_t ate_wra;
48 : /** Data write address */
49 1 : uint32_t data_wra;
50 : /** File system is split into sectors, each sector must be multiple of erase-block-size */
51 1 : uint16_t sector_size;
52 : /** Number of sectors in the file system */
53 1 : uint16_t sector_count;
54 : /** Flag indicating if the file system is initialized */
55 1 : bool ready;
56 : /** Mutex */
57 1 : struct k_mutex nvs_lock;
58 : /** Flash device runtime structure */
59 1 : const struct device *flash_device;
60 : /** Flash memory parameters structure */
61 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
|
