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