armsrc/spiffs.h

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