RA Flexible Software Package Documentation  Release v5.1.0

 
Virtual EEPROM on Flash (rm_vee_flash)

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

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.

rm_vee_single_data_segment.svg
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.

rm_vee_segment_refresh.svg
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.

rm_vee_record_format.svg
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.

rm_vee_reference_data_area.svg
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:

ConfigurationOptionsDefaultDescription
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 SizeValue 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.

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_vee0 Module name.
Record Max IDValue must be an integer.16 Set this value to the highest record ID in use.
Number of SegmentsValue 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 AddressManual EntryBSP_FEATURE_FLASH_DATA_FLASH_START Start address of the flash area used by Virtual EEPROM.
Total SizeManual EntryBSP_DATA_FLASH_SIZE_BYTES The total size (In bytes) of the flash area used by Virtual EEPROM.
Reference Data SizeValue must be an integer.0 The size of the reference area (In bytes) used by Virtual EEPROM.
CallbackName must be a valid C symbolvee_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;
}

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_SUCCESSSuccessful. FSP_SUCCESS_RECOVERY changed to FSP_SUCCESS
FSP_ERR_ASSERTIONAn input parameter is NULL.
FSP_ERR_ALREADY_OPENThis function has already been called.
FSP_ERR_PE_FAILUREThis error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_TIMEOUTInterrupts disabled outside of VEE
FSP_ERR_NOT_INITIALIZEDCorruption found. A refresh is required.
FSP_ERR_INVALID_ARGUMENTThe 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_SUCCESSWrite started successfully.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_ASSERTIONAn input parameter is NULL.
FSP_ERR_INVALID_ARGUMENTAn argument contains an illegal value.
FSP_ERR_INVALID_MODEThe operation cannot be started in the current mode.
FSP_ERR_IN_USELast API call still executing.
FSP_ERR_PE_FAILUREThis error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_TIMEOUTFlash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_NOT_INITIALIZEDCorruption 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_SUCCESSWrite started successfully.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_IN_USELast API call still executing.
FSP_ERR_ASSERTIONAn input parameter is NULL.
FSP_ERR_INVALID_MODEThe operation cannot be started in the current mode.
FSP_ERR_PE_FAILUREThis error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_TIMEOUTFlash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_UNSUPPORTEDReference data is not supported in the current configuration.
FSP_ERR_NOT_INITIALIZEDCorruption 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_SUCCESSSuccessful.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_IN_USELast API call still executing.
FSP_ERR_ASSERTIONp_ref_data is NULL.
FSP_ERR_INVALID_ARGUMENTRecord data not configured.
FSP_ERR_NOT_FOUNDThe 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_SUCCESSSuccessful.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_IN_USELast API call still executing.
FSP_ERR_ASSERTIONAn input parameter is NULL.
FSP_ERR_UNSUPPORTEDReference data is not supported in the current configuration.
FSP_ERR_NOT_FOUNDNo 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_SUCCESSSuccessful.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_ASSERTIONAn input parameter is NULL.
FSP_ERR_IN_USELast API call still executing.
FSP_ERR_PE_FAILUREThis error indicates that a flash programming, erase, or blankcheck operation has failed in hardware.
FSP_ERR_INVALID_MODEThe operation cannot be started in the current mode.
FSP_ERR_TIMEOUTFlash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_NOT_INITIALIZEDCorruption 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_SUCCESSSuccessful.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_IN_USELast API call still executing.
FSP_ERR_PE_FAILUREThis error indicates that a flash programming, erase, or blankcheck operation has failed
FSP_ERR_ASSERTIONAn input parameter is NULL.
FSP_ERR_TIMEOUTFlash write timed out (Should not be possible when flash bgo is used).
FSP_ERR_NOT_INITIALIZEDCorruption 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_SUCCESSCallback updated successfully.
FSP_ERR_ASSERTIONA required pointer is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORYp_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_SUCCESSSuccessful.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_ASSERTIONAn 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_SUCCESSSuccessful.
FSP_ERR_NOT_OPENThe module has not been opened.
FSP_ERR_ASSERTIONAn input parameter is NULL.