LittleFS on SPI Flash (rm_littlefs_spi_flash_w)

Functions
fsp_err_t	RM_LITTLEFS_SPI_FLASH_W_Open (rm_littlefs_ctrl_t *const p_ctrl, rm_littlefs_cfg_t const *const p_cfg)
fsp_err_t	RM_LITTLEFS_SPI_FLASH_W_Close (rm_littlefs_ctrl_t *const p_ctrl)
int	rm_littlefs_spi_flash_w_read (const struct lfs_config *c, lfs_block_t block, lfs_off_t off, void *buffer, lfs_size_t size)
int	rm_littlefs_spi_flash_w_write (const struct lfs_config *c, lfs_block_t block, lfs_off_t off, const void *buffer, lfs_size_t size)
int	rm_littlefs_spi_flash_w_erase (const struct lfs_config *c, lfs_block_t block)
int	rm_littlefs_spi_flash_w_lock (const struct lfs_config *c)
int	rm_littlefs_spi_flash_w_unlock (const struct lfs_config *c)
int	rm_littlefs_spi_flash_w_sync (const struct lfs_config *c)

Detailed Description

Middleware for the LittleFS File System control using external SPI Flash on RA6W1/RA6W2. This module implements the LittleFS Interface.

Overview

This module provides the hardware port layer for the LittleFS file system. After initializing this module, refer to the LittleFS documentation to use the file system: https://github.com/ARMmbed/littlefs

Configuration

Build Time Configurations for rm_littlefs_spi_flash_w

The following build time configurations are defined in fsp_cfg/rm_littlefs_spi_flash_w_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Storage > LittleFS on Flash (rm_littlefs_flash_w)

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rm_littlefs0	Module name.
Read Size	Must be a non-negative integer	1	Minimum size of a block read. All read operations will be a multiple of this value.
Program Size	Must be a non-negative integer	4	Minimum size of a block program. All program operations will be a multiple of this value.
Block Size (bytes)	Must be a multiple of 64	128	Size of an erasable block. This does not impact RAM consumption and may be larger than the physical erase size. However, non-inlined files take up at minimum one block. Must be a multiple of the read and program sizes.
Block Count	Manual Entry	(BSP_DATA_FLASH_SIZE_BYTES/128)	Number of erasable blocks on the device.
Block Cycles	Must be an integer	1024	Number of erase cycles before LittleFS evicts metadata logs and moves the metadata to another block. Suggested values are in the range 100-1000, with large values having better performance at the cost of less consistent wear distribution. Set to -1 to disable block-level wear-leveling.
Cache Size	Must be a non-negative integer	64	Size of block caches. Each cache buffers a portion of a block in RAM. The LittleFS needs a read cache, a program cache, and one additional cache per file. Larger caches can improve performance by storing more data and reducing the number of disk accesses. Must be a multiple of the read and program sizes, and a factor of the block size.
Lookahead Size	Must be a non-negative multiple of 8	16	Size of the lookahead buffer in bytes. A larger lookahead buffer increases the number of blocks found during an allocation pass. The lookahead buffer is stored as a compact bitmap, so each byte of RAM can track 8 blocks. Must be a multiple of 8.

Common SPI LittleFS Configuration

Build Time Configurations for LittleFS

The following build time configurations are defined in arm/littlefs/lfs_util.h:

Configuration	Options	Default	Description
Custom lfs_util.h	Manual Entry		Add a path to your custom lfs_util.h file. It can be used to override some or all of the configurations defined here, and to define additional configurations.
Thread Safe	Enabled Disabled	Disabled	Enables thread safety in LittleFS.
Read Only	Enabled Disabled	Disabled	Enables Read Only mode in LittleFS.
Use Malloc	Enabled Disabled	Enabled	Configures the use of malloc by LittleFS.
Use Assert	Enabled Disabled	Enabled	Configures the use of assert by LittleFS.
Debug Messages	Enabled Disabled	Disabled	Configures debug messages.
Warning Messages	Enabled Disabled	Disabled	Configures warning messages.
Error Messages	Enabled Disabled	Disabled	Configures error messages.
Trace Messages	Enabled Disabled	Disabled	Configures trace messages.
Intrinsics	Enabled Disabled	Enabled	Configures intrinsic functions such as __builtin_clz.
Instance Name for STDIO wrapper	Name must be a valid C symbol	g_rm_littlefs0	The rm_littlefs instance name to use with the STDIO wrapper.

Usage Notes

Blocking Read/Write/Erase

The LittleFS port blocks on Read/Write/Erase calls until the operation has completed.

Memory Constraints

This module is designed for use with an external SPI NOR Flash device.

• The block size defined in the LittleFS configuration must be a multiple of the SPI flash erase sector size (typically 4 KB).
• The block size must be greater than 104 bytes, which is the minimum block size supported by LittleFS.
• The total number of blocks must not exceed the usable size of the external flash.

Ensure that the flash page size, sector size, and total capacity configured in the driver match the connected SPI flash device.

Performance Considerations

• SPI flash access is slower than internal flash.
• File system performance depends on SPI clock frequency and flash device timings.
• For optimal performance:
  • Avoid frequent small writes
  • Use buffered file operations
  • Align writes to page boundaries when possible

Limitations

This module is not thread safe.

Examples

Basic Example

This is a basic example of LittleFS on external SPI Flash in an application.

extern rm_littlefs_cfg_t g_rm_littlefs_spi_flash_w0_cfg;

#ifdef LFS_NO_MALLOC
static uint8_t                g_file_buffer[LFS_CACHE_SIZE];
static struct lfs_file_config g_file_cfg =
{
    .buffer = g_file_buffer
};
#endif

void rm_littlefs_example (void)
{
    uint8_t    buffer[30];
    lfs_file_t file;


    /* Open the LittleFS SPI flash instance. */
    fsp_err_t err = RM_LITTLEFS_SPI_FLASH_W_Open(&g_rm_littlefs_spi_flash_w0_ctrl, &g_rm_littlefs_spi_flash_w0_cfg);

    if (FSP_SUCCESS != err)
    {
        handle_lfs_error(err);
    }


    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    /* Format the filesystem. */
    int lfs_err = lfs_format(&g_rm_littlefs_spi_flash_w0_lfs, &g_rm_littlefs_spi_flash_w0_lfs_cfg);
    handle_lfs_error(lfs_err);

    /* Mount the filesystem. */
    lfs_err = lfs_mount(&g_rm_littlefs_spi_flash_w0_lfs, &g_rm_littlefs_spi_flash_w0_lfs_cfg);
    handle_lfs_error(lfs_err);

    /* Create a breakfast directory. */
    lfs_err = lfs_mkdir(&g_rm_littlefs_spi_flash_w0_lfs, "breakfast");
    handle_lfs_error(lfs_err);

    /* Create a file toast in the breakfast directory. */
    const char * path = "breakfast/toast";
#ifdef LFS_NO_MALLOC

    /***********************************************************************************************************************
     * By default LittleFS uses malloc to allocate buffers. This can be disabled in the RA Configuration editor.
     * Buffers will be generated from the configuration for the read, program and lookahead buffers.
     * When opening a file a unique buffer must be passed in for use as a file buffer.
     * The buffer size must be equal to the cache size.
     **********************************************************************************************************************/
    lfs_err = lfs_file_opencfg(&g_rm_littlefs_spi_flash_w0_lfs,
                               &file,
                               path,
                               LFS_O_WRONLY | LFS_O_CREAT | LFS_O_APPEND,
                               &g_file_cfg);
    handle_lfs_error(lfs_err);
#else
    lfs_err = lfs_file_open(&g_rm_littlefs_spi_flash_w0_lfs, &file, path, LFS_O_WRONLY | LFS_O_CREAT | LFS_O_APPEND);
    handle_lfs_error(lfs_err);
#endif

    const char * contents = "butter";
    lfs_size_t   len      = strlen(contents);

    /* Apply butter to toast 10 times. */
    for (uint32_t i = 0; i < 10; i++)
    {
        lfs_err = lfs_file_write(&g_rm_littlefs_spi_flash_w0_lfs, &file, contents, len);
        if (lfs_err < 0)
        {
            handle_lfs_error(lfs_err);
        }
    }

    /* Close the file. */
    lfs_err = lfs_file_close(&g_rm_littlefs_spi_flash_w0_lfs, &file);
    handle_lfs_error(lfs_err);

    /* Unmount the filesystem. */
    lfs_err = lfs_unmount(&g_rm_littlefs_spi_flash_w0_lfs);
    handle_lfs_error(lfs_err);

    /* Remount the filesystem. */
    lfs_err = lfs_mount(&g_rm_littlefs_spi_flash_w0_lfs, &g_rm_littlefs_spi_flash_w0_lfs_cfg);
    handle_lfs_error(lfs_err);

    /* Open breakfast/toast. */
#ifdef LFS_NO_MALLOC
    lfs_err = lfs_file_opencfg(&g_rm_littlefs_spi_flash_w0_lfs, &file, path, LFS_O_RDONLY, &g_file_cfg);
    handle_lfs_error(lfs_err);
#else
    lfs_err = lfs_file_open(&g_rm_littlefs_spi_flash_w0_lfs, &file, path, LFS_O_RDONLY);
    handle_lfs_error(lfs_err);
#endif

    /* Verify the toast is buttered the correct amount. */
    for (uint32_t i = 0; i < 10; i++)
    {
        lfs_err = lfs_file_read(&g_rm_littlefs_spi_flash_w0_lfs, &file, buffer, len);
        if (lfs_err < 0)
        {
            handle_lfs_error(lfs_err);
        }

        assert(0 == memcmp(buffer, contents, len));
    }

    /* Close the file. */
    lfs_err = lfs_file_close(&g_rm_littlefs_spi_flash_w0_lfs, &file);
    handle_lfs_error(lfs_err);
}

Function Documentation

RM_LITTLEFS_SPI_FLASH_W_Open()

fsp_err_t RM_LITTLEFS_SPI_FLASH_W_Open	(	rm_littlefs_ctrl_t *const	p_ctrl,
		rm_littlefs_cfg_t const *const	p_cfg
	)

Opens the driver and initializes lower layer SPI driver.

Implements rm_littlefs_api_t::open().

Return values

FSP_SUCCESS	Success.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_INVALID_SIZE	The provided block size is invalid.
FSP_ERR_INVALID_ARGUMENT	Invalid configuration parameter.
FSP_ERR_INTERNAL	Failed to create the semaphore.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• spi_api_t::open

RM_LITTLEFS_SPI_FLASH_W_Close()

fsp_err_t RM_LITTLEFS_SPI_FLASH_W_Close

(

rm_littlefs_ctrl_t *const

p_ctrl

)

Closes the driver and the lower level SPI driver.

Implements rm_littlefs_api_t::close().

Return values

FSP_SUCCESS	The driver was closed successfully.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• spi_api_t::close

rm_littlefs_spi_flash_w_read()

int rm_littlefs_spi_flash_w_read	(	const struct lfs_config *	c,
		lfs_block_t	block,
		lfs_off_t	off,
		void *	buffer,
		lfs_size_t	size
	)

Read data from SPI flash for LittleFS.

Parameters

[in]	c	Pointer to LittleFS configuration.
[in]	block	Block to read from.
[in]	off	Offset within block.
[out]	buffer	Buffer to store read data.
[in]	size	Size of data to read.

Return values

0	Success.
Non-zero	Error occurred.

rm_littlefs_spi_flash_w_write()

int rm_littlefs_spi_flash_w_write	(	const struct lfs_config *	c,
		lfs_block_t	block,
		lfs_off_t	off,
		const void *	buffer,
		lfs_size_t	size
	)

Write data to SPI flash for LittleFS.

Parameters

[in]	c	Pointer to LittleFS configuration.
[in]	block	Block to write to.
[in]	off	Offset within block.
[in]	buffer	Buffer containing data to write.
[in]	size	Size of data to write.

Return values

0	Success.
Non-zero	Error occurred.

rm_littlefs_spi_flash_w_erase()

int rm_littlefs_spi_flash_w_erase	(	const struct lfs_config *	c,
		lfs_block_t	block
	)

Erase block from SPI flash for LittleFS.

Parameters

[in]	c	Pointer to LittleFS configuration.
[in]	block	Block to erase.

Return values

0	Success.
Non-zero	Error occurred.

rm_littlefs_spi_flash_w_lock()

int rm_littlefs_spi_flash_w_lock

(

const struct lfs_config *

c

)

Lock access to SPI flash.

Parameters

[in]

c

Pointer to LittleFS configuration.

Return values

0

Success.

rm_littlefs_spi_flash_w_unlock()

int rm_littlefs_spi_flash_w_unlock

(

const struct lfs_config *

c

)

Unlock access to SPI flash.

Parameters

[in]

c

Pointer to LittleFS configuration.

Return values

0

Success.

rm_littlefs_spi_flash_w_sync()

int rm_littlefs_spi_flash_w_sync

(

const struct lfs_config *

c

)

Sync SPI flash operations.

Parameters

[in]

c

Pointer to LittleFS configuration.

Return values

0

Success.