spiffs.h 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691
  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_FILE_EXISTS -10030
  45. #define SPIFFS_ERR_NOT_A_FILE -10031
  46. #define SPIFFS_ERR_RO_NOT_IMPL -10032
  47. #define SPIFFS_ERR_RO_ABORTED_OPERATION -10033
  48. #define SPIFFS_ERR_PROBE_TOO_FEW_BLOCKS -10034
  49. #define SPIFFS_ERR_PROBE_NOT_A_FS -10035
  50. #define SPIFFS_ERR_NAME_TOO_LONG -10036
  51. #define SPIFFS_ERR_INTERNAL -10050
  52. #define SPIFFS_ERR_TEST -10100
  53. // spiffs file descriptor index type. must be signed
  54. typedef s16_t spiffs_file;
  55. // spiffs file descriptor flags
  56. typedef u16_t spiffs_flags;
  57. // spiffs file mode
  58. typedef u16_t spiffs_mode;
  59. // object type
  60. typedef u8_t spiffs_obj_type;
  61. struct spiffs_t;
  62. #if SPIFFS_HAL_CALLBACK_EXTRA
  63. /* spi read call function type */
  64. typedef s32_t (*spiffs_read)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *dst);
  65. /* spi write call function type */
  66. typedef s32_t (*spiffs_write)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *src);
  67. /* spi erase call function type */
  68. typedef s32_t (*spiffs_erase)(struct spiffs_t *fs, u32_t addr, u32_t size);
  69. #else // SPIFFS_HAL_CALLBACK_EXTRA
  70. /* spi read call function type */
  71. typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
  72. /* spi write call function type */
  73. typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
  74. /* spi erase call function type */
  75. typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
  76. #endif // SPIFFS_HAL_CALLBACK_EXTRA
  77. /* file system check callback report operation */
  78. typedef enum {
  79. SPIFFS_CHECK_LOOKUP = 0,
  80. SPIFFS_CHECK_INDEX,
  81. SPIFFS_CHECK_PAGE
  82. } spiffs_check_type;
  83. /* file system check callback report type */
  84. typedef enum {
  85. SPIFFS_CHECK_PROGRESS = 0,
  86. SPIFFS_CHECK_ERROR,
  87. SPIFFS_CHECK_FIX_INDEX,
  88. SPIFFS_CHECK_FIX_LOOKUP,
  89. SPIFFS_CHECK_DELETE_ORPHANED_INDEX,
  90. SPIFFS_CHECK_DELETE_PAGE,
  91. SPIFFS_CHECK_DELETE_BAD_FILE
  92. } spiffs_check_report;
  93. /* file system check callback function */
  94. #if SPIFFS_HAL_CALLBACK_EXTRA
  95. typedef void (*spiffs_check_callback)(struct spiffs_t *fs, spiffs_check_type type, spiffs_check_report report,
  96. u32_t arg1, u32_t arg2);
  97. #else // SPIFFS_HAL_CALLBACK_EXTRA
  98. typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
  99. u32_t arg1, u32_t arg2);
  100. #endif // SPIFFS_HAL_CALLBACK_EXTRA
  101. /* file system listener callback operation */
  102. typedef enum {
  103. /* the file has been created */
  104. SPIFFS_CB_CREATED = 0,
  105. /* the file has been updated or moved to another page */
  106. SPIFFS_CB_UPDATED,
  107. /* the file has been deleted */
  108. SPIFFS_CB_DELETED
  109. } spiffs_fileop_type;
  110. /* file system listener callback function */
  111. typedef void (*spiffs_file_callback)(struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix);
  112. #ifndef SPIFFS_DBG
  113. #define SPIFFS_DBG(...) \
  114. print(__VA_ARGS__)
  115. #endif
  116. #ifndef SPIFFS_GC_DBG
  117. #define SPIFFS_GC_DBG(...) printf(__VA_ARGS__)
  118. #endif
  119. #ifndef SPIFFS_CACHE_DBG
  120. #define SPIFFS_CACHE_DBG(...) printf(__VA_ARGS__)
  121. #endif
  122. #ifndef SPIFFS_CHECK_DBG
  123. #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
  124. #endif
  125. /* Any write to the filehandle is appended to end of the file */
  126. #define SPIFFS_APPEND (1<<0)
  127. #define SPIFFS_O_APPEND SPIFFS_APPEND
  128. /* If the opened file exists, it will be truncated to zero length before opened */
  129. #define SPIFFS_TRUNC (1<<1)
  130. #define SPIFFS_O_TRUNC SPIFFS_TRUNC
  131. /* If the opened file does not exist, it will be created before opened */
  132. #define SPIFFS_CREAT (1<<2)
  133. #define SPIFFS_O_CREAT SPIFFS_CREAT
  134. /* The opened file may only be read */
  135. #define SPIFFS_RDONLY (1<<3)
  136. #define SPIFFS_O_RDONLY SPIFFS_RDONLY
  137. /* The opened file may only be written */
  138. #define SPIFFS_WRONLY (1<<4)
  139. #define SPIFFS_O_WRONLY SPIFFS_WRONLY
  140. /* The opened file may be both read and written */
  141. #define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY)
  142. #define SPIFFS_O_RDWR SPIFFS_RDWR
  143. /* Any writes to the filehandle will never be cached but flushed directly */
  144. #define SPIFFS_DIRECT (1<<5)
  145. #define SPIFFS_O_DIRECT SPIFFS_DIRECT
  146. /* If SPIFFS_O_CREAT and SPIFFS_O_EXCL are set, SPIFFS_open() shall fail if the file exists */
  147. #define SPIFFS_EXCL (1<<6)
  148. #define SPIFFS_O_EXCL SPIFFS_EXCL
  149. #define SPIFFS_SEEK_SET (0)
  150. #define SPIFFS_SEEK_CUR (1)
  151. #define SPIFFS_SEEK_END (2)
  152. #define SPIFFS_TYPE_FILE (1)
  153. #define SPIFFS_TYPE_DIR (2)
  154. #define SPIFFS_TYPE_HARD_LINK (3)
  155. #define SPIFFS_TYPE_SOFT_LINK (4)
  156. #ifndef SPIFFS_LOCK
  157. #define SPIFFS_LOCK(fs)
  158. #endif
  159. #ifndef SPIFFS_UNLOCK
  160. #define SPIFFS_UNLOCK(fs)
  161. #endif
  162. // phys structs
  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
  178. u32_t phys_erase_block;
  179. // logical size of a block, must be on physical
  180. // block size boundary and must never be less than
  181. // a physical block
  182. u32_t log_block_size;
  183. // logical size of a page, must be at least
  184. // log_block_size / 8
  185. u32_t log_page_size;
  186. #endif
  187. #if SPIFFS_FILEHDL_OFFSET
  188. // an integer offset added to each file handle
  189. u16_t fh_ix_offset;
  190. #endif
  191. } spiffs_config;
  192. typedef struct spiffs_t {
  193. // file system configuration
  194. spiffs_config cfg;
  195. // number of logical blocks
  196. u32_t block_count;
  197. // cursor for free blocks, block index
  198. spiffs_block_ix free_cursor_block_ix;
  199. // cursor for free blocks, entry index
  200. int free_cursor_obj_lu_entry;
  201. // cursor when searching, block index
  202. spiffs_block_ix cursor_block_ix;
  203. // cursor when searching, entry index
  204. int cursor_obj_lu_entry;
  205. // primary work buffer, size of a logical page
  206. u8_t *lu_work;
  207. // secondary work buffer, size of a logical page
  208. u8_t *work;
  209. // file descriptor memory area
  210. u8_t *fd_space;
  211. // available file descriptors
  212. u32_t fd_count;
  213. // last error
  214. s32_t err_code;
  215. // current number of free blocks
  216. u32_t free_blocks;
  217. // current number of busy pages
  218. u32_t stats_p_allocated;
  219. // current number of deleted pages
  220. u32_t stats_p_deleted;
  221. // flag indicating that garbage collector is cleaning
  222. u8_t cleaning;
  223. // max erase count amongst all blocks
  224. spiffs_obj_id max_erase_count;
  225. #if SPIFFS_GC_STATS
  226. u32_t stats_gc_runs;
  227. #endif
  228. #if SPIFFS_CACHE
  229. // cache memory
  230. void *cache;
  231. // cache size
  232. u32_t cache_size;
  233. #if SPIFFS_CACHE_STATS
  234. u32_t cache_hits;
  235. u32_t cache_misses;
  236. #endif
  237. #endif
  238. // check callback function
  239. spiffs_check_callback check_cb_f;
  240. // file callback function
  241. spiffs_file_callback file_cb_f;
  242. // mounted flag
  243. u8_t mounted;
  244. // user data
  245. void *user_data;
  246. // config magic
  247. u32_t config_magic;
  248. } spiffs;
  249. /* spiffs file status struct */
  250. typedef struct {
  251. spiffs_obj_id obj_id;
  252. u32_t size;
  253. spiffs_obj_type type;
  254. spiffs_page_ix pix;
  255. u8_t name[SPIFFS_OBJ_NAME_LEN];
  256. } spiffs_stat;
  257. struct spiffs_dirent {
  258. spiffs_obj_id obj_id;
  259. u8_t name[SPIFFS_OBJ_NAME_LEN];
  260. spiffs_obj_type type;
  261. u32_t size;
  262. spiffs_page_ix pix;
  263. };
  264. typedef struct {
  265. spiffs *fs;
  266. spiffs_block_ix block;
  267. int entry;
  268. } spiffs_DIR;
  269. // functions
  270. #if SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
  271. /**
  272. * Special function. This takes a spiffs config struct and returns the number
  273. * of blocks this file system was formatted with. This function relies on
  274. * that following info is set correctly in given config struct:
  275. *
  276. * phys_addr, log_page_size, and log_block_size.
  277. *
  278. * Also, hal_read_f must be set in the config struct.
  279. *
  280. * One must be sure of the correct page size and that the physical address is
  281. * correct in the probed file system when calling this function. It is not
  282. * checked if the phys_addr actually points to the start of the file system,
  283. * so one might get a false positive if entering a phys_addr somewhere in the
  284. * middle of the file system at block boundary. In addition, it is not checked
  285. * if the page size is actually correct. If it is not, weird file system sizes
  286. * will be returned.
  287. *
  288. * If this function detects a file system it returns the assumed file system
  289. * size, which can be used to set the phys_size.
  290. *
  291. * Otherwise, it returns an error indicating why it is not regarded as a file
  292. * system.
  293. *
  294. * Note: this function is not protected with SPIFFS_LOCK and SPIFFS_UNLOCK
  295. * macros. It returns the error code directly, instead of as read by
  296. * SPIFFS_errno.
  297. *
  298. * @param config essential parts of the physical and logical
  299. * configuration of the file system.
  300. */
  301. s32_t SPIFFS_probe_fs(spiffs_config *config);
  302. #endif // SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
  303. /**
  304. * Initializes the file system dynamic parameters and mounts the filesystem.
  305. * If SPIFFS_USE_MAGIC is enabled the mounting may fail with SPIFFS_ERR_NOT_A_FS
  306. * if the flash does not contain a recognizable file system.
  307. * In this case, SPIFFS_format must be called prior to remounting.
  308. * @param fs the file system struct
  309. * @param config the physical and logical configuration of the file system
  310. * @param work a memory work buffer comprising 2*config->log_page_size
  311. * bytes used throughout all file system operations
  312. * @param fd_space memory for file descriptors
  313. * @param fd_space_size memory size of file descriptors
  314. * @param cache memory for cache, may be null
  315. * @param cache_size memory size of cache
  316. * @param check_cb_f callback function for reporting during consistency checks
  317. */
  318. s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
  319. u8_t *fd_space, u32_t fd_space_size,
  320. void *cache, u32_t cache_size,
  321. spiffs_check_callback check_cb_f);
  322. /**
  323. * Unmounts the file system. All file handles will be flushed of any
  324. * cached writes and closed.
  325. * @param fs the file system struct
  326. */
  327. void SPIFFS_unmount(spiffs *fs);
  328. /**
  329. * Creates a new file.
  330. * @param fs the file system struct
  331. * @param path the path of the new file
  332. * @param mode ignored, for posix compliance
  333. */
  334. s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode);
  335. /**
  336. * Opens/creates a file.
  337. * @param fs the file system struct
  338. * @param path the path of the new file
  339. * @param flags the flags for the open command, can be combinations of
  340. * SPIFFS_O_APPEND, SPIFFS_O_TRUNC, SPIFFS_O_CREAT, SPIFFS_O_RDONLY,
  341. * SPIFFS_O_WRONLY, SPIFFS_O_RDWR, SPIFFS_O_DIRECT, SPIFFS_O_EXCL
  342. * @param mode ignored, for posix compliance
  343. */
  344. spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode);
  345. /**
  346. * Opens a file by given dir entry.
  347. * Optimization purposes, when traversing a file system with SPIFFS_readdir
  348. * a normal SPIFFS_open would need to traverse the filesystem again to find
  349. * the file, whilst SPIFFS_open_by_dirent already knows where the file resides.
  350. * @param fs the file system struct
  351. * @param e the dir entry to the file
  352. * @param flags the flags for the open command, can be combinations of
  353. * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
  354. * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT.
  355. * SPIFFS_CREAT will have no effect in this case.
  356. * @param mode ignored, for posix compliance
  357. */
  358. spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode);
  359. /**
  360. * Opens a file by given page index.
  361. * Optimization purposes, opens a file by directly pointing to the page
  362. * index in the spi flash.
  363. * If the page index does not point to a file header SPIFFS_ERR_NOT_A_FILE
  364. * is returned.
  365. * @param fs the file system struct
  366. * @param page_ix the page index
  367. * @param flags the flags for the open command, can be combinations of
  368. * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
  369. * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT.
  370. * SPIFFS_CREAT will have no effect in this case.
  371. * @param mode ignored, for posix compliance
  372. */
  373. spiffs_file SPIFFS_open_by_page(spiffs *fs, spiffs_page_ix page_ix, spiffs_flags flags, spiffs_mode mode);
  374. /**
  375. * Reads from given filehandle.
  376. * @param fs the file system struct
  377. * @param fh the filehandle
  378. * @param buf where to put read data
  379. * @param len how much to read
  380. * @returns number of bytes read, or -1 if error
  381. */
  382. s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
  383. /**
  384. * Writes to given filehandle.
  385. * @param fs the file system struct
  386. * @param fh the filehandle
  387. * @param buf the data to write
  388. * @param len how much to write
  389. * @returns number of bytes written, or -1 if error
  390. */
  391. s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
  392. /**
  393. * Moves the read/write file offset. Resulting offset is returned or negative if error.
  394. * lseek(fs, fd, 0, SPIFFS_SEEK_CUR) will thus return current offset.
  395. * @param fs the file system struct
  396. * @param fh the filehandle
  397. * @param offs how much/where to move the offset
  398. * @param whence if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes
  399. * if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset
  400. * if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offse, which should be negative
  401. */
  402. s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
  403. /**
  404. * Removes a file by path
  405. * @param fs the file system struct
  406. * @param path the path of the file to remove
  407. */
  408. s32_t SPIFFS_remove(spiffs *fs, const char *path);
  409. /**
  410. * Removes a file by filehandle
  411. * @param fs the file system struct
  412. * @param fh the filehandle of the file to remove
  413. */
  414. s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
  415. /**
  416. * Gets file status by path
  417. * @param fs the file system struct
  418. * @param path the path of the file to stat
  419. * @param s the stat struct to populate
  420. */
  421. s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
  422. /**
  423. * Gets file status by filehandle
  424. * @param fs the file system struct
  425. * @param fh the filehandle of the file to stat
  426. * @param s the stat struct to populate
  427. */
  428. s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
  429. /**
  430. * Flushes all pending write operations from cache for given file
  431. * @param fs the file system struct
  432. * @param fh the filehandle of the file to flush
  433. */
  434. s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
  435. /**
  436. * Closes a filehandle. If there are pending write operations, these are finalized before closing.
  437. * @param fs the file system struct
  438. * @param fh the filehandle of the file to close
  439. */
  440. s32_t SPIFFS_close(spiffs *fs, spiffs_file fh);
  441. /**
  442. * Renames a file
  443. * @param fs the file system struct
  444. * @param old path of file to rename
  445. * @param newPath new path of file
  446. */
  447. s32_t SPIFFS_rename(spiffs *fs, const char *old, const char *newPath);
  448. /**
  449. * Returns last error of last file operation.
  450. * @param fs the file system struct
  451. */
  452. s32_t SPIFFS_errno(spiffs *fs);
  453. /**
  454. * Clears last error.
  455. * @param fs the file system struct
  456. */
  457. void SPIFFS_clearerr(spiffs *fs);
  458. /**
  459. * Opens a directory stream corresponding to the given name.
  460. * The stream is positioned at the first entry in the directory.
  461. * On hydrogen builds the name argument is ignored as hydrogen builds always correspond
  462. * to a flat file structure - no directories.
  463. * @param fs the file system struct
  464. * @param name the name of the directory
  465. * @param d pointer the directory stream to be populated
  466. */
  467. spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
  468. /**
  469. * Closes a directory stream
  470. * @param d the directory stream to close
  471. */
  472. s32_t SPIFFS_closedir(spiffs_DIR *d);
  473. /**
  474. * Reads a directory into given spifs_dirent struct.
  475. * @param d pointer to the directory stream
  476. * @param e the dirent struct to be populated
  477. * @returns null if error or end of stream, else given dirent is returned
  478. */
  479. struct spiffs_dirent *SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e);
  480. /**
  481. * Runs a consistency check on given filesystem.
  482. * @param fs the file system struct
  483. */
  484. s32_t SPIFFS_check(spiffs *fs);
  485. /**
  486. * Returns number of total bytes available and number of used bytes.
  487. * This is an estimation, and depends on if there a many files with little
  488. * data or few files with much data.
  489. * NB: If used number of bytes exceeds total bytes, a SPIFFS_check should
  490. * run. This indicates a power loss in midst of things. In worst case
  491. * (repeated powerlosses in mending or gc) you might have to delete some files.
  492. *
  493. * @param fs the file system struct
  494. * @param total total number of bytes in filesystem
  495. * @param used used number of bytes in filesystem
  496. */
  497. s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used);
  498. /**
  499. * Formats the entire file system. All data will be lost.
  500. * The filesystem must not be mounted when calling this.
  501. *
  502. * NB: formatting is awkward. Due to backwards compatibility, SPIFFS_mount
  503. * MUST be called prior to formatting in order to configure the filesystem.
  504. * If SPIFFS_mount succeeds, SPIFFS_unmount must be called before calling
  505. * SPIFFS_format.
  506. * If SPIFFS_mount fails, SPIFFS_format can be called directly without calling
  507. * SPIFFS_unmount first.
  508. *
  509. * @param fs the file system struct
  510. */
  511. s32_t SPIFFS_format(spiffs *fs);
  512. /**
  513. * Returns nonzero if spiffs is mounted, or zero if unmounted.
  514. * @param fs the file system struct
  515. */
  516. u8_t SPIFFS_mounted(spiffs *fs);
  517. /**
  518. * Tries to find a block where most or all pages are deleted, and erase that
  519. * block if found. Does not care for wear levelling. Will not move pages
  520. * around.
  521. * If parameter max_free_pages are set to 0, only blocks with only deleted
  522. * pages will be selected.
  523. *
  524. * NB: the garbage collector is automatically called when spiffs needs free
  525. * pages. The reason for this function is to give possibility to do background
  526. * tidying when user knows the system is idle.
  527. *
  528. * Use with care.
  529. *
  530. * Setting max_free_pages to anything larger than zero will eventually wear
  531. * flash more as a block containing free pages can be erased.
  532. *
  533. * Will set err_no to SPIFFS_OK if a block was found and erased,
  534. * SPIFFS_ERR_NO_DELETED_BLOCK if no matching block was found,
  535. * or other error.
  536. *
  537. * @param fs the file system struct
  538. * @param max_free_pages maximum number allowed free pages in block
  539. */
  540. s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages);
  541. /**
  542. * Will try to make room for given amount of bytes in the filesystem by moving
  543. * pages and erasing blocks.
  544. * If it is physically impossible, err_no will be set to SPIFFS_ERR_FULL. If
  545. * there already is this amount (or more) of free space, SPIFFS_gc will
  546. * silently return. It is recommended to call SPIFFS_info before invoking
  547. * this method in order to determine what amount of bytes to give.
  548. *
  549. * NB: the garbage collector is automatically called when spiffs needs free
  550. * pages. The reason for this function is to give possibility to do background
  551. * tidying when user knows the system is idle.
  552. *
  553. * Use with care.
  554. *
  555. * @param fs the file system struct
  556. * @param size amount of bytes that should be freed
  557. */
  558. s32_t SPIFFS_gc(spiffs *fs, u32_t size);
  559. /**
  560. * Check if EOF reached.
  561. * @param fs the file system struct
  562. * @param fh the filehandle of the file to check
  563. */
  564. s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh);
  565. /**
  566. * Get position in file.
  567. * @param fs the file system struct
  568. * @param fh the filehandle of the file to check
  569. */
  570. s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh);
  571. /**
  572. * Registers a callback function that keeps track on operations on file
  573. * headers. Do note, that this callback is called from within internal spiffs
  574. * mechanisms. Any operations on the actual file system being callbacked from
  575. * in this callback will mess things up for sure - do not do this.
  576. * This can be used to track where files are and move around during garbage
  577. * collection, which in turn can be used to build location tables in ram.
  578. * Used in conjuction with SPIFFS_open_by_page this may improve performance
  579. * when opening a lot of files.
  580. * Must be invoked after mount.
  581. *
  582. * @param fs the file system struct
  583. * @param cb_func the callback on file operations
  584. */
  585. s32_t SPIFFS_set_file_callback_func(spiffs *fs, spiffs_file_callback cb_func);
  586. #if SPIFFS_TEST_VISUALISATION
  587. /**
  588. * Prints out a visualization of the filesystem.
  589. * @param fs the file system struct
  590. */
  591. s32_t SPIFFS_vis(spiffs *fs);
  592. #endif
  593. #if SPIFFS_BUFFER_HELP
  594. /**
  595. * Returns number of bytes needed for the filedescriptor buffer given
  596. * amount of file descriptors.
  597. */
  598. u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
  599. #if SPIFFS_CACHE
  600. /**
  601. * Returns number of bytes needed for the cache buffer given
  602. * amount of cache pages.
  603. */
  604. u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
  605. #endif
  606. #endif
  607. #if SPIFFS_CACHE
  608. #endif
  609. #if defined(__cplusplus)
  610. }
  611. #endif
  612. #endif /* SPIFFS_H_ */