SPIFFS Service

SPIFFS Service provides a server which manages the SPI Flash File System.

SPIFFS (SPI Flash File System)

SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. SPIFFS is designed with the following characteristics in mind:

  • 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 ones to zeros
  • Zeros can only be pulled to ones by erase
  • Wear leveling

SPIFFS is allocated to a part or all of SOMANET SoCs data-partition. The allocated area is divided into logical blocks, which in turn are divided into logical pages. The boundary of a logical block must coincide with one or more physical blocks.

../../../../../../_images/spiffs_block_structure.png

A logical block is divided further into a number of logical pages. A page defines the smallest data holding element known to SPIFFS.

../../../../../../_images/spiffs_file.png

The service provides access to all functions of the SPIFFS - writing/reading/erasing of files and much more. For low-level access to flash memory, the module_flash_service is required as a dependency.

../../../../../../_images/spiffs_service_structure.png

Note

The SOMANET SPIFFS Service is based on Peter Andersson’s SPIFFS implementation, which you can find here.

How to use

Important

We assume that you are using SOMANET Base and your app includes the required board support files for your SOMANET device.

See also

You might find useful the SPIFFS Console example app, which illustrates the use of this module.

  1. module_flash_service should be part of your workspace.

  2. Add the SPIFFS Service module to your app Makefile.

    USED_MODULES = module_flash_service module_spiffs
    
  3. Include the SPIFFS Service header spiffs_service.h in your app.

  4. Inside your main function, instantiate the interfaces array for the Service-Clients communication.

  5. Optionally, instantiate the shared memory interface.

  6. On whichever other core you can now perform calls to the SPIFFS Service through the interfaces connected to it.

#include <flash_service.h>

#ifdef XCORE200
    #include <quadflash.h>
#else
    #include <flash.h>
#endif

#include <spiffs_service.h>

#define MAX_FLASH_DATA_INTERFACES 2
#define MAX_SPIFFS_INTERFACES 2

//---------SPI flash definitions---------

// Ports for QuadSPI access on explorerKIT.
fl_QSPIPorts ports = {
    PORT_SQI_CS,
    PORT_SQI_SCLK,
    PORT_SQI_SIO,
    on tile[0]: XS1_CLKBLK_1
};

int main(void)
{
    FlashDataInterface i_data[MAX_FLASH_DATA_INTERFACES];
    FlashBootInterface i_boot;
    SPIFFSInterface i_spiffs[MAX_SPIFFS_INTERFACES];

    par
    {
    on tile[0]:
        {
            flash_service(ports, i_boot, i_data, 1);
        }

        on tile[1]:
        {
            spiffs_service(i_data[0], i_spiffs, 1);
        }
     }

     return 0;
 }

See also

For further information about SPIFFS see the GitHub Wiki-Pages provided by Peter Andersson

API

Definitions

SPIFFS_MAX_FILENAME_SIZE

Maximum size of file name in bytes !Should be the same value as defined in SPIFFS_OBJ_NAME_LEN file spiffs_config.h!

SPIFFS_MAX_DATA_BUFFER_SIZE

Maximum data buffer size.

Types

spiffs_stat

Structure Members:

spiffs_obj_id obj_id
u32_t size
spiffs_obj_type type
spiffs_page_ix pix
u8_t name
unsigned short obj_id
unsigned int size
unsigned char type
unsigned short pix
unsigned char name

Service

[[distributable]] void spiffs_service(CLIENT_INTERFACE(FlashDataInterface, i_data), interface SPIFFSInterface server i_spiffs[n_spiffs], unsigned n_spiffs)

SPIFFS Service provides a server, which managed the SPI Flash File System.

Parameters:
  • CLIENT_INTERFACE(FlashDataInterfacei_data) – Client class for flash service
  • i_spiffs – Server interfaces for SPIFFS service
  • n_spiffs – Pattern variable for SPIFFS service

Interface

interface SPIFFSInterface
[[guarded]] short open_file(char path[], unsigned path_length, unsigned short flags)

Opens/creates a file.

Parameters:
  • path – the path of the new file
  • path_length – the lenght of 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
Returns:

the filehandle

[[guarded]] int close_file(unsigned short fd)

Closes a filehandle.

If there are pending write operations, these are finalized before closing.

Parameters:
  • fd – the filehandle of the file to close
[[guarded]] int read(unsigned short fd, unsigned char data[], unsigned int len)

Reads from given filehandle.

Parameters:
  • fd – the filehandle
  • buf – where to put read data
  • len – how much to read
Returns:

number of bytes read, or -1 if error

[[guarded]] int write(unsigned short fd, unsigned char data[], unsigned int len)

Writes to given filehandle.

Parameters:
  • fd – the filehandle
  • buf – the data to write
  • len – how much to write
Returns:

number of bytes written, or -1 if error

[[guarded]] int remove_file(unsigned short fd)

Removes a file by filehandle.

Parameters:
  • fd – the filehandle of the file to remove
[[guarded]] int vis(void)

Prints out a visualization of the filesystem.

[[guarded]] int ls(void)

Prints out a list of files in filesystem.

[[guarded]] int ls_struct(spiffs_stat s[])

Moves list of files in filesystem to array of spiffs_stat structs.

Parameters:
  • s – array of the file status structs
[[guarded]] int check(void)

Runs a consistency check on given filesystem.

[[guarded]] int status(unsigned short fd, unsigned short &obj_id, unsigned int &size, unsigned char &type, unsigned short &pix, char name[])

Gets file status by filehandle.

Parameters:
  • fd – the filehandle of the file to stat
  • obj_id – Object id
  • size – Size of file
  • type – Type of file
  • pix – Page index
  • name – Name of file
[[guarded]] int get_file_size(unsigned short fd)

Gets file size by filehandle.

[[guarded]] int rename_file(char path[], unsigned path_length, char new_path[], unsigned new_path_length)

Renames a file.

Parameters:
  • path – path of file to rename
  • path_length – length of path of file to rename
  • new_path – new path of file
  • new_path_length – length of new path of file
[[guarded]] int format(void)

Formats the entire file system.

All data will be lost. The filesystem must not be mounted when calling this.

[[guarded]] void unmount(void)

Unmounts the file system.

All file handles will be flushed of any cached writes and closed.

[[guarded]] int seek(unsigned short fd, int offs, int whence)

Moves the read/write file offset.

Resulting offset is returned or negative if error. seek(fd, 0, SPIFFS_SEEK_CUR) will thus return current offset.

Parameters:
  • fd – 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
[[guarded]] int tell(unsigned short fd)

Get position in file.

Parameters:
  • fh – the filehandle of the file to check
[[guarded]] int flush(unsigned short fd)

Flushes all pending write operations from cache for given file.

Parameters:
  • fd – the filehandle of the file to flush
[[guarded]] int errno(void)

Returns last error of last file operation.

[[guarded]] int fs_info(unsigned int &itotal, unsigned int &iused)

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.

Parameters:
  • itotal – total number of bytes in filesystem
  • iused – used number of bytes in filesystem
[[guarded]] int gc(unsigned int size)

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.

Parameters:
  • size – amount of bytes that should be freed
[[guarded]] int gc_quick(unsigned short max_free_pages)

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.

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.

Parameters:
  • max_free_pages – maximum number allowed free pages in block
[[notification]] slave void service_ready(void)