Line data Source code
1 0 : /* Copyright (c) 2018 Laczen
2 : * Copyright (c) 2024 BayLibre SAS
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : *
6 : * ZMS: Zephyr Memory Storage
7 : */
8 : #ifndef ZEPHYR_INCLUDE_FS_ZMS_H_
9 : #define ZEPHYR_INCLUDE_FS_ZMS_H_
10 :
11 : #include <sys/types.h>
12 : #include <zephyr/drivers/flash.h>
13 : #include <zephyr/kernel.h>
14 : #include <zephyr/device.h>
15 : #include <zephyr/toolchain.h>
16 :
17 : #ifdef __cplusplus
18 : extern "C" {
19 : #endif
20 :
21 : /**
22 : * @defgroup zms Zephyr Memory Storage (ZMS)
23 : * @ingroup file_system_storage
24 : * @{
25 : * @}
26 : */
27 :
28 : /**
29 : * @defgroup zms_data_structures ZMS data structures
30 : * @ingroup zms
31 : * @{
32 : */
33 :
34 : /** Zephyr Memory Storage file system structure */
35 1 : struct zms_fs {
36 : /** File system offset in flash */
37 1 : off_t offset;
38 : /** Allocation Table Entry (ATE) write address.
39 : * Addresses are stored as `uint64_t`:
40 : * - high 4 bytes correspond to the sector
41 : * - low 4 bytes are the offset in the sector
42 : */
43 1 : uint64_t ate_wra;
44 : /** Data write address */
45 1 : uint64_t data_wra;
46 : /** Storage system is split into sectors. The sector size must be a multiple of
47 : * `erase-block-size` if the device has erase capabilities
48 : */
49 1 : uint32_t sector_size;
50 : /** Number of sectors in the file system */
51 1 : uint32_t sector_count;
52 : /** Current cycle counter of the active sector (pointed to by `ate_wra`) */
53 1 : uint8_t sector_cycle;
54 : /** Flag indicating if the file system is initialized */
55 1 : bool ready;
56 : /** Mutex used to lock flash writes */
57 1 : struct k_mutex zms_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 : /** Size of an Allocation Table Entry */
63 1 : size_t ate_size;
64 : #if CONFIG_ZMS_LOOKUP_CACHE
65 : /** Lookup table used to cache ATE addresses of written IDs */
66 : uint64_t lookup_cache[CONFIG_ZMS_LOOKUP_CACHE_SIZE];
67 : #endif
68 : };
69 :
70 : /**
71 : * @}
72 : */
73 :
74 : /**
75 : * @defgroup zms_high_level_api ZMS API
76 : * @ingroup zms
77 : * @{
78 : */
79 :
80 : /**
81 : * @brief Mount a ZMS file system onto the device specified in `fs`.
82 : *
83 : * @param fs Pointer to the file system.
84 : *
85 : * @retval 0 on success.
86 : * @retval -ENOTSUP if the detected file system is not ZMS.
87 : * @retval -EPROTONOSUPPORT if the ZMS version is not supported.
88 : * @retval -EINVAL if `fs` is NULL or any of the flash parameters or the sector layout is invalid.
89 : * @retval -ENXIO if there is a device error.
90 : * @retval -EIO if there is a memory read/write error.
91 : */
92 1 : int zms_mount(struct zms_fs *fs);
93 :
94 : /**
95 : * @brief Clear the ZMS file system from device. The ZMS file system must be re-mounted after this
96 : * operation.
97 : *
98 : * @param fs Pointer to the file system.
99 : *
100 : * @retval 0 on success.
101 : * @retval -EACCES if `fs` is not mounted.
102 : * @retval -ENXIO if there is a device error.
103 : * @retval -EIO if there is a memory read/write error.
104 : * @retval -EINVAL if `fs` is NULL.
105 : */
106 1 : int zms_clear(struct zms_fs *fs);
107 :
108 : /**
109 : * @brief Write an entry to the file system.
110 : *
111 : * @note When the `len` parameter is equal to `0` the entry is effectively removed (it is
112 : * equivalent to calling @ref zms_delete()). It is not possible to distinguish between a deleted
113 : * entry and an entry with data of length 0.
114 : *
115 : * @param fs Pointer to the file system.
116 : * @param id ID of the entry to be written.
117 : * @param data Pointer to the data to be written.
118 : * @param len Number of bytes to be written (maximum 64 KiB).
119 : *
120 : * @return Number of bytes written. On success, it will be equal to the number of bytes requested
121 : * to be written or 0.
122 : * When a rewrite of the same data already stored is attempted, nothing is written to flash,
123 : * thus 0 is returned. On error, returns negative value of error codes defined in `errno.h`.
124 : * @retval Number of bytes written (`len` or 0) on success.
125 : * @retval -EACCES if ZMS is still not initialized.
126 : * @retval -ENXIO if there is a device error.
127 : * @retval -EIO if there is a memory read/write error.
128 : * @retval -EINVAL if `fs` is NULL or `len` is invalid.
129 : * @retval -ENOSPC if no space is left on the device.
130 : */
131 1 : ssize_t zms_write(struct zms_fs *fs, uint32_t id, const void *data, size_t len);
132 :
133 : /**
134 : * @brief Delete an entry from the file system
135 : *
136 : * @param fs Pointer to the file system.
137 : * @param id ID of the entry to be deleted.
138 : *
139 : * @retval 0 on success.
140 : * @retval -EACCES if ZMS is still not initialized.
141 : * @retval -ENXIO if there is a device error.
142 : * @retval -EIO if there is a memory read/write error.
143 : * @retval -EINVAL if `fs` is NULL.
144 : */
145 1 : int zms_delete(struct zms_fs *fs, uint32_t id);
146 :
147 : /**
148 : * @brief Read an entry from the file system.
149 : *
150 : * @param fs Pointer to the file system.
151 : * @param id ID of the entry to be read.
152 : * @param data Pointer to data buffer.
153 : * @param len Number of bytes to read at most.
154 : *
155 : * @return Number of bytes read. On success, it will be equal to the number of bytes requested
156 : * to be read or less than that if the stored data has a smaller size than the requested one.
157 : * On error, returns negative value of error codes defined in `errno.h`.
158 : * @retval Number of bytes read (> 0) on success.
159 : * @retval -EACCES if ZMS is still not initialized.
160 : * @retval -EIO if there is a memory read/write error.
161 : * @retval -ENOENT if there is no entry with the given `id`.
162 : * @retval -EINVAL if `fs` is NULL.
163 : */
164 1 : ssize_t zms_read(struct zms_fs *fs, uint32_t id, void *data, size_t len);
165 :
166 : /**
167 : * @brief Read a history entry from the file system.
168 : *
169 : * @param fs Pointer to the file system.
170 : * @param id ID of the entry to be read.
171 : * @param data Pointer to data buffer.
172 : * @param len Number of bytes to be read.
173 : * @param cnt History counter: 0: latest entry, 1: one before latest ...
174 : *
175 : * @return Number of bytes read. On success, it will be equal to the number of bytes requested
176 : * to be read. When the return value is larger than the number of bytes requested to read this
177 : * indicates not all bytes were read, and more data is available. On error, returns negative
178 : * value of error codes defined in `errno.h`.
179 : * @retval Number of bytes read (> 0) on success.
180 : * @retval -EACCES if ZMS is still not initialized.
181 : * @retval -EIO if there is a memory read/write error.
182 : * @retval -ENOENT if there is no entry with the given `id` and history counter.
183 : * @retval -EINVAL if `fs` is NULL.
184 : */
185 1 : ssize_t zms_read_hist(struct zms_fs *fs, uint32_t id, void *data, size_t len, uint32_t cnt);
186 :
187 : /**
188 : * @brief Gets the length of the data that is stored in an entry with a given `id`
189 : *
190 : * @param fs Pointer to the file system.
191 : * @param id ID of the entry whose data length to retrieve.
192 : *
193 : * @return Data length contained in the ATE. On success, it will be equal to the number of bytes
194 : * in the ATE. On error, returns negative value of error codes defined in `errno.h`.
195 : * @retval Length of the entry with the given `id` (> 0) on success.
196 : * @retval -EACCES if ZMS is still not initialized.
197 : * @retval -EIO if there is a memory read/write error.
198 : * @retval -ENOENT if there is no entry with the given id.
199 : * @retval -EINVAL if `fs` is NULL.
200 : */
201 1 : ssize_t zms_get_data_length(struct zms_fs *fs, uint32_t id);
202 :
203 : /**
204 : * @brief Calculate the available free space in the file system.
205 : *
206 : * @param fs Pointer to the file system.
207 : *
208 : * @return Number of free bytes. On success, it will be equal to the number of bytes that can
209 : * still be written to the file system.
210 : * Calculating the free space is a time-consuming operation, especially on SPI flash.
211 : * On error, returns negative value of error codes defined in `errno.h`.
212 : * @retval Number of free bytes (>= 0) on success.
213 : * @retval -EACCES if ZMS is still not initialized.
214 : * @retval -EIO if there is a memory read/write error.
215 : * @retval -EINVAL if `fs` is NULL.
216 : */
217 1 : ssize_t zms_calc_free_space(struct zms_fs *fs);
218 :
219 : /**
220 : * @brief Tell how much contiguous free space remains in the currently active ZMS sector.
221 : *
222 : * @param fs Pointer to the file system.
223 : *
224 : * @retval >=0 Number of free bytes in the currently active sector
225 : * @retval -EACCES if ZMS is still not initialized.
226 : * @retval -EINVAL if `fs` is NULL.
227 : */
228 1 : ssize_t zms_active_sector_free_space(struct zms_fs *fs);
229 :
230 : /**
231 : * @brief Close the currently active sector and switch to the next one.
232 : *
233 : * @note The garbage collector is called on the new sector.
234 : *
235 : * @warning This routine is made available for specific use cases.
236 : * It collides with ZMS's goal of avoiding any unnecessary flash erase operations.
237 : * Using this routine extensively can result in premature failure of the flash device.
238 : *
239 : * @param fs Pointer to the file system.
240 : *
241 : * @retval 0 on success.
242 : * @retval -EACCES if ZMS is still not initialized.
243 : * @retval -EIO if there is a memory read/write error.
244 : * @retval -EINVAL if `fs` is NULL.
245 : */
246 1 : int zms_sector_use_next(struct zms_fs *fs);
247 :
248 : /**
249 : * @}
250 : */
251 :
252 : #ifdef __cplusplus
253 : }
254 : #endif
255 :
256 : #endif /* ZEPHYR_INCLUDE_FS_ZMS_H_ */
|
