FileX I/O (rm_filex_levelx_nor)

Functions
void	RM_FILEX_LEVELX_NOR_DeviceDriver (FX_MEDIA *p_fx_media)
	Access LevelX NOR device functions open, close, read, write and control. More...

Detailed Description

Middleware for the Azure RTOS FileX File System control using LevelX NOR on RA MCUs.

Overview

This module provides the hardware port layer for FileX file system. After initializing this module, refer to the FileX API reference to use the file system: https://docs.microsoft.com/en-us/azure/rtos/filex/

Features

The FileX LevelX NOR module supports the following features:

• ThreadX is typically required for FileX. To use FileX without ThreadX FX_STANDALONE_ENABLE must be defined.
• Unless FX_SINGLE_THREAD or FX_STANDALONE_ENABLE are defined, all FileX operations are thread safe.

Configuration

Build Time Configurations for rm_filex_levelx_nor

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

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	Selects if code for parameter checking is to be included in the build.

Configurations for Storage > FileX I/O (rm_filex_levelx_nor)

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rm_filex_levelx_nor0	Module name.
Callback	Name must be a valid C symbol	g_rm_filex_levelx_nor_0_callback	A user callback function can be provided. If this callback function is provided, it will be called during operations by the lower level block media as a way for the user to provide their desired waiting functionality.
LevelX NOR Name (String)	Manual Entry	g_rm_filex_levelx_nor_0	String name to be input into LevelX API.

Build Time Configurations for fx

The following build time configurations are defined in fsp_cfg/azure/fx/fx_user.h:

Configuration	Options	Default	Description
Common
Max Long Name Len	Value must be an integer greater than or equal to 13 and less than or equal to 256, or empty		Specifies the maximum file name size for FileX. If left blank the default value is 256. Legal values range between 13 and 256.
Max Last Name Len	Value must be an integer greater than or equal to 13 and less than or equal to 256, or empty		This value defines the maximum file name length, which includes full path name. If left blank the default value is 256. Legal values range between 13 and 256.
Max Sector Cache	Value must be an integer greater than 0 and power of 2 or empty		Specifies the maximum number of logical sectors that can be cached by FileX. The actual number of sectors that can be cached is lesser of this constant and how many sectors can fit in the amount of memory supplied at fx_media_open. The default value if left blank is 256. All values must be a power of 2.
Fat Map Size	Value must be an integer greater than 0 or empty		Specifies the number of sectors that can be represented in the FAT update map. The default value if left blank is 256. Larger values help reduce unneeded updates of secondary FAT sectors.
Max Fat Cache	Value must be an integer greater than 0 and power of 2 or empty		Specifies the number of entries in the internal FAT cache. The default value if left blank is 16. All values must be a power of 2.
Threading
Update Rate (Seconds)	Value must be an integer greater than 0 or empty		Specifies rate at which system time in FileX is adjusted. Default value if left blank is 10, specifying that the FileX system time is updated every 10 seconds.
No Timer	Enabled Disabled (default)	Disabled (default)	Eliminates the ThreadX timer setup to update the FileX system time and date. Doing so causes default time and date to be placed on all file operations.
Single Thread	Enabled Disabled (default)	Disabled (default)	Eliminates ThreadX protection logic from the FileX source. It should be used if FileX is being used only from one thread.
Standalone	Enabled Disabled (default)	Disabled (default)	Enables FileX to be used in standalone mode (without Azure RTOS).
Extra Features
Don't Update Open Files	Enabled Disabled (default)	Disabled (default)	When enabled, FileX does not update already opened files.
Media Search Cache	Enabled (default) Disabled	Enabled (default)	When disabled, the file search cache optimization is disabled.
Direct Data Read Cache Fill	Enabled (default) Disabled	Enabled (default)	When disabled, the direct read sector update of cache is disabled.
Media Statistics	Enabled (default) Disabled	Enabled (default)	When disabled, gathering of media statistics is disabled.
Single Open Legacy	Enabled Disabled (default)	Disabled (default)	When enabled, legacy single open logic for the same file is enabled.
Rename Path Inherit	Enabled Disabled (default)	Disabled (default)	When enabled, renaming inherits path information.
No Local Path	Enabled Disabled (default)	Disabled (default)	When enabled, removes local path logic from FileX, resulting in smaller code size.
64-bit LBA	Enabled Disabled (default)	Disabled (default)	When enabled, 64-bits sector addresses are used in I/O driver.
Cache	Enabled (default) Disabled	Enabled (default)	Enables or disables the cache, default is enabled.
File Close	Enabled (default) Disabled	Enabled (default)	Enables or disables file close, default is enabled.
Fast Close	Enabled (default) Disabled	Enabled (default)	Enables or disables fast open, default is enabled.
Force Memory Operation	Enabled (default) Disabled	Enabled (default)	Enables or disables force memory operation, default is enabled.
Build Options	Enabled (default) Disabled	Enabled (default)	Enables or disables build options, default is enabled.
One Line Function	Enabled (default) Disabled	Enabled (default)	Enables or disables one line function, default is enabled.
FAT Entry Refresh	Enabled (default) Disabled	Enabled (default)	Enables or disables FAT entry refresh, default is enabled.
Consecutive Detect	Enabled (default) Disabled	Enabled (default)	Enables or disables consecutive detect, default is enabled.
Enable exFAT	Enabled Disabled (default)	Disabled (default)	Enables exFAT support in FileX.
Fault Tolerant
Fault Tolerant Service	Enabled Disabled (default)	Disabled (default)	When enabled, enables the FileX Fault Tolerant Module. Enabling Fault Tolerant automatically defines the symbol FX_FAULT_TOLERANT and FX_FAULT_TOLERANT_DATA.
Fault Tolerant Data	Enabled Disabled (default)	Disabled (default)	When enabled, FileX immediately passes all file data write requests to the media's driver. This potentially decreases performance, but helps limit lost file data. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which should be enabled separately.
Fault Tolerant	Enabled Disabled (default)	Disabled (default)	When enabled, FileX immediately passes write requests of all system sectors (boot, FAT, and directory sectors) to the media's driver. This potentially decreases performance, but helps limit corruption to lost clusters. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which should be enabled separately.
Fault Tolerant Boot Index	Value must be an integer greater than or equal to 116 and less than or equal to 119		Defines byte offset in the boot sector where the cluster for the fault tolerant log is. By default if left blank this value is 116. This field takes 4 bytes. Bytes 116 through 119 are chosen because they are marked as reserved by FAT 12/16/32/exFAT specification.
Error Checking	Enabled (default) Disabled	Enabled (default)

Configurations for Storage > Azure RTOS FileX on LevelX NOR

This module can be added to the Stacks tab via New Stack > Storage > Azure RTOS FileX on LevelX NOR.

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_fx_media0	Symbol used for media_ptr parameter in FileX APIs
Volume Name	Name must be a maximum of 11 characters	Volume 1	Volume name string, which is a maximum of 11 characters.
Number of FATs	Number of FATs must be an integer greater than 0	1	Number of FATs in the media. The minimal value is 1 for the primary FAT. Values greater than 1 result in additional FAT copies being maintained at run-time.
Directory Entries	Number of Directory Entries must be an integer greater than 0	256	Number of directory entries in the root directory.
Hidden Sectors	Number of Hidden Sectors must be an integer	0	Number of sectors hidden before this media’s boot sector. If using media formatted with multiple partitions this number should correspond to the starting block number for the desired partition.
Total Sectors	Total Sectors must be an integer greater than 0	57337	Total number of sectors in the media. When using a Renesas provided block media implementation, total sectors can be fetched by the infoGet from the block media API. Any removable media must be inserted and initialized first to retrieve this info.
Sectors per Cluster	Sectors per Cluster must be an integer greater than 0	1	Number of sectors in each cluster. The cluster is the minimum allocation unit in a FAT file system.
Volume Serial Number (exFAT only)	Volume Serial Number must be an integer greater than 0	12345	Serial number to be used for this volume. exFAT only.
Boundary Unit (exFAT only)	Boundary unit must be an integer greater than 0	128	Physical data area alignment size, in number of sectors. exFAT only.
Working media memory size	Memory size must be an integer greater than or equal to the size of one sector	512	Memory allocated for file system. Memory size must be an integer greater than or equal to the size of one sector.

Usage Notes

Pending during Write/Erase

If the underlying LevelX NOR driver performs a blocking operation that requires waiting to complete (such as a long write/erase on NOR SPI), a callback can be provided to provide a way to wait with an OS-specific thread wait. This callback will also pass up block erase events.

Partitioned Media

Partitioned media is not supported directly by the FileX LevelX NOR port.

Examples

Basic Example

This is a basic example of FileX Block Media in an application.

#define RM_FILEX_LEVELX_NOR_EXAMPLE_FILE_NAME                "TEST_FILE.txt"
#define RM_FILEX_LEVELX_NOR_EXAMPLE_BUFFER_SIZE_BYTES        (10240)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_PARTITION_NUMBER         (0)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_BLOCK_SIZE               (512)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_DIRECTORY_ENTRIES    (128)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_FATS                 (1)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_HIDDEN_SECTORS           (0)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_TOTAL_SECTORS            (512)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_SECTOR_SIZE              (512)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_SECTORS_PER_CLUSTER      (1)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_HEADS                (1)
#define RM_FILEX_LEVELX_NOR_EXAMPLE_SECTORS_PER_TRACK        (1)

extern rm_filex_levelx_nor_instance_t      g_filex_levelx_nor0;
extern rm_filex_levelx_nor_instance_ctrl_t g_filex_levelx_nor0_ctrl;
extern rm_filex_levelx_nor_cfg_t           g_filex_levelx_nor0_cfg;

extern FX_MEDIA g_fx_media0;
extern uint8_t  g_fx_media0_memory[RM_FILEX_LEVELX_NOR_EXAMPLE_BLOCK_SIZE];
extern uint8_t  g_file_data[RM_FILEX_LEVELX_NOR_EXAMPLE_BUFFER_SIZE_BYTES];
extern uint8_t  g_read_buffer[RM_FILEX_LEVELX_NOR_EXAMPLE_BUFFER_SIZE_BYTES];

void rm_filex_levelx_nor_example (void)
{
    /* Initialize FileX */
    fx_system_initialize();

    /* Initialize LevelX */
    lx_nor_flash_initialize();

    /* Open the media. This assumes the flash is already formatted. */
    UINT fx_err = fx_media_open(&g_fx_media0,
                                "filex_example_media",
                                RM_FILEX_LEVELX_NOR_DeviceDriver,
                                &g_filex_levelx_nor0,
                                g_fx_media0_memory,
                                sizeof(g_fx_media0_memory));
    handle_fx_error(fx_err);

    /* Create a file */
    fx_err = fx_file_create(&g_fx_media0, RM_FILEX_LEVELX_NOR_EXAMPLE_FILE_NAME);
    handle_fx_error(fx_err);

    /* Open source file for writing. */
    FX_FILE sourceFile;
    fx_err = fx_file_open(&g_fx_media0, &sourceFile, RM_FILEX_LEVELX_NOR_EXAMPLE_FILE_NAME, FX_OPEN_FOR_WRITE);
    handle_fx_error(fx_err);

    /* Write file data. */
    fx_err = fx_file_write(&sourceFile, g_file_data, sizeof(g_file_data));
    handle_fx_error(fx_err);

    /* Close the file. */
    fx_err = fx_file_close(&sourceFile);
    handle_fx_error(fx_err);

    /* Open the source file in read mode. */
    fx_err = fx_file_open(&g_fx_media0, &sourceFile, RM_FILEX_LEVELX_NOR_EXAMPLE_FILE_NAME, FX_OPEN_FOR_READ);
    handle_fx_error(fx_err);

    /* Read file data. */
    ULONG actual_size_read;
    fx_err = fx_file_read(&sourceFile, g_read_buffer, sizeof(g_file_data), &actual_size_read);
    handle_fx_error(fx_err);
    assert(sizeof(g_file_data) == actual_size_read);

    /* Close the file. */
    fx_err = fx_file_close(&sourceFile);
    handle_fx_error(fx_err);

    /* Verify the file data read matches the file written. */
    assert(0U == memcmp(g_file_data, g_read_buffer, sizeof(g_file_data)));

    /* Close the Media */
    fx_err = fx_media_close(&g_fx_media0);
    handle_fx_error(fx_err);
}

Format Example

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

extern rm_levelx_nor_spi_cfg_t g_levelx_nor_spi0_cfg;
#define RM_FILEX_LEVELX_NOR_EXAMPLE_SPI_SECTOR_SIZE    (4096)

void rm_filex_levelx_nor_format_example (void)
{
    spi_flash_instance_t * p_spi_flash_instance = (spi_flash_instance_t *) g_levelx_nor_spi0_cfg.p_lower_lvl;
    spi_flash_status_t     status;

    /* Erase flash prior to usage */
    fsp_err_t err = p_spi_flash_instance->p_api->open(p_spi_flash_instance->p_ctrl, p_spi_flash_instance->p_cfg);
    assert(FSP_SUCCESS == err);

    for (uint32_t i = g_levelx_nor_spi0_cfg.address_offset;
         i < g_levelx_nor_spi0_cfg.size;
         i += RM_FILEX_LEVELX_NOR_EXAMPLE_SPI_SECTOR_SIZE)
    {
        err = p_spi_flash_instance->p_api->erase(p_spi_flash_instance->p_ctrl,
                                                 (uint8_t *) g_levelx_nor_spi0_cfg.base_address + i,
                                                 RM_FILEX_LEVELX_NOR_EXAMPLE_SPI_SECTOR_SIZE);
        assert(FSP_SUCCESS == err);

        status.write_in_progress = true;

        while (status.write_in_progress)
        {
            err = p_spi_flash_instance->p_api->statusGet(p_spi_flash_instance->p_ctrl, &status);
            assert(FSP_SUCCESS == err);
        }
    }

    err = p_spi_flash_instance->p_api->close(p_spi_flash_instance->p_ctrl);
    assert(FSP_SUCCESS == err);

    /* Format the media */
    UINT fx_err = fx_media_format(&g_fx_media0,                                      // Pointer to FileX media control block.
                                  RM_FILEX_LEVELX_NOR_DeviceDriver,                  // Driver entry
                                  &g_filex_levelx_nor0,                              // Pointer to Block Media Driver
                                  g_fx_media0_memory,                                // Media buffer pointer
                                  sizeof(g_fx_media0_memory),                        // Media buffer size
                                  "EXAMPLE_VOLUME",                                  // Volume Name
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_FATS,              // Number of FATs
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_DIRECTORY_ENTRIES, // Directory Entries
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_HIDDEN_SECTORS,        // Hidden sectors
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_TOTAL_SECTORS,         // Total sectors
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_SECTOR_SIZE,           // Sector size
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_SECTORS_PER_CLUSTER,   // Sectors per cluster
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_HEADS,             // Heads
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_SECTORS_PER_TRACK);    // Sectors per track
    handle_fx_error(fx_err);
}

Callback Wait Example

This shows how to use the I/O driver callback with ThreadX in order to wait for operations to complete.

/* Callback called by FileX block media I/O driver needs to wait on operation. */
void rm_filex_levelx_nor_test_callback_wait (rm_filex_levelx_nor_callback_args_t * p_args)
{
    if (p_args->event & RM_FILEX_LEVELX_NOR_EVENT_BUSY)
    {
        /* Put the thread to sleep while waiting for operation to complete. */
        tx_thread_sleep(1);
    }
}

void rm_filex_levelx_nor_callback_wait_example (void)
{
    /* Format the media */
    UINT fx_err = fx_media_format(&g_fx_media0,                                      // Pointer to FileX media control block.
                                  RM_FILEX_LEVELX_NOR_DeviceDriver,                  // Driver entry
                                  &g_filex_levelx_nor0,                              // Pointer to Block Media Driver
                                  g_fx_media0_memory,                                // Media buffer pointer
                                  sizeof(g_fx_media0_memory),                        // Media buffer size
                                  "EXAMPLE_VOLUME",                                  // Volume Name
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_FATS,              // Number of FATs
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_DIRECTORY_ENTRIES, // Directory Entries
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_HIDDEN_SECTORS,        // Hidden sectors
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_TOTAL_SECTORS,         // Total sectors
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_SECTOR_SIZE,           // Sector size
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_SECTORS_PER_CLUSTER,   // Sectors per cluster
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_NUM_HEADS,             // Heads
                                  RM_FILEX_LEVELX_NOR_EXAMPLE_SECTORS_PER_TRACK);    // Sectors per track
    handle_fx_error(fx_err);
}

Data Structures
struct	rm_filex_levelx_nor_callback_args_t
struct	rm_filex_levelx_nor_cfg_t
struct	rm_filex_levelx_nor_instance_ctrl_t
struct	rm_filex_levelx_nor_instance_t

Macros
#define	VOID

Enumerations
enum	rm_filex_levelx_nor_event_t

---

Data Structure Documentation

rm_filex_levelx_nor_callback_args_t

struct rm_filex_levelx_nor_callback_args_t

Callback function parameter data

Data Fields
rm_filex_levelx_nor_event_t	event	The event can be used to identify what caused the callback.
void const *	p_context	Placeholder for user data.

rm_filex_levelx_nor_cfg_t

struct rm_filex_levelx_nor_cfg_t

FileX LevelX configuration

Data Fields
UINT(*	nor_driver_initialize )(LX_NOR_FLASH *)
	Pointer to the initialization function.
LX_NOR_FLASH *	p_nor_flash
	NOR Flash instance.
CHAR *	p_nor_flash_name
	NOR Flash instance name.
fsp_err_t(*	close )()
	Pointer to underlying driver close.
void(*	p_callback )(rm_filex_levelx_nor_callback_args_t *p_args)
	Pointer to callback function.
void const *	p_context
	Placeholder for user data.

rm_filex_levelx_nor_instance_ctrl_t

struct rm_filex_levelx_nor_instance_ctrl_t

FileX block media private control block. DO NOT MODIFY. Initialization occurs when RM_FILEX_LEVELX_NOR_Open is called.

Data Fields
rm_filex_levelx_nor_cfg_t const *	p_cfg	Pointer to instance configuration.

rm_filex_levelx_nor_instance_t

struct rm_filex_levelx_nor_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
rm_filex_levelx_nor_instance_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
rm_filex_levelx_nor_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.

Macro Definition Documentation

VOID

#define VOID

Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file.

Enumeration Type Documentation

rm_filex_levelx_nor_event_t

enum rm_filex_levelx_nor_event_t

Options for the callback events.

Enumerator
RM_FILEX_LEVELX_NOR_EVENT_BUSY	Pending operation, user can define their own wait functionality.

Function Documentation

RM_FILEX_LEVELX_NOR_DeviceDriver()

void RM_FILEX_LEVELX_NOR_DeviceDriver

(

FX_MEDIA *

p_fx_media

)

Access LevelX NOR device functions open, close, read, write and control.

The RM_FILEX_LEVELX_NOR_DeviceDriver function is called from the FileX file system driver and issues requests to a LevelX NOR device through the LevelX API.

Parameters

[in,out]

p_fx_media

FileX media control block. All information about each open media device are maintained in the FX_MEDIA data type. The I/O driver communicates the success or failure of the request through the fx_media_driver_status member of FX_MEDIA (p_fx_media->fx_media_driver_status). Possible values are documented in the FileX User Guide.

Return values

None

Returns

Nothing, but updates FileX media control block.