Functions
fsp_err_t	RM_VEE_FLASH_Open (rm_vee_ctrl_t const p_api_ctrl, rm_vee_cfg_t const const p_cfg)

fsp_err_t	RM_VEE_FLASH_RecordWrite (rm_vee_ctrl_t const p_api_ctrl, uint32_t const rec_id, uint8_t const const p_rec_data, uint32_t const num_bytes)

fsp_err_t	RM_VEE_FLASH_RefDataWrite (rm_vee_ctrl_t const p_api_ctrl, uint8_t const const p_ref_data)

fsp_err_t	RM_VEE_FLASH_RecordPtrGet (rm_vee_ctrl_t const p_api_ctrl, uint32_t const rec_id, uint8_t const pp_rec_data, uint32_t const p_num_bytes)

fsp_err_t	RM_VEE_FLASH_RefDataPtrGet (rm_vee_ctrl_t const p_api_ctrl, uint8_t *const pp_ref_data)

fsp_err_t	RM_VEE_FLASH_Refresh (rm_vee_ctrl_t *const p_api_ctrl)

fsp_err_t	RM_VEE_FLASH_Format (rm_vee_ctrl_t const p_api_ctrl, uint8_t const const p_ref_data)

fsp_err_t	RM_VEE_FLASH_CallbackSet (rm_vee_ctrl_t const p_api_ctrl, void(p_callback)(rm_vee_callback_args_t ), void const const p_context, rm_vee_callback_args_t *const p_callback_memory)

fsp_err_t	RM_VEE_FLASH_StatusGet (rm_vee_ctrl_t const p_api_ctrl, rm_vee_status_t const p_status)

fsp_err_t	RM_VEE_FLASH_Close (rm_vee_ctrl_t *const p_api_ctrl)

Detailed Description

Virtual EEPROM on RA MCUs. This module implements the Virtual EEPROM Interface.

Overview

This VEE module emulates basic EEPROM capabilities. Support is provided for reading and writing both common records and reference data (originally programmed during product assembly or test). A count of the number of segments erased throughout the lifetime of the application is maintained and can be accessed at any time. Wear leveling is handled automatically by the driver.

Features

Writing and reading user defined records of any length to data flash.
Wear leveling is handled automatically.
Reference data such as calibration data programmed at assembly or test time is preserved.
Reference data can be updated at run time.
Fault resilient design.

Data Flash Segmentation

Wear leveling is handled by changing the location in the data flash where a record is stored every time that it is updated. This change in physical location of the record is transparent to the user. Any time an update for a specific record ID is written, it is written to the next unused location in data flash and its location is stored in RAM for quick look-up later. When required, only the most recent version of these records is automatically copied to the next blank segment in data flash. The data flash area is divided into a number of equal-size segments. There is only one segment active at a time. A segment contains two areas- the record area (which is the vast majority of the segment) and the reference data area which contains optional data typically programmed during assembly or final test. Records and updated reference data are written to this segment until one of the two areas becomes full. The record area must be able to hold at least one of every record ID possible and still have space left over for record updates.

Segment Data Format

When a segment does not have sufficient space for additional records or updated reference data, a Refresh occurs. This process copies the most recent record for each ID as well as the latest version of reference data (if any) to the next segment. The very first time VEE runs on an MCU, it marks the last segment as active whether there is reference data configured or not. The end of VEE data flash area is used to provide an easily identified physical flash address that can be used while programming reference data without requiring Virtual EEPROM middleware.

Refresh Operation

Record Format

Each record begins with a header that contains the record size, followed by the data, and the trailer. The trailer contains a validation code which is used for internal purposes only and is not a 16-bit CRC or ECC value. If that level of error checking is desired, the user should include that in the record data passed to the driver. Padding is added between the end of user data and the trailer to ensure the trailer is aligned properly.

Record Format

Reference Data Area

VEE can be configured for the presence of reference data. The original programmed reference data must be located at the end of the VEE data flash area. An area of equal size is reserved below this in case updated reference data becomes available later. Below that is a header which indicates whether the update area has been written to.

Reference Data Area Format

Just as with records, the validation code is used for internal purposes only and is not a 16-bit CRC or ECC value. If that level of error checking is desired, the user should include that in the updated reference data passed to the driver.

Fault Tolerance

The Virtual EEPROM has a fault tolerant design. If for any reason an operation fails before it is completed the next time the module is opened a refresh will occur. Any corrupted data will be discarded.

Configuration

Build Time Configurations for rm_vee_flash

The following build time configurations are defined in fsp_cfg/rm_vee_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.
Reference Data Support	Enabled Disabled	Disabled	Support writing reference data to the end of the segment.
Refresh Buffer Size	Value must be an integer greater than 0 and a multiple of 4 bytes.	32	The size of the internal buffer used to copying data from one flash segment to another during a refresh operation. This is required because data flash to data flash transfers are not supported by the hardware.

Configurations for Storage > Virtual EEPROM on Flash (rm_vee_flash)

This module can be added to the Stacks tab via New Stack > Storage > Virtual EEPROM on Flash (rm_vee_flash). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_vee0	Module name.
Record Max ID	Value must be an integer.	16	Set this value to the highest record ID in use.
Number of Segments	Value must be an integer.	2	Set value to number of segments desired in data flash (minimum 2). The fewer the segments, the fewer refreshes occur, but the longer refreshes take to complete (erase time).
Start Address	Manual Entry	BSP_FEATURE_FLASH_DATA_FLASH_START	Start address of the flash area used by Virtual EEPROM.
Total Size	Manual Entry	BSP_DATA_FLASH_SIZE_BYTES	The total size (In bytes) of the flash area used by Virtual EEPROM.
Reference Data Size	Value must be an integer.	0	The size of the reference area (In bytes) used by Virtual EEPROM.
Callback	Name must be a valid C symbol	vee_callback	A user callback function can be provided. If this callback function is provided, it will be called from the flash interrupt service routine (ISR).

Clock Configuration

There is no clock configuration for the RM_VEE_FLASH module.

Pin Configuration

This module does not use I/O pins.

Usage Notes

A refresh buffer is required to copy data between segments. Data flash cannot be simultaneously read from and written to. Data will be temporarily copied into RAM during refresh operations.

Examples

Basic Example

This is a basic example of minimal use of the RM_VEE_FLASH module in an application.

volatile bool callback_called = false;
/* Record ID to use for storing pressure data. */
#define ID_PRESSURE    (0U)
/* Example data structure. */
typedef struct st_pressure
{
    uint32_t timestamp;
    uint16_t low;
    uint16_t average;
    uint16_t high;
} pressure_t;
void rm_vee_example ()
{
    /* Open the Virtual EEPROM Module. */
    fsp_err_t err = RM_VEE_FLASH_Open(&g_vee_ctrl, &g_vee_cfg);
    if (FSP_SUCCESS != err)
    {
        error_handler();
    }
    /* Read pressure data from external sensor. */
    pressure_t pressure_data;
    get_pressure_data(&pressure_data);
    /* Write the pressure data to a Virtual EEPROM Record. */
    err = RM_VEE_FLASH_RecordWrite(&g_vee_ctrl, ID_PRESSURE, (uint8_t *) &pressure_data, sizeof(pressure_t));
    if (FSP_SUCCESS != err)
    {
        error_handler();
    }
    /* Wait for the Virtual EEPROM callback to indicate it finished writing data. */
    while (false == callback_called)
    {
        ;
    }
    /* Get a pointer to the record that is stored in data flash. */
    uint32_t     length;
    pressure_t * p_pressure_data;
    err = RM_VEE_FLASH_RecordPtrGet(&g_vee_ctrl, ID_PRESSURE, (uint8_t **) &p_pressure_data, &length);
    if (FSP_SUCCESS != err)
    {
        error_handler();
    }
    /* Close the Virtual EEPROM Module. */
    err = RM_VEE_FLASH_Close(&g_vee_ctrl);
    if (FSP_SUCCESS != err)
    {
        error_handler();
    }
}
void rm_vee_tests_callback (rm_vee_callback_args_t * p_args)
{
    callback_called = true;
    FSP_PARAMETER_NOT_USED(p_args);
}

Data Structures
struct	rm_vee_flash_cfg_t

struct	rm_vee_flash_instance_ctrl_t

Data Structure Documentation

◆ rm_vee_flash_cfg_t

struct rm_vee_flash_cfg_t

User configuration structure, used in open function

Data Fields
flash_instance_t const *	p_flash	Pointer to a flash instance.

◆ rm_vee_flash_instance_ctrl_t

struct rm_vee_flash_instance_ctrl_t

Instance control block. This is private to the FSP and should not be used or modified by the application.

Function Documentation

◆ RM_VEE_FLASH_Open()

fsp_err_t RM_VEE_FLASH_Open	(	rm_vee_ctrl_t *const	p_api_ctrl,
		rm_vee_cfg_t const *const	p_cfg
	)

Open the RM_VEE_FLASH driver module

Implements rm_vee_api_t::open

Initializes the driver's internal structures and opens the Flash driver. The Flash driver must be closed prior to opening VEE. The error code FSP_SUCCESS_RECOVERY indicates that VEE detected corrupted data; most likely due to a power loss during a data flash write or erase. In these cases, an automatic internal Refresh is performed and the partially written data is lost.

Return values

FSP_SUCCESS	Successful. FSP_SUCCESS_RECOVERY changed to FSP_SUCCESS
FSP_ERR_ASSERTION	An input parameter is NULL.
FSP_ERR_ALREADY_OPEN	This function has already been called.
FSP_ERR_PE_FAILURE	This error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_TIMEOUT	Interrupts disabled outside of VEE
FSP_ERR_NOT_INITIALIZED	Corruption found. A refresh is required.
FSP_ERR_INVALID_ARGUMENT	The supplied configuration is invalid.

◆ RM_VEE_FLASH_RecordWrite()

fsp_err_t RM_VEE_FLASH_RecordWrite	(	rm_vee_ctrl_t *const	p_api_ctrl,
		uint32_t const	rec_id,
		uint8_t const *const	p_rec_data,
		uint32_t const	num_bytes
	)

Writes a record to data flash.

Implements rm_vee_api_t::recordWrite

This function writes num_bytes of data pointed to by p_rec_data to data flash. This function returns immediately after starting the flash write. BE SURE NOT TO MODIFY the data buffer contents until after the write completes. This includes exiting the calling function when the data buffer is a local variable (stack may be used by another function and corrupt the data buffer contents).

Return values

FSP_SUCCESS	Write started successfully.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_ASSERTION	An input parameter is NULL.
FSP_ERR_INVALID_ARGUMENT	An argument contains an illegal value.
FSP_ERR_INVALID_MODE	The operation cannot be started in the current mode.
FSP_ERR_IN_USE	Last API call still executing.
FSP_ERR_PE_FAILURE	This error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_TIMEOUT	Flash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_NOT_INITIALIZED	Corruption found. A refresh is required.

◆ RM_VEE_FLASH_RefDataWrite()

fsp_err_t RM_VEE_FLASH_RefDataWrite	(	rm_vee_ctrl_t *const	p_api_ctrl,
		uint8_t const *const	p_ref_data
	)

Writes new Reference data to the reference update area.

Implements rm_vee_api_t::refDataWrite

This function writes VEE_CFG_REF_DATA_SIZE bytes pointed to by p_ref_data to data flash. This function returns immediately after starting the flash write. BE SURE NOT TO MODIFY the data buffer contents until after the write completes.

Return values

FSP_SUCCESS	Write started successfully.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_IN_USE	Last API call still executing.
FSP_ERR_ASSERTION	An input parameter is NULL.
FSP_ERR_INVALID_MODE	The operation cannot be started in the current mode.
FSP_ERR_PE_FAILURE	This error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_TIMEOUT	Flash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_UNSUPPORTED	Reference data is not supported in the current configuration.
FSP_ERR_NOT_INITIALIZED	Corruption found. A refresh is required.

◆ RM_VEE_FLASH_RecordPtrGet()

fsp_err_t RM_VEE_FLASH_RecordPtrGet	(	rm_vee_ctrl_t *const	p_api_ctrl,
		uint32_t const	rec_id,
		uint8_t **const	pp_rec_data,
		uint32_t *const	p_num_bytes
	)

Gets a pointer to the most recent record data.

Implements rm_vee_api_t::recordPtrGet

This function sets the argument pointer to the most recent version of the record data in flash. Flash cannot be accessed for reading and writing at the same time. Therefore, reading the data at p_ref_data must be completed prior to initiating any type of Flash write.

Return values

FSP_SUCCESS	Successful.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_IN_USE	Last API call still executing.
FSP_ERR_ASSERTION	p_ref_data is NULL.
FSP_ERR_INVALID_ARGUMENT	Record data not configured.
FSP_ERR_NOT_FOUND	The record associated with the requested ID could not be found.

◆ RM_VEE_FLASH_RefDataPtrGet()

fsp_err_t RM_VEE_FLASH_RefDataPtrGet	(	rm_vee_ctrl_t *const	p_api_ctrl,
		uint8_t **const	pp_ref_data
	)

Gets a pointer to the most recent reference data.

Implements rm_vee_api_t::recordPtrGet

This function sets the argument pointer to the most recent version of the reference data in flash. Flash cannot be accessed for reading and writing at the same time.

Return values

FSP_SUCCESS	Successful.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_IN_USE	Last API call still executing.
FSP_ERR_ASSERTION	An input parameter is NULL.
FSP_ERR_UNSUPPORTED	Reference data is not supported in the current configuration.
FSP_ERR_NOT_FOUND	No reference data was found.

◆ RM_VEE_FLASH_Refresh()

fsp_err_t RM_VEE_FLASH_Refresh ( rm_vee_ctrl_t *const p_api_ctrl )

Manually start a refresh operation

Implements rm_vee_api_t::refresh

This function is used to start a segment Refresh at any time. The Refresh process by default occurs automatically when no more record or reference data space is available and a Write is requested. However, the app may desire to force a refresh when it knows it is running low on space and large amounts of data are about to be recorded.

Return values

FSP_SUCCESS	Successful.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_ASSERTION	An input parameter is NULL.
FSP_ERR_IN_USE	Last API call still executing.
FSP_ERR_PE_FAILURE	This error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_INVALID_MODE	The operation cannot be started in the current mode.
FSP_ERR_TIMEOUT	Flash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_NOT_INITIALIZED	Corruption found. A refresh is required.

◆ RM_VEE_FLASH_Format()

fsp_err_t RM_VEE_FLASH_Format	(	rm_vee_ctrl_t *const	p_api_ctrl,
		uint8_t const *const	p_ref_data
	)

Start a manual format operation.

Implements rm_vee_api_t::format

Return values

FSP_SUCCESS	Successful.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_IN_USE	Last API call still executing.
FSP_ERR_PE_FAILURE	This error indicates that a flash programming, erase, or blankcheck operation has failed
FSP_ERR_ASSERTION	An input parameter is NULL.
FSP_ERR_TIMEOUT	Flash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_NOT_INITIALIZED	Corruption found. A refresh is required.

◆ RM_VEE_FLASH_CallbackSet()

fsp_err_t RM_VEE_FLASH_CallbackSet	(	rm_vee_ctrl_t *const	p_api_ctrl,
		void()(rm_vee_callback_args_t )	p_callback,
		void const *const	p_context,
		rm_vee_callback_args_t *const	p_callback_memory
	)

Updates the user callback with the option to provide memory for the callback argument structure.

Implements rm_vee_api_t::callbackSet.

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.

◆ RM_VEE_FLASH_StatusGet()

fsp_err_t RM_VEE_FLASH_StatusGet	(	rm_vee_ctrl_t *const	p_api_ctrl,
		rm_vee_status_t *const	p_status
	)

Get the current status of the driver.

Implements rm_vee_api_t::statusGet

This command is typically used to verify that the last Write or Refresh command has completed before attempting to perform another API call.

Return values

FSP_SUCCESS	Successful.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_ASSERTION	An input parameter is NULL.

◆ RM_VEE_FLASH_Close()

fsp_err_t RM_VEE_FLASH_Close ( rm_vee_ctrl_t *const p_api_ctrl )

Closes the Flash driver and VEE driver.

Implements rm_vee_api_t::close

Return values

FSP_SUCCESS	Successful.
FSP_ERR_NOT_OPEN	The module has not been opened.
FSP_ERR_ASSERTION	An input parameter is NULL.

Functions

Detailed Description

Overview

Features

Data Flash Segmentation

Record Format

Reference Data Area

Fault Tolerance

Configuration

Build Time Configurations for rm_vee_flash

Configurations for Storage > Virtual EEPROM on Flash (rm_vee_flash)

Clock Configuration

Pin Configuration

Usage Notes

Examples

Basic Example

Data Structures

Data Structure Documentation

◆ rm_vee_flash_cfg_t

◆ rm_vee_flash_instance_ctrl_t

Function Documentation

◆ RM_VEE_FLASH_Open()

◆ RM_VEE_FLASH_RecordWrite()

◆ RM_VEE_FLASH_RefDataWrite()

◆ RM_VEE_FLASH_RecordPtrGet()

◆ RM_VEE_FLASH_RefDataPtrGet()

◆ RM_VEE_FLASH_Refresh()

◆ RM_VEE_FLASH_Format()

◆ RM_VEE_FLASH_CallbackSet()

◆ RM_VEE_FLASH_StatusGet()

◆ RM_VEE_FLASH_Close()