Data Structures | Macros | Typedefs | Functions
SPIFFSNVS.h File Reference

Detailed Description

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

Using SPIFFS and SPIFFSNVS

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

Note
It is recommended to set logical block size equal to the physical block size when starting with SPIFFS. This can be changed later when optimizing the file system for your application.

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

Note
SPIFFS always keeps 2 logical blocks free; in the example above there would only be 14 logical blocks available for storage (16k is unusable). The logical block size can be reduced to have more space for data. The logical block size and logical page size should be changed to optimize the file system for your application.

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.

#define SPIFFS_LOGICAL_BLOCK_SIZE (4096)
#define SPIFFS_LOGICAL_PAGE_SIZE (128)
#define SPIFFS_FILE_DESCRIPTOR_SIZE (44)
static uint8_t spiffsWorkBuffer[SPIFFS_LOGICAL_PAGE_SIZE * 2];
static uint8_t spiffsFileDescriptorCache[SPIFFS_FILE_DESCRIPTOR_SIZE * 4];
static uint8_t spiffsReadWriteCache[SPIFFS_LOGICAL_PAGE_SIZE * 2];
spiffs fs;
spiffs_config fsConfig;
SPIFFSNVS_Object spiffsnvs;
status = SPIFFSNVS_config(&spiffsnvs, Board_NVSINTERNAL, &fs, &fsConfig,
SPIFFS_LOGICAL_BLOCK_SIZE, SPIFFS_LOGICAL_PAGE_SIZE);
if (status != SPIFFSNVS_STATUS_SUCCESS) {
// Handle error condition...
}
status = SPIFFS_mount(&fs, &fsConfig, spiffsWorkBuffer,
spiffsFileDescriptorCache, sizeof(spiffsFileDescriptorCache),
spiffsReadWriteCache, sizeof(spiffsReadWriteCache), NULL);

Logical block and page size restrictions on CC13XX and CC26XX devices

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>
Include dependency graph for SPIFFSNVS.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

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 Documentation

§ SPIFFSNVS_Lock

SPIFFSNVS Lock.

Lock mechanism to ensure thread safety.

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

Function Documentation

§ SPIFFSNVS_config()

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:

  1. Opens the TI NVS driver instance
  2. Verifies valid logical block and logical page sizes are used
  3. Creates a lock used by SPIFFS for thread-safety
  4. Sets fields in spiffs, spiffs_config and SPIFFSNVS_Data structures to enable SPIFFS to use the TI NVS as the interface to flash memory.

The spiffs and spiffs_config structures are used to mount the file system. This function must be called only once for each SPIFFS instance.

Parameters
spiffsnvsDataPointer to a SPIFFSNVS_Data structure
nvsIndexIndex of the NVS driver to be used to read/write flash memory.
fsPointer to a spiffs file system object
fsConfigPointer to a spiffs_config structure
logicalBlockSizeLogical block size in bytes
logicalPageSizeLogical page size in bytes
Returns
SPIFFSNVS_STATUS_SUCCESS if structures were configured correctly.
SPIFFSNVS_STATUS_INV_NVS_IDX if an invalid index is used.
SPIFFSNVS_STATUS_INV_BLOCK_SIZE if an invalid logical block size is used.
SPIFFSNVS_STATUS_INV_PAGE_SIZE if an invalid logical page size is used.
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale