|
- /*
- * spiffs.h
- *
- * Created on: May 26, 2013
- * Author: petera
- */
-
- #ifndef SPIFFS_H_
- #define SPIFFS_H_
- #if defined(__cplusplus)
- extern "C" {
- #endif
-
- #include "spiffs_config.h"
-
- #define SPIFFS_OK 0
- #define SPIFFS_ERR_NOT_MOUNTED -10000
- #define SPIFFS_ERR_FULL -10001
- #define SPIFFS_ERR_NOT_FOUND -10002
- #define SPIFFS_ERR_END_OF_OBJECT -10003
- #define SPIFFS_ERR_DELETED -10004
- #define SPIFFS_ERR_NOT_FINALIZED -10005
- #define SPIFFS_ERR_NOT_INDEX -10006
- #define SPIFFS_ERR_OUT_OF_FILE_DESCS -10007
- #define SPIFFS_ERR_FILE_CLOSED -10008
- #define SPIFFS_ERR_FILE_DELETED -10009
- #define SPIFFS_ERR_BAD_DESCRIPTOR -10010
- #define SPIFFS_ERR_IS_INDEX -10011
- #define SPIFFS_ERR_IS_FREE -10012
- #define SPIFFS_ERR_INDEX_SPAN_MISMATCH -10013
- #define SPIFFS_ERR_DATA_SPAN_MISMATCH -10014
- #define SPIFFS_ERR_INDEX_REF_FREE -10015
- #define SPIFFS_ERR_INDEX_REF_LU -10016
- #define SPIFFS_ERR_INDEX_REF_INVALID -10017
- #define SPIFFS_ERR_INDEX_FREE -10018
- #define SPIFFS_ERR_INDEX_LU -10019
- #define SPIFFS_ERR_INDEX_INVALID -10020
- #define SPIFFS_ERR_NOT_WRITABLE -10021
- #define SPIFFS_ERR_NOT_READABLE -10022
- #define SPIFFS_ERR_CONFLICTING_NAME -10023
- #define SPIFFS_ERR_NOT_CONFIGURED -10024
-
- #define SPIFFS_ERR_NOT_A_FS -10025
- #define SPIFFS_ERR_MOUNTED -10026
- #define SPIFFS_ERR_ERASE_FAIL -10027
- #define SPIFFS_ERR_MAGIC_NOT_POSSIBLE -10028
-
- #define SPIFFS_ERR_NO_DELETED_BLOCKS -10029
-
- #define SPIFFS_ERR_FILE_EXISTS -10030
-
- #define SPIFFS_ERR_NOT_A_FILE -10031
- #define SPIFFS_ERR_RO_NOT_IMPL -10032
- #define SPIFFS_ERR_RO_ABORTED_OPERATION -10033
- #define SPIFFS_ERR_PROBE_TOO_FEW_BLOCKS -10034
- #define SPIFFS_ERR_PROBE_NOT_A_FS -10035
- #define SPIFFS_ERR_NAME_TOO_LONG -10036
-
- #define SPIFFS_ERR_IX_MAP_UNMAPPED -10037
- #define SPIFFS_ERR_IX_MAP_MAPPED -10038
- #define SPIFFS_ERR_IX_MAP_BAD_RANGE -10039
-
- #define SPIFFS_ERR_INTERNAL -10050
-
- #define SPIFFS_ERR_TEST -10100
-
-
- // spiffs file descriptor index type. must be signed
- typedef s16_t spiffs_file;
- // spiffs file descriptor flags
- typedef u16_t spiffs_flags;
- // spiffs file mode
- typedef u16_t spiffs_mode;
- // object type
- typedef u8_t spiffs_obj_type;
-
- struct spiffs_t;
-
- #if SPIFFS_HAL_CALLBACK_EXTRA
-
- /* spi read call function type */
- typedef s32_t (*spiffs_read)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *dst);
- /* spi write call function type */
- typedef s32_t (*spiffs_write)(struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *src);
- /* spi erase call function type */
- typedef s32_t (*spiffs_erase)(struct spiffs_t *fs, u32_t addr, u32_t size);
-
- #else // SPIFFS_HAL_CALLBACK_EXTRA
-
- /* spi read call function type */
- typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
- /* spi write call function type */
- typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
- /* spi erase call function type */
- typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
- #endif // SPIFFS_HAL_CALLBACK_EXTRA
-
- /* file system check callback report operation */
- typedef enum {
- SPIFFS_CHECK_LOOKUP = 0,
- SPIFFS_CHECK_INDEX,
- SPIFFS_CHECK_PAGE
- } spiffs_check_type;
-
- /* file system check callback report type */
- typedef enum {
- SPIFFS_CHECK_PROGRESS = 0,
- SPIFFS_CHECK_ERROR,
- SPIFFS_CHECK_FIX_INDEX,
- SPIFFS_CHECK_FIX_LOOKUP,
- SPIFFS_CHECK_DELETE_ORPHANED_INDEX,
- SPIFFS_CHECK_DELETE_PAGE,
- SPIFFS_CHECK_DELETE_BAD_FILE
- } spiffs_check_report;
-
- /* file system check callback function */
- #if SPIFFS_HAL_CALLBACK_EXTRA
- typedef void (*spiffs_check_callback)(struct spiffs_t *fs, spiffs_check_type type, spiffs_check_report report,
- u32_t arg1, u32_t arg2);
- #else // SPIFFS_HAL_CALLBACK_EXTRA
- typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
- u32_t arg1, u32_t arg2);
- #endif // SPIFFS_HAL_CALLBACK_EXTRA
-
- /* file system listener callback operation */
- typedef enum {
- /* the file has been created */
- SPIFFS_CB_CREATED = 0,
- /* the file has been updated or moved to another page */
- SPIFFS_CB_UPDATED,
- /* the file has been deleted */
- SPIFFS_CB_DELETED
- } spiffs_fileop_type;
-
- /* file system listener callback function */
- typedef void (*spiffs_file_callback)(struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix);
-
- #ifndef SPIFFS_DBG
- #define SPIFFS_DBG(...) \
- printf(__VA_ARGS__)
- #endif
- #ifndef SPIFFS_GC_DBG
- #define SPIFFS_GC_DBG(...) printf(__VA_ARGS__)
- #endif
- #ifndef SPIFFS_CACHE_DBG
- #define SPIFFS_CACHE_DBG(...) printf(__VA_ARGS__)
- #endif
- #ifndef SPIFFS_CHECK_DBG
- #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
- #endif
-
- /* Any write to the filehandle is appended to end of the file */
- #define SPIFFS_APPEND (1<<0)
- #define SPIFFS_O_APPEND SPIFFS_APPEND
- /* If the opened file exists, it will be truncated to zero length before opened */
- #define SPIFFS_TRUNC (1<<1)
- #define SPIFFS_O_TRUNC SPIFFS_TRUNC
- /* If the opened file does not exist, it will be created before opened */
- #define SPIFFS_CREAT (1<<2)
- #define SPIFFS_O_CREAT SPIFFS_CREAT
- /* The opened file may only be read */
- #define SPIFFS_RDONLY (1<<3)
- #define SPIFFS_O_RDONLY SPIFFS_RDONLY
- /* The opened file may only be written */
- #define SPIFFS_WRONLY (1<<4)
- #define SPIFFS_O_WRONLY SPIFFS_WRONLY
- /* The opened file may be both read and written */
- #define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY)
- #define SPIFFS_O_RDWR SPIFFS_RDWR
- /* Any writes to the filehandle will never be cached but flushed directly */
- #define SPIFFS_DIRECT (1<<5)
- #define SPIFFS_O_DIRECT SPIFFS_DIRECT
- /* If SPIFFS_O_CREAT and SPIFFS_O_EXCL are set, SPIFFS_open() shall fail if the file exists */
- #define SPIFFS_EXCL (1<<6)
- #define SPIFFS_O_EXCL SPIFFS_EXCL
-
- #define SPIFFS_SEEK_SET (0)
- #define SPIFFS_SEEK_CUR (1)
- #define SPIFFS_SEEK_END (2)
-
- #define SPIFFS_TYPE_FILE (1)
- #define SPIFFS_TYPE_DIR (2)
- #define SPIFFS_TYPE_HARD_LINK (3)
- #define SPIFFS_TYPE_SOFT_LINK (4)
-
- #ifndef SPIFFS_LOCK
- #define SPIFFS_LOCK(fs)
- #endif
-
- #ifndef SPIFFS_UNLOCK
- #define SPIFFS_UNLOCK(fs)
- #endif
-
- // phys structs
-
- // spiffs spi configuration struct
- typedef struct {
- // physical read function
- spiffs_read hal_read_f;
- // physical write function
- spiffs_write hal_write_f;
- // physical erase function
- spiffs_erase hal_erase_f;
- #if SPIFFS_SINGLETON == 0
- // physical size of the spi flash
- u32_t phys_size;
- // physical offset in spi flash used for spiffs,
- // must be on block boundary
- u32_t phys_addr;
- // physical size when erasing a block
- u32_t phys_erase_block;
-
- // logical size of a block, must be on physical
- // block size boundary and must never be less than
- // a physical block
- u32_t log_block_size;
- // logical size of a page, must be at least
- // log_block_size / 8
- u32_t log_page_size;
-
- #endif
- #if SPIFFS_FILEHDL_OFFSET
- // an integer offset added to each file handle
- u16_t fh_ix_offset;
- #endif
- } spiffs_config;
-
- typedef struct spiffs_t {
- // file system configuration
- spiffs_config cfg;
- // number of logical blocks
- u32_t block_count;
-
- // cursor for free blocks, block index
- spiffs_block_ix free_cursor_block_ix;
- // cursor for free blocks, entry index
- int free_cursor_obj_lu_entry;
- // cursor when searching, block index
- spiffs_block_ix cursor_block_ix;
- // cursor when searching, entry index
- int cursor_obj_lu_entry;
-
- // primary work buffer, size of a logical page
- u8_t *lu_work;
- // secondary work buffer, size of a logical page
- u8_t *work;
- // file descriptor memory area
- u8_t *fd_space;
- // available file descriptors
- u32_t fd_count;
-
- // last error
- s32_t err_code;
-
- // current number of free blocks
- u32_t free_blocks;
- // current number of busy pages
- u32_t stats_p_allocated;
- // current number of deleted pages
- u32_t stats_p_deleted;
- // flag indicating that garbage collector is cleaning
- u8_t cleaning;
- // max erase count amongst all blocks
- spiffs_obj_id max_erase_count;
-
- #if SPIFFS_GC_STATS
- u32_t stats_gc_runs;
- #endif
-
- #if SPIFFS_CACHE
- // cache memory
- void *cache;
- // cache size
- u32_t cache_size;
- #if SPIFFS_CACHE_STATS
- u32_t cache_hits;
- u32_t cache_misses;
- #endif
- #endif
-
- // check callback function
- spiffs_check_callback check_cb_f;
- // file callback function
- spiffs_file_callback file_cb_f;
- // mounted flag
- u8_t mounted;
- // user data
- void *user_data;
- // config magic
- u32_t config_magic;
- } spiffs;
-
- /* spiffs file status struct */
- typedef struct {
- spiffs_obj_id obj_id;
- u32_t size;
- spiffs_obj_type type;
- spiffs_page_ix pix;
- u8_t name[SPIFFS_OBJ_NAME_LEN];
- #if SPIFFS_OBJ_META_LEN
- u8_t meta[SPIFFS_OBJ_META_LEN];
- #endif
- } spiffs_stat;
-
- struct spiffs_dirent {
- spiffs_obj_id obj_id;
- u8_t name[SPIFFS_OBJ_NAME_LEN];
- spiffs_obj_type type;
- u32_t size;
- spiffs_page_ix pix;
- #if SPIFFS_OBJ_META_LEN
- u8_t meta[SPIFFS_OBJ_META_LEN];
- #endif
- };
-
- typedef struct {
- spiffs *fs;
- spiffs_block_ix block;
- int entry;
- } spiffs_DIR;
-
- #if SPIFFS_IX_MAP
-
- typedef struct {
- // buffer with looked up data pixes
- spiffs_page_ix *map_buf;
- // precise file byte offset
- u32_t offset;
- // start data span index of lookup buffer
- spiffs_span_ix start_spix;
- // end data span index of lookup buffer
- spiffs_span_ix end_spix;
- } spiffs_ix_map;
-
- #endif
-
- // functions
-
- #if SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
- /**
- * Special function. This takes a spiffs config struct and returns the number
- * of blocks this file system was formatted with. This function relies on
- * that following info is set correctly in given config struct:
- *
- * phys_addr, log_page_size, and log_block_size.
- *
- * Also, hal_read_f must be set in the config struct.
- *
- * One must be sure of the correct page size and that the physical address is
- * correct in the probed file system when calling this function. It is not
- * checked if the phys_addr actually points to the start of the file system,
- * so one might get a false positive if entering a phys_addr somewhere in the
- * middle of the file system at block boundary. In addition, it is not checked
- * if the page size is actually correct. If it is not, weird file system sizes
- * will be returned.
- *
- * If this function detects a file system it returns the assumed file system
- * size, which can be used to set the phys_size.
- *
- * Otherwise, it returns an error indicating why it is not regarded as a file
- * system.
- *
- * Note: this function is not protected with SPIFFS_LOCK and SPIFFS_UNLOCK
- * macros. It returns the error code directly, instead of as read by
- * SPIFFS_errno.
- *
- * @param config essential parts of the physical and logical
- * configuration of the file system.
- */
- s32_t SPIFFS_probe_fs(spiffs_config *config);
- #endif // SPIFFS_USE_MAGIC && SPIFFS_USE_MAGIC_LENGTH && SPIFFS_SINGLETON==0
-
- /**
- * Initializes the file system dynamic parameters and mounts the filesystem.
- * If SPIFFS_USE_MAGIC is enabled the mounting may fail with SPIFFS_ERR_NOT_A_FS
- * if the flash does not contain a recognizable file system.
- * In this case, SPIFFS_format must be called prior to remounting.
- * @param fs the file system struct
- * @param config the physical and logical configuration of the file system
- * @param work a memory work buffer comprising 2*config->log_page_size
- * bytes used throughout all file system operations
- * @param fd_space memory for file descriptors
- * @param fd_space_size memory size of file descriptors
- * @param cache memory for cache, may be null
- * @param cache_size memory size of cache
- * @param check_cb_f callback function for reporting during consistency checks
- */
- s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
- u8_t *fd_space, u32_t fd_space_size,
- void *cache, u32_t cache_size,
- spiffs_check_callback check_cb_f);
-
- /**
- * Unmounts the file system. All file handles will be flushed of any
- * cached writes and closed.
- * @param fs the file system struct
- */
- void SPIFFS_unmount(spiffs *fs);
-
- /**
- * Creates a new file.
- * @param fs the file system struct
- * @param path the path of the new file
- * @param mode ignored, for posix compliance
- */
- s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode);
-
- /**
- * Opens/creates a file.
- * @param fs the file system struct
- * @param path the path of the new file
- * @param flags the flags for the open command, can be combinations of
- * SPIFFS_O_APPEND, SPIFFS_O_TRUNC, SPIFFS_O_CREAT, SPIFFS_O_RDONLY,
- * SPIFFS_O_WRONLY, SPIFFS_O_RDWR, SPIFFS_O_DIRECT, SPIFFS_O_EXCL
- * @param mode ignored, for posix compliance
- */
- spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode);
-
- /**
- * Opens a file by given dir entry.
- * Optimization purposes, when traversing a file system with SPIFFS_readdir
- * a normal SPIFFS_open would need to traverse the filesystem again to find
- * the file, whilst SPIFFS_open_by_dirent already knows where the file resides.
- * @param fs the file system struct
- * @param e the dir entry to the file
- * @param flags the flags for the open command, can be combinations of
- * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
- * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT.
- * SPIFFS_CREAT will have no effect in this case.
- * @param mode ignored, for posix compliance
- */
- spiffs_file SPIFFS_open_by_dirent(spiffs *fs, struct spiffs_dirent *e, spiffs_flags flags, spiffs_mode mode);
-
- /**
- * Opens a file by given page index.
- * Optimization purposes, opens a file by directly pointing to the page
- * index in the spi flash.
- * If the page index does not point to a file header SPIFFS_ERR_NOT_A_FILE
- * is returned.
- * @param fs the file system struct
- * @param page_ix the page index
- * @param flags the flags for the open command, can be combinations of
- * SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
- * SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT.
- * SPIFFS_CREAT will have no effect in this case.
- * @param mode ignored, for posix compliance
- */
- spiffs_file SPIFFS_open_by_page(spiffs *fs, spiffs_page_ix page_ix, spiffs_flags flags, spiffs_mode mode);
-
- /**
- * Reads from given filehandle.
- * @param fs the file system struct
- * @param fh the filehandle
- * @param buf where to put read data
- * @param len how much to read
- * @returns number of bytes read, or -1 if error
- */
- s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
-
- /**
- * Writes to given filehandle.
- * @param fs the file system struct
- * @param fh the filehandle
- * @param buf the data to write
- * @param len how much to write
- * @returns number of bytes written, or -1 if error
- */
- s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
-
- /**
- * Moves the read/write file offset. Resulting offset is returned or negative if error.
- * lseek(fs, fd, 0, SPIFFS_SEEK_CUR) will thus return current offset.
- * @param fs the file system struct
- * @param fh the filehandle
- * @param offs how much/where to move the offset
- * @param whence if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes
- * if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset
- * if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offse, which should be negative
- */
- s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
-
- /**
- * Removes a file by path
- * @param fs the file system struct
- * @param path the path of the file to remove
- */
- s32_t SPIFFS_remove(spiffs *fs, const char *path);
-
- /**
- * Removes a file by filehandle
- * @param fs the file system struct
- * @param fh the filehandle of the file to remove
- */
- s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
-
- /**
- * Gets file status by path
- * @param fs the file system struct
- * @param path the path of the file to stat
- * @param s the stat struct to populate
- */
- s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
-
- /**
- * Gets file status by filehandle
- * @param fs the file system struct
- * @param fh the filehandle of the file to stat
- * @param s the stat struct to populate
- */
- s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
-
- /**
- * Flushes all pending write operations from cache for given file
- * @param fs the file system struct
- * @param fh the filehandle of the file to flush
- */
- s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
-
- /**
- * Closes a filehandle. If there are pending write operations, these are finalized before closing.
- * @param fs the file system struct
- * @param fh the filehandle of the file to close
- */
- s32_t SPIFFS_close(spiffs *fs, spiffs_file fh);
-
- /**
- * Renames a file
- * @param fs the file system struct
- * @param old path of file to rename
- * @param newPath new path of file
- */
- s32_t SPIFFS_rename(spiffs *fs, const char *old, const char *newPath);
-
- #if SPIFFS_OBJ_META_LEN
- /**
- * Updates file's metadata
- * @param fs the file system struct
- * @param path path to the file
- * @param meta new metadata. must be SPIFFS_OBJ_META_LEN bytes long.
- */
- s32_t SPIFFS_update_meta(spiffs *fs, const char *name, const void *meta);
-
- /**
- * Updates file's metadata
- * @param fs the file system struct
- * @param fh file handle of the file
- * @param meta new metadata. must be SPIFFS_OBJ_META_LEN bytes long.
- */
- s32_t SPIFFS_fupdate_meta(spiffs *fs, spiffs_file fh, const void *meta);
- #endif
-
- /**
- * Returns last error of last file operation.
- * @param fs the file system struct
- */
- s32_t SPIFFS_errno(spiffs *fs);
-
- /**
- * Clears last error.
- * @param fs the file system struct
- */
- void SPIFFS_clearerr(spiffs *fs);
-
- /**
- * Opens a directory stream corresponding to the given name.
- * The stream is positioned at the first entry in the directory.
- * On hydrogen builds the name argument is ignored as hydrogen builds always correspond
- * to a flat file structure - no directories.
- * @param fs the file system struct
- * @param name the name of the directory
- * @param d pointer the directory stream to be populated
- */
- spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
-
- /**
- * Closes a directory stream
- * @param d the directory stream to close
- */
- s32_t SPIFFS_closedir(spiffs_DIR *d);
-
- /**
- * Reads a directory into given spifs_dirent struct.
- * @param d pointer to the directory stream
- * @param e the dirent struct to be populated
- * @returns null if error or end of stream, else given dirent is returned
- */
- struct spiffs_dirent *SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e);
-
- /**
- * Runs a consistency check on given filesystem.
- * @param fs the file system struct
- */
- s32_t SPIFFS_check(spiffs *fs);
-
- /**
- * Returns number of total bytes available and number of used bytes.
- * This is an estimation, and depends on if there a many files with little
- * data or few files with much data.
- * NB: If used number of bytes exceeds total bytes, a SPIFFS_check should
- * run. This indicates a power loss in midst of things. In worst case
- * (repeated powerlosses in mending or gc) you might have to delete some files.
- *
- * @param fs the file system struct
- * @param total total number of bytes in filesystem
- * @param used used number of bytes in filesystem
- */
- s32_t SPIFFS_info(spiffs *fs, u32_t *total, u32_t *used);
-
- /**
- * Formats the entire file system. All data will be lost.
- * The filesystem must not be mounted when calling this.
- *
- * NB: formatting is awkward. Due to backwards compatibility, SPIFFS_mount
- * MUST be called prior to formatting in order to configure the filesystem.
- * If SPIFFS_mount succeeds, SPIFFS_unmount must be called before calling
- * SPIFFS_format.
- * If SPIFFS_mount fails, SPIFFS_format can be called directly without calling
- * SPIFFS_unmount first.
- *
- * @param fs the file system struct
- */
- s32_t SPIFFS_format(spiffs *fs);
-
- /**
- * Returns nonzero if spiffs is mounted, or zero if unmounted.
- * @param fs the file system struct
- */
- u8_t SPIFFS_mounted(spiffs *fs);
-
- /**
- * Tries to find a block where most or all pages are deleted, and erase that
- * block if found. Does not care for wear levelling. Will not move pages
- * around.
- * If parameter max_free_pages are set to 0, only blocks with only deleted
- * pages will be selected.
- *
- * NB: the garbage collector is automatically called when spiffs needs free
- * pages. The reason for this function is to give possibility to do background
- * tidying when user knows the system is idle.
- *
- * Use with care.
- *
- * Setting max_free_pages to anything larger than zero will eventually wear
- * flash more as a block containing free pages can be erased.
- *
- * Will set err_no to SPIFFS_OK if a block was found and erased,
- * SPIFFS_ERR_NO_DELETED_BLOCK if no matching block was found,
- * or other error.
- *
- * @param fs the file system struct
- * @param max_free_pages maximum number allowed free pages in block
- */
- s32_t SPIFFS_gc_quick(spiffs *fs, u16_t max_free_pages);
-
- /**
- * Will try to make room for given amount of bytes in the filesystem by moving
- * pages and erasing blocks.
- * If it is physically impossible, err_no will be set to SPIFFS_ERR_FULL. If
- * there already is this amount (or more) of free space, SPIFFS_gc will
- * silently return. It is recommended to call SPIFFS_info before invoking
- * this method in order to determine what amount of bytes to give.
- *
- * NB: the garbage collector is automatically called when spiffs needs free
- * pages. The reason for this function is to give possibility to do background
- * tidying when user knows the system is idle.
- *
- * Use with care.
- *
- * @param fs the file system struct
- * @param size amount of bytes that should be freed
- */
- s32_t SPIFFS_gc(spiffs *fs, u32_t size);
-
- /**
- * Check if EOF reached.
- * @param fs the file system struct
- * @param fh the filehandle of the file to check
- */
- s32_t SPIFFS_eof(spiffs *fs, spiffs_file fh);
-
- /**
- * Get position in file.
- * @param fs the file system struct
- * @param fh the filehandle of the file to check
- */
- s32_t SPIFFS_tell(spiffs *fs, spiffs_file fh);
-
- /**
- * Registers a callback function that keeps track on operations on file
- * headers. Do note, that this callback is called from within internal spiffs
- * mechanisms. Any operations on the actual file system being callbacked from
- * in this callback will mess things up for sure - do not do this.
- * This can be used to track where files are and move around during garbage
- * collection, which in turn can be used to build location tables in ram.
- * Used in conjuction with SPIFFS_open_by_page this may improve performance
- * when opening a lot of files.
- * Must be invoked after mount.
- *
- * @param fs the file system struct
- * @param cb_func the callback on file operations
- */
- s32_t SPIFFS_set_file_callback_func(spiffs *fs, spiffs_file_callback cb_func);
-
- #if SPIFFS_IX_MAP
-
- /**
- * Maps the first level index lookup to a given memory map.
- * This will make reading big files faster, as the memory map will be used for
- * looking up data pages instead of searching for the indices on the physical
- * medium. When mapping, all affected indicies are found and the information is
- * copied to the array.
- * Whole file or only parts of it may be mapped. The index map will cover file
- * contents from argument offset until and including arguments (offset+len).
- * It is valid to map a longer range than the current file size. The map will
- * then be populated when the file grows.
- * On garbage collections and file data page movements, the map array will be
- * automatically updated. Do not tamper with the map array, as this contains
- * the references to the data pages. Modifying it from outside will corrupt any
- * future readings using this file descriptor.
- * The map will no longer be used when the file descriptor closed or the file
- * is unmapped.
- * This can be useful to get faster and more deterministic timing when reading
- * large files, or when seeking and reading a lot within a file.
- * @param fs the file system struct
- * @param fh the file handle of the file to map
- * @param map a spiffs_ix_map struct, describing the index map
- * @param offset absolute file offset where to start the index map
- * @param len length of the mapping in actual file bytes
- * @param map_buf the array buffer for the look up data - number of required
- * elements in the array can be derived from function
- * SPIFFS_bytes_to_ix_map_entries given the length
- */
- s32_t SPIFFS_ix_map(spiffs *fs, spiffs_file fh, spiffs_ix_map *map,
- u32_t offset, u32_t len, spiffs_page_ix *map_buf);
-
- /**
- * Unmaps the index lookup from this filehandle. All future readings will
- * proceed as normal, requiring reading of the first level indices from
- * physical media.
- * The map and map buffer given in function SPIFFS_ix_map will no longer be
- * referenced by spiffs.
- * It is not strictly necessary to unmap a file before closing it, as closing
- * a file will automatically unmap it.
- * @param fs the file system struct
- * @param fh the file handle of the file to unmap
- */
- s32_t SPIFFS_ix_unmap(spiffs *fs, spiffs_file fh);
-
- /**
- * Moves the offset for the index map given in function SPIFFS_ix_map. Parts or
- * all of the map buffer will repopulated.
- * @param fs the file system struct
- * @param fh the mapped file handle of the file to remap
- * @param offset new absolute file offset where to start the index map
- */
- s32_t SPIFFS_ix_remap(spiffs *fs, spiffs_file fh, u32_t offs);
-
- /**
- * Utility function to get number of spiffs_page_ix entries a map buffer must
- * contain on order to map given amount of file data in bytes.
- * See function SPIFFS_ix_map and SPIFFS_ix_map_entries_to_bytes.
- * @param fs the file system struct
- * @param bytes number of file data bytes to map
- * @return needed number of elements in a spiffs_page_ix array needed to
- * map given amount of bytes in a file
- */
- s32_t SPIFFS_bytes_to_ix_map_entries(spiffs *fs, u32_t bytes);
-
- /**
- * Utility function to amount of file data bytes that can be mapped when
- * mapping a file with buffer having given number of spiffs_page_ix entries.
- * See function SPIFFS_ix_map and SPIFFS_bytes_to_ix_map_entries.
- * @param fs the file system struct
- * @param map_page_ix_entries number of entries in a spiffs_page_ix array
- * @return amount of file data in bytes that can be mapped given a map
- * buffer having given amount of spiffs_page_ix entries
- */
- s32_t SPIFFS_ix_map_entries_to_bytes(spiffs *fs, u32_t map_page_ix_entries);
-
- #endif // SPIFFS_IX_MAP
-
-
- #if SPIFFS_TEST_VISUALISATION
- /**
- * Prints out a visualization of the filesystem.
- * @param fs the file system struct
- */
- s32_t SPIFFS_vis(spiffs *fs);
- #endif
-
- #if SPIFFS_BUFFER_HELP
- /**
- * Returns number of bytes needed for the filedescriptor buffer given
- * amount of file descriptors.
- */
- u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
-
- #if SPIFFS_CACHE
- /**
- * Returns number of bytes needed for the cache buffer given
- * amount of cache pages.
- */
- u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
- #endif
- #endif
-
- #if SPIFFS_CACHE
- #endif
- #if defined(__cplusplus)
- }
- #endif
-
- #endif /* SPIFFS_H_ */
|