Merge pull request #1331 from Guilhem7/master
[RRG-proxmark3.git] / armsrc / spiffs.h
blob520ff8809510262f524dc2f797aa0f6bab0bfc99
1 /*
2 * spiffs.h
4 * Created on: May 26, 2013
5 * Author: petera
6 */
8 #ifndef SPIFFS_H_
9 #define SPIFFS_H_
10 #if defined(__cplusplus)
11 extern "C" {
12 #endif
14 #include "spiffs_config.h"
16 typedef enum spiffs_safety_level { RDV40_SPIFFS_SAFETY_NORMAL, RDV40_SPIFFS_SAFETY_LAZY, RDV40_SPIFFS_SAFETY_SAFE } RDV40SpiFFSSafetyLevel;
18 typedef enum spiffs_file_type {
19 RDV40_SPIFFS_FILETYPE_REAL,
20 RDV40_SPIFFS_FILETYPE_SYMLINK,
21 RDV40_SPIFFS_FILETYPE_BOTH,
22 RDV40_SPIFFS_FILETYPE_UNKNOWN
23 } RDV40SpiFFSFileType;
25 typedef struct rdv40_spiffs_fsinfo {
26 uint32_t blockSize;
27 uint32_t pageSize;
28 uint32_t maxOpenFiles;
29 uint32_t maxPathLength;
30 uint32_t totalBytes, usedBytes, freeBytes;
31 uint32_t usedPercent, freePercent;
32 } rdv40_spiffs_fsinfo;
34 int rdv40_spiffs_read_as_filetype(char *filename, uint8_t *dst, uint32_t size, RDV40SpiFFSSafetyLevel level);
36 int rdv40_spiffs_check(void);
37 int rdv40_spiffs_lazy_unmount(void);
38 int rdv40_spiffs_lazy_mount(void);
39 int rdv40_spiffs_lazy_mount_rollback(int changed);
40 int rdv40_spiffs_write(const char *filename, uint8_t *src, uint32_t size, RDV40SpiFFSSafetyLevel level);
41 int rdv40_spiffs_read(const char *filename, uint8_t *dst, uint32_t size, RDV40SpiFFSSafetyLevel level);
42 int rdv40_spiffs_rename(char *old_filename, char *new_filename, RDV40SpiFFSSafetyLevel level);
43 int rdv40_spiffs_remove(char *filename, RDV40SpiFFSSafetyLevel level);
44 int rdv40_spiffs_read_as_symlink(char *filename, uint8_t *dst, uint32_t size, RDV40SpiFFSSafetyLevel level);
45 void write_to_spiffs(const char *filename, uint8_t *src, uint32_t size);
46 void read_from_spiffs(const char *filename, uint8_t *dst, uint32_t size);
47 void test_spiffs(void);
48 void rdv40_spiffs_safe_print_tree(void);
49 int rdv40_spiffs_unmount(void);
50 int rdv40_spiffs_mount(void);
51 int rdv40_spiffs_is_symlink(const char *s);
52 void rdv40_spiffs_safe_print_fsinfo(void);
53 int rdv40_spiffs_make_symlink(char *linkdest, char *filename, RDV40SpiFFSSafetyLevel level);
54 void append_to_spiffs(const char *filename, uint8_t *src, uint32_t size);
55 int rdv40_spiffs_copy(char *src, char *dst, RDV40SpiFFSSafetyLevel level);
56 int rdv40_spiffs_append(const char *filename, uint8_t *src, uint32_t size, RDV40SpiFFSSafetyLevel level);
57 int rdv40_spiffs_stat(char *filename, uint32_t *buf, RDV40SpiFFSSafetyLevel level);
58 uint32_t size_in_spiffs(const char *filename);
59 int exists_in_spiffs(const char *filename);
61 void rdv40_spiffs_safe_wipe(void);
63 #define SPIFFS_OK 0
64 #define SPIFFS_ERR_NOT_MOUNTED -10000
65 #define SPIFFS_ERR_FULL -10001
66 #define SPIFFS_ERR_NOT_FOUND -10002
67 #define SPIFFS_ERR_END_OF_OBJECT -10003
68 #define SPIFFS_ERR_DELETED -10004
69 #define SPIFFS_ERR_NOT_FINALIZED -10005
70 #define SPIFFS_ERR_NOT_INDEX -10006
71 #define SPIFFS_ERR_OUT_OF_FILE_DESCS -10007
72 #define SPIFFS_ERR_FILE_CLOSED -10008
73 #define SPIFFS_ERR_FILE_DELETED -10009
74 #define SPIFFS_ERR_BAD_DESCRIPTOR -10010
75 #define SPIFFS_ERR_IS_INDEX -10011
76 #define SPIFFS_ERR_IS_FREE -10012
77 #define SPIFFS_ERR_INDEX_SPAN_MISMATCH -10013
78 #define SPIFFS_ERR_DATA_SPAN_MISMATCH -10014
79 #define SPIFFS_ERR_INDEX_REF_FREE -10015
80 #define SPIFFS_ERR_INDEX_REF_LU -10016
81 #define SPIFFS_ERR_INDEX_REF_INVALID -10017
82 #define SPIFFS_ERR_INDEX_FREE -10018
83 #define SPIFFS_ERR_INDEX_LU -10019
84 #define SPIFFS_ERR_INDEX_INVALID -10020
85 #define SPIFFS_ERR_NOT_WRITABLE -10021
86 #define SPIFFS_ERR_NOT_READABLE -10022
87 #define SPIFFS_ERR_CONFLICTING_NAME -10023
88 #define SPIFFS_ERR_NOT_CONFIGURED -10024
90 #define SPIFFS_ERR_NOT_A_FS -10025
91 #define SPIFFS_ERR_MOUNTED -10026
92 #define SPIFFS_ERR_ERASE_FAIL -10027
93 #define SPIFFS_ERR_MAGIC_NOT_POSSIBLE -10028
95 #define SPIFFS_ERR_NO_DELETED_BLOCKS -10029
97 #define SPIFFS_ERR_FILE_EXISTS -10030
99 #define SPIFFS_ERR_NOT_A_FILE -10031
100 #define SPIFFS_ERR_RO_NOT_IMPL -10032
101 #define SPIFFS_ERR_RO_ABORTED_OPERATION -10033
102 #define SPIFFS_ERR_PROBE_TOO_FEW_BLOCKS -10034
103 #define SPIFFS_ERR_PROBE_NOT_A_FS -10035
104 #define SPIFFS_ERR_NAME_TOO_LONG -10036
106 #define SPIFFS_ERR_IX_MAP_UNMAPPED -10037
107 #define SPIFFS_ERR_IX_MAP_MAPPED -10038
108 #define SPIFFS_ERR_IX_MAP_BAD_RANGE -10039
110 #define SPIFFS_ERR_SEEK_BOUNDS -10040
113 #define SPIFFS_ERR_INTERNAL -10050
115 #define SPIFFS_ERR_TEST -10100
118 // spiffs file descriptor index type. must be signed
119 typedef s16_t spiffs_file;
120 // spiffs file descriptor flags
121 typedef u16_t spiffs_flags;
122 // spiffs file mode
123 typedef u16_t spiffs_mode;
124 // object type
125 typedef u8_t spiffs_obj_type;
127 struct spiffs_t;
129 #if SPIFFS_HAL_CALLBACK_EXTRA
131 /* spi read call function type */
132 typedef s32_t (*spiffs_read)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *dst);
133 /* spi write call function type */
134 typedef s32_t (*spiffs_write)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *src);
135 /* spi erase call function type */
136 typedef s32_t (*spiffs_erase)(struct spiffs_t *fs, u32_t addr, u32_t size);
138 #else // SPIFFS_HAL_CALLBACK_EXTRA
140 /* spi read call function type */
141 typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
142 /* spi write call function type */
143 typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
144 /* spi erase call function type */
145 typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
146 #endif // SPIFFS_HAL_CALLBACK_EXTRA
148 /* file system check callback report operation */
149 typedef enum {
150 SPIFFS_CHECK_LOOKUP = 0,
151 SPIFFS_CHECK_INDEX,
152 SPIFFS_CHECK_PAGE
153 } spiffs_check_type;
155 /* file system check callback report type */
156 typedef enum {
157 SPIFFS_CHECK_PROGRESS = 0,
158 SPIFFS_CHECK_ERROR,
159 SPIFFS_CHECK_FIX_INDEX,
160 SPIFFS_CHECK_FIX_LOOKUP,
161 SPIFFS_CHECK_DELETE_ORPHANED_INDEX,
162 SPIFFS_CHECK_DELETE_PAGE,
163 SPIFFS_CHECK_DELETE_BAD_FILE
164 } spiffs_check_report;
166 /* file system check callback function */
167 #if SPIFFS_HAL_CALLBACK_EXTRA
168 typedef void (*spiffs_check_callback)(struct spiffs_t *fs, spiffs_check_type type, spiffs_check_report report,
169 u32_t arg1, u32_t arg2);
170 #else // SPIFFS_HAL_CALLBACK_EXTRA
171 typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
172 u32_t arg1, u32_t arg2);
173 #endif // SPIFFS_HAL_CALLBACK_EXTRA
175 /* file system listener callback operation */
176 typedef enum {
177 /* the file has been created */
178 SPIFFS_CB_CREATED = 0,
179 /* the file has been updated or moved to another page */
180 SPIFFS_CB_UPDATED,
181 /* the file has been deleted */
182 SPIFFS_CB_DELETED
183 } spiffs_fileop_type;
185 /* file system listener callback function */
186 typedef void (*spiffs_file_callback)(struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix);
188 #ifndef SPIFFS_DBG
189 #define SPIFFS_DBG(...) \
190 printf(__VA_ARGS__)
191 #endif
192 #ifndef SPIFFS_GC_DBG
193 #define SPIFFS_GC_DBG(...) printf(__VA_ARGS__)
194 #endif
195 #ifndef SPIFFS_CACHE_DBG
196 #define SPIFFS_CACHE_DBG(...) printf(__VA_ARGS__)
197 #endif
198 #ifndef SPIFFS_CHECK_DBG
199 #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
200 #endif
202 /* Any write to the filehandle is appended to end of the file */
203 #define SPIFFS_APPEND (1<<0)
204 #define SPIFFS_O_APPEND SPIFFS_APPEND
205 /* If the opened file exists, it will be truncated to zero length before opened */
206 #define SPIFFS_TRUNC (1<<1)
207 #define SPIFFS_O_TRUNC SPIFFS_TRUNC
208 /* If the opened file does not exist, it will be created before opened */
209 #define SPIFFS_CREAT (1<<2)
210 #define SPIFFS_O_CREAT SPIFFS_CREAT
211 /* The opened file may only be read */
212 #define SPIFFS_RDONLY (1<<3)
213 #define SPIFFS_O_RDONLY SPIFFS_RDONLY
214 /* The opened file may only be written */
215 #define SPIFFS_WRONLY (1<<4)
216 #define SPIFFS_O_WRONLY SPIFFS_WRONLY
217 /* The opened file may be both read and written */
218 #define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY)
219 #define SPIFFS_O_RDWR SPIFFS_RDWR
220 /* Any writes to the filehandle will never be cached but flushed directly */
221 #define SPIFFS_DIRECT (1<<5)
222 #define SPIFFS_O_DIRECT SPIFFS_DIRECT
223 /* If SPIFFS_O_CREAT and SPIFFS_O_EXCL are set, SPIFFS_open() shall fail if the file exists */
224 #define SPIFFS_EXCL (1<<6)
225 #define SPIFFS_O_EXCL SPIFFS_EXCL
227 #define SPIFFS_SEEK_SET (0)
228 #define SPIFFS_SEEK_CUR (1)
229 #define SPIFFS_SEEK_END (2)
231 #define SPIFFS_TYPE_FILE (1)
232 #define SPIFFS_TYPE_DIR (2)
233 #define SPIFFS_TYPE_HARD_LINK (3)
234 #define SPIFFS_TYPE_SOFT_LINK (4)
236 #ifndef SPIFFS_LOCK
237 #define SPIFFS_LOCK(fs)
238 #endif
240 #ifndef SPIFFS_UNLOCK
241 #define SPIFFS_UNLOCK(fs)
242 #endif
244 // phys structs
246 // spiffs spi configuration struct
247 typedef struct {
248 // physical read function
249 spiffs_read hal_read_f;
250 // physical write function
251 spiffs_write hal_write_f;
252 // physical erase function
253 spiffs_erase hal_erase_f;
254 #if SPIFFS_SINGLETON == 0
255 // physical size of the spi flash
256 u32_t phys_size;
257 // physical offset in spi flash used for spiffs,
258 // must be on block boundary
259 u32_t phys_addr;
260 // physical size when erasing a block
261 u32_t phys_erase_block;
263 // logical size of a block, must be on physical
264 // block size boundary and must never be less than
265 // a physical block
266 u32_t log_block_size;
267 // logical size of a page, must be at least
268 // log_block_size / 8
269 u32_t log_page_size;
271 #endif
272 #if SPIFFS_FILEHDL_OFFSET
273 // an integer offset added to each file handle
274 u16_t fh_ix_offset;
275 #endif
276 } spiffs_config;
278 typedef struct spiffs_t {
279 // file system configuration
280 spiffs_config cfg;
281 // number of logical blocks
282 u32_t block_count;
284 // cursor for free blocks, block index
285 spiffs_block_ix free_cursor_block_ix;
286 // cursor for free blocks, entry index
287 int free_cursor_obj_lu_entry;
288 // cursor when searching, block index
289 spiffs_block_ix cursor_block_ix;
290 // cursor when searching, entry index
291 int cursor_obj_lu_entry;
293 // primary work buffer, size of a logical page
294 u8_t *lu_work;
295 // secondary work buffer, size of a logical page
296 u8_t *work;
297 // file descriptor memory area
298 u8_t *fd_space;
299 // available file descriptors
300 u32_t fd_count;
302 // last error
303 s32_t err_code;
305 // current number of free blocks
306 u32_t free_blocks;
307 // current number of busy pages
308 u32_t stats_p_allocated;
309 // current number of deleted pages
310 u32_t stats_p_deleted;
311 // flag indicating that garbage collector is cleaning
312 u8_t cleaning;
313 // max erase count amongst all blocks
314 spiffs_obj_id max_erase_count;
316 #if SPIFFS_GC_STATS
317 u32_t stats_gc_runs;
318 #endif
320 #if SPIFFS_CACHE
321 // cache memory
322 void *cache;
323 // cache size
324 u32_t cache_size;
325 #if SPIFFS_CACHE_STATS
326 u32_t cache_hits;
327 u32_t cache_misses;
328 #endif
329 #endif
331 // check callback function
332 spiffs_check_callback check_cb_f;
333 // file callback function
334 spiffs_file_callback file_cb_f;
335 // mounted flag
336 u8_t mounted;
337 // user data
338 void *user_data;
339 // config magic
340 u32_t config_magic;
341 } spiffs;
343 /* spiffs file status struct */
344 typedef struct {
345 spiffs_obj_id obj_id;
346 u32_t size;
347 spiffs_obj_type type;
348 spiffs_page_ix pix;
349 u8_t name[SPIFFS_OBJ_NAME_LEN];
350 #if SPIFFS_OBJ_META_LEN
351 u8_t meta[SPIFFS_OBJ_META_LEN];
352 #endif
353 } spiffs_stat;
355 struct spiffs_dirent {
356 spiffs_obj_id obj_id;
357 u8_t name[SPIFFS_OBJ_NAME_LEN];
358 spiffs_obj_type type;
359 u32_t size;
360 spiffs_page_ix pix;
361 #if SPIFFS_OBJ_META_LEN
362 u8_t meta[SPIFFS_OBJ_META_LEN];
363 #endif
366 typedef struct {
367 spiffs *fs;
368 spiffs_block_ix block;
369 int entry;
370 } spiffs_DIR;
372 #if SPIFFS_IX_MAP
374 typedef struct {
375 // buffer with looked up data pixes
376 spiffs_page_ix *map_buf;
377 // precise file byte offset
378 u32_t offset;
379 // start data span index of lookup buffer
380 spiffs_span_ix start_spix;
381 // end data span index of lookup buffer
382 spiffs_span_ix end_spix;
383 } spiffs_ix_map;
385 #endif
387 // functions
389 #if SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
391 * Special function. This takes a spiffs config struct and returns the number
392 * of blocks this file system was formatted with. This function relies on
393 * that following info is set correctly in given config struct:
395 * phys_addr, log_page_size, and log_block_size.
397 * Also, hal_read_f must be set in the config struct.
399 * One must be sure of the correct page size and that the physical address is
400 * correct in the probed file system when calling this function. It is not
401 * checked if the phys_addr actually points to the start of the file system,
402 * so one might get a false positive if entering a phys_addr somewhere in the
403 * middle of the file system at block boundary. In addition, it is not checked
404 * if the page size is actually correct. If it is not, weird file system sizes
405 * will be returned.
407 * If this function detects a file system it returns the assumed file system
408 * size, which can be used to set the phys_size.
410 * Otherwise, it returns an error indicating why it is not regarded as a file
411 * system.
413 * Note: this function is not protected with SPIFFS_LOCK and SPIFFS_UNLOCK
414 * macros. It returns the error code directly, instead of as read by
415 * SPIFFS_errno.
417 * @param config essential parts of the physical and logical
418 * configuration of the file system.
420 s32_t SPIFFS_probe_fs(spiffs_config *config);
421 #endif // SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
424 * Initializes the file system dynamic parameters and mounts the filesystem.
425 * If SPIFFS_USE_MAGIC is enabled the mounting may fail with SPIFFS_ERR_NOT_A_FS
426 * if the flash does not contain a recognizable file system.
427 * In this case, SPIFFS_format must be called prior to remounting.
428 * @param fs the file system struct
429 * @param config the physical and logical configuration of the file system
430 * @param work a memory work buffer comprising 2*config->log_page_size
431 * bytes used throughout all file system operations
432 * @param fd_space memory for file descriptors
433 * @param fd_space_size memory size of file descriptors
434 * @param cache memory for cache, may be null
435 * @param cache_size memory size of cache
436 * @param check_cb_f callback function for reporting during consistency checks
438 s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
439 u8_t *fd_space, u32_t fd_space_size,
440 void *cache, u32_t cache_size,
441 spiffs_check_callback check_cb_f);
444 * Unmounts the file system. All file handles will be flushed of any
445 * cached writes and closed.
446 * @param fs the file system struct
448 void SPIFFS_unmount(spiffs *fs);
451 * Creates a new file.
452 * @param fs the file system struct
453 * @param path the path of the new file
454 * @param mode ignored, for posix compliance
456 s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode);
459 * Opens/creates a file.
460 * @param fs the file system struct
461 * @param path the path of the new file
462 * @param flags the flags for the open command, can be combinations of
463 * SPIFFS_O_APPEND, SPIFFS_O_TRUNC, SPIFFS_O_CREAT, SPIFFS_O_RDONLY,
464 * SPIFFS_O_WRONLY, SPIFFS_O_RDWR, SPIFFS_O_DIRECT, SPIFFS_O_EXCL
465 * @param mode ignored, for posix compliance
467 spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode);
470 * Opens a file by given dir entry.
471 * Optimization purposes, when traversing a file system with SPIFFS_readdir
472 * a normal SPIFFS_open would need to traverse the filesystem again to find
473 * the file, whilst SPIFFS_open_by_dirent already knows where the file resides.
474 * @param fs the file system struct
475 * @param e the dir entry to the file
476 * @param flags the flags for the open command, can be combinations of
477 * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
478 * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT.
479 * SPIFFS_CREAT will have no effect in this case.
480 * @param mode ignored, for posix compliance
482 spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode);
485 * Opens a file by given page index.
486 * Optimization purposes, opens a file by directly pointing to the page
487 * index in the spi flash.
488 * If the page index does not point to a file header SPIFFS_ERR_NOT_A_FILE
489 * is returned.
490 * @param fs the file system struct
491 * @param page_ix the page index
492 * @param flags the flags for the open command, can be combinations of
493 * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
494 * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT.
495 * SPIFFS_CREAT will have no effect in this case.
496 * @param mode ignored, for posix compliance
498 spiffs_file SPIFFS_open_by_page(spiffs *fs, spiffs_page_ix page_ix, spiffs_flags flags, spiffs_mode mode);
501 * Reads from given filehandle.
502 * @param fs the file system struct
503 * @param fh the filehandle
504 * @param buf where to put read data
505 * @param len how much to read
506 * @returns number of bytes read, or -1 if error
508 s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
511 * Writes to given filehandle.
512 * @param fs the file system struct
513 * @param fh the filehandle
514 * @param buf the data to write
515 * @param len how much to write
516 * @returns number of bytes written, or -1 if error
518 s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
521 * Moves the read/write file offset. Resulting offset is returned or negative if error.
522 * lseek(fs, fd, 0, SPIFFS_SEEK_CUR) will thus return current offset.
523 * @param fs the file system struct
524 * @param fh the filehandle
525 * @param offs how much/where to move the offset
526 * @param whence if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes
527 * if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset
528 * if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offse, which should be negative
530 s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
533 * Removes a file by path
534 * @param fs the file system struct
535 * @param path the path of the file to remove
537 s32_t SPIFFS_remove(spiffs *fs, const char *path);
540 * Removes a file by filehandle
541 * @param fs the file system struct
542 * @param fh the filehandle of the file to remove
544 s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
547 * Gets file status by path
548 * @param fs the file system struct
549 * @param path the path of the file to stat
550 * @param s the stat struct to populate
552 s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
555 * Gets file status by filehandle
556 * @param fs the file system struct
557 * @param fh the filehandle of the file to stat
558 * @param s the stat struct to populate
560 s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
563 * Flushes all pending write operations from cache for given file
564 * @param fs the file system struct
565 * @param fh the filehandle of the file to flush
567 s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
570 * Closes a filehandle. If there are pending write operations, these are finalized before closing.
571 * @param fs the file system struct
572 * @param fh the filehandle of the file to close
574 s32_t SPIFFS_close(spiffs *fs, spiffs_file fh);
577 * Renames a file
578 * @param fs the file system struct
579 * @param old path of file to rename
580 * @param newPath new path of file
582 s32_t SPIFFS_rename(spiffs *fs, const char *old_path, const char *new_path);
584 #if SPIFFS_OBJ_META_LEN
586 * Updates file's metadata
587 * @param fs the file system struct
588 * @param path path to the file
589 * @param meta new metadata. must be SPIFFS_OBJ_META_LEN bytes long.
591 s32_t SPIFFS_update_meta(spiffs *fs, const char *name, const void *meta);
594 * Updates file's metadata
595 * @param fs the file system struct
596 * @param fh file handle of the file
597 * @param meta new metadata. must be SPIFFS_OBJ_META_LEN bytes long.
599 s32_t SPIFFS_fupdate_meta(spiffs *fs, spiffs_file fh, const void *meta);
600 #endif
603 * Returns last error of last file operation.
604 * @param fs the file system struct
606 s32_t SPIFFS_errno(spiffs *fs);
609 * Clears last error.
610 * @param fs the file system struct
612 void SPIFFS_clearerr(spiffs *fs);
615 * Opens a directory stream corresponding to the given name.
616 * The stream is positioned at the first entry in the directory.
617 * On hydrogen builds the name argument is ignored as hydrogen builds always correspond
618 * to a flat file structure - no directories.
619 * @param fs the file system struct
620 * @param name the name of the directory
621 * @param d pointer the directory stream to be populated
623 spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
626 * Closes a directory stream
627 * @param d the directory stream to close
629 s32_t SPIFFS_closedir(spiffs_DIR *d);
632 * Reads a directory into given spifs_dirent struct.
633 * @param d pointer to the directory stream
634 * @param e the dirent struct to be populated
635 * @returns null if error or end of stream, else given dirent is returned
637 struct spiffs_dirent *SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e);
640 * Runs a consistency check on given filesystem.
641 * @param fs the file system struct
643 s32_t SPIFFS_check(spiffs *fs);
646 * Returns number of total bytes available and number of used bytes.
647 * This is an estimation, and depends on if there a many files with little
648 * data or few files with much data.
649 * NB: If used number of bytes exceeds total bytes, a SPIFFS_check should
650 * run. This indicates a power loss in midst of things. In worst case
651 * (repeated powerlosses in mending or gc) you might have to delete some files.
653 * @param fs the file system struct
654 * @param total total number of bytes in filesystem
655 * @param used used number of bytes in filesystem
657 s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used);
660 * Formats the entire file system. All data will be lost.
661 * The filesystem must not be mounted when calling this.
663 * NB: formatting is awkward. Due to backwards compatibility, SPIFFS_mount
664 * MUST be called prior to formatting in order to configure the filesystem.
665 * If SPIFFS_mount succeeds, SPIFFS_unmount must be called before calling
666 * SPIFFS_format.
667 * If SPIFFS_mount fails, SPIFFS_format can be called directly without calling
668 * SPIFFS_unmount first.
670 * @param fs the file system struct
672 s32_t SPIFFS_format(spiffs *fs);
675 * Returns nonzero if spiffs is mounted, or zero if unmounted.
676 * @param fs the file system struct
678 u8_t SPIFFS_mounted(spiffs *fs);
681 * Tries to find a block where most or all pages are deleted, and erase that
682 * block if found. Does not care for wear levelling. Will not move pages
683 * around.
684 * If parameter max_free_pages are set to 0, only blocks with only deleted
685 * pages will be selected.
687 * NB: the garbage collector is automatically called when spiffs needs free
688 * pages. The reason for this function is to give possibility to do background
689 * tidying when user knows the system is idle.
691 * Use with care.
693 * Setting max_free_pages to anything larger than zero will eventually wear
694 * flash more as a block containing free pages can be erased.
696 * Will set err_no to SPIFFS_OK if a block was found and erased,
697 * SPIFFS_ERR_NO_DELETED_BLOCK if no matching block was found,
698 * or other error.
700 * @param fs the file system struct
701 * @param max_free_pages maximum number allowed free pages in block
703 s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages);
706 * Will try to make room for given amount of bytes in the filesystem by moving
707 * pages and erasing blocks.
708 * If it is physically impossible, err_no will be set to SPIFFS_ERR_FULL. If
709 * there already is this amount (or more) of free space, SPIFFS_gc will
710 * silently return. It is recommended to call SPIFFS_info before invoking
711 * this method in order to determine what amount of bytes to give.
713 * NB: the garbage collector is automatically called when spiffs needs free
714 * pages. The reason for this function is to give possibility to do background
715 * tidying when user knows the system is idle.
717 * Use with care.
719 * @param fs the file system struct
720 * @param size amount of bytes that should be freed
722 s32_t SPIFFS_gc(spiffs *fs, u32_t size);
725 * Check if EOF reached.
726 * @param fs the file system struct
727 * @param fh the filehandle of the file to check
729 s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh);
732 * Get position in file.
733 * @param fs the file system struct
734 * @param fh the filehandle of the file to check
736 s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh);
739 * Registers a callback function that keeps track on operations on file
740 * headers. Do note, that this callback is called from within internal spiffs
741 * mechanisms. Any operations on the actual file system being callbacked from
742 * in this callback will mess things up for sure - do not do this.
743 * This can be used to track where files are and move around during garbage
744 * collection, which in turn can be used to build location tables in ram.
745 * Used in conjuction with SPIFFS_open_by_page this may improve performance
746 * when opening a lot of files.
747 * Must be invoked after mount.
749 * @param fs the file system struct
750 * @param cb_func the callback on file operations
752 s32_t SPIFFS_set_file_callback_func(spiffs *fs, spiffs_file_callback cb_func);
754 #if SPIFFS_IX_MAP
757 * Maps the first level index lookup to a given memory map.
758 * This will make reading big files faster, as the memory map will be used for
759 * looking up data pages instead of searching for the indices on the physical
760 * medium. When mapping, all affected indicies are found and the information is
761 * copied to the array.
762 * Whole file or only parts of it may be mapped. The index map will cover file
763 * contents from argument offset until and including arguments (offset+len).
764 * It is valid to map a longer range than the current file size. The map will
765 * then be populated when the file grows.
766 * On garbage collections and file data page movements, the map array will be
767 * automatically updated. Do not tamper with the map array, as this contains
768 * the references to the data pages. Modifying it from outside will corrupt any
769 * future readings using this file descriptor.
770 * The map will no longer be used when the file descriptor closed or the file
771 * is unmapped.
772 * This can be useful to get faster and more deterministic timing when reading
773 * large files, or when seeking and reading a lot within a file.
774 * @param fs the file system struct
775 * @param fh the file handle of the file to map
776 * @param map a spiffs_ix_map struct, describing the index map
777 * @param offset absolute file offset where to start the index map
778 * @param len length of the mapping in actual file bytes
779 * @param map_buf the array buffer for the look up data - number of required
780 * elements in the array can be derived from function
781 * SPIFFS_bytes_to_ix_map_entries given the length
783 s32_t SPIFFS_ix_map(spiffs *fs, spiffs_file fh, spiffs_ix_map *map,
784 u32_t offset, u32_t len, spiffs_page_ix *map_buf);
787 * Unmaps the index lookup from this filehandle. All future readings will
788 * proceed as normal, requiring reading of the first level indices from
789 * physical media.
790 * The map and map buffer given in function SPIFFS_ix_map will no longer be
791 * referenced by spiffs.
792 * It is not strictly necessary to unmap a file before closing it, as closing
793 * a file will automatically unmap it.
794 * @param fs the file system struct
795 * @param fh the file handle of the file to unmap
797 s32_t SPIFFS_ix_unmap(spiffs *fs, spiffs_file fh);
800 * Moves the offset for the index map given in function SPIFFS_ix_map. Parts or
801 * all of the map buffer will repopulated.
802 * @param fs the file system struct
803 * @param fh the mapped file handle of the file to remap
804 * @param offset new absolute file offset where to start the index map
806 s32_t SPIFFS_ix_remap(spiffs *fs, spiffs_file fh, u32_t offset);
809 * Utility function to get number of spiffs_page_ix entries a map buffer must
810 * contain on order to map given amount of file data in bytes.
811 * See function SPIFFS_ix_map and SPIFFS_ix_map_entries_to_bytes.
812 * @param fs the file system struct
813 * @param bytes number of file data bytes to map
814 * @return needed number of elements in a spiffs_page_ix array needed to
815 * map given amount of bytes in a file
817 s32_t SPIFFS_bytes_to_ix_map_entries(spiffs *fs, u32_t bytes);
820 * Utility function to amount of file data bytes that can be mapped when
821 * mapping a file with buffer having given number of spiffs_page_ix entries.
822 * See function SPIFFS_ix_map and SPIFFS_bytes_to_ix_map_entries.
823 * @param fs the file system struct
824 * @param map_page_ix_entries number of entries in a spiffs_page_ix array
825 * @return amount of file data in bytes that can be mapped given a map
826 * buffer having given amount of spiffs_page_ix entries
828 s32_t SPIFFS_ix_map_entries_to_bytes(spiffs *fs, u32_t map_page_ix_entries);
830 #endif // SPIFFS_IX_MAP
833 #if SPIFFS_TEST_VISUALISATION
835 * Prints out a visualization of the filesystem.
836 * @param fs the file system struct
838 s32_t SPIFFS_vis(spiffs *fs);
839 #endif
841 #if SPIFFS_BUFFER_HELP
843 * Returns number of bytes needed for the filedescriptor buffer given
844 * amount of file descriptors.
846 u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
848 #if SPIFFS_CACHE
850 * Returns number of bytes needed for the cache buffer given
851 * amount of cache pages.
853 u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
854 #endif
855 #endif
857 #if SPIFFS_CACHE
858 #endif
859 #if defined(__cplusplus)
861 #endif
863 #endif /* SPIFFS_H_ */