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
73 // spiffs file descriptor flags
75 // spiffs file mode
77 // object 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
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
210  // physical offset in spi flash used for spiffs,
211  // must be on block boundary
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
236 
237  // cursor for free blocks, block index
239  // cursor for free blocks, entry index
241  // cursor when searching, block index
243  // cursor when searching, entry index
245 
246  // primary work buffer, size of a logical page
248  // secondary work buffer, size of a logical page
250  // file descriptor memory area
252  // available file descriptors
254 
255  // last error
257 
258  // current number of free blocks
260  // current number of busy pages
262  // current number of deleted pages
264  // flag indicating that garbage collector is cleaning
266  // max erase count amongst all blocks
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
290  // user data
291  void *user_data;
292  // config magic
295 
296 /* spiffs file status struct */
297 typedef struct {
303 #if SPIFFS_OBJ_META_LEN
305 #endif
306 } spiffs_stat;
307 
314 #if SPIFFS_OBJ_META_LEN
316 #endif
317 };
318 
319 typedef struct {
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
373 s32_t SPIFFS_probe_fs(spiffs_config *config);
374 #endif // SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
375 
392  u8_t *fd_space, u32_t fd_space_size,
393  void *cache, u32_t cache_size,
394  spiffs_check_callback check_cb_f);
395 
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 
436 
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 
498 
507 
514 s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
515 
523 
530 
537 
544 s32_t SPIFFS_rename(spiffs *fs, const char *old, const char *newPath);
545 
546 #if SPIFFS_OBJ_META_LEN
553 s32_t SPIFFS_update_meta(spiffs *fs, const char *name, const void *meta);
554 
561 s32_t SPIFFS_fupdate_meta(spiffs *fs, spiffs_file fh, const void *meta);
562 #endif
563 
569 
575 
585 spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
586 
592 
600 
606 
619 s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used);
620 
635 
641 
665 s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages);
666 
685 
692 
699 
715 
716 #if SPIFFS_IX_MAP
717 
745 s32_t SPIFFS_ix_map(spiffs *fs, spiffs_file fh, spiffs_ix_map *map,
746  u32_t offset, u32_t len, spiffs_page_ix *map_buf);
747 
759 s32_t SPIFFS_ix_unmap(spiffs *fs, spiffs_file fh);
760 
768 s32_t SPIFFS_ix_remap(spiffs *fs, spiffs_file fh, u32_t offs);
769 
779 s32_t SPIFFS_bytes_to_ix_map_entries(spiffs *fs, u32_t bytes);
780 
790 s32_t SPIFFS_ix_map_entries_to_bytes(spiffs *fs, u32_t map_page_ix_entries);
791 
792 #endif // SPIFFS_IX_MAP
793 
794 
795 #if SPIFFS_TEST_VISUALISATION
800 s32_t SPIFFS_vis(spiffs *fs);
801 #endif
802 
803 #if SPIFFS_BUFFER_HELP
808 u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
809 
810 #if SPIFFS_CACHE
815 u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
816 #endif
817 #endif
818 
819 #if SPIFFS_CACHE
820 #endif
821 #if defined(__cplusplus)
822 }
823 #endif
824 
825 #endif /* SPIFFS_H_ */
long map(long x, long in_min, long in_max, long out_min, long out_max)
@ type
or urn:{domain}:service:{serviceType}:{v}
signed short s16_t
Definition: params_test.h:79
unsigned char u8_t
Definition: params_test.h:82
signed int s32_t
Definition: params_test.h:77
unsigned short u16_t
Definition: params_test.h:80
s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s)
spiffs_check_report
Definition: spiffs.h:109
@ SPIFFS_CHECK_PROGRESS
Definition: spiffs.h:110
@ SPIFFS_CHECK_DELETE_PAGE
Definition: spiffs.h:115
@ SPIFFS_CHECK_ERROR
Definition: spiffs.h:111
@ SPIFFS_CHECK_DELETE_BAD_FILE
Definition: spiffs.h:116
@ SPIFFS_CHECK_FIX_LOOKUP
Definition: spiffs.h:113
@ SPIFFS_CHECK_DELETE_ORPHANED_INDEX
Definition: spiffs.h:114
@ SPIFFS_CHECK_FIX_INDEX
Definition: spiffs.h:112
s32_t SPIFFS_set_file_callback_func(spiffs *fs, spiffs_file_callback cb_func)
spiffs_DIR * SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d)
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)
s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh)
s32_t SPIFFS_rename(spiffs *fs, const char *old, const char *newPath)
u8_t spiffs_obj_type
Definition: spiffs.h:78
struct spiffs_t spiffs
s32_t(* spiffs_read)(u32_t addr, u32_t size, u8_t *dst)
Definition: spiffs.h:94
s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s)
s32_t(* spiffs_erase)(u32_t addr, u32_t size)
Definition: spiffs.h:98
spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode)
void SPIFFS_clearerr(spiffs *fs)
u8_t SPIFFS_mounted(spiffs *fs)
void(* spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report, u32_t arg1, u32_t arg2)
Definition: spiffs.h:124
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_errno(spiffs *fs)
u16_t spiffs_flags
Definition: spiffs.h:74
s32_t(* spiffs_write)(u32_t addr, u32_t size, u8_t *src)
Definition: spiffs.h:96
s32_t SPIFFS_format(spiffs *fs)
s32_t SPIFFS_closedir(spiffs_DIR *d)
s32_t SPIFFS_remove(spiffs *fs, const char *path)
void SPIFFS_unmount(spiffs *fs)
s32_t SPIFFS_gc(spiffs *fs, u32_t size)
s32_t SPIFFS_close(spiffs *fs, spiffs_file fh)
s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh)
u16_t spiffs_mode
Definition: spiffs.h:76
s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh)
s32_t SPIFFS_check(spiffs *fs)
spiffs_fileop_type
Definition: spiffs.h:129
@ SPIFFS_CB_UPDATED
Definition: spiffs.h:133
@ SPIFFS_CB_CREATED
Definition: spiffs.h:131
@ SPIFFS_CB_DELETED
Definition: spiffs.h:135
s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len)
s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh)
s32_t SPIFFS_ftruncate(spiffs *fs, spiffs_file fh, u32_t new_size)
s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used)
spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode)
s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode)
struct spiffs_dirent * SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e)
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_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence)
s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages)
spiffs_check_type
Definition: spiffs.h:102
@ SPIFFS_CHECK_INDEX
Definition: spiffs.h:104
@ SPIFFS_CHECK_PAGE
Definition: spiffs.h:105
@ SPIFFS_CHECK_LOOKUP
Definition: spiffs.h:103
s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len)
u16_t spiffs_block_ix
Definition: spiffs_config.h:369
u16_t spiffs_obj_id
Definition: spiffs_config.h:376
#define SPIFFS_OBJ_META_LEN
Definition: spiffs_config.h:165
#define SPIFFS_OBJ_NAME_LEN
Definition: spiffs_config.h:151
u16_t spiffs_span_ix
Definition: spiffs_config.h:380
u16_t spiffs_page_ix
Definition: spiffs_config.h:372
Definition: spiffs.h:319
int entry
Definition: spiffs.h:322
spiffs_block_ix block
Definition: spiffs.h:321
spiffs * fs
Definition: spiffs.h:320
Definition: spiffs.h:200
u32_t log_page_size
Definition: spiffs.h:222
spiffs_read hal_read_f
Definition: spiffs.h:202
u32_t phys_erase_block
Definition: spiffs.h:214
spiffs_erase hal_erase_f
Definition: spiffs.h:206
spiffs_write hal_write_f
Definition: spiffs.h:204
u32_t phys_addr
Definition: spiffs.h:212
u32_t phys_size
Definition: spiffs.h:209
u32_t log_block_size
Definition: spiffs.h:219
Definition: spiffs.h:308
spiffs_obj_type type
Definition: spiffs.h:311
u32_t size
Definition: spiffs.h:312
u8_t name[SPIFFS_OBJ_NAME_LEN]
Definition: spiffs.h:310
spiffs_obj_id obj_id
Definition: spiffs.h:309
spiffs_page_ix pix
Definition: spiffs.h:313
Definition: spiffs.h:297
spiffs_page_ix pix
Definition: spiffs.h:301
spiffs_obj_id obj_id
Definition: spiffs.h:298
u32_t size
Definition: spiffs.h:299
spiffs_obj_type type
Definition: spiffs.h:300
Definition: spiffs.h:231
void * user_data
Definition: spiffs.h:291
spiffs_block_ix free_cursor_block_ix
Definition: spiffs.h:238
u32_t fd_count
Definition: spiffs.h:253
u8_t * fd_space
Definition: spiffs.h:251
u8_t mounted
Definition: spiffs.h:289
u8_t cleaning
Definition: spiffs.h:265
s32_t err_code
Definition: spiffs.h:256
spiffs_check_callback check_cb_f
Definition: spiffs.h:285
u32_t free_blocks
Definition: spiffs.h:259
spiffs_config cfg
Definition: spiffs.h:233
u32_t block_count
Definition: spiffs.h:235
spiffs_obj_id max_erase_count
Definition: spiffs.h:267
int free_cursor_obj_lu_entry
Definition: spiffs.h:240
int cursor_obj_lu_entry
Definition: spiffs.h:244
u8_t * lu_work
Definition: spiffs.h:247
spiffs_file_callback file_cb_f
Definition: spiffs.h:287
spiffs_block_ix cursor_block_ix
Definition: spiffs.h:242
u32_t stats_p_allocated
Definition: spiffs.h:261
u32_t config_magic
Definition: spiffs.h:293
u32_t stats_p_deleted
Definition: spiffs.h:263
u8_t * work
Definition: spiffs.h:249