Functions
fsp_err_t	RM_FREERTOS_PLUS_FAT_Open (rm_freertos_plus_fat_ctrl_t const p_ctrl, rm_freertos_plus_fat_cfg_t const const p_cfg)

fsp_err_t	RM_FREERTOS_PLUS_FAT_MediaInit (rm_freertos_plus_fat_ctrl_t const p_ctrl, rm_freertos_plus_fat_device_t const p_device)

fsp_err_t	RM_FREERTOS_PLUS_FAT_DiskInit (rm_freertos_plus_fat_ctrl_t const p_ctrl, rm_freertos_plus_fat_disk_cfg_t const const p_disk_cfg, FF_Disk_t *const p_disk)

fsp_err_t	RM_FREERTOS_PLUS_FAT_DiskDeinit (rm_freertos_plus_fat_ctrl_t const p_ctrl, FF_Disk_t const p_disk)

fsp_err_t	RM_FREERTOS_PLUS_FAT_InfoGet (rm_freertos_plus_fat_ctrl_t const p_ctrl, FF_Disk_t const p_disk, rm_freertos_plus_fat_info_t *const p_info)

fsp_err_t	RM_FREERTOS_PLUS_FAT_Close (rm_freertos_plus_fat_ctrl_t *const p_ctrl)

Detailed Description

Middleware for the FAT File System control on RA MCUs.

Overview

This module provides the hardware port layer for FreeRTOS+FAT file system. After initializing this module, refer to the FreeRTOS+FAT API reference to use the file system: https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_FAT/index.html

Features

The FreeRTOS+FAT port module supports the following features:

Callbacks for insertion and removal for removable devices.
Helper function to initialize FF_Disk_t
Blocking read and write port functions that use FreeRTOS task notification to pend if FreeRTOS is used
FreeRTOS is optional

Configuration

Build Time Configurations for rm_freertos_plus_fat

The following build time configurations are defined in fsp_cfg/middleware/rm_freertos_plus_fat_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 > FreeRTOS+FAT Port for RA (rm_freertos_plus_fat)

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rm_freertos_plus_fat0	Module name.
Total Number of Sectors	Must be a non-negative integer	31293440	Enter the total number of sectors on the device. If this is not known, update rm_freertos_plus_fat_disk_cfg_t::num_blocks after calling RM_FREERTOS_PLUS_FAT_MediaInit().
Sector Size (bytes)	Must be a power of 2 multiple of 512	512	Select the sector size. Must match the underlying media sector size and at least 512. If this is not known, update rm_freertos_plus_fat_disk_cfg_t::num_blocks after calling RM_FREERTOS_PLUS_FAT_MediaInit().
Cache Size (bytes)	Must be a power of 2 multiple of 512	1024	Select the cache size. Must be a multiple of the sector size and at least 2 times the sector size.
Partition Number	Must be a non-negative integer	0	Select the partition number for this disk.
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided. If this callback function is provided, it will be called when a card is inserted or removed.

Usage Notes

Pending during Read/Write

If the underlying driver supports non-blocking operations, the FreeRTOS+FAT port pends the active FreeRTOS task during read and write operations so other tasks can run in the background.

If FreeRTOS is not used, the FreeRTOS+FAT port spins in a while loop waiting for read and write operations to complete.

FreeRTOS+FAT without FreeRTOS

To use FreeRTOS+FAT without FreeRTOS, copy FreeRTOSConfigMinimal.h to one of your project's include paths and rename it FreeRTOSConfig.h.

Also, update the Malloc function to malloc and the Free function to free in the Common configurations.

Examples

Basic Example

This is a basic example of FreeRTOS+FAT in an application.

#define RM_FREERTOS_PLUS_FAT_EXAMPLE_FILE_NAME            "TEST_FILE.txt"
#define RM_FREERTOS_PLUS_FAT_EXAMPLE_BUFFER_SIZE_BYTES    (10240)
#define RM_FREERTOS_PLUS_FAT_EXAMPLE_PARTITION_NUMBER     (0)
extern rm_freertos_plus_fat_instance_ctrl_t g_freertos_plus_fat0_ctrl;
extern const rm_freertos_plus_fat_cfg_t     g_freertos_plus_fat0_cfg;
extern rm_freertos_plus_fat_disk_cfg_t      g_rm_freertos_plus_fat_disk_cfg;
extern uint8_t g_file_data[RM_FREERTOS_PLUS_FAT_EXAMPLE_BUFFER_SIZE_BYTES];
extern uint8_t g_read_buffer[RM_FREERTOS_PLUS_FAT_EXAMPLE_BUFFER_SIZE_BYTES];
void rm_freertos_plus_fat_example (void)
{
    /* Open media driver.*/
    fsp_err_t err = RM_FREERTOS_PLUS_FAT_Open(&g_freertos_plus_fat0_ctrl, &g_freertos_plus_fat0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Initialize the media and the disk. If the media is removable, it must be inserted before calling
     * RM_FREERTOS_PLUS_FAT_MediaInit. */
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg.device);
    assert(FSP_SUCCESS == err);
    /* Initialize one disk for each partition used in the application. */
    FF_Disk_t disk;
    err = RM_FREERTOS_PLUS_FAT_DiskInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg, &disk);
    assert(FSP_SUCCESS == err);
    /* Mount each disk.  This assumes the disk is already partitioned and formatted. */
    FF_Error_t ff_err = FF_Mount(&disk, RM_FREERTOS_PLUS_FAT_EXAMPLE_PARTITION_NUMBER);
    handle_ff_error(ff_err);
    /* Add the disk to the file system. */
    FF_FS_Add("/", &disk);
    /* Open a source file for writing. */
    FF_FILE * pxSourceFile = ff_fopen((const char *) RM_FREERTOS_PLUS_FAT_EXAMPLE_FILE_NAME, "w");
    assert(NULL != pxSourceFile);
    /* Write file data. */
    size_t size_return = ff_fwrite(g_file_data, sizeof(g_file_data), 1, pxSourceFile);
    assert(1 == size_return);
    /* Close the file. */
    int close_err = ff_fclose(pxSourceFile);
    assert(0 == close_err);
    /* Open the source file in read mode. */
    pxSourceFile = ff_fopen((const char *) RM_FREERTOS_PLUS_FAT_EXAMPLE_FILE_NAME, "r");
    assert(NULL != pxSourceFile);
    /* Read file data. */
    size_return = ff_fread(g_read_buffer, sizeof(g_file_data), 1, pxSourceFile);
    assert(1 == size_return);
    /* Close the file. */
    close_err = ff_fclose(pxSourceFile);
    assert(0 == close_err);
    /* Verify the file data read matches the file written. */
    assert(0U == memcmp(g_file_data, g_read_buffer, sizeof(g_file_data)));
}

Format Example

This shows how to partition and format a disk if it is not already partitioned and formatted.

void rm_freertos_plus_fat_format_example (void)
{
    /* Open media driver.*/
    fsp_err_t err = RM_FREERTOS_PLUS_FAT_Open(&g_freertos_plus_fat0_ctrl, &g_freertos_plus_fat0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Initialize the media and the disk. If the media is removable, it must be inserted before calling
     * RM_FREERTOS_PLUS_FAT_MediaInit. */
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg.device);
    assert(FSP_SUCCESS == err);
    /* Initialize one disk for each partition used in the application. */
    FF_Disk_t disk;
    err = RM_FREERTOS_PLUS_FAT_DiskInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg, &disk);
    assert(FSP_SUCCESS == err);
    /* Try to mount the disk.  If the disk is not formatted, mount will fail. */
    FF_Error_t ff_err = FF_Mount(&disk, RM_FREERTOS_PLUS_FAT_EXAMPLE_PARTITION_NUMBER);
    if (FF_isERR((uint32_t) ff_err))
    {
        /* The disk is likely not formatted. Partition and format the disk, then mount again. */
        FF_PartitionParameters_t partition_params;
        partition_params.ulSectorCount   = g_rm_freertos_plus_fat_disk_cfg.device.sector_count;
        partition_params.ulHiddenSectors = 1;
        partition_params.ulInterSpace    = 0;
        memset(partition_params.xSizes, 0, sizeof(partition_params.xSizes));
        partition_params.xSizes[RM_FREERTOS_PLUS_FAT_EXAMPLE_PARTITION_NUMBER] =
            (BaseType_t) partition_params.ulSectorCount - 1;
        partition_params.xPrimaryCount = 1;
        partition_params.eSizeType     = eSizeIsSectors;
        ff_err = FF_Partition(&disk, &partition_params);
        handle_ff_error(ff_err);
        ff_err = FF_Format(&disk, RM_FREERTOS_PLUS_FAT_EXAMPLE_PARTITION_NUMBER, pdFALSE, pdFALSE);
        handle_ff_error(ff_err);
        ff_err = FF_Mount(&disk, RM_FREERTOS_PLUS_FAT_EXAMPLE_PARTITION_NUMBER);
        handle_ff_error(ff_err);
    }
}

Media Insertion Example

This shows how to use the callback to wait for media insertion.

#if 2 == BSP_CFG_RTOS
static EventGroupHandle_t xUSBEventGroupHandle = NULL;
#else
volatile uint32_t g_rm_freertos_plus_fat_insertion_events = 0;
volatile uint32_t g_rm_freertos_plus_fat_removal_events   = 0;
#endif
/* Callback called by media driver when a removable device is inserted or removed. */
void rm_freertos_plus_fat_test_callback (rm_freertos_plus_fat_callback_args_t * p_args)
{
#if 2 == BSP_CFG_RTOS
    /* Post an event if FreeRTOS is available. */
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    xEventGroupSetBitsFromISR(xUSBEventGroupHandle, p_args->event, &xHigherPriorityTaskWoken);
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
#else
    /* If FreeRTOS is not used, set a global flag. */
    if (p_args->event & RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_INSERTED)
    {
        g_rm_freertos_plus_fat_insertion_events++;
    }
    if (p_args->event & RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_REMOVED)
    {
        g_rm_freertos_plus_fat_removal_events++;
    }
#endif
}
void rm_freertos_plus_fat_media_insertion_example (void)
{
#if 2 == BSP_CFG_RTOS
    /* Create event flags if FreeRTOS is used. */
    xUSBEventGroupHandle = xEventGroupCreate();
    TEST_ASSERT_NOT_EQUAL(NULL, xUSBEventGroupHandle);
#endif
    /* Open media driver.*/
    fsp_err_t err = RM_FREERTOS_PLUS_FAT_Open(&g_freertos_plus_fat0_ctrl, &g_freertos_plus_fat0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Wait for media insertion. */
#if 2 == BSP_CFG_RTOS
    EventBits_t xEventGroupValue = xEventGroupWaitBits(xUSBEventGroupHandle,
                                                       RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_INSERTED,
                                                       pdTRUE,
                                                       pdFALSE,
                                                       portMAX_DELAY);
    assert(RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_INSERTED ==
           (RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_INSERTED & xEventGroupValue));
#else
    while (0U == g_rm_freertos_plus_fat_insertion_events)
    {
        /* Wait for media insertion. */
    }
#endif
    /* Initialize the media and the disk. If the media is removable, it must be inserted before calling
     * RM_FREERTOS_PLUS_FAT_MediaInit. */
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg.device);
    assert(FSP_SUCCESS == err);
    /* Initialize one disk for each partition used in the application. */
    FF_Disk_t disk;
    err = RM_FREERTOS_PLUS_FAT_DiskInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg, &disk);
    assert(FSP_SUCCESS == err);
}

Media Insertion Example for USB

This shows how to use the callback to read and write to USB media.

void rm_freertos_plus_fat_usb_example (void)
{
#if 2 == BSP_CFG_RTOS
    /* Create event flags if FreeRTOS is used. */
    xUSBEventGroupHandle = xEventGroupCreate();
#endif
    /* Open media driver.*/
    fsp_err_t err = RM_FREERTOS_PLUS_FAT_Open(&g_freertos_plus_fat0_ctrl, &g_freertos_plus_fat0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Wait for the USB media to be attached. */
#if 2 == BSP_CFG_RTOS
    EventBits_t xEventGroupValue = xEventGroupWaitBits(xUSBEventGroupHandle,
                                                       RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_INSERTED,
                                                       pdTRUE,
                                                       pdFALSE,
                                                       portMAX_DELAY);
    assert(RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_INSERTED ==
           (RM_FREERTOS_PLUS_FAT_EVENT_MEDIA_INSERTED & xEventGroupValue));
#else
    while (0U == g_rm_freertos_plus_fat_insertion_events)
    {
        /* Wait for the USB media to be attached. */
    }
#endif
    /* Initialize the media and the disk. If the media is removable, it must be inserted before calling
     * RM_FREERTOS_PLUS_FAT_MediaInit. */
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg.device);
    assert(FSP_SUCCESS == err);
    /* Initialize one disk for each partition used in the application. */
    FF_Disk_t disk;
    err = RM_FREERTOS_PLUS_FAT_DiskInit(&g_freertos_plus_fat0_ctrl, &g_rm_freertos_plus_fat_disk_cfg, &disk);
    assert(FSP_SUCCESS == err);
    /* Mount each disk.  This assumes the disk is already partitioned and formatted. */
    FF_Error_t ff_err = FF_Mount(&disk, RM_FREERTOS_PLUS_FAT_EXAMPLE_PARTITION_NUMBER);
    handle_ff_error(ff_err);
    /* Add the disk to the file system. */
    FF_FS_Add("/", &disk);
    /* Open a source file for writing. */
    FF_FILE * pxSourceFile = ff_fopen((const char *) RM_FREERTOS_PLUS_FAT_EXAMPLE_FILE_NAME, "w");
    assert(NULL != pxSourceFile);
    /* Write file data. */
    size_t size_return = ff_fwrite(g_file_data, sizeof(g_file_data), 1, pxSourceFile);
    assert(1 == size_return);
    /* Close the file. */
    int close_err = ff_fclose(pxSourceFile);
    assert(0 == close_err);
    /* Open the source file in read mode. */
    pxSourceFile = ff_fopen((const char *) RM_FREERTOS_PLUS_FAT_EXAMPLE_FILE_NAME, "r");
    assert(NULL != pxSourceFile);
    /* Read file data. */
    size_return = ff_fread(g_read_buffer, sizeof(g_file_data), 1, pxSourceFile);
    assert(1 == size_return);
    /* Close the file. */
    close_err = ff_fclose(pxSourceFile);
    assert(0 == close_err);
    /* Verify the file data read matches the file written. */
    assert(0U == memcmp(g_file_data, g_read_buffer, sizeof(g_file_data)));
}

Data Structures
struct	rm_freertos_plus_fat_instance_ctrl_t

Data Structure Documentation

◆ rm_freertos_plus_fat_instance_ctrl_t

struct rm_freertos_plus_fat_instance_ctrl_t

FreeRTOS plus FAT private control block. DO NOT MODIFY. Initialization occurs when RM_FREERTOS_PLUS_FAT_Open is called.

Function Documentation

◆ RM_FREERTOS_PLUS_FAT_Open()

fsp_err_t RM_FREERTOS_PLUS_FAT_Open	(	rm_freertos_plus_fat_ctrl_t *const	p_ctrl,
		rm_freertos_plus_fat_cfg_t const *const	p_cfg
	)

Initializes lower layer media device.

Implements rm_freertos_plus_fat_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_OUT_OF_MEMORY	Not enough memory to create semaphore.

Returns

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

rm_block_media_api_t::open

◆ RM_FREERTOS_PLUS_FAT_MediaInit()

fsp_err_t RM_FREERTOS_PLUS_FAT_MediaInit	(	rm_freertos_plus_fat_ctrl_t *const	p_ctrl,
		rm_freertos_plus_fat_device_t *const	p_device
	)

Initializes the media device. This function blocks until all identification and configuration commands are complete.

Implements rm_freertos_plus_fat_api_t::mediaInit().

Return values

FSP_SUCCESS	Module is initialized and ready to access the memory device.
FSP_ERR_ASSERTION	An input parameter is invalid.
FSP_ERR_NOT_OPEN	Module has not been initialized.

Returns

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

◆ RM_FREERTOS_PLUS_FAT_DiskInit()

fsp_err_t RM_FREERTOS_PLUS_FAT_DiskInit	(	rm_freertos_plus_fat_ctrl_t *const	p_ctrl,
		rm_freertos_plus_fat_disk_cfg_t const *const	p_disk_cfg,
		FF_Disk_t *const	p_disk
	)

Initializes a FreeRTOS+FAT disk structure. This function calls FF_CreateIOManger.

Implements rm_freertos_plus_fat_api_t::diskInit().

Return values

FSP_SUCCESS	Module is initialized and ready to access the memory device.
FSP_ERR_ASSERTION	An input parameter is invalid.
FSP_ERR_NOT_OPEN	Module has not been initialized.
FSP_ERR_INTERNAL	Call to FF_CreateIOManger failed.

◆ RM_FREERTOS_PLUS_FAT_DiskDeinit()

fsp_err_t RM_FREERTOS_PLUS_FAT_DiskDeinit	(	rm_freertos_plus_fat_ctrl_t *const	p_ctrl,
		FF_Disk_t *const	p_disk
	)

Deinitializes a FreeRTOS+FAT disk structure. This function calls FF_DeleteIOManger.

Implements rm_freertos_plus_fat_api_t::diskDeinit().

Return values

FSP_SUCCESS	Module is initialized and ready to access the memory device.
FSP_ERR_ASSERTION	An input parameter is invalid.
FSP_ERR_NOT_OPEN	Module has not been initialized.

◆ RM_FREERTOS_PLUS_FAT_InfoGet()

fsp_err_t RM_FREERTOS_PLUS_FAT_InfoGet	(	rm_freertos_plus_fat_ctrl_t *const	p_ctrl,
		FF_Disk_t *const	p_disk,
		rm_freertos_plus_fat_info_t *const	p_info
	)

Get partition information. This function can only be called after rm_freertos_plus_fat_api_t::diskInit().

Implements rm_freertos_plus_fat_api_t::infoGet().

Return values

FSP_SUCCESS	Information stored in p_info.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.
FSP_ERR_NOT_FOUND	The value of p_iomanager is NULL.

◆ RM_FREERTOS_PLUS_FAT_Close()

fsp_err_t RM_FREERTOS_PLUS_FAT_Close ( rm_freertos_plus_fat_ctrl_t *const p_ctrl )

Closes media device.

Implements rm_freertos_plus_fat_api_t::close().

Return values

FSP_SUCCESS	Media device closed.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

Returns

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

rm_block_media_api_t::close

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for rm_freertos_plus_fat

Configurations for Storage > FreeRTOS+FAT Port for RA (rm_freertos_plus_fat)

Usage Notes

Pending during Read/Write

FreeRTOS+FAT without FreeRTOS

Examples

Basic Example

Format Example

Media Insertion Example

Media Insertion Example for USB

Data Structures

Data Structure Documentation

◆ rm_freertos_plus_fat_instance_ctrl_t

Function Documentation

◆ RM_FREERTOS_PLUS_FAT_Open()

◆ RM_FREERTOS_PLUS_FAT_MediaInit()

◆ RM_FREERTOS_PLUS_FAT_DiskInit()

◆ RM_FREERTOS_PLUS_FAT_DiskDeinit()

◆ RM_FREERTOS_PLUS_FAT_InfoGet()

◆ RM_FREERTOS_PLUS_FAT_Close()