ESP8266
spiffs.h
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_INTERNAL -10050
53 
54 #define SPIFFS_ERR_TEST -10100
55 
56 
57 // spiffs file descriptor index type. must be signed
58 typedef s16_t spiffs_file;
59 // spiffs file descriptor flags
60 typedef u16_t spiffs_flags;
61 // spiffs file mode
62 typedef u16_t spiffs_mode;
63 // object type
64 typedef u8_t spiffs_obj_type;
65 
66 #if SPIFFS_HAL_CALLBACK_EXTRA
67 struct spiffs_t;
68 
69 /* spi read call function type */
70 typedef s32_t (*spiffs_read)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *dst);
71 /* spi write call function type */
72 typedef s32_t (*spiffs_write)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *src);
73 /* spi erase call function type */
74 typedef s32_t (*spiffs_erase)(struct spiffs_t *fs, u32_t addr, u32_t size);
75 
76 #else // SPIFFS_HAL_CALLBACK_EXTRA
77 
78 /* spi read call function type */
79 typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
80 /* spi write call function type */
81 typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
82 /* spi erase call function type */
83 typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
84 #endif // SPIFFS_HAL_CALLBACK_EXTRA
85 
86 /* file system check callback report operation */
87 typedef enum {
88  SPIFFS_CHECK_LOOKUP = 0,
89  SPIFFS_CHECK_INDEX,
90  SPIFFS_CHECK_PAGE
91 } spiffs_check_type;
92 
93 /* file system check callback report type */
94 typedef enum {
95  SPIFFS_CHECK_PROGRESS = 0,
96  SPIFFS_CHECK_ERROR,
97  SPIFFS_CHECK_FIX_INDEX,
98  SPIFFS_CHECK_FIX_LOOKUP,
99  SPIFFS_CHECK_DELETE_ORPHANED_INDEX,
100  SPIFFS_CHECK_DELETE_PAGE,
101  SPIFFS_CHECK_DELETE_BAD_FILE,
102 } spiffs_check_report;
103 
104 /* file system check callback function */
105 #if SPIFFS_HAL_CALLBACK_EXTRA
106 typedef void (*spiffs_check_callback)(struct spiffs_t *fs, spiffs_check_type type, spiffs_check_report report,
107  u32_t arg1, u32_t arg2);
108 #else // SPIFFS_HAL_CALLBACK_EXTRA
109 typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
110  u32_t arg1, u32_t arg2);
111 #endif // SPIFFS_HAL_CALLBACK_EXTRA
112 
113 #ifndef SPIFFS_DBG
114 #define SPIFFS_DBG(...) \
115  print(__VA_ARGS__)
116 #endif
117 #ifndef SPIFFS_GC_DBG
118 #define SPIFFS_GC_DBG(...) printf(__VA_ARGS__)
119 #endif
120 #ifndef SPIFFS_CACHE_DBG
121 #define SPIFFS_CACHE_DBG(...) printf(__VA_ARGS__)
122 #endif
123 #ifndef SPIFFS_CHECK_DBG
124 #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
125 #endif
126 
127 /* Any write to the filehandle is appended to end of the file */
128 #define SPIFFS_APPEND (1<<0)
129 /* If the opened file exists, it will be truncated to zero length before opened */
130 #define SPIFFS_TRUNC (1<<1)
131 /* If the opened file does not exist, it will be created before opened */
132 #define SPIFFS_CREAT (1<<2)
133 /* The opened file may only be read */
134 #define SPIFFS_RDONLY (1<<3)
135 /* The opened file may only be writted */
136 #define SPIFFS_WRONLY (1<<4)
137 /* The opened file may be both read and writted */
138 #define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY)
139 /* Any writes to the filehandle will never be cached */
140 #define SPIFFS_DIRECT (1<<5)
141 /* If SPIFFS_CREAT and SPIFFS_EXCL are set, SPIFFS_open() shall fail if the file exists */
142 #define SPIFFS_EXCL (1<<6)
143 
144 #define SPIFFS_SEEK_SET (0)
145 #define SPIFFS_SEEK_CUR (1)
146 #define SPIFFS_SEEK_END (2)
147 
148 #define SPIFFS_TYPE_FILE (1)
149 #define SPIFFS_TYPE_DIR (2)
150 #define SPIFFS_TYPE_HARD_LINK (3)
151 #define SPIFFS_TYPE_SOFT_LINK (4)
152 
153 #ifndef SPIFFS_LOCK
154 #define SPIFFS_LOCK(fs)
155 #endif
156 
157 #ifndef SPIFFS_UNLOCK
158 #define SPIFFS_UNLOCK(fs)
159 #endif
160 
161 // phys structs
162 
163 // spiffs spi configuration struct
164 typedef struct {
165  // physical read function
166  spiffs_read hal_read_f;
167  // physical write function
168  spiffs_write hal_write_f;
169  // physical erase function
170  spiffs_erase hal_erase_f;
171 #if SPIFFS_SINGLETON == 0
172  // physical size of the spi flash
173  u32_t phys_size;
174  // physical offset in spi flash used for spiffs,
175  // must be on block boundary
176  u32_t phys_addr;
177  // physical size when erasing a block
179 
180  // logical size of a block, must be on physical
181  // block size boundary and must never be less than
182  // a physical block
184  // logical size of a page, must be at least
185  // log_block_size / 8
187 
188 #endif
189 #if SPIFFS_FILEHDL_OFFSET
190  // an integer offset added to each file handle
191  u16_t fh_ix_offset;
192 #endif
193 } spiffs_config;
194 
195 typedef struct spiffs_t {
196  // file system configuration
198  // number of logical blocks
199  u32_t block_count;
200 
201  // cursor for free blocks, block index
202  spiffs_block_ix free_cursor_block_ix;
203  // cursor for free blocks, entry index
205  // cursor when searching, block index
206  spiffs_block_ix cursor_block_ix;
207  // cursor when searching, entry index
209 
210  // primary work buffer, size of a logical page
211  u8_t *lu_work;
212  // secondary work buffer, size of a logical page
213  u8_t *work;
214  // file descriptor memory area
215  u8_t *fd_space;
216  // available file descriptors
217  u32_t fd_count;
218 
219  // last error
220  s32_t err_code;
221 
222  // current number of free blocks
223  u32_t free_blocks;
224  // current number of busy pages
226  // current number of deleted pages
228  // flag indicating that garbage collector is cleaning
229  u8_t cleaning;
230  // max erase count amongst all blocks
231  spiffs_obj_id max_erase_count;
232 
233 #if SPIFFS_GC_STATS
234  u32_t stats_gc_runs;
235 #endif
236 
237 #if SPIFFS_CACHE
238  // cache memory
239  void *cache;
240  // cache size
241  u32_t cache_size;
242 #if SPIFFS_CACHE_STATS
243  u32_t cache_hits;
244  u32_t cache_misses;
245 #endif
246 #endif
247 
248  // check callback function
249  spiffs_check_callback check_cb_f;
250 
251  // mounted flag
252  u8_t mounted;
253  // user data
254  void *user_data;
255  // config magic
257 } spiffs;
258 
259 /* spiffs file status struct */
260 typedef struct {
261  spiffs_obj_id obj_id;
262  u32_t size;
263  spiffs_obj_type type;
264  u8_t name[SPIFFS_OBJ_NAME_LEN];
265 } spiffs_stat;
266 
268  spiffs_obj_id obj_id;
269  u8_t name[SPIFFS_OBJ_NAME_LEN];
270  spiffs_obj_type type;
271  u32_t size;
272  spiffs_page_ix pix;
273 };
274 
275 typedef struct {
277  spiffs_block_ix block;
278  int entry;
279 } spiffs_DIR;
280 
281 // functions
282 
298 s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
299  u8_t *fd_space, u32_t fd_space_size,
300  void *cache, u32_t cache_size,
301  spiffs_check_callback check_cb_f);
302 
308 void SPIFFS_unmount(spiffs *fs);
309 
316 s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode);
317 
327 spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode);
328 
329 
343 spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode);
344 
353 s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
354 
363 s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
364 
375 s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
376 
382 s32_t SPIFFS_remove(spiffs *fs, const char *path);
383 
389 s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
390 
397 s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
398 
405 s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
406 
412 s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
413 
419 s32_t SPIFFS_close(spiffs *fs, spiffs_file fh);
420 
427 s32_t SPIFFS_rename(spiffs *fs, const char *old, const char *newPath);
428 
433 s32_t SPIFFS_errno(spiffs *fs);
434 
439 void SPIFFS_clearerr(spiffs *fs);
440 
450 spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
451 
456 s32_t SPIFFS_closedir(spiffs_DIR *d);
457 
464 struct spiffs_dirent *SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e);
465 
470 s32_t SPIFFS_check(spiffs *fs);
471 
484 s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used);
485 
499 s32_t SPIFFS_format(spiffs *fs);
500 
505 u8_t SPIFFS_mounted(spiffs *fs);
506 
530 s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages);
531 
549 s32_t SPIFFS_gc(spiffs *fs, u32_t size);
550 
556 s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh);
557 
563 s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh);
564 
565 #if SPIFFS_TEST_VISUALISATION
566 
570 s32_t SPIFFS_vis(spiffs *fs);
571 #endif
572 
573 #if SPIFFS_BUFFER_HELP
574 
578 u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
579 
580 #if SPIFFS_CACHE
581 
585 u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
586 #endif
587 #endif
588 
589 #if SPIFFS_CACHE
590 #endif
591 #if defined(__cplusplus)
592 }
593 #endif
594 
595 #endif /* SPIFFS_H_ */
u32_t size
Definition: spiffs.h:271
spiffs * fs
Definition: spiffs.h:276
u32_t free_blocks
Definition: spiffs.h:223
u8_t * lu_work
Definition: spiffs.h:211
Definition: spiffs.h:164
spiffs_obj_id max_erase_count
Definition: spiffs.h:231
u32_t log_block_size
Definition: spiffs.h:183
Definition: spiffs.h:275
u8_t name[(32)]
Definition: spiffs.h:269
spiffs_block_ix block
Definition: spiffs.h:277
void * user_data
Definition: spiffs.h:254
u32_t fd_count
Definition: spiffs.h:217
int cursor_obj_lu_entry
Definition: spiffs.h:208
u8_t * work
Definition: spiffs.h:213
Definition: spiffs.h:260
spiffs_write hal_write_f
Definition: spiffs.h:168
Definition: ESP8266WebServer.h:55
Definition: spiffs.h:195
u32_t cache_size
Definition: spiffs.h:241
spiffs_obj_type type
Definition: spiffs.h:270
Definition: spiffs.h:267
u32_t stats_p_deleted
Definition: spiffs.h:227
spiffs_erase hal_erase_f
Definition: spiffs.h:170
spiffs_obj_type type
Definition: spiffs.h:263
u32_t phys_addr
Definition: spiffs.h:176
u8_t cleaning
Definition: spiffs.h:229
spiffs_check_callback check_cb_f
Definition: spiffs.h:249
spiffs_page_ix pix
Definition: spiffs.h:272
spiffs_config cfg
Definition: spiffs.h:197
u8_t * fd_space
Definition: spiffs.h:215
u32_t size
Definition: spiffs.h:262
spiffs_block_ix cursor_block_ix
Definition: spiffs.h:206
u32_t phys_erase_block
Definition: spiffs.h:178
u32_t stats_p_allocated
Definition: spiffs.h:225
u32_t log_page_size
Definition: spiffs.h:186
s32_t err_code
Definition: spiffs.h:220
spiffs_block_ix free_cursor_block_ix
Definition: spiffs.h:202
int free_cursor_obj_lu_entry
Definition: spiffs.h:204
u8_t mounted
Definition: spiffs.h:252
spiffs_read hal_read_f
Definition: spiffs.h:166
void * cache
Definition: spiffs.h:239
u32_t phys_size
Definition: spiffs.h:173
u32_t config_magic
Definition: spiffs.h:256
int entry
Definition: spiffs.h:278
spiffs_obj_id obj_id
Definition: spiffs.h:261
u32_t block_count
Definition: spiffs.h:199
spiffs_obj_id obj_id
Definition: spiffs.h:268