spiffs.h 28 KB

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