FreeRTOS+FAT Port (rm_freertos_plus_fat)

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 RZ microprocessor.

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

Currently, the module supports only Block Media USB, but will support Block Media SDMMC in the future.

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 RZT (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_device_t::sector_count 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_device_t::sector_size_bytes 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.

Stack size for FreeRTOS threads using FreeRTOS+FAT

When using the FreeRTOS+FAT function on the Cortex-A55 side, the default stack size of the FreeRTOS thread may be insufficient. Please increase the stack size as needed.

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.

Debug

Please refer to "Debug" section in FreeRTOS Port(rm_freertos_port).

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 const 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. */
    handle_error(err);

    /* Initialize the media and the disk. If the media is removable, it must be inserted before calling
     * RM_FREERTOS_PLUS_FAT_MediaInit. */
    rm_freertos_plus_fat_device_t device;
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &device);
    handle_error(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);
    handle_error(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. */
    handle_error(err);

    /* Initialize the media and the disk. If the media is removable, it must be inserted before calling
     * RM_FREERTOS_PLUS_FAT_MediaInit. */
    rm_freertos_plus_fat_device_t device;
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &device);
    handle_error(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);
    handle_error(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   = 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();
    assert(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. */
    handle_error(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. */
    rm_freertos_plus_fat_device_t device;
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &device);
    handle_error(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);
    handle_error(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. */
    handle_error(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

    /* When not using FreeRTOS, the status of the USB media attachment must be checked using the R_USB_StatusGet function. */
    rm_block_media_usb_instance_ctrl_t * p_block_media_usb_ctrl =
        (rm_block_media_usb_instance_ctrl_t *) g_freertos_plus_fat0_cfg.p_block_media->p_ctrl;
    volatile uint32_t timeout = UINT32_MAX;
    usb_event_info_t  event_info;
    usb_status_t      event = USB_STATUS_NONE;
    while (USB_STATUS_CONFIGURED != event)
    {
        R_USB_EventGet(&event_info, &event);
        timeout--;
        assert(timeout > 0);
    }
    p_block_media_usb_ctrl->device_address = event_info.device_address;
#endif

    /* Initialize the media and the disk. If the media is removable, it must be inserted before calling
     * RM_FREERTOS_PLUS_FAT_MediaInit. */
    rm_freertos_plus_fat_device_t device;
    err = RM_FREERTOS_PLUS_FAT_MediaInit(&g_freertos_plus_fat0_ctrl, &device);
    handle_error(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);
    handle_error(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)));
}

Create multiple file Example for USB

When closing multiple files simultaneously, some USB devices may require a long time to flush data. As a result, the host may proceed to the next operation while the USB device is still processing.

Please add an appropriate wait time or implement a check to ensure that data has been written to the file, as shown below.

#define RM_FREERTOS_PLUS_FAT_EXAMPLE_FILES_TO_CREATE       (10)
#define RM_FREERTOS_PLUS_FAT_EXAMPLE_FILENAME_BUF_BYTES    (64)

void rm_freertos_plus_fat_create_multiple_file_example (void)
{
    char      filename[RM_FREERTOS_PLUS_FAT_EXAMPLE_FILENAME_BUF_BYTES];
    FF_FILE * pxSourceFile[RM_FREERTOS_PLUS_FAT_EXAMPLE_FILES_TO_CREATE];
    for (uint32_t i = 0; i < RM_FREERTOS_PLUS_FAT_EXAMPLE_FILES_TO_CREATE; i++)
    {
        /* Open the source file in read and write mode. */
        sprintf(&filename[0], "TEST%d_FILE.txt", (int) i);
        pxSourceFile[i] = ff_fopen(filename, "w");
        assert(NULL != pxSourceFile[i]);
    }

    for (uint32_t i = 0; i < RM_FREERTOS_PLUS_FAT_EXAMPLE_FILES_TO_CREATE; i++)
    {
        /* Write 7 KB of lorem ipsum text, starting at a different index for each file. */
        size_t size_return = ff_fwrite(&g_file_data, sizeof(g_file_data), 1, pxSourceFile[i]);
        assert(1 == size_return);

        int close_err = ff_fclose(pxSourceFile[i]);
        assert(0 == close_err);

        /* The next close process is not performed until it is confirmed that the data can be written. */
        volatile uint32_t timeout = UINT32_MAX;

        sprintf(&filename[0], "TEST%d_FILE.txt", (int) i);
        pxSourceFile[i] = ff_fopen(filename, "r");
        assert(NULL != pxSourceFile[i]);
        size_t xCount = 0;

        while (xCount < sizeof(g_file_data))
        {
            xCount = ff_fread(g_read_buffer, 1, sizeof(g_file_data), pxSourceFile[i]);
            timeout--;
            assert(timeout > 0);
        }

        close_err = ff_fclose(pxSourceFile[i]);
        assert(0 == close_err);
    }
}

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_block_media_api_t::mediaInit
• rm_block_media_api_t::infoGet

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