Functions
fsp_err_t	RM_LITTLEFS_FLASH_Open (rm_littlefs_ctrl_t const p_ctrl, rm_littlefs_cfg_t const const p_cfg)

fsp_err_t	RM_LITTLEFS_FLASH_Close (rm_littlefs_ctrl_t *const p_ctrl)

Detailed Description

Middleware for the LittleFS File System control on RA MCUs.

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_flash

The following build time configurations are defined in fsp_cfg/rm_littlefs_flash_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)

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

The block size defined in the LittleFS configuration must be a multiple of the data flash erase size of the MCU. It must be greater than 104 bytes which is the minimum block size of a LittleFS block. For information about data flash erase sizes refer to the "Specifications of the code flash memory and data flash memory" table of the "Flash Memory" chapter's "Overview" section.

Examples

Basic Example

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

extern const rm_littlefs_cfg_t g_rm_littlefs_flash0_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 LittleFS Flash port.*/
    fsp_err_t err = RM_LITTLEFS_FLASH_Open(&g_rm_littlefs_flash0_ctrl, &g_rm_littlefs_flash0_cfg);
    /* 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_flash0_lfs, &g_rm_littlefs_flash0_lfs_cfg);
    handle_lfs_error(lfs_err);
    /* Mount the filesystem. */
    lfs_err = lfs_mount(&g_rm_littlefs_flash0_lfs, &g_rm_littlefs_flash0_lfs_cfg);
    handle_lfs_error(lfs_err);
    /* Create a breakfast directory. */
    lfs_err = lfs_mkdir(&g_rm_littlefs_flash0_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_flash0_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_flash0_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_flash0_lfs, &file, contents, len);
        if (lfs_err < 0)
        {
            handle_lfs_error(lfs_err);
        }
    }
    /* Close the file. */
    lfs_err = lfs_file_close(&g_rm_littlefs_flash0_lfs, &file);
    handle_lfs_error(lfs_err);
    /* Unmount the filesystem. */
    lfs_err = lfs_unmount(&g_rm_littlefs_flash0_lfs);
    handle_lfs_error(lfs_err);
    /* Remount the filesystem. */
    lfs_err = lfs_mount(&g_rm_littlefs_flash0_lfs, &g_rm_littlefs_flash0_lfs_cfg);
    handle_lfs_error(lfs_err);
    /* Open breakfast/toast. */
#ifdef LFS_NO_MALLOC
    lfs_err = lfs_file_opencfg(&g_rm_littlefs_flash0_lfs, &file, path, LFS_O_RDONLY, &g_file_cfg);
    handle_lfs_error(lfs_err);
#else
    lfs_err = lfs_file_open(&g_rm_littlefs_flash0_lfs, &file, path, LFS_O_RDONLY);
    handle_lfs_error(lfs_err);
#endif
    handle_lfs_error(lfs_err);
    /* Verify the toast is buttered the correct amount. */
    for (uint32_t i = 0; i < 10; i++)
    {
        lfs_err = lfs_file_read(&g_rm_littlefs_flash0_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_flash0_lfs, &file);
    handle_lfs_error(lfs_err);
}

Function Documentation

◆ RM_LITTLEFS_FLASH_Open()

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

Opens the driver and initializes lower layer 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	Flash BGO mode must be disabled.
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:

flash_api_t::open

◆ RM_LITTLEFS_FLASH_Close()

fsp_err_t RM_LITTLEFS_FLASH_Close ( rm_littlefs_ctrl_t *const p_ctrl )

Closes the lower level driver.

Implements rm_littlefs_api_t::close().