spiffs.h

00001 /*
00002  * spiffs.h
00003  *
00004  *  Created on: May 26, 2013
00005  *      Author: petera
00006  */
00007 
00008 
00009 
00010 #ifndef SPIFFS_H_
00011 #define SPIFFS_H_
00012 
00013 #include "spiffs_config.h"
00014 
00015 #ifdef __cplusplus
00016 extern "C"
00017 {
00018 #endif
00019 
00020 #define SPIFFS_OK                       0
00021 #define SPIFFS_ERR_NOT_MOUNTED          -10000
00022 #define SPIFFS_ERR_FULL                 -10001
00023 #define SPIFFS_ERR_NOT_FOUND            -10002
00024 #define SPIFFS_ERR_END_OF_OBJECT        -10003
00025 #define SPIFFS_ERR_DELETED              -10004
00026 #define SPIFFS_ERR_NOT_FINALIZED        -10005
00027 #define SPIFFS_ERR_NOT_INDEX            -10006
00028 #define SPIFFS_ERR_OUT_OF_FILE_DESCS    -10007
00029 #define SPIFFS_ERR_FILE_CLOSED          -10008
00030 #define SPIFFS_ERR_FILE_DELETED         -10009
00031 #define SPIFFS_ERR_BAD_DESCRIPTOR       -10010
00032 #define SPIFFS_ERR_IS_INDEX             -10011
00033 #define SPIFFS_ERR_IS_FREE              -10012
00034 #define SPIFFS_ERR_INDEX_SPAN_MISMATCH  -10013
00035 #define SPIFFS_ERR_DATA_SPAN_MISMATCH   -10014
00036 #define SPIFFS_ERR_INDEX_REF_FREE       -10015
00037 #define SPIFFS_ERR_INDEX_REF_LU         -10016
00038 #define SPIFFS_ERR_INDEX_REF_INVALID    -10017
00039 #define SPIFFS_ERR_INDEX_FREE           -10018
00040 #define SPIFFS_ERR_INDEX_LU             -10019
00041 #define SPIFFS_ERR_INDEX_INVALID        -10020
00042 #define SPIFFS_ERR_NOT_WRITABLE         -10021
00043 #define SPIFFS_ERR_NOT_READABLE         -10022
00044 
00045 #define SPIFFS_ERR_INTERNAL             -10050
00046 
00047 #define SPIFFS_ERR_TEST                 -10100
00048 
00049 
00050 // spiffs file descriptor index type. must be signed
00051 typedef s16_t spiffs_file;
00052 // spiffs file descriptor flags
00053 typedef u16_t spiffs_flags;
00054 // spiffs file mode
00055 typedef u16_t spiffs_mode;
00056 // object type
00057 typedef u8_t spiffs_obj_type;
00058 
00059 /* spi read call function type */
00060 typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
00061 /* spi write call function type */
00062 typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
00063 /* spi erase call function type */
00064 typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
00065 
00066 /* file system check callback report operation */
00067 typedef enum {
00068   SPIFFS_CHECK_LOOKUP = 0,
00069   SPIFFS_CHECK_INDEX,
00070   SPIFFS_CHECK_PAGE
00071 } spiffs_check_type;
00072 
00073 /* file system check callback report type */
00074 typedef enum {
00075   SPIFFS_CHECK_PROGRESS = 0,
00076   SPIFFS_CHECK_ERROR,
00077   SPIFFS_CHECK_FIX_INDEX,
00078   SPIFFS_CHECK_FIX_LOOKUP,
00079   SPIFFS_CHECK_DELETE_ORPHANED_INDEX,
00080   SPIFFS_CHECK_DELETE_PAGE,
00081   SPIFFS_CHECK_DELETE_BAD_FILE,
00082 } spiffs_check_report;
00083 
00084 /* file system check callback function */
00085 typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
00086     u32_t arg1, u32_t arg2);
00087 
00088 #ifndef SPIFFS_DBG
00089 #define SPIFFS_DBG(...) \
00090     print(__VA_ARGS__)
00091 #endif
00092 #ifndef SPIFFS_GC_DBG
00093 #define SPIFFS_GC_DBG(...) printf(__VA_ARGS__)
00094 #endif
00095 #ifndef SPIFFS_CACHE_DBG
00096 #define SPIFFS_CACHE_DBG(...) printf(__VA_ARGS__)
00097 #endif
00098 #ifndef SPIFFS_CHECK_DBG
00099 #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
00100 #endif
00101 
00102 /* Any write to the filehandle is appended to end of the file */
00103 #define SPIFFS_APPEND                   (1<<0)
00104 /* If the opened file exists, it will be truncated to zero length before opened */
00105 #define SPIFFS_TRUNC                    (1<<1)
00106 /* If the opened file does not exist, it will be created before opened */
00107 #define SPIFFS_CREAT                    (1<<2)
00108 /* The opened file may only be read */
00109 #define SPIFFS_RDONLY                   (1<<3)
00110 /* The opened file may only be writted */
00111 #define SPIFFS_WRONLY                   (1<<4)
00112 /* The opened file may be both read and writted */
00113 #define SPIFFS_RDWR                     (SPIFFS_RDONLY | SPIFFS_WRONLY)
00114 /* Any writes to the filehandle will never be cached */
00115 #define SPIFFS_DIRECT                   (1<<5)
00116 
00117 #define SPIFFS_SEEK_SET                 (0)
00118 #define SPIFFS_SEEK_CUR                 (1)
00119 #define SPIFFS_SEEK_END                 (2)
00120 
00121 #define SPIFFS_TYPE_FILE                (1)
00122 #define SPIFFS_TYPE_DIR                 (2)
00123 #define SPIFFS_TYPE_HARD_LINK           (3)
00124 #define SPIFFS_TYPE_SOFT_LINK           (4)
00125 
00126 #ifndef SPIFFS_LOCK
00127 #define SPIFFS_LOCK(fs)
00128 #endif
00129 
00130 #ifndef SPIFFS_UNLOCK
00131 #define SPIFFS_UNLOCK(fs)
00132 #endif
00133 
00134 // phys structs
00135 
00136 // spiffs spi configuration struct
00137 typedef struct {
00138   // physical read function
00139   spiffs_read hal_read_f;
00140   // physical write function
00141   spiffs_write hal_write_f;
00142   // physical erase function
00143   spiffs_erase hal_erase_f;
00144 #if SPIFFS_SINGLETON == 0
00145   // physical size of the spi flash
00146   u32_t phys_size;
00147   // physical offset in spi flash used for spiffs,
00148   // must be on block boundary
00149   u32_t phys_addr;
00150   // physical size when erasing a block
00151   u32_t phys_erase_block;
00152 
00153   // logical size of a block, must be on physical
00154   // block size boundary and must never be less than
00155   // a physical block
00156   u32_t log_block_size;
00157   // logical size of a page, must be at least
00158   // log_block_size / 8
00159   u32_t log_page_size;
00160 #endif
00161 } spiffs_config;
00162 
00163 typedef struct {
00164   // file system configuration
00165   spiffs_config cfg;
00166   // number of logical blocks
00167   u32_t block_count;
00168 
00169   // cursor for free blocks, block index
00170   spiffs_block_ix free_cursor_block_ix;
00171   // cursor for free blocks, entry index
00172   int free_cursor_obj_lu_entry;
00173   // cursor when searching, block index
00174   spiffs_block_ix cursor_block_ix;
00175   // cursor when searching, entry index
00176   int cursor_obj_lu_entry;
00177 
00178   // primary work buffer, size of a logical page
00179   u8_t *lu_work;
00180   // secondary work buffer, size of a logical page
00181   u8_t *work;
00182   // file descriptor memory area
00183   u8_t *fd_space;
00184   // available file descriptors
00185   u32_t fd_count;
00186 
00187   // last error
00188   s32_t err_code;
00189 
00190   // current number of free blocks
00191   u32_t free_blocks;
00192   // current number of busy pages
00193   u32_t stats_p_allocated;
00194   // current number of deleted pages
00195   u32_t stats_p_deleted;
00196   // flag indicating that garbage collector is cleaning
00197   u8_t cleaning;
00198   // max erase count amongst all blocks
00199   spiffs_obj_id max_erase_count;
00200 
00201 #if SPIFFS_GC_STATS
00202   u32_t stats_gc_runs;
00203 #endif
00204 
00205 #if SPIFFS_CACHE
00206   // cache memory
00207   u8_t *cache;
00208   // cache size
00209   u32_t cache_size;
00210 #if SPIFFS_CACHE_STATS
00211   u32_t cache_hits;
00212   u32_t cache_misses;
00213 #endif
00214 #endif
00215 
00216   // check callback function
00217   spiffs_check_callback check_cb_f;
00218 } spiffs;
00219 
00220 /* spiffs file status struct */
00221 typedef struct {
00222   spiffs_obj_id obj_id;
00223   u32_t size;
00224   spiffs_obj_type type;
00225   u8_t name[SPIFFS_OBJ_NAME_LEN];
00226 } spiffs_stat;
00227 
00228 struct spiffs_dirent {
00229   spiffs_obj_id obj_id;
00230   u8_t name[SPIFFS_OBJ_NAME_LEN];
00231   spiffs_obj_type type;
00232   u32_t size;
00233 };
00234 
00235 typedef struct {
00236   spiffs *fs;
00237   spiffs_block_ix block;
00238   int entry;
00239 } spiffs_DIR;
00240 
00241 // functions
00242 
00243 /**
00244  * Initializes the file system dynamic parameters and mounts the filesystem
00245  * @param fs            the file system struct
00246  * @param config        the physical and logical configuration of the file system
00247  * @param work          a memory work buffer comprising 2*config->log_page_size
00248  *                      bytes used throughout all file system operations
00249  * @param fd_space      memory for file descriptors
00250  * @param fd_space_size memory size of file descriptors
00251  * @param cache         memory for cache, may be null
00252  * @param cache_size    memory size of cache
00253  * @param check_cb_f    callback function for reporting during consistency checks
00254  */
00255 s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
00256     u8_t *fd_space, u32_t fd_space_size,
00257     u8_t *cache, u32_t cache_size,
00258     spiffs_check_callback check_cb_f);
00259 
00260 /**
00261  * Unmounts the file system. All file handles will be flushed of any
00262  * cached writes and closed.
00263  * @param fs            the file system struct
00264  */
00265 void SPIFFS_unmount(spiffs *fs);
00266 
00267 /**
00268  * Creates a new file.
00269  * @param fs            the file system struct
00270  * @param path          the path of the new file
00271  * @param mode          ignored, for posix compliance
00272  */
00273 s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_mode mode);
00274 
00275 /**
00276  * Opens/creates a file.
00277  * @param fs            the file system struct
00278  * @param path          the path of the new file
00279  * @param flags         the flags for the open command, can be combinations of
00280  *                      SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
00281  *                      SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT
00282  * @param mode          ignored, for posix compliance
00283  */
00284 spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_flags flags, spiffs_mode mode);
00285 
00286 /**
00287  * Reads from given filehandle.
00288  * @param fs            the file system struct
00289  * @param fh            the filehandle
00290  * @param buf           where to put read data
00291  * @param len           how much to read
00292  * @returns number of bytes read, or -1 if error
00293  */
00294 s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
00295 
00296 /**
00297  * Writes to given filehandle.
00298  * @param fs            the file system struct
00299  * @param fh            the filehandle
00300  * @param buf           the data to write
00301  * @param len           how much to write
00302  * @returns number of bytes written, or -1 if error
00303  */
00304 s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
00305 
00306 /**
00307  * Moves the read/write file offset
00308  * @param fs            the file system struct
00309  * @param fh            the filehandle
00310  * @param offs          how much/where to move the offset
00311  * @param whence        if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes
00312  *                      if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset
00313  *                      if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offset
00314  */
00315 s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
00316 
00317 /**
00318  * Removes a file by path
00319  * @param fs            the file system struct
00320  * @param path          the path of the file to remove
00321  */
00322 s32_t SPIFFS_remove(spiffs *fs, const char *path);
00323 
00324 /**
00325  * Removes a file by path
00326  * @param fs            the file system struct
00327  * @param path          the path of the file to move
00328  * @param new_path          the path of the file to move
00329  */
00330 s32_t SPIFFS_move(spiffs *fs, const char *path, const char *new_path);
00331 
00332 /**
00333  * Removes a file by filehandle
00334  * @param fs            the file system struct
00335  * @param fh            the filehandle of the file to remove
00336  */
00337 s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
00338 
00339 /**
00340  * Gets file status by path
00341  * @param fs            the file system struct
00342  * @param path          the path of the file to stat
00343  * @param s             the stat struct to populate
00344  */
00345 s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
00346 
00347 /**
00348  * Gets file status by filehandle
00349  * @param fs            the file system struct
00350  * @param fh            the filehandle of the file to stat
00351  * @param s             the stat struct to populate
00352  */
00353 s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
00354 
00355 /**
00356  * Flushes all pending write operations from cache for given file
00357  * @param fs            the file system struct
00358  * @param fh            the filehandle of the file to flush
00359  */
00360 s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
00361 
00362 /**
00363  * Closes a filehandle. If there are pending write operations, these are finalized before closing.
00364  * @param fs            the file system struct
00365  * @param fh            the filehandle of the file to close
00366  */
00367 void SPIFFS_close(spiffs *fs, spiffs_file fh);
00368 
00369 /**
00370  * Returns last error of last file operation.
00371  * @param fs            the file system struct
00372  */
00373 s32_t SPIFFS_errno(spiffs *fs);
00374 
00375 /**
00376  * Opens a directory stream corresponding to the given name.
00377  * The stream is positioned at the first entry in the directory.
00378  * On hydrogen builds the name argument is ignored as hydrogen builds always correspond
00379  * to a flat file structure - no directories.
00380  * @param fs            the file system struct
00381  * @param name          the name of the directory
00382  * @param d             pointer the directory stream to be populated
00383  */
00384 spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
00385 
00386 /**
00387  * Closes a directory stream
00388  * @param d             the directory stream to close
00389  */
00390 s32_t SPIFFS_closedir(spiffs_DIR *d);
00391 
00392 /**
00393  * Reads a directory into given spifs_dirent struct.
00394  * @param d             pointer to the directory stream
00395  * @param e             the dirent struct to be populated
00396  * @returns null if error or end of stream, else given dirent is returned
00397  */
00398 struct spiffs_dirent *SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e);
00399 
00400 /**
00401  * Runs a consistency check on given filesystem.
00402  * @param fs            the file system struct
00403  */
00404 s32_t SPIFFS_check(spiffs *fs);
00405 
00406 #if SPIFFS_TEST_VISUALISATION
00407 /**
00408  * Prints out a visualization of the filesystem.
00409  * @param fs            the file system struct
00410  */
00411 s32_t SPIFFS_vis(spiffs *fs);
00412 #endif
00413 
00414 #if SPIFFS_BUFFER_HELP
00415 /**
00416  * Returns number of bytes needed for the filedescriptor buffer given
00417  * amount of file descriptors.
00418  */
00419 u32_t SPIFFS_buffer_bytes_for_filedescs(spiffs *fs, u32_t num_descs);
00420 
00421 #if SPIFFS_CACHE
00422 /**
00423  * Returns number of bytes needed for the cache buffer given
00424  * amount of cache pages.
00425  */
00426 u32_t SPIFFS_buffer_bytes_for_cache(spiffs *fs, u32_t num_pages);
00427 #endif
00428 #endif
00429 
00430 #if SPIFFS_CHACHE
00431 #endif
00432 
00433 #ifdef __cplusplus
00434 }
00435 #endif
00436 
00437 #endif /* SPIFFS_H_ */