ChibiOS/HAL  6.1.0
mfs.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.
3 
4  This file is part of ChibiOS.
5 
6  ChibiOS is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 3 of the License, or
9  (at your option) any later version.
10 
11  ChibiOS is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  GNU General Public License for more details.
15 
16  You should have received a copy of the GNU General Public License
17  along with this program. If not, see <http://www.gnu.org/licenses/>.
18 */
19 
20 /**
21  * @file mfs.h
22  * @brief Managed Flash Storage module header.
23  *
24  * @addtogroup MFS
25  * @{
26  */
27 
28 #ifndef MFS_H
29 #define MFS_H
30 
31 #include "hal_flash.h"
32 
33 /*===========================================================================*/
34 /* Driver constants. */
35 /*===========================================================================*/
36 
37 #define MFS_BANK_MAGIC_1 0xEC705ADEU
38 #define MFS_BANK_MAGIC_2 0xF0339CC5U
39 #define MFS_HEADER_MAGIC 0x5FAE45F0U
40 
41 /*===========================================================================*/
42 /* Driver pre-compile time settings. */
43 /*===========================================================================*/
44 
45 /**
46  * @name Configuration options
47  * @{
48  */
49 /**
50  * @brief Maximum number of indexed records in the managed storage.
51  * @note Record indexes go from 0 to @p MFS_CFG_MAX_RECORDS - 1.
52  */
53 #if !defined(MFS_CFG_MAX_RECORDS) || defined(__DOXYGEN__)
54 #define MFS_CFG_MAX_RECORDS 32
55 #endif
56 
57 /**
58  * @brief Maximum number of repair attempts on partition mount.
59  */
60 #if !defined(MFS_CFG_MAX_REPAIR_ATTEMPTS) || defined(__DOXYGEN__)
61 #define MFS_CFG_MAX_REPAIR_ATTEMPTS 3
62 #endif
63 
64 /**
65  * @brief Verify written data.
66  */
67 #if !defined(MFS_CFG_WRITE_VERIFY) || defined(__DOXYGEN__)
68 #define MFS_CFG_WRITE_VERIFY TRUE
69 #endif
70 
71 /**
72  * @brief Enables a stronger and slower check procedure on mount.
73  * @details Strong checking requires reading of the whole written data and
74  * this can be slow, normal checking only checks integrity of
75  * metadata, data errors would be detected on read.
76  */
77 #if !defined(MFS_CFG_STRONG_CHECKING) || defined(__DOXYGEN__)
78 #define MFS_CFG_STRONG_CHECKING TRUE
79 #endif
80 
81 /**
82  * @brief Size of the buffer used for data copying.
83  * @note The buffer size must be a power of two and not smaller than
84  * 16 bytes.
85  * @note Larger buffers improve performance, buffers with size multiple
86  * of the flash program page size work better.
87  */
88 #if !defined(MFS_CFG_BUFFER_SIZE) || defined(__DOXYGEN__)
89 #define MFS_CFG_BUFFER_SIZE 32
90 #endif
91 /** @} */
92 
93 /*===========================================================================*/
94 /* Derived constants and error checks. */
95 /*===========================================================================*/
96 
97 #if MFS_CFG_MAX_RECORDS < 0
98 #error "invalid MFS_CFG_MAX_RECORDS value"
99 #endif
100 
101 #if (MFS_CFG_MAX_REPAIR_ATTEMPTS < 1) || (MFS_CFG_MAX_REPAIR_ATTEMPTS > 10)
102 #error "invalid MFS_MAX_REPAIR_ATTEMPTS value"
103 #endif
104 
105 #if MFS_CFG_BUFFER_SIZE < 16
106 #error "invalid MFS_CFG_BUFFER_SIZE value"
107 #endif
108 
109 #if (MFS_CFG_BUFFER_SIZE & (MFS_CFG_BUFFER_SIZE - 1)) != 0
110 #error "MFS_CFG_BUFFER_SIZE is not a power of two"
111 #endif
112 
113 /*===========================================================================*/
114 /* Driver data structures and types. */
115 /*===========================================================================*/
116 
117 /**
118  * @brief Type of a flash bank.
119  */
120 typedef enum {
121  MFS_BANK_0 = 0,
122  MFS_BANK_1 = 1
123 } mfs_bank_t;
124 
125 /**
126  * @brief Type of driver state machine states.
127  */
128 typedef enum {
129  MFS_UNINIT = 0,
130  MFS_STOP = 1,
131  MFS_READY = 2,
132  MFS_ERROR = 3
133 } mfs_state_t;
134 
135 /**
136  * @brief Type of an MFS error code.
137  * @note Errors are negative integers, informative warnings are positive
138  * integers.
139  */
140 typedef enum {
141  MFS_NO_ERROR = 0,
142  MFS_WARN_REPAIR = 1,
143  MFS_WARN_GC = 2,
144  MFS_ERR_INV_STATE = -1,
145  MFS_ERR_INV_SIZE = -2,
146  MFS_ERR_NOT_FOUND = -3,
147  MFS_ERR_OUT_OF_MEM = -4,
148  MFS_ERR_NOT_ERASED = -5,
149  MFS_ERR_FLASH_FAILURE = -6,
150  MFS_ERR_INTERNAL = -7
151 } mfs_error_t;
152 
153 /**
154  * @brief Type of a bank state assessment.
155  */
156 typedef enum {
157  MFS_BANK_ERASED = 0,
158  MFS_BANK_OK = 1,
159  MFS_BANK_PARTIAL = 2,
160  MFS_BANK_GARBAGE = 3
162 
163 /**
164  * @brief Type of a record state assessment.
165  */
166 typedef enum {
167  MFS_RECORD_ERASED = 0,
168  MFS_RECORD_OK = 1,
169  MFS_RECORD_CRC = 2,
170  MFS_RECORD_GARBAGE = 3
172 
173 /**
174  * @brief Type of a record identifier.
175  */
176 typedef uint32_t mfs_id_t;
177 
178 /**
179  * @brief Type of a bank header.
180  * @note The header resides in the first 16 bytes of a bank.
181  */
182 typedef union {
183  struct {
184  /**
185  * @brief Bank magic 1.
186  */
187  uint32_t magic1;
188  /**
189  * @brief Bank magic 2.
190  */
191  uint32_t magic2;
192  /**
193  * @brief Usage counter of the bank.
194  * @details This value is increased each time a bank swap is performed. It
195  * indicates how much wearing the flash has already endured.
196  */
197  uint32_t counter;
198  /**
199  * @brief Reserved field.
200  */
201  uint16_t reserved1;
202  /**
203  * @brief Header CRC.
204  */
205  uint16_t crc;
206  } fields;
207  uint8_t hdr8[16];
208  uint32_t hdr32[4];
210 
211 /**
212  * @brief Type of a data block header.
213  * @details This structure is placed before each written data block.
214  */
215 typedef union {
216  struct {
217  /**
218  * @brief Data header magic.
219  */
220  uint32_t magic;
221  /**
222  * @brief Data identifier.
223  */
224  uint16_t id;
225  /**
226  * @brief Data CRC.
227  */
228  uint16_t crc;
229  /**
230  * @brief Data size.
231  */
232  uint32_t size;
233  } fields;
234  uint8_t hdr8[12];
235  uint32_t hdr32[3];
237 
238 typedef struct {
239  /**
240  * @brief Offset of the record header.
241  */
242  flash_offset_t offset;
243  /**
244  * @brief Record data size.
245  */
246  uint32_t size;
247 } mfs_record_descriptor_t;
248 
249 /**
250  * @brief Type of a MFS configuration structure.
251  */
252 typedef struct {
253  /**
254  * @brief Flash driver associated to this MFS instance.
255  */
257  /**
258  * @brief Erased value.
259  */
260  uint32_t erased;
261  /**
262  * @brief Banks size.
263  */
265  /**
266  * @brief Base sector index for bank 0.
267  */
269  /**
270  * @brief Number of sectors for bank 0.
271  * @note The total size of bank0 sectors must be greater or equal to
272  * @p bank_size.
273  */
275  /**
276  * @brief Base sector index for bank 1.
277  */
279  /**
280  * @brief Number of sectors for bank 1.
281  * @note The total size of bank1 sectors must be greater or equal to
282  * @p bank_size.
283  */
285 } MFSConfig;
286 
287 /**
288  * @extends BaseFlash
289  *
290  * @brief Type of an MFS instance.
291  */
292 typedef struct {
293  /**
294  * @brief Driver state.
295  */
297  /**
298  * @brief Current configuration data.
299  */
301  /**
302  * @brief Bank currently in use.
303  */
305  /**
306  * @brief Usage counter of the current bank.
307  */
308  uint32_t current_counter;
309  /**
310  * @brief Pointer to the next free position in the current bank.
311  */
313  /**
314  * @brief Used space in the current bank without considering erased records.
315  */
317  /**
318  * @brief Offsets of the most recent instance of the records.
319  * @note Zero means that there is not a record with that id.
320  */
321  mfs_record_descriptor_t descriptors[MFS_CFG_MAX_RECORDS];
322  /**
323  * @brief Transient buffer.
324  */
325  union {
326  mfs_data_header_t dhdr;
327  mfs_bank_header_t bhdr;
328  uint8_t data8[MFS_CFG_BUFFER_SIZE];
329  uint16_t data16[MFS_CFG_BUFFER_SIZE / sizeof (uint16_t)];
330  uint32_t data32[MFS_CFG_BUFFER_SIZE / sizeof (uint32_t)];
331  } buffer;
332 } MFSDriver;
333 
334 /*===========================================================================*/
335 /* Driver macros. */
336 /*===========================================================================*/
337 
338 /**
339  * @name Error codes handling macros
340  * @{
341  */
342 #define MFS_IS_ERROR(err) ((err) < MFS_NO_ERROR)
343 #define MFS_IS_WARNING(err) ((err) > MFS_NO_ERROR)
344 /** @} */
345 
346 /*===========================================================================*/
347 /* External declarations. */
348 /*===========================================================================*/
349 
350 #ifdef __cplusplus
351 extern "C" {
352 #endif
353  void mfsObjectInit(MFSDriver *devp);
354  mfs_error_t mfsStart(MFSDriver *devp, const MFSConfig *config);
355  void mfsStop(MFSDriver *devp);
358  size_t *np, uint8_t *buffer);
360  size_t n, const uint8_t *buffer);
363 #ifdef __cplusplus
364 }
365 #endif
366 
367 #endif /* MFS_H */
368 
369 /** @} */
370 
uint16_t crc
Data CRC.
Definition: mfs.h:228
uint32_t flash_sector_t
Type of a flash sector number.
Definition: hal_flash.h:88
uint32_t erased
Erased value.
Definition: mfs.h:260
mfs_state_t state
Driver state.
Definition: mfs.h:296
void mfsStop(MFSDriver *mfsp)
Deactivates a MFS driver.
Definition: mfs.c:873
Type of a MFS configuration structure.
Definition: mfs.h:252
flash_offset_t used_space
Used space in the current bank without considering erased records.
Definition: mfs.h:316
Type of a data block header.
Definition: mfs.h:215
uint32_t size
Data size.
Definition: mfs.h:232
uint16_t crc
Header CRC.
Definition: mfs.h:205
uint32_t magic1
Bank magic 1.
Definition: mfs.h:187
Base flash class.
Definition: hal_flash.h:187
mfs_error_t mfsReadRecord(MFSDriver *mfsp, mfs_id_t id, size_t *np, uint8_t *buffer)
Retrieves and reads a data record.
Definition: mfs.c:931
flash_offset_t bank_size
Banks size.
Definition: mfs.h:264
mfs_bank_state_t
Type of a bank state assessment.
Definition: mfs.h:156
#define MFS_CFG_BUFFER_SIZE
Size of the buffer used for data copying.
Definition: mfs.h:89
uint16_t reserved1
Reserved field.
Definition: mfs.h:201
uint32_t magic
Data header magic.
Definition: mfs.h:220
mfs_error_t mfsWriteRecord(MFSDriver *mfsp, mfs_id_t id, size_t n, const uint8_t *buffer)
Creates or updates a data record.
Definition: mfs.c:996
mfs_error_t mfsStart(MFSDriver *mfsp, const MFSConfig *config)
Configures and activates a MFS driver.
Definition: mfs.c:854
mfs_bank_t
Type of a flash bank.
Definition: mfs.h:120
#define MFS_CFG_MAX_RECORDS
Maximum number of indexed records in the managed storage.
Definition: mfs.h:54
flash_sector_t bank1_start
Base sector index for bank 1.
Definition: mfs.h:278
mfs_error_t
Type of an MFS error code.
Definition: mfs.h:140
flash_sector_t bank0_sectors
Number of sectors for bank 0.
Definition: mfs.h:274
flash_sector_t bank1_sectors
Number of sectors for bank 1.
Definition: mfs.h:284
flash_offset_t next_offset
Pointer to the next free position in the current bank.
Definition: mfs.h:312
Type of a bank header.
Definition: mfs.h:182
uint32_t flash_offset_t
Type of a flash offset.
Definition: hal_flash.h:83
mfs_error_t mfsErase(MFSDriver *mfsp)
Destroys the state of the managed storage by erasing the flash.
Definition: mfs.c:896
uint32_t counter
Usage counter of the bank.
Definition: mfs.h:197
mfs_record_state_t
Type of a record state assessment.
Definition: mfs.h:166
Type of an MFS instance.
Definition: mfs.h:292
mfs_error_t mfsEraseRecord(MFSDriver *mfsp, mfs_id_t id)
Erases a data record.
Definition: mfs.c:1084
mfs_error_t mfsPerformGarbageCollection(MFSDriver *mfsp)
Enforces a garbage collection operation.
Definition: mfs.c:1153
void mfsObjectInit(MFSDriver *mfsp)
Initializes an instance.
Definition: mfs.c:832
mfs_bank_t current_bank
Bank currently in use.
Definition: mfs.h:304
mfs_state_t
Type of driver state machine states.
Definition: mfs.h:128
uint32_t current_counter
Usage counter of the current bank.
Definition: mfs.h:308
Generic flash driver class header.
uint32_t mfs_id_t
Type of a record identifier.
Definition: mfs.h:176
flash_sector_t bank0_start
Base sector index for bank 0.
Definition: mfs.h:268
BaseFlash * flashp
Flash driver associated to this MFS instance.
Definition: mfs.h:256
uint32_t magic2
Bank magic 2.
Definition: mfs.h:191
const MFSConfig * config
Current configuration data.
Definition: mfs.h:300
uint16_t id
Data identifier.
Definition: mfs.h:224