nodemcu-firmware/app/spiffs/docs/INTEGRATION

* QUICK AND DIRTY INTEGRATION EXAMPLE

So, assume you're running a Cortex-M3 board with a 2 MB SPI flash on it. The 
SPI flash has 64kB blocks. Your project is built using gnumake, and now you 
want to try things out.

First, you simply copy the files in src/ to your own source folder. Exclude
all files in test folder. Then you point out these files in your make script 
for compilation.

Also copy the spiffs_config.h over from the src/default/ folder.

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:

  typedef signed int s32_t;
  typedef unsigned int u32_t;
  typedef signed short s16_t;
  typedef unsigned short u16_t;
  typedef signed char s8_t;
  typedef unsigned char u8_t;
  
Now it should build. Over to the mounting business. Assume you already 
implemented the read, write and erase functions to your SPI flash:

  void my_spi_read(int addr, int size, char *buf)
  void my_spi_write(int addr, int size, char *buf)
  void my_spi_erase(int addr, int size)

In your main.c or similar, include the spiffs.h and do that spiffs struct:

  #include <spiffs.h>
  
  static spiffs fs;

Also, toss up some of the needed buffers:

  #define LOG_PAGE_SIZE       256
  
  static u8_t spiffs_work_buf[LOG_PAGE_SIZE*2];
  static u8_t spiffs_fds[32*4];
  static u8_t spiffs_cache_buf[(LOG_PAGE_SIZE+32)*4];
  
Now, write the my_spiffs_mount function:

  void my_spiffs_mount() {
    spiffs_config cfg;
    cfg.phys_size = 2*1024*1024; // use all spi flash
    cfg.phys_addr = 0; // start spiffs at start of spi flash
    cfg.phys_erase_block = 65536; // according to datasheet
    cfg.log_block_size = 65536; // let us not complicate things
    cfg.log_page_size = LOG_PAGE_SIZE; // as we said
    
    cfg.hal_read_f = my_spi_read;
    cfg.hal_write_f = my_spi_write;
    cfg.hal_erase_f = my_spi_erase;
    
    int res = SPIFFS_mount(&fs,
      &cfg,
      spiffs_work_buf,
      spiffs_fds,
      sizeof(spiffs_fds),
      spiffs_cache_buf,
      sizeof(spiffs_cache_buf),
      0);
    printf("mount res: %i\n", res);
  }

Now, build warns about the my_spi_read, write and erase functions. Wrong 
signatures, so go wrap them:

  static s32_t my_spiffs_read(u32_t addr, u32_t size, u8_t *dst) {
    my_spi_read(addr, size, dst);
    return SPIFFS_OK;
  }

  static s32_t my_spiffs_write(u32_t addr, u32_t size, u8_t *src) {
    my_spi_write(addr, size, dst);
    return SPIFFS_OK;
  }

  static s32_t my_spiffs_erase(u32_t addr, u32_t size) {
    my_spi_erase(addr, size);
    return SPIFFS_OK;
  } 

Redirect the config in my_spiffs_mount to the wrappers instead:

    cfg.hal_read_f = my_spiffs_read;
    cfg.hal_write_f = my_spiffs_write;
    cfg.hal_erase_f = my_spiffs_erase;

Ok, now you should be able to build and run. However, you get this output:
  
  mount res: -1
  
but you wanted 

  mount res: 0
  
This is probably due to you having experimented with your SPI flash, so it
contains rubbish from spiffs's point of view. Do a mass erase and run again.

If all is ok now, you're good to go. Try creating a file and read it back:

  static void test_spiffs() {
    char buf[12];
    
    // Surely, I've mounted spiffs before entering here
  
    spiffs_file fd = SPIFFS_open(&fs, "my_file", SPIFFS_CREAT | SPIFFS_TRUNC | SPIFFS_RDWR, 0);
    if (SPIFFS_write(&fs, fd, (u8_t *)"Hello world", 12) < 0) printf("errno %i\n", SPIFFS_errno(&fs));
    SPIFFS_close(&fs, fd); 
  
    fd = SPIFFS_open(&fs, "my_file", SPIFFS_RDWR, 0);
    if (SPIFFS_read(&fs, fd, (u8_t *)buf, 12) < 0) printf("errno %i\n", SPIFFS_errno(&fs));
    SPIFFS_close(&fs, fd);
  
    printf("--> %s <--\n", buf);
  }
  
Compile, run, cross fingers hard, and you'll get the output:

  --> Hello world <-- 
  
Got errors? Check spiffs.h for error definitions to get a clue what went voodoo.


* THINGS TO CHECK

When you alter the spiffs_config values, make sure you also check the typedefs
in spiffs_config.h:

 - spiffs_block_ix
 - spiffs_page_ix
 - spiffs_obj_id
 - spiffs_span_ix

The sizes of these typedefs must not underflow, else spiffs might end up in
eternal loops. Each typedef is commented what check for.

Also, if you alter the code or just want to verify your configuration, you can
run

 > make test

in the spiffs folder. This will run all testcases using the configuration in
default/spiffs_config.h and test/params_test.h. The tests are written for linux
but should run under cygwin also.


* INTEGRATING SPIFFS

In order to integrate spiffs to your embedded target, you will basically need:
 - A SPI flash device which your processor can communicate with
 - An implementation for reading, writing and erasing the flash
 - Memory (flash or ram) for the code
 - Memory (ram) for the stack

Other stuff may be needed, threaded systems might need mutexes and so on. 

** Logical structure

First and foremost, one must decide how to divide up the SPI flash for spiffs. 
Having the datasheet for the actual SPI flash in hand will help. Spiffs can be 
defined to use all or only parts of the SPI flash.

If following seems arcane, read the "HOW TO CONFIG" chapter first.

 - Decide the logical size of blocks. This must be a multiple of the biggest 
   physical SPI flash block size. To go safe, use the physical block size - 
   which in many cases is 65536 bytes.
 - Decide the logical size of pages. This must be a 2nd logarithm part of the
   logical block size. To go safe, use 256 bytes to start with.
 - Decide how much of the SPI flash memory to be used for spiffs. This must be
   on logical block boundary. If unsafe, use 1 megabyte to start with.
 - Decide where on the SPI flash memory the spiffs area should start. This must
   be on physical block/sector boundary. If unsafe, use address 0.

** SPI flash API

The target must provide three functions to spiffs:

 - s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst)
 - s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src)
 - s32_t (*spiffs_erase)(u32_t addr, u32_t size)
 
These functions define the only communication between the SPI flash and the
spiffs stack. 
 
On success these must return 0 (or SPIFFS_OK). Anything else will be considered
an error. 

The size for read and write requests will never exceed the logical page size,
but it may be less.

The address and size on erase requests will always be on physical block size
boundaries.  

** Mount specification

In spiffs.h, there is a SPIFFS_mount function defined, used to mount spiffs on
the SPI flash.

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)
    
 - fs            Points to a spiffs struct. This may be totally uninitialized.
 - config        Points to a spiffs_config struct. This struct must be
                 initialized when mounting. See below.
 - work          A ram memory buffer being double the size of the logical page
                 size. This buffer is used excessively by the spiffs stack. If
                 logical page size is 256, this buffer must be 512 bytes.
 - fd_space      A ram memory buffer used for file descriptors.
 - fd_space_size The size of the file descriptor buffer. A file descriptor
                 normally is around 32 bytes depending on the build config -
                 the bigger the buffer, the more file descriptors are
                 available.
 - cache         A ram memory buffer used for cache. Ignored if cache is
                 disabled in build config. 
 - cache_size    The size of the cache buffer. Ignored if cache is disabled in
                 build config. One cache page will be slightly larger than the 
                 logical page size. The more ram, the more cache pages, the 
                 quicker the system.
 - check_cb_f    Callback function for monitoring spiffs consistency checks and
                 mending operations. May be null.

The config struct must be initialized prior to mounting. One must always 
define the SPI flash access functions:

 spiffs_config.hal_read_f - pointing to the function reading the SPI flash

 spiffs_config.hal_write_f - pointing to the function writing the SPI flash

 spiffs_config.hal_erase_f - pointing to the function erasing the SPI flash
 
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 
                           spiffs on the SPI flash

 spiffs_config.phys_addr - the physical starting address on the SPI flash

 spiffs_config.phys_erase_block - the physical size of the largest block/sector
                                  on the SPI flash found within the spiffs
                                  usage address space

 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.h.


** Build config

makefile: The files needed to be compiled to your target resides in files.mk to
be included in your makefile, either by cut and paste or by inclusion.

Types: spiffs uses the types u8_t, s8_t, u16_t, s16_t, u32_t, s32_t; these must 
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 
logical page size. It also needs at least one file descriptor. If cache is 
enabled (highly recommended), it will also need a bunch of cache pages.

Say you have a logical page size of 256 bytes. You want to be able to have four
files open simultaneously, and you can give spiffs four cache pages. This 
roughly sums up to:

256*2 (work buffer) + 
32*4 (file descriptors) + 
(256+32)*4 (cache pages) + 40 (cache metadata)

i.e. 1832 bytes. 

This is apart from call stack usage.

To get the exact amount of bytes needed on your specific target, enable 
SPIFFS_BUFFER_HELP in spiffs_config.h, rebuild and call:

  SPIFFS_buffer_bytes_for_filedescs
  SPIFFS_buffer_bytes_for_cache
  
Having these figures you can disable SPIFFS_BUFFER_HELP again to save flash.
 

* HOW TO CONFIG

TODO