Module to enable the SPI Flash File System (SPIFFS) on the TI NVS driver.
The SPIFFSNVS header file should be included in an application as follows:
SPIFFSNVS is designed to provide interface functions required by the SPIFFS to read/write/erase NOR flash memory. These functions are implemented using the TI NVS driver. By leveraging the NVS driver, application code using SPIFFS is not tied to a physical memory type (like SPI flash). The NVS driver abstracts the physical memory interface so SPIFFS application code can run on any NVS driver instance. Changing between internal flash or external SPI flash can be done by having SPIFFS use a different NVS driver instance. SPIFFS will operate within the memory region which has been allocated for the NVS driver instance.
It is highly recommended that you read SPIFFS design and usage documentation before using SPIFFS. Documentation available here: https://github.com/pellepl/spiffs
To mount a SPIFFS file system some configuration parameters and RAM must be provided at runtime (all sizes in bytes):
NVS drivers are aware of the physical block size and the amount of memory allocated (values are set in driver configuration; see board files). The logical block size must be an integer multiple of the physical block size (a.k.a. sector size): logicalBlockSize = n * physicalBlockSize
The logical block size must also be an integer multiple of the logical page size: logicalBlockSize = i * logicalPageSize
A statically allocated RAM work buffer must be provided. This buffer must be (2 * logicalPageSize) in length. A statically allocated RAM file descriptor cache must also be provided. File descriptors are 44 bytes for the default SPIFFS configuration. The cache must be large enough to store as many file descriptors as desired. Start with 4 file descriptors and modify when optimizing for your application. Finally, SPIFFS requires a read/write cache be provided. Start with a (2 * logicalPageSize) size cache; this can be increased or reduced later.
As an example assume that we want to use SPIFFS with a NVS driver instance that has 128k of memory and the the physical block size is 4096 bytes. In this case the logical block size can be set to 8192 bytes (16 logical blocks). Now we can set the logical page size to 256 bytes (32 logical pages per logical block).
Knowing the logical block and logical page sizes desired; SPIFFSNVS_config() must be used to initialize the spiffs_config spiffs structures. SPIFFSNVS_config() requires a SPIFFSNVS_Data object be provided. This object is used by SPIFFSNVS when reading/writing to flash memory. It also stores references to OS objects used for thread safety. Each SPIFFS file system instance must have it's own SPIFFSNVS_Data object and these objects must reside in persistent memory (not on a task stack or memory lost during low power modes). The spiffs.user_data field is used to store a pointer to its respective SPIFFSNVS_Data object. Users must not change spiffs_config and spiffs structures after SPIFFSNVS_config() has been called.
Flash memory on CC13XX and CC26XX devices is divided into rows of 128 or 256 bytes (refer to datasheet for exact size). These rows can support up to 83 write operations before suffering effects of row disturb in which data can be corrupted. Setting the logical page size very small or setting the logical block size too large can lead to many logical pages in a logical block. Normal use and updates to pages can cause more than 83 write operations on a logical block's index page (first page in the logical block). The following conditions must be followed to prevent exceeding the 83 write limit:
It is the user's responsibility to make sure the logical page size is equal to or an integer multiple of the physical row size. SPIFFSNVS_init() will verify and return SPIFFSNVS_STATUS_INV_PAGE_SIZE if the amount of logical pages in a logical block is > 32.
#include <stdint.h>
#include "spiffs_config.h"
#include "spiffs.h"
#include <ti/drivers/NVS.h>
#include <ti/drivers/dpl/MutexP.h>
Go to the source code of this file.
Data Structures | |
struct | SPIFFSNVS_Lock_ |
SPIFFSNVS Lock. More... | |
struct | SPIFFSNVS_Data_ |
SPIFFSNVS data object. More... | |
Macros | |
#define | SPIFFSNVS_STATUS_SUCCESS (0) |
Successful status code returned by: SPIFFSNVS_config() More... | |
#define | SPIFFSNVS_STATUS_ERROR (-1) |
Generic error status code returned by: SPIFFSNVS_config() More... | |
#define | SPIFFSNVS_STATUS_INV_NVS_IDX (-2) |
An error status code returned by SPIFFSNVS_config() More... | |
#define | SPIFFSNVS_STATUS_INV_BLOCK_SIZE (-3) |
An error status code returned by SPIFFSNVS_config() More... | |
#define | SPIFFSNVS_STATUS_INV_PAGE_SIZE (-4) |
An error status code returned by SPIFFSNVS_config() More... | |
Typedefs | |
typedef struct SPIFFSNVS_Lock_ | SPIFFSNVS_Lock |
SPIFFSNVS Lock. More... | |
typedef struct SPIFFSNVS_Data_ | SPIFFSNVS_Data |
SPIFFSNVS data object. More... | |
Functions | |
void | SPIFFSNVS_close (SPIFFSNVS_Data *spiffsnvsData) |
Closes the NVS flash region used for the file system. More... | |
s32_t | SPIFFSNVS_config (SPIFFSNVS_Data *spiffsnvsData, u32_t nvsIndex, spiffs *fs, spiffs_config *fsConfig, u32_t logicalBlockSize, u32_t logicalPageSize) |
Initializes spiffs, spiffs_config and SPIFFSNVS_Data structures for SPIFFS to interface with the NVS driver. More... | |
typedef struct SPIFFSNVS_Lock_ SPIFFSNVS_Lock |
SPIFFSNVS Lock.
Lock mechanism to ensure thread safety.
typedef struct SPIFFSNVS_Data_ SPIFFSNVS_Data |
SPIFFSNVS data object.
Memory required to store the NVS handle used to read/write memory and the locking mechanism used to provide thread safety to SPIFFS. Each SPIFFS file system must have it's own SPIFFSNVS_Data object and it must be persistent.
void SPIFFSNVS_close | ( | SPIFFSNVS_Data * | spiffsnvsData | ) |
Closes the NVS flash region used for the file system.
This function closes the flash region used for the file system by the NVS driver interface configured in SPIFFSNVS_config(). This allows the SPIFFS interface to issue low power commands to any external flash interfaces.
spiffsnvsData | Pointer to a SPIFFSNVS_Data structure |
s32_t SPIFFSNVS_config | ( | SPIFFSNVS_Data * | spiffsnvsData, |
u32_t | nvsIndex, | ||
spiffs * | fs, | ||
spiffs_config * | fsConfig, | ||
u32_t | logicalBlockSize, | ||
u32_t | logicalPageSize | ||
) |
Initializes spiffs, spiffs_config and SPIFFSNVS_Data structures for SPIFFS to interface with the NVS driver.
This function initializes fields in the spiffs, spiffs_config and SPIFFSNVS_Data structures to enable SPIFFS to interface with a NVS driver instance. This function performs the following actions:
The spiffs and spiffs_config structures are used to mount the file system. This function must be called only once for each SPIFFS instance.
spiffsnvsData | Pointer to a SPIFFSNVS_Data structure |
nvsIndex | Index of the NVS driver to be used to read/write flash memory. |
fs | Pointer to a spiffs file system object |
fsConfig | Pointer to a spiffs_config structure |
logicalBlockSize | Logical block size in bytes |
logicalPageSize | Logical page size in bytes |