spiffs.h
Go to the documentation of this file.
1 /*
2  * spiffs.h
3  *
4  * Created on: May 26, 2013
5  * Author: petera
6  */
7 
8 #ifndef SPIFFS_H_
9 #define SPIFFS_H_
10 #if defined(__cplusplus)
11 extern "C" {
12 #endif
13 
14 #include "spiffs_config.h"
15 
16 #define SPIFFS_OK 0
17 #define SPIFFS_ERR_NOT_MOUNTED -10000
18 #define SPIFFS_ERR_FULL -10001
19 #define SPIFFS_ERR_NOT_FOUND -10002
20 #define SPIFFS_ERR_END_OF_OBJECT -10003
21 #define SPIFFS_ERR_DELETED -10004
22 #define SPIFFS_ERR_NOT_FINALIZED -10005
23 #define SPIFFS_ERR_NOT_INDEX -10006
24 #define SPIFFS_ERR_OUT_OF_FILE_DESCS -10007
25 #define SPIFFS_ERR_FILE_CLOSED -10008
26 #define SPIFFS_ERR_FILE_DELETED -10009
27 #define SPIFFS_ERR_BAD_DESCRIPTOR -10010
28 #define SPIFFS_ERR_IS_INDEX -10011
29 #define SPIFFS_ERR_IS_FREE -10012
30 #define SPIFFS_ERR_INDEX_SPAN_MISMATCH -10013
31 #define SPIFFS_ERR_DATA_SPAN_MISMATCH -10014
32 #define SPIFFS_ERR_INDEX_REF_FREE -10015
33 #define SPIFFS_ERR_INDEX_REF_LU -10016
34 #define SPIFFS_ERR_INDEX_REF_INVALID -10017
35 #define SPIFFS_ERR_INDEX_FREE -10018
36 #define SPIFFS_ERR_INDEX_LU -10019
37 #define SPIFFS_ERR_INDEX_INVALID -10020
38 #define SPIFFS_ERR_NOT_WRITABLE -10021
39 #define SPIFFS_ERR_NOT_READABLE -10022
40 #define SPIFFS_ERR_CONFLICTING_NAME -10023
41 #define SPIFFS_ERR_NOT_CONFIGURED -10024
42 
43 #define SPIFFS_ERR_NOT_A_FS -10025
44 #define SPIFFS_ERR_MOUNTED -10026
45 #define SPIFFS_ERR_ERASE_FAIL -10027
46 #define SPIFFS_ERR_MAGIC_NOT_POSSIBLE -10028
47 
48 #define SPIFFS_ERR_NO_DELETED_BLOCKS -10029
49 
50 #define SPIFFS_ERR_FILE_EXISTS -10030
51 
52 #define SPIFFS_ERR_NOT_A_FILE -10031
53 #define SPIFFS_ERR_RO_NOT_IMPL -10032
54 #define SPIFFS_ERR_RO_ABORTED_OPERATION -10033
55 #define SPIFFS_ERR_PROBE_TOO_FEW_BLOCKS -10034
56 #define SPIFFS_ERR_PROBE_NOT_A_FS -10035
57 #define SPIFFS_ERR_NAME_TOO_LONG -10036
58 
59 #define SPIFFS_ERR_IX_MAP_UNMAPPED -10037
60 #define SPIFFS_ERR_IX_MAP_MAPPED -10038
61 #define SPIFFS_ERR_IX_MAP_BAD_RANGE -10039
62 
63 #define SPIFFS_ERR_SEEK_BOUNDS -10040
64 
65 
66 #define SPIFFS_ERR_INTERNAL -10050
67 
68 #define SPIFFS_ERR_TEST -10100
69 
70 
71 // spiffs file descriptor index type. must be signed
72 typedef s16_t spiffs_file;
73 // spiffs file descriptor flags
74 typedef u16_t spiffs_flags;
75 // spiffs file mode
76 typedef u16_t spiffs_mode;
77 // object type
78 typedef u8_t spiffs_obj_type;
79 
80 struct spiffs_t;
81 
82 #if SPIFFS_HAL_CALLBACK_EXTRA
83 
84 /* spi read call function type */
85 typedef s32_t (*spiffs_read)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *dst);
86 /* spi write call function type */
87 typedef s32_t (*spiffs_write)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *src);
88 /* spi erase call function type */
89 typedef s32_t (*spiffs_erase)(struct spiffs_t *fs, u32_t addr, u32_t size);
90 
91 #else // SPIFFS_HAL_CALLBACK_EXTRA
92 
93 /* spi read call function type */
94 typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
95 /* spi write call function type */
96 typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
97 /* spi erase call function type */
98 typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
99 #endif // SPIFFS_HAL_CALLBACK_EXTRA
100 
101 /* file system check callback report operation */
102 typedef enum {
107 
108 /* file system check callback report type */
109 typedef enum {
118 
119 /* file system check callback function */
120 #if SPIFFS_HAL_CALLBACK_EXTRA
121 typedef void (*spiffs_check_callback)(struct spiffs_t *fs, spiffs_check_type type, spiffs_check_report report,
122  u32_t arg1, u32_t arg2);
123 #else // SPIFFS_HAL_CALLBACK_EXTRA
124 typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
125  u32_t arg1, u32_t arg2);
126 #endif // SPIFFS_HAL_CALLBACK_EXTRA
127 
128 /* file system listener callback operation */
129 typedef enum {
130  /* the file has been created */
132  /* the file has been updated or moved to another page */
134  /* the file has been deleted */
137 
138 /* file system listener callback function */
139 typedef void (*spiffs_file_callback)(struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix);
140 
141 #ifndef SPIFFS_DBG
142 #define SPIFFS_DBG(...) \
143  printf(__VA_ARGS__)
144 #endif
145 #ifndef SPIFFS_GC_DBG
146 #define SPIFFS_GC_DBG(...) printf(__VA_ARGS__)
147 #endif
148 #ifndef SPIFFS_CACHE_DBG
149 #define SPIFFS_CACHE_DBG(...) printf(__VA_ARGS__)
150 #endif
151 #ifndef SPIFFS_CHECK_DBG
152 #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
153 #endif
154 
155 /* Any write to the filehandle is appended to end of the file */
156 #define SPIFFS_APPEND (1<<0)
157 #define SPIFFS_O_APPEND SPIFFS_APPEND
158 /* If the opened file exists, it will be truncated to zero length before opened */
159 #define SPIFFS_TRUNC (1<<1)
160 #define SPIFFS_O_TRUNC SPIFFS_TRUNC
161 /* If the opened file does not exist, it will be created before opened */
162 #define SPIFFS_CREAT (1<<2)
163 #define SPIFFS_O_CREAT SPIFFS_CREAT
164 /* The opened file may only be read */
165 #define SPIFFS_RDONLY (1<<3)
166 #define SPIFFS_O_RDONLY SPIFFS_RDONLY
167 /* The opened file may only be written */
168 #define SPIFFS_WRONLY (1<<4)
169 #define SPIFFS_O_WRONLY SPIFFS_WRONLY
170 /* The opened file may be both read and written */
171 #define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY)
172 #define SPIFFS_O_RDWR SPIFFS_RDWR
173 /* Any writes to the filehandle will never be cached but flushed directly */
174 #define SPIFFS_DIRECT (1<<5)
175 #define SPIFFS_O_DIRECT SPIFFS_DIRECT
176 /* If SPIFFS_O_CREAT and SPIFFS_O_EXCL are set, SPIFFS_open() shall fail if the file exists */
177 #define SPIFFS_EXCL (1<<6)
178 #define SPIFFS_O_EXCL SPIFFS_EXCL
179 
180 #define SPIFFS_SEEK_SET (0)
181 #define SPIFFS_SEEK_CUR (1)
182 #define SPIFFS_SEEK_END (2)
183 
184 #define SPIFFS_TYPE_FILE (1)
185 #define SPIFFS_TYPE_DIR (2)
186 #define SPIFFS_TYPE_HARD_LINK (3)
187 #define SPIFFS_TYPE_SOFT_LINK (4)
188 
189 #ifndef SPIFFS_LOCK
190 #define SPIFFS_LOCK(fs)
191 #endif
192 
193 #ifndef SPIFFS_UNLOCK
194 #define SPIFFS_UNLOCK(fs)
195 #endif
196 
197 // phys structs
198 
199 // spiffs spi configuration struct
200 typedef struct {
201  // physical read function
203  // physical write function
205  // physical erase function
207 #if SPIFFS_SINGLETON == 0
208  // physical size of the spi flash
209  u32_t phys_size;
210  // physical offset in spi flash used for spiffs,
211  // must be on block boundary
212  u32_t phys_addr;
213  // physical size when erasing a block
215 
216  // logical size of a block, must be on physical
217  // block size boundary and must never be less than
218  // a physical block
220  // logical size of a page, must be at least
221  // log_block_size / 8
223 
224 #endif
225 #if SPIFFS_FILEHDL_OFFSET
226  // an integer offset added to each file handle
227  u16_t fh_ix_offset;
228 #endif
229 } spiffs_config;
230 
231 typedef struct spiffs_t {
232  // file system configuration
234  // number of logical blocks
235  u32_t block_count;
236 
237  // cursor for free blocks, block index
238  spiffs_block_ix free_cursor_block_ix;
239  // cursor for free blocks, entry index
241  // cursor when searching, block index
242  spiffs_block_ix cursor_block_ix;
243  // cursor when searching, entry index
245 
246  // primary work buffer, size of a logical page
247  u8_t *lu_work;
248  // secondary work buffer, size of a logical page
249  u8_t *work;
250  // file descriptor memory area
251  u8_t *fd_space;
252  // available file descriptors
253  u32_t fd_count;
254 
255  // last error
256  s32_t err_code;
257 
258  // current number of free blocks
259  u32_t free_blocks;
260  // current number of busy pages
262  // current number of deleted pages
264  // flag indicating that garbage collector is cleaning
265  u8_t cleaning;
266  // max erase count amongst all blocks
267  spiffs_obj_id max_erase_count;
268 
269 #if SPIFFS_GC_STATS
270  u32_t stats_gc_runs;
271 #endif
272 
273 #if SPIFFS_CACHE
274  // cache memory
275  void *cache;
276  // cache size
277  u32_t cache_size;
278 #if SPIFFS_CACHE_STATS
279  u32_t cache_hits;
280  u32_t cache_misses;
281 #endif
282 #endif
283 
284  // check callback function
286  // file callback function
288  // mounted flag
289  u8_t mounted;
290  // user data
291  void *user_data;
292  // config magic
294 } spiffs;
295 
296 /* spiffs file status struct */
297 typedef struct {
298  spiffs_obj_id obj_id;
299  u32_t size;
300  spiffs_obj_type type;
301  spiffs_page_ix pix;
302  u8_t name[SPIFFS_OBJ_NAME_LEN];
303 #if SPIFFS_OBJ_META_LEN
304  u8_t meta[SPIFFS_OBJ_META_LEN];
305 #endif
306 } spiffs_stat;
307 
309  spiffs_obj_id obj_id;
310  u8_t name[SPIFFS_OBJ_NAME_LEN];
311  spiffs_obj_type type;
312  u32_t size;
313  spiffs_page_ix pix;
314 #if SPIFFS_OBJ_META_LEN
315  u8_t meta[SPIFFS_OBJ_META_LEN];
316 #endif
317 };
318 
319 typedef struct {
321  spiffs_block_ix block;
322  int entry;
323 } spiffs_DIR;
324 
325 #if SPIFFS_IX_MAP
326 
327 typedef struct {
328  // buffer with looked up data pixes
329  spiffs_page_ix *map_buf;
330  // precise file byte offset
331  u32_t offset;
332  // start data span index of lookup buffer
333  spiffs_span_ix start_spix;
334  // end data span index of lookup buffer
335  spiffs_span_ix end_spix;
336 } spiffs_ix_map;
337 
338 #endif
339 
340 // functions
341 
342 #if SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
343 
373 s32_t SPIFFS_probe_fs(spiffs_config *config);
374 #endif // SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
375 
391 s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
392  u8_t *fd_space, u32_t fd_space_size,
393  void *cache, u32_t cache_size,
395 
401 void SPIFFS_unmount(spiffs *fs);
402 
409 s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode);
410 
420 spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode);
421 
435 spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode);
436 
451 spiffs_file SPIFFS_open_by_page(spiffs *fs, spiffs_page_ix page_ix, spiffs_flags flags, spiffs_mode mode);
452 
461 s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
462 
471 s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
472 
483 s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
484 
490 s32_t SPIFFS_remove(spiffs *fs, const char *path);
491 
497 s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
498 
505 s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
506 
513 s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
514 
520 s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
521 
527 s32_t SPIFFS_close(spiffs *fs, spiffs_file fh);
528 
535 s32_t SPIFFS_rename(spiffs *fs, const char *old, const char *newPath);
536 
537 #if SPIFFS_OBJ_META_LEN
538 
544 s32_t SPIFFS_update_meta(spiffs *fs, const char *name, const void *meta);
545 
552 s32_t SPIFFS_fupdate_meta(spiffs *fs, spiffs_file fh, const void *meta);
553 #endif
554 
559 s32_t SPIFFS_errno(spiffs *fs);
560 
565 void SPIFFS_clearerr(spiffs *fs);
566 
576 spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
577 
582 s32_t SPIFFS_closedir(spiffs_DIR *d);
583 
591 
596 s32_t SPIFFS_check(spiffs *fs);
597 
610 s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used);
611 
625 s32_t SPIFFS_format(spiffs *fs);
626 
631 u8_t SPIFFS_mounted(spiffs *fs);
632 
656 s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages);
657 
675 s32_t SPIFFS_gc(spiffs *fs, u32_t size);
676 
682 s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh);
683 
689 s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh);
690 
706 
707 #if SPIFFS_IX_MAP
708 
736 s32_t SPIFFS_ix_map(spiffs *fs, spiffs_file fh, spiffs_ix_map *map,
737  u32_t offset, u32_t len, spiffs_page_ix *map_buf);
738 
750 s32_t SPIFFS_ix_unmap(spiffs *fs, spiffs_file fh);
751 
759 s32_t SPIFFS_ix_remap(spiffs *fs, spiffs_file fh, u32_t offs);
760 
770 s32_t SPIFFS_bytes_to_ix_map_entries(spiffs *fs, u32_t bytes);
771 
781 s32_t SPIFFS_ix_map_entries_to_bytes(spiffs *fs, u32_t map_page_ix_entries);
782 
783 #endif // SPIFFS_IX_MAP
784 
785 
786 #if SPIFFS_TEST_VISUALISATION
787 
791 s32_t SPIFFS_vis(spiffs *fs);
792 #endif
793 
794 #if SPIFFS_BUFFER_HELP
795 
799 u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
800 
801 #if SPIFFS_CACHE
802 
806 u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
807 #endif
808 #endif
809 
810 #if SPIFFS_CACHE
811 #endif
812 #if defined(__cplusplus)
813 }
814 #endif
815 
816 #endif /* SPIFFS_H_ */
s32_t SPIFFS_set_file_callback_func(spiffs *fs, spiffs_file_callback cb_func)
s32_t SPIFFS_close(spiffs *fs, spiffs_file fh)
u32_t size
Definition: spiffs.h:312
s32_t SPIFFS_closedir(spiffs_DIR *d)
Definition: spiffs.h:135
spiffs * fs
Definition: spiffs.h:320
spiffs_fileop_type
Definition: spiffs.h:129
u8_t spiffs_obj_type
Definition: spiffs.h:78
Definition: spiffs.h:103
u8_t SPIFFS_mounted(spiffs *fs)
u32_t free_blocks
Definition: spiffs.h:259
s32_t SPIFFS_remove(spiffs *fs, const char *path)
u8_t * lu_work
Definition: spiffs.h:247
s32_t SPIFFS_check(spiffs *fs)
s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh)
Definition: spiffs.h:200
Definition: spiffs.h:110
s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode)
spiffs_obj_id max_erase_count
Definition: spiffs.h:267
s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used)
u32_t log_block_size
Definition: spiffs.h:219
Definition: spiffs.h:319
Definition: spiffs.h:104
s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh)
Definition: spiffs.h:112
spiffs_block_ix block
Definition: spiffs.h:321
void * user_data
Definition: spiffs.h:291
Definition: spiffs.h:105
u32_t fd_count
Definition: spiffs.h:253
int cursor_obj_lu_entry
Definition: spiffs.h:244
u8_t * work
Definition: spiffs.h:249
Definition: spiffs.h:297
spiffs_file_callback file_cb_f
Definition: spiffs.h:287
s32_t SPIFFS_format(spiffs *fs)
Definition: spiffs.h:113
spiffs_write hal_write_f
Definition: spiffs.h:204
s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh)
struct spiffs_dirent * SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e)
spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode)
void SPIFFS_clearerr(spiffs *fs)
void(* spiffs_file_callback)(struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix)
Definition: spiffs.h:139
s32_t(* spiffs_write)(u32_t addr, u32_t size, u8_t *src)
Definition: spiffs.h:96
Definition: spiffs.h:231
u16_t spiffs_mode
Definition: spiffs.h:76
spiffs_DIR * SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d)
spiffs_obj_type type
Definition: spiffs.h:311
Definition: spiffs.h:308
Definition: spiffs.h:133
u32_t stats_p_deleted
Definition: spiffs.h:263
spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode)
spiffs_erase hal_erase_f
Definition: spiffs.h:206
struct spiffs_t spiffs
s32_t SPIFFS_errno(spiffs *fs)
spiffs_check_type
Definition: spiffs.h:102
spiffs_obj_type type
Definition: spiffs.h:300
u32_t phys_addr
Definition: spiffs.h:212
u8_t cleaning
Definition: spiffs.h:265
spiffs_check_callback check_cb_f
Definition: spiffs.h:285
Definition: spiffs.h:131
s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work, u8_t *fd_space, u32_t fd_space_size, void *cache, u32_t cache_size, spiffs_check_callback check_cb_f)
spiffs_page_ix pix
Definition: spiffs.h:313
s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len)
void SPIFFS_unmount(spiffs *fs)
spiffs_config cfg
Definition: spiffs.h:233
u8_t * fd_space
Definition: spiffs.h:251
s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len)
s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence)
s32_t(* spiffs_read)(u32_t addr, u32_t size, u8_t *dst)
Definition: spiffs.h:94
u32_t size
Definition: spiffs.h:299
spiffs_check_report
Definition: spiffs.h:109
Definition: spiffs.h:115
spiffs_block_ix cursor_block_ix
Definition: spiffs.h:242
u16_t spiffs_flags
Definition: spiffs.h:74
s32_t SPIFFS_gc(spiffs *fs, u32_t size)
u32_t phys_erase_block
Definition: spiffs.h:214
Definition: spiffs.h:116
u32_t stats_p_allocated
Definition: spiffs.h:261
u32_t log_page_size
Definition: spiffs.h:222
s32_t err_code
Definition: spiffs.h:256
s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s)
spiffs_block_ix free_cursor_block_ix
Definition: spiffs.h:238
int free_cursor_obj_lu_entry
Definition: spiffs.h:240
u8_t mounted
Definition: spiffs.h:289
spiffs_read hal_read_f
Definition: spiffs.h:202
s32_t SPIFFS_rename(spiffs *fs, const char *old, const char *newPath)
spiffs_page_ix pix
Definition: spiffs.h:301
spiffs_file SPIFFS_open_by_page(spiffs *fs, spiffs_page_ix page_ix, spiffs_flags flags, spiffs_mode mode)
s16_t spiffs_file
Definition: spiffs.h:72
s32_t(* spiffs_erase)(u32_t addr, u32_t size)
Definition: spiffs.h:98
Definition: spiffs.h:111
s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s)
u32_t phys_size
Definition: spiffs.h:209
s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh)
u32_t config_magic
Definition: spiffs.h:293
int entry
Definition: spiffs.h:322
s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages)
spiffs_obj_id obj_id
Definition: spiffs.h:298
u32_t block_count
Definition: spiffs.h:235
spiffs_obj_id obj_id
Definition: spiffs.h:309
Definition: spiffs.h:114
void(* spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report, u32_t arg1, u32_t arg2)
Definition: spiffs.h:124
© Copyright 1995-2018, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale