RA Flexible Software Package Documentation  Release v5.2.0

 
LittleFS on Flash (rm_littlefs_flash)

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:

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

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_rm_littlefs0 Module name.
Read SizeMust be a non-negative integer1 Minimum size of a block read. All read operations will be a multiple of this value.
Program SizeMust be a non-negative integer4 Minimum size of a block program. All program operations will be a multiple of this value.
Block Size (bytes)Must be a multiple of 64128 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 CountManual Entry(BSP_DATA_FLASH_SIZE_BYTES/128) Number of erasable blocks on the device.
Block CyclesMust be an integer1024 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 SizeMust be a non-negative integer64 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 SizeMust be a non-negative multiple of 816 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:

ConfigurationOptionsDefaultDescription
Custom lfs_util.hManual EntryAdd 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.
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 wrapperName must be a valid C symbolg_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 104bytes 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.

Limitations

This module is not thread safe.

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_SUCCESSSuccess.
FSP_ERR_ASSERTIONAn input parameter was invalid.
FSP_ERR_ALREADY_OPENModule is already open.
FSP_ERR_INVALID_SIZEThe provided block size is invalid.
FSP_ERR_INVALID_ARGUMENTFlash BGO mode must be disabled.
FSP_ERR_INTERNALFailed to create the semaphore.
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls:

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

Return values
FSP_SUCCESSMedia device closed.
FSP_ERR_ASSERTIONAn input parameter was invalid.
FSP_ERR_NOT_OPENModule not open.
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls: