spiffs.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584
  1. /*
  2. * spiffs.h
  3. *
  4. * Created on: May 26, 2013
  5. * Author: petera
  6. */
  7. #ifndef SPIFFS_H_
  8. #define SPIFFS_H_
  9. #if defined(__cplusplus)
  10. extern "C" {
  11. #endif
  12. #include "spiffs_config.h"
  13. #define SPIFFS_OK 0
  14. #define SPIFFS_ERR_NOT_MOUNTED -10000
  15. #define SPIFFS_ERR_FULL -10001
  16. #define SPIFFS_ERR_NOT_FOUND -10002
  17. #define SPIFFS_ERR_END_OF_OBJECT -10003
  18. #define SPIFFS_ERR_DELETED -10004
  19. #define SPIFFS_ERR_NOT_FINALIZED -10005
  20. #define SPIFFS_ERR_NOT_INDEX -10006
  21. #define SPIFFS_ERR_OUT_OF_FILE_DESCS -10007
  22. #define SPIFFS_ERR_FILE_CLOSED -10008
  23. #define SPIFFS_ERR_FILE_DELETED -10009
  24. #define SPIFFS_ERR_BAD_DESCRIPTOR -10010
  25. #define SPIFFS_ERR_IS_INDEX -10011
  26. #define SPIFFS_ERR_IS_FREE -10012
  27. #define SPIFFS_ERR_INDEX_SPAN_MISMATCH -10013
  28. #define SPIFFS_ERR_DATA_SPAN_MISMATCH -10014
  29. #define SPIFFS_ERR_INDEX_REF_FREE -10015
  30. #define SPIFFS_ERR_INDEX_REF_LU -10016
  31. #define SPIFFS_ERR_INDEX_REF_INVALID -10017
  32. #define SPIFFS_ERR_INDEX_FREE -10018
  33. #define SPIFFS_ERR_INDEX_LU -10019
  34. #define SPIFFS_ERR_INDEX_INVALID -10020
  35. #define SPIFFS_ERR_NOT_WRITABLE -10021
  36. #define SPIFFS_ERR_NOT_READABLE -10022
  37. #define SPIFFS_ERR_CONFLICTING_NAME -10023
  38. #define SPIFFS_ERR_NOT_CONFIGURED -10024
  39. #define SPIFFS_ERR_NOT_A_FS -10025
  40. #define SPIFFS_ERR_MOUNTED -10026
  41. #define SPIFFS_ERR_ERASE_FAIL -10027
  42. #define SPIFFS_ERR_MAGIC_NOT_POSSIBLE -10028
  43. #define SPIFFS_ERR_NO_DELETED_BLOCKS -10029
  44. #define SPIFFS_ERR_INTERNAL -10050
  45. #define SPIFFS_ERR_TEST -10100
  46. // spiffs file descriptor index type. must be signed
  47. typedef s16_t spiffs_file;
  48. // spiffs file descriptor flags
  49. typedef u16_t spiffs_flags;
  50. // spiffs file mode
  51. typedef u16_t spiffs_mode;
  52. // object type
  53. typedef u8_t spiffs_obj_type;
  54. /* spi read call function type */
  55. typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
  56. /* spi write call function type */
  57. typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
  58. /* spi erase call function type */
  59. typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
  60. /* file system check callback report operation */
  61. typedef enum {
  62. SPIFFS_CHECK_LOOKUP = 0,
  63. SPIFFS_CHECK_INDEX,
  64. SPIFFS_CHECK_PAGE
  65. } spiffs_check_type;
  66. /* file system check callback report type */
  67. typedef enum {
  68. SPIFFS_CHECK_PROGRESS = 0,
  69. SPIFFS_CHECK_ERROR,
  70. SPIFFS_CHECK_FIX_INDEX,
  71. SPIFFS_CHECK_FIX_LOOKUP,
  72. SPIFFS_CHECK_DELETE_ORPHANED_INDEX,
  73. SPIFFS_CHECK_DELETE_PAGE,
  74. SPIFFS_CHECK_DELETE_BAD_FILE,
  75. } spiffs_check_report;
  76. /* file system check callback function */
  77. typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
  78. u32_t arg1, u32_t arg2);
  79. #ifndef SPIFFS_DBG
  80. #define SPIFFS_DBG(...) \
  81. print(__VA_ARGS__)
  82. #endif
  83. #ifndef SPIFFS_GC_DBG
  84. #define SPIFFS_GC_DBG(...) printf(__VA_ARGS__)
  85. #endif
  86. #ifndef SPIFFS_CACHE_DBG
  87. #define SPIFFS_CACHE_DBG(...) printf(__VA_ARGS__)
  88. #endif
  89. #ifndef SPIFFS_CHECK_DBG
  90. #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
  91. #endif
  92. /* Any write to the filehandle is appended to end of the file */
  93. #define SPIFFS_APPEND (1<<0)
  94. /* If the opened file exists, it will be truncated to zero length before opened */
  95. #define SPIFFS_TRUNC (1<<1)
  96. /* If the opened file does not exist, it will be created before opened */
  97. #define SPIFFS_CREAT (1<<2)
  98. /* The opened file may only be read */
  99. #define SPIFFS_RDONLY (1<<3)
  100. /* The opened file may only be writted */
  101. #define SPIFFS_WRONLY (1<<4)
  102. /* The opened file may be both read and writted */
  103. #define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY)
  104. /* Any writes to the filehandle will never be cached */
  105. #define SPIFFS_DIRECT (1<<5)
  106. #define SPIFFS_SEEK_SET (0)
  107. #define SPIFFS_SEEK_CUR (1)
  108. #define SPIFFS_SEEK_END (2)
  109. #define SPIFFS_TYPE_FILE (1)
  110. #define SPIFFS_TYPE_DIR (2)
  111. #define SPIFFS_TYPE_HARD_LINK (3)
  112. #define SPIFFS_TYPE_SOFT_LINK (4)
  113. #ifndef SPIFFS_LOCK
  114. #define SPIFFS_LOCK(fs)
  115. #endif
  116. #ifndef SPIFFS_UNLOCK
  117. #define SPIFFS_UNLOCK(fs)
  118. #endif
  119. // phys structs
  120. // spiffs spi configuration struct
  121. typedef struct {
  122. // physical read function
  123. spiffs_read hal_read_f;
  124. // physical write function
  125. spiffs_write hal_write_f;
  126. // physical erase function
  127. spiffs_erase hal_erase_f;
  128. #if SPIFFS_SINGLETON == 0
  129. // physical size of the spi flash
  130. u32_t phys_size;
  131. // physical offset in spi flash used for spiffs,
  132. // must be on block boundary
  133. u32_t phys_addr;
  134. // physical size when erasing a block
  135. u32_t phys_erase_block;
  136. // logical size of a block, must be on physical
  137. // block size boundary and must never be less than
  138. // a physical block
  139. u32_t log_block_size;
  140. // logical size of a page, must be at least
  141. // log_block_size / 8
  142. u32_t log_page_size;
  143. #endif
  144. } spiffs_config;
  145. typedef struct {
  146. // file system configuration
  147. spiffs_config cfg;
  148. // number of logical blocks
  149. u32_t block_count;
  150. // cursor for free blocks, block index
  151. spiffs_block_ix free_cursor_block_ix;
  152. // cursor for free blocks, entry index
  153. int free_cursor_obj_lu_entry;
  154. // cursor when searching, block index
  155. spiffs_block_ix cursor_block_ix;
  156. // cursor when searching, entry index
  157. int cursor_obj_lu_entry;
  158. // primary work buffer, size of a logical page
  159. u8_t *lu_work;
  160. // secondary work buffer, size of a logical page
  161. u8_t *work;
  162. // file descriptor memory area
  163. u8_t *fd_space;
  164. // available file descriptors
  165. u32_t fd_count;
  166. // last error
  167. s32_t err_code;
  168. // current number of free blocks
  169. u32_t free_blocks;
  170. // current number of busy pages
  171. u32_t stats_p_allocated;
  172. // current number of deleted pages
  173. u32_t stats_p_deleted;
  174. // flag indicating that garbage collector is cleaning
  175. u8_t cleaning;
  176. // max erase count amongst all blocks
  177. spiffs_obj_id max_erase_count;
  178. #if SPIFFS_GC_STATS
  179. u32_t stats_gc_runs;
  180. #endif
  181. #if SPIFFS_CACHE
  182. // cache memory
  183. void *cache;
  184. // cache size
  185. u32_t cache_size;
  186. #if SPIFFS_CACHE_STATS
  187. u32_t cache_hits;
  188. u32_t cache_misses;
  189. #endif
  190. #endif
  191. // check callback function
  192. spiffs_check_callback check_cb_f;
  193. // mounted flag
  194. u8_t mounted;
  195. // config magic
  196. u32_t config_magic;
  197. } spiffs;
  198. /* spiffs file status struct */
  199. typedef struct {
  200. spiffs_obj_id obj_id;
  201. u32_t size;
  202. spiffs_obj_type type;
  203. u8_t name[SPIFFS_OBJ_NAME_LEN];
  204. } spiffs_stat;
  205. struct spiffs_dirent {
  206. spiffs_obj_id obj_id;
  207. u8_t name[SPIFFS_OBJ_NAME_LEN];
  208. spiffs_obj_type type;
  209. u32_t size;
  210. spiffs_page_ix pix;
  211. };
  212. typedef struct {
  213. spiffs *fs;
  214. spiffs_block_ix block;
  215. int entry;
  216. } spiffs_DIR;
  217. // functions
  218. /**
  219. * Initializes the file system dynamic parameters and mounts the filesystem.
  220. * If SPIFFS_USE_MAGIC is enabled the mounting may fail with SPIFFS_ERR_NOT_A_FS
  221. * if the flash does not contain a recognizable file system.
  222. * In this case, SPIFFS_format must be called prior to remounting.
  223. * @param fs the file system struct
  224. * @param config the physical and logical configuration of the file system
  225. * @param work a memory work buffer comprising 2*config->log_page_size
  226. * bytes used throughout all file system operations
  227. * @param fd_space memory for file descriptors
  228. * @param fd_space_size memory size of file descriptors
  229. * @param cache memory for cache, may be null
  230. * @param cache_size memory size of cache
  231. * @param check_cb_f callback function for reporting during consistency checks
  232. */
  233. s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
  234. u8_t *fd_space, u32_t fd_space_size,
  235. void *cache, u32_t cache_size,
  236. spiffs_check_callback check_cb_f);
  237. /**
  238. * Unmounts the file system. All file handles will be flushed of any
  239. * cached writes and closed.
  240. * @param fs the file system struct
  241. */
  242. void SPIFFS_unmount(spiffs *fs);
  243. /**
  244. * Creates a new file.
  245. * @param fs the file system struct
  246. * @param path the path of the new file
  247. * @param mode ignored, for posix compliance
  248. */
  249. s32_t SPIFFS_creat(spiffs *fs, char *path, spiffs_mode mode);
  250. /**
  251. * Opens/creates a file.
  252. * @param fs the file system struct
  253. * @param path the path of the new file
  254. * @param flags the flags for the open command, can be combinations of
  255. * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
  256. * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT
  257. * @param mode ignored, for posix compliance
  258. */
  259. spiffs_file SPIFFS_open(spiffs *fs, char *path, spiffs_flags flags, spiffs_mode mode);
  260. /**
  261. * Opens a file by given dir entry.
  262. * Optimization purposes, when traversing a file system with SPIFFS_readdir
  263. * a normal SPIFFS_open would need to traverse the filesystem again to find
  264. * the file, whilst SPIFFS_open_by_dirent already knows where the file resides.
  265. * @param fs the file system struct
  266. * @param path the dir entry to the file
  267. * @param flags the flags for the open command, can be combinations of
  268. * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
  269. * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT.
  270. * SPIFFS_CREAT will have no effect in this case.
  271. * @param mode ignored, for posix compliance
  272. */
  273. spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode);
  274. /**
  275. * Reads from given filehandle.
  276. * @param fs the file system struct
  277. * @param fh the filehandle
  278. * @param buf where to put read data
  279. * @param len how much to read
  280. * @returns number of bytes read, or -1 if error
  281. */
  282. s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
  283. /**
  284. * Writes to given filehandle.
  285. * @param fs the file system struct
  286. * @param fh the filehandle
  287. * @param buf the data to write
  288. * @param len how much to write
  289. * @returns number of bytes written, or -1 if error
  290. */
  291. s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
  292. /**
  293. * Moves the read/write file offset
  294. * @param fs the file system struct
  295. * @param fh the filehandle
  296. * @param offs how much/where to move the offset
  297. * @param whence if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes
  298. * if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset
  299. * if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offset
  300. */
  301. s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
  302. /**
  303. * Removes a file by path
  304. * @param fs the file system struct
  305. * @param path the path of the file to remove
  306. */
  307. s32_t SPIFFS_remove(spiffs *fs, char *path);
  308. /**
  309. * Removes a file by filehandle
  310. * @param fs the file system struct
  311. * @param fh the filehandle of the file to remove
  312. */
  313. s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
  314. /**
  315. * Gets file status by path
  316. * @param fs the file system struct
  317. * @param path the path of the file to stat
  318. * @param s the stat struct to populate
  319. */
  320. s32_t SPIFFS_stat(spiffs *fs, char *path, spiffs_stat *s);
  321. /**
  322. * Gets file status by filehandle
  323. * @param fs the file system struct
  324. * @param fh the filehandle of the file to stat
  325. * @param s the stat struct to populate
  326. */
  327. s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
  328. /**
  329. * Flushes all pending write operations from cache for given file
  330. * @param fs the file system struct
  331. * @param fh the filehandle of the file to flush
  332. */
  333. s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
  334. /**
  335. * Closes a filehandle. If there are pending write operations, these are finalized before closing.
  336. * @param fs the file system struct
  337. * @param fh the filehandle of the file to close
  338. */
  339. void SPIFFS_close(spiffs *fs, spiffs_file fh);
  340. /**
  341. * Renames a file
  342. * @param fs the file system struct
  343. * @param old path of file to rename
  344. * @param newPath new path of file
  345. */
  346. s32_t SPIFFS_rename(spiffs *fs, char *old, char *newPath);
  347. /**
  348. * Returns last error of last file operation.
  349. * @param fs the file system struct
  350. */
  351. s32_t SPIFFS_errno(spiffs *fs);
  352. /**
  353. * Clears last error.
  354. * @param fs the file system struct
  355. */
  356. void SPIFFS_clearerr(spiffs *fs);
  357. /**
  358. * Opens a directory stream corresponding to the given name.
  359. * The stream is positioned at the first entry in the directory.
  360. * On hydrogen builds the name argument is ignored as hydrogen builds always correspond
  361. * to a flat file structure - no directories.
  362. * @param fs the file system struct
  363. * @param name the name of the directory
  364. * @param d pointer the directory stream to be populated
  365. */
  366. spiffs_DIR *SPIFFS_opendir(spiffs *fs, char *name, spiffs_DIR *d);
  367. /**
  368. * Closes a directory stream
  369. * @param d the directory stream to close
  370. */
  371. s32_t SPIFFS_closedir(spiffs_DIR *d);
  372. /**
  373. * Reads a directory into given spifs_dirent struct.
  374. * @param d pointer to the directory stream
  375. * @param e the dirent struct to be populated
  376. * @returns null if error or end of stream, else given dirent is returned
  377. */
  378. struct spiffs_dirent *SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e);
  379. /**
  380. * Runs a consistency check on given filesystem.
  381. * @param fs the file system struct
  382. */
  383. s32_t SPIFFS_check(spiffs *fs);
  384. /**
  385. * Searches for a block with only deleted entries. If found, it is erased.
  386. * @param fs the file system struct
  387. */
  388. s32_t SPIFFS_erase_deleted_block(spiffs *fs);
  389. /**
  390. * Returns number of total bytes available and number of used bytes.
  391. * This is an estimation, and depends on if there a many files with little
  392. * data or few files with much data.
  393. * NB: If used number of bytes exceeds total bytes, a SPIFFS_check should
  394. * run. This indicates a power loss in midst of things. In worst case
  395. * (repeated powerlosses in mending or gc) you might have to delete some files.
  396. *
  397. * @param fs the file system struct
  398. * @param total total number of bytes in filesystem
  399. * @param used used number of bytes in filesystem
  400. */
  401. s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used);
  402. /**
  403. * Formats the entire file system. All data will be lost.
  404. * The filesystem must not be mounted when calling this.
  405. *
  406. * NB: formatting is awkward. Due to backwards compatibility, SPIFFS_mount
  407. * MUST be called prior to formatting in order to configure the filesystem.
  408. * If SPIFFS_mount succeeds, SPIFFS_unmount must be called before calling
  409. * SPIFFS_format.
  410. * If SPIFFS_mount fails, SPIFFS_format can be called directly without calling
  411. * SPIFFS_unmount first.
  412. *
  413. * @param fs the file system struct
  414. */
  415. s32_t SPIFFS_format(spiffs *fs);
  416. /**
  417. * Returns nonzero if spiffs is mounted, or zero if unmounted.
  418. * @param fs the file system struct
  419. */
  420. u8_t SPIFFS_mounted(spiffs *fs);
  421. /**
  422. * Tries to find a block where most or all pages are deleted, and erase that
  423. * block if found. Does not care for wear levelling. Will not move pages
  424. * around.
  425. * If parameter max_free_pages are set to 0, only blocks with only deleted
  426. * pages will be selected.
  427. *
  428. * NB: the garbage collector is automatically called when spiffs needs free
  429. * pages. The reason for this function is to give possibility to do background
  430. * tidying when user knows the system is idle.
  431. *
  432. * Use with care.
  433. *
  434. * Setting max_free_pages to anything larger than zero will eventually wear
  435. * flash more as a block containing free pages can be erased.
  436. *
  437. * Will set err_no to SPIFFS_OK if a block was found and erased,
  438. * SPIFFS_ERR_NO_DELETED_BLOCK if no matching block was found,
  439. * or other error.
  440. *
  441. * @param fs the file system struct
  442. * @param max_free_pages maximum number allowed free pages in block
  443. */
  444. s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages);
  445. /**
  446. * Will try to make room for given amount of bytes in the filesystem by moving
  447. * pages and erasing blocks.
  448. * If it is physically impossible, err_no will be set to SPIFFS_ERR_FULL. If
  449. * there already is this amount (or more) of free space, SPIFFS_gc will
  450. * silently return. It is recommended to call SPIFFS_info before invoking
  451. * this method in order to determine what amount of bytes to give.
  452. *
  453. * NB: the garbage collector is automatically called when spiffs needs free
  454. * pages. The reason for this function is to give possibility to do background
  455. * tidying when user knows the system is idle.
  456. *
  457. * Use with care.
  458. *
  459. * @param fs the file system struct
  460. * @param size amount of bytes that should be freed
  461. */
  462. s32_t SPIFFS_gc(spiffs *fs, u32_t size);
  463. #if SPIFFS_TEST_VISUALISATION
  464. /**
  465. * Prints out a visualization of the filesystem.
  466. * @param fs the file system struct
  467. */
  468. s32_t SPIFFS_vis(spiffs *fs);
  469. #endif
  470. #if SPIFFS_BUFFER_HELP
  471. /**
  472. * Returns number of bytes needed for the filedescriptor buffer given
  473. * amount of file descriptors.
  474. */
  475. u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
  476. #if SPIFFS_CACHE
  477. /**
  478. * Returns number of bytes needed for the cache buffer given
  479. * amount of cache pages.
  480. */
  481. u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
  482. #endif
  483. #endif
  484. #if SPIFFS_CACHE
  485. #endif
  486. void myspiffs_mount();
  487. void myspiffs_unmount();
  488. int myspiffs_open(const char *name, int flags);
  489. int myspiffs_close( int fd );
  490. size_t myspiffs_write( int fd, const void* ptr, size_t len );
  491. size_t myspiffs_read( int fd, void* ptr, size_t len);
  492. int myspiffs_lseek( int fd, int off, int whence );
  493. int myspiffs_eof( int fd );
  494. int myspiffs_tell( int fd );
  495. int myspiffs_getc( int fd );
  496. int myspiffs_ungetc( int c, int fd );
  497. int myspiffs_flush( int fd );
  498. int myspiffs_error( int fd );
  499. void myspiffs_clearerr( int fd );
  500. int myspiffs_check( void );
  501. int myspiffs_rename( const char *old, const char *newname );
  502. size_t myspiffs_size( int fd );
  503. int myspiffs_format (void);
  504. s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh);
  505. s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh);
  506. s32_t SPIFFS_size(spiffs *fs, spiffs_file fh);
  507. #if defined(__cplusplus)
  508. }
  509. #endif
  510. #endif /* SPIFFS_H_ */