upped version: doc fixing, check fixing, commenting, config restructu…

…ring

README

@@ -1,5 +1,5 @@
 SPIFFS (SPI Flash File System)
-V0.1
+V0.2
 
 Copyright (c) 2013 Peter Andersson (pelleplutt1976<at>gmail.com)
 
@@ -15,7 +15,7 @@ Love to hear feedback though!
 Spiffs is a file system intended for SPI NOR flash devices on embedded targets.
 
 Spiffs is designed with following characteristics in mind:
- - Small (embedded) targets, sparse RAM
+ - Small (embedded) targets, sparse RAM without heap
  - Only big areas of data (blocks) can be erased
  - An erase will reset all bits in block to ones
  - Writing pulls one to zeroes
@@ -26,15 +26,16 @@ Spiffs is designed with following characteristics in mind:
 * FEATURES
 
 What spiffs does:
+ - Specifically designed for low ram usage
+ - Uses statically sized ram buffers, independent of number of files
  - Posix-like api: open, close, read, write, seek, stat, etc
  - It can be run on any NOR flash, not only SPI flash - theoretically also on
    embedded flash of an microprocessor
  - Multiple spiffs configurations can be run on same target - and even on same
    SPI flash device
  - Implements static wear leveling 
  - Built in file system consistency checks
- - Specifically designed for low ram usage
-
+
 What spiffs does not:
  - Presently, spiffs does not support directories. It produces a flat
    structure. Creating a file with path "tmp/myfile.txt" will create a file 

docs/INTEGRATION

@@ -90,7 +90,7 @@ define the SPI flash access functions:
 
  spiffs_config.hal_erase_f - pointing to the function erasing the SPI flash
 
-Depending on the build config - if SPIFFS_SINGLETON is undefined - following
+Depending on the build config - if SPIFFS_SINGLETON is set to zero - following
 parameters must be defined:
 
  spiffs_config.phys_size - the physical number of bytes accounted for 
@@ -102,9 +102,13 @@ parameters must be defined:
                                   on the SPI flash found within the spiffs
                                   usage address space
 
- spiffs_config.log_block_size - 
+ spiffs_config.log_block_size - the logical size of a spiffs block
+
+ spiffs_config.log_page_size - the logical size of a spiffs page
+
+If SPIFFS_SINGLETON is set to one, above parameters must be set ny defines in
+the config header file.
 
- spiffs_config.log_page_size - 
 
 ** Build config
 
@@ -117,6 +121,7 @@ be typedeffed.
 spiffs_config.h: you also need to define a spiffs_config.h header. Example of
 this is found in the default/ directory.
 
+
 ** RAM
 
 Spiffs needs ram. It needs a working buffer being double the size of the 
@@ -144,7 +149,7 @@ you point out these files in your make script for compilation.
 
 Also copy the spiffs_config.h over from the default/ folder.
 
-Try buliding. This fails, nagging about inclusions and u32_t and whatnot. Open 
+Try building. This fails, nagging about inclusions and u32_t and whatnot. Open 
 the spiffs_config.h and delete the bad inclusions. Also, add following 
 typedefs:
 

docs/TECH_SPEC

@@ -228,9 +228,9 @@ would look like this:
 
 PAGE 0  [  12   12  545   12  *12   34   34   *4    0    0    0    0 ...]
 
-where the asterisk means the msb is set.
+where the asterisk means the msb of the object id is set.
 
 This is another way to speed up the searches when looking for object indices.
 By looking on the object id's msb in the object lookup, it is also possible 
-whether the page is an object index page or a data page.
+to find out whether the page is an object index page or a data page.
 

src/default/spiffs_config.h

@@ -20,33 +20,40 @@
 
 // compile time switches
 
-// set generic spiffs debug output
+// Set generic spiffs debug output call.
 #define SPIFFS_DBG(...)
-// set spiffs debug output for garbage collecting
+// Set spiffs debug output call for garbage collecting.
 #define SPIFFS_GC_DBG(...)
-// set spiffs debug output for caching
+// Set spiffs debug output call for caching.
 #define SPIFFS_CACHE_DBG(...)
-// set spiffs debug output for system consistency checks
+// Set spiffs debug output call for system consistency checks.
 #define SPIFFS_CHECK_DBG(...)
 
-// define maximum number of gc runs to perform to reach desired free pages
-#define SPIFFS_GC_MAX_RUNS              3
-// enable/disable statistics on gc
-#define SPIFFS_GC_STATS                 1
+// Enable/disable API functions to determine exact number of bytes
+// for filedescriptor and cache buffers. Once decided for a configuration,
+// this can be disabled to reduce flash.
+#define SPIFFS_BUFFER_HELP              0
 
-// enables/disable memory read caching of nucleus file system operations
-// if enabled, memory area must be provided for cache in SPIFFS_init
+// Enables/disable memory read caching of nucleus file system operations.
+// If enabled, memory area must be provided for cache in SPIFFS_mount.
 #define SPIFFS_CACHE                    1
 #if SPIFFS_CACHE
-// enables memory write caching for file descriptors in hydrogen
+// Enables memory write caching for file descriptors in hydrogen
 #define SPIFFS_CACHE_WR                 1
-// enable/disable statistics on caching
+// Enable/disable statistics on caching. Debug/test purpose only.
 #define SPIFFS_CACHE_STATS              1
 #endif
 
-// checks header of each accessed page to validate state
+// Always check header of each accessed page to ensure consistent state.
+// If enabled it will increase number of reads, will increase flash.
 #define SPIFFS_PAGE_CHECK               1
 
+// Define maximum number of gc runs to perform to reach desired free pages.
+#define SPIFFS_GC_MAX_RUNS              3
+
+// Enable/disable statistics on gc. Debug/test purpose only.
+#define SPIFFS_GC_STATS                 1
+
 // Garbage collecting examines all pages in a block which and sums up
 // to a block score. Deleted pages normally gives positive score and
 // used pages normally gives a negative score (as these must be moved).
@@ -55,22 +62,24 @@
 // The larger the score, the more likely it is that the block will
 // picked for garbage collection.
 
-// garbage collecting heuristics - weight used for deleted pages
+// Farbage collecting heuristics - weight used for deleted pages.
 #define SPIFFS_GC_HEUR_W_DELET          (10)
-// garbage collecting heuristics - weight used for used pages
+// Farbage collecting heuristics - weight used for used pages.
 #define SPIFFS_GC_HEUR_W_USED           (-1)
-// garbage collecting heuristics - weight used for time between
-// last erased and erase of this block
+// Farbage collecting heuristics - weight used for time between
+// last erased and erase of this block.
 #define SPIFFS_GC_HEUR_W_ERASE_AGE      (30)
 
-// object name length
-#define SPIFFS_OBJ_NAME_LEN (32 - sizeof(spiffs_obj_type))
+// Object name maximum length.
+#define SPIFFS_OBJ_NAME_LEN             (32)
 
-// size of buffer on stack used when copying data
+// Size of buffer allocated on stack used when copying data.
+// Lower value generates more read/writes. No meaning having it bigger
+// than logical page size.
 #define SPIFFS_COPY_BUFFER_STACK        (64)
 
 // SPIFFS_LOCK and SPIFFS_UNLOCK protects spiffs from reentrancy on api level
-// These must be defined on a multithreaded system
+// These should be defined on a multithreaded system
 
 // define this to entering a mutex if you're running on a multithreaded system
 #define SPIFFS_LOCK(fs)
@@ -79,12 +88,13 @@
 
 
 // Enable if only one spiffs instance with constant configuration will exist
-// on the target, this will reduce calculations, flash and memory accesses.
+// on the target. This will reduce calculations, flash and memory accesses.
+// Parts of configuration must be defined below instead of at time of mount.
 #define SPIFFS_SINGLETON 0
 
 #if SPIFFS_SINGLETON
-// instead of giving parameters in config struct, singleton build must
-// give parameters in defines below
+// Instead of giving parameters in config struct, singleton build must
+// give parameters in defines below.
 #define SPIFFS_CFG_PHYS_SZ(ignore)        (1024*1024*2)
 #define SPIFFS_CFG_PHYS_ERASE_SZ(ignore)  (65536)
 #define SPIFFS_CFG_PHYS_ADDR(ignore)      (0)
@@ -108,24 +118,24 @@
 #define SPIFFS_TEST_VIS_DATA_STR(id)      "d"
 #endif
 
-// types and constants
-
-// spiffs file descriptor index type
-typedef s16_t spiffs_file;
-// spiffs file descriptor flags
-typedef u32_t spiffs_flags;
-// spiffs file mode
-typedef u32_t spiffs_mode;
-
-// block index type
-typedef u16_t spiffs_block_ix; // (address-phys_addr) / block_size
-// page index type
-typedef u16_t spiffs_page_ix;  // (address-phys_addr) / page_size
-// object id type - most significant bit is reserved for index flag
+// Types depending on configuration such as the amount of flash bytes
+// given to spiffs file system in total (spiffs_file_system_size),
+// the logical block size (log_block_size), and the logical page size
+// (log_page_size)
+
+// Block index type. Make sure the size of this type can hold
+// the highest number of all blocks - i.e. spiffs_file_system_size / log_block_size
+typedef u8_t spiffs_block_ix;
+// Page index type. Make sure the size of this type can hold
+// the highest page number of all pages - i.e. spiffs_file_system_size / log_page_size
+typedef u16_t spiffs_page_ix;
+// Object id type - most significant bit is reserved for index flag. Make sure the
+// size of this type can hold the highest object id on a full system,
+// i.e. 2 + (spiffs_file_system_size / (2*log_page_size))*2
 typedef u16_t spiffs_obj_id;
-// object span index type
+// Object span index type. Make sure the size of this type can
+// hold the largest possible span index on the system -
+// i.e. (spiffs_file_system_size / log_page_size) - 1
 typedef u16_t spiffs_span_ix;
-// object type
-typedef u8_t spiffs_obj_type;
 
 #endif /* SPIFFS_CONFIG_H_ */

src/spiffs.h

@@ -40,6 +40,15 @@
 #define SPIFFS_ERR_INTERNAL             -10050
 
 
+// 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;
+
 /* spi read call function type */
 typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
 /* spi write call function type */
@@ -59,6 +68,7 @@ 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,
@@ -386,4 +396,23 @@ s32_t SPIFFS_check(spiffs *fs);
 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_CHACHE
+#endif
+
 #endif /* SPIFFS_H_ */