|
|
#include "spiffs_config.h"Go to the source code of this file.
Data Structures | |
| struct | spiffs_config |
| struct | spiffs_t |
| struct | spiffs_stat |
| struct | spiffs_dirent |
| struct | spiffs_DIR |
| struct | spiffs_ix_map |
Typedefs | |
| typedef s16_t | spiffs_file |
| typedef u16_t | spiffs_flags |
| typedef u16_t | spiffs_mode |
| typedef u8_t | spiffs_obj_type |
| typedef s32_t(* | spiffs_read) (struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *dst) |
| typedef s32_t(* | spiffs_write) (struct spiffs_t *fs, u32_t addr, u32_t size, u8_t *src) |
| typedef s32_t(* | spiffs_erase) (struct spiffs_t *fs, u32_t addr, u32_t size) |
| typedef void(* | spiffs_check_callback) (struct spiffs_t *fs, spiffs_check_type type, spiffs_check_report report, u32_t arg1, u32_t arg2) |
| typedef void(* | spiffs_file_callback) (struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix) |
| typedef struct spiffs_t | spiffs |
| #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_SEEK_BOUNDS -10040 |
| #define SPIFFS_ERR_INTERNAL -10050 |
| #define SPIFFS_ERR_TEST -10100 |
| #define SPIFFS_APPEND (1<<0) |
| #define SPIFFS_O_APPEND SPIFFS_APPEND |
| #define SPIFFS_TRUNC (1<<1) |
| #define SPIFFS_O_TRUNC SPIFFS_TRUNC |
| #define SPIFFS_CREAT (1<<2) |
| #define SPIFFS_O_CREAT SPIFFS_CREAT |
| #define SPIFFS_RDONLY (1<<3) |
| #define SPIFFS_O_RDONLY SPIFFS_RDONLY |
| #define SPIFFS_WRONLY (1<<4) |
| #define SPIFFS_O_WRONLY SPIFFS_WRONLY |
| #define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY) |
| #define SPIFFS_O_RDWR SPIFFS_RDWR |
| #define SPIFFS_DIRECT (1<<5) |
| #define SPIFFS_O_DIRECT SPIFFS_DIRECT |
| #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) |
| typedef s16_t spiffs_file |
| typedef u16_t spiffs_flags |
| typedef u16_t spiffs_mode |
| typedef u8_t spiffs_obj_type |
| typedef void(* spiffs_check_callback) (struct spiffs_t *fs, spiffs_check_type type, spiffs_check_report report, u32_t arg1, u32_t arg2) |
| typedef void(* spiffs_file_callback) (struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix) |
| enum spiffs_check_type |
| enum spiffs_check_report |
| enum spiffs_fileop_type |
| s32_t SPIFFS_probe_fs | ( | spiffs_config * | config | ) |
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.
| config | essential parts of the physical and logical configuration of the file system. |
| 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 | ||
| ) |
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.
| fs | the file system struct |
| config | the physical and logical configuration of the file system |
| work | a memory work buffer comprising 2*config->log_page_size bytes used throughout all file system operations |
| fd_space | memory for file descriptors |
| fd_space_size | memory size of file descriptors |
| cache | memory for cache, may be null |
| cache_size | memory size of cache |
| check_cb_f | callback function for reporting during consistency checks |
| void SPIFFS_unmount | ( | spiffs * | fs | ) |
Unmounts the file system. All file handles will be flushed of any cached writes and closed.
| fs | the file system struct |
| s32_t SPIFFS_creat | ( | spiffs * | fs, |
| const char * | path, | ||
| spiffs_mode | mode | ||
| ) |
Creates a new file.
| fs | the file system struct |
| path | the path of the new file |
| mode | ignored, for posix compliance |
| spiffs_file SPIFFS_open | ( | spiffs * | fs, |
| const char * | path, | ||
| spiffs_flags | flags, | ||
| spiffs_mode | mode | ||
| ) |
Opens/creates a file.
| fs | the file system struct |
| path | the path of the new file |
| 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 |
| 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 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.
| fs | the file system struct |
| e | the dir entry to the file |
| 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. |
| mode | ignored, for posix compliance |
| spiffs_file SPIFFS_open_by_page | ( | spiffs * | fs, |
| spiffs_page_ix | page_ix, | ||
| 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.
| fs | the file system struct |
| page_ix | the page index |
| 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. |
| mode | ignored, for posix compliance |
| s32_t SPIFFS_read | ( | spiffs * | fs, |
| spiffs_file | fh, | ||
| void * | buf, | ||
| s32_t | len | ||
| ) |
Reads from given filehandle.
| fs | the file system struct |
| fh | the filehandle |
| buf | where to put read data |
| len | how much to read |
| s32_t SPIFFS_write | ( | spiffs * | fs, |
| spiffs_file | fh, | ||
| void * | buf, | ||
| s32_t | len | ||
| ) |
Writes to given filehandle.
| fs | the file system struct |
| fh | the filehandle |
| buf | the data to write |
| len | how much to write |
| s32_t SPIFFS_lseek | ( | spiffs * | fs, |
| spiffs_file | fh, | ||
| s32_t | offs, | ||
| int | whence | ||
| ) |
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.
| fs | the file system struct |
| fh | the filehandle |
| offs | how much/where to move the offset |
| 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 |
Removes a file by path
| fs | the file system struct |
| path | the path of the file to remove |
| s32_t SPIFFS_fremove | ( | spiffs * | fs, |
| spiffs_file | fh | ||
| ) |
Removes a file by filehandle
| fs | the file system struct |
| fh | the filehandle of the file to remove |
| s32_t SPIFFS_stat | ( | spiffs * | fs, |
| const char * | path, | ||
| spiffs_stat * | s | ||
| ) |
Gets file status by path
| fs | the file system struct |
| path | the path of the file to stat |
| s | the stat struct to populate |
| s32_t SPIFFS_fstat | ( | spiffs * | fs, |
| spiffs_file | fh, | ||
| spiffs_stat * | s | ||
| ) |
Gets file status by filehandle
| fs | the file system struct |
| fh | the filehandle of the file to stat |
| s | the stat struct to populate |
| s32_t SPIFFS_fflush | ( | spiffs * | fs, |
| spiffs_file | fh | ||
| ) |
Flushes all pending write operations from cache for given file
| fs | the file system struct |
| fh | the filehandle of the file to flush |
| s32_t SPIFFS_close | ( | spiffs * | fs, |
| spiffs_file | fh | ||
| ) |
Closes a filehandle. If there are pending write operations, these are finalized before closing.
| fs | the file system struct |
| fh | the filehandle of the file to close |
Renames a file
| fs | the file system struct |
| old | path of file to rename |
| newPath | new path of file |
Returns last error of last file operation.
| fs | the file system struct |
| void SPIFFS_clearerr | ( | spiffs * | fs | ) |
Clears last error.
| fs | the file system struct |
| spiffs_DIR* SPIFFS_opendir | ( | spiffs * | fs, |
| const char * | name, | ||
| spiffs_DIR * | d | ||
| ) |
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.
| fs | the file system struct |
| name | the name of the directory |
| d | pointer the directory stream to be populated |
| s32_t SPIFFS_closedir | ( | spiffs_DIR * | d | ) |
Closes a directory stream
| d | the directory stream to close |
| struct spiffs_dirent* SPIFFS_readdir | ( | spiffs_DIR * | d, |
| struct spiffs_dirent * | e | ||
| ) |
Reads a directory into given spifs_dirent struct.
| d | pointer to the directory stream |
| e | the dirent struct to be populated |
Runs a consistency check on given filesystem.
| fs | the file system struct |
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.
| fs | the file system struct |
| total | total number of bytes in filesystem |
| used | used number of bytes in filesystem |
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.
| fs | the file system struct |
Returns nonzero if spiffs is mounted, or zero if unmounted.
| fs | the file system struct |
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.
| fs | the file system struct |
| max_free_pages | maximum number allowed free pages in block |
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.
| fs | the file system struct |
| size | amount of bytes that should be freed |
| s32_t SPIFFS_eof | ( | spiffs * | fs, |
| spiffs_file | fh | ||
| ) |
Check if EOF reached.
| fs | the file system struct |
| fh | the filehandle of the file to check |
| s32_t SPIFFS_tell | ( | spiffs * | fs, |
| spiffs_file | fh | ||
| ) |
Get position in file.
| fs | the file system struct |
| fh | the filehandle of the file to check |
| s32_t SPIFFS_set_file_callback_func | ( | spiffs * | fs, |
| spiffs_file_callback | cb_func | ||
| ) |
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.
| fs | the file system struct |
| cb_func | the callback on file operations |
| 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 | ||
| ) |
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.
| fs | the file system struct |
| fh | the file handle of the file to map |
| map | a spiffs_ix_map struct, describing the index map |
| offset | absolute file offset where to start the index map |
| len | length of the mapping in actual file bytes |
| 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_unmap | ( | spiffs * | fs, |
| spiffs_file | fh | ||
| ) |
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.
| fs | the file system struct |
| fh | the file handle of the file to unmap |
| s32_t SPIFFS_ix_remap | ( | spiffs * | fs, |
| spiffs_file | fh, | ||
| u32_t | offs | ||
| ) |
Moves the offset for the index map given in function SPIFFS_ix_map. Parts or all of the map buffer will repopulated.
| fs | the file system struct |
| fh | the mapped file handle of the file to remap |
| offs | new absolute file offset where to start the index map |
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.
| fs | the file system struct |
| bytes | number of file data bytes to map |
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.
| fs | the file system struct |
| map_page_ix_entries | number of entries in a spiffs_page_ix array |
Returns number of bytes needed for the filedescriptor buffer given amount of file descriptors.