Functions
fsp_err_t	R_MRAM_Open (flash_ctrl_t const p_api_ctrl, flash_cfg_t const const p_cfg)

fsp_err_t	R_MRAM_Write (flash_ctrl_t *const p_api_ctrl, uint32_t const src_address, uint32_t mram_address, uint32_t const num_bytes)

fsp_err_t	R_MRAM_Erase (flash_ctrl_t *const p_api_ctrl, uint32_t const address, uint32_t const num_blocks)

fsp_err_t	R_MRAM_BlankCheck (flash_ctrl_t const p_api_ctrl, uint32_t const address, uint32_t num_bytes, flash_result_t p_blank_check_result)

fsp_err_t	R_MRAM_StatusGet (flash_ctrl_t const p_api_ctrl, flash_status_t const p_status)

fsp_err_t	R_MRAM_IdCodeSet (flash_ctrl_t const p_api_ctrl, uint8_t const const p_id_code, flash_id_code_mode_t mode)

fsp_err_t	R_MRAM_AccessWindowSet (flash_ctrl_t *const p_api_ctrl, uint32_t const start_addr, uint32_t const end_addr)

fsp_err_t	R_MRAM_AccessWindowClear (flash_ctrl_t *const p_api_ctrl)

fsp_err_t	R_MRAM_Reset (flash_ctrl_t *const p_api_ctrl)

fsp_err_t	R_MRAM_StartUpAreaSelect (flash_ctrl_t *const p_api_ctrl, flash_startup_area_swap_t swap_type, bool is_temporary)

fsp_err_t	R_MRAM_BankSwap (flash_ctrl_t *const p_api_ctrl)

fsp_err_t	R_MRAM_UpdateFlashClockFreq (flash_ctrl_t *const p_api_ctrl)

fsp_err_t	R_MRAM_InfoGet (flash_ctrl_t const p_api_ctrl, flash_info_t const p_info)

fsp_err_t	R_MRAM_Close (flash_ctrl_t *const p_api_ctrl)

fsp_err_t	R_MRAM_CallbackSet (flash_ctrl_t const p_api_ctrl, void(p_callback)(flash_callback_args_t ), void const p_context, flash_callback_args_t *const p_callback_memory)

fsp_err_t	R_MRAM_AntiRollbackCounterIncrement (flash_ctrl_t *const p_api_ctrl, flash_arc_t counter)

fsp_err_t	R_MRAM_AntiRollbackCounterRefresh (flash_ctrl_t *const p_api_ctrl, flash_arc_t counter)

fsp_err_t	R_MRAM_AntiRollbackCounterRead (flash_ctrl_t const p_api_ctrl, flash_arc_t counter, uint32_t const p_count)

fsp_err_t	R_MRAM_UserLockableAreaWrite (flash_ctrl_t *const p_api_ctrl, uint32_t const src_address, uint32_t mram_address, uint32_t const num_bytes)

Detailed Description

Driver for the MRAM memory on RA MCUs. This module implements the Flash Interface.

Overview

The MRAM HAL module APIs allow an application to write and erase MRAM areas that reside within the MCU. The amount of MRAM memory available varies across MCU parts.

Features

The R_MRAM module has the following key features:

Blocking writing and erasing of MRAM.
Boot block-swapping.
Anti-rollback counter support (select MCUs).

Configuration

Build Time Configurations for r_mram

The following build time configurations are defined in fsp_cfg/r_mram_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 > MRAM (r_mram)

This module can be added to the Stacks tab via New Stack > Storage > MRAM (r_mram). 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_mram0	Module name.

Clock Configuration

MRAM uses MRAM bus clock for Code MRAM and MRAM clock for Extra MRAM.

Pin Configuration

This module does not use I/O pins.

Usage Notes

Code MRAM Precautions

Code MRAM cannot be accessed while writing or erasing code MRAM. In order to support modifying code MRAM all supporting code must reside in RAM. Code MRAM operation will not return before the operation has completed. By default, the vector table resides in the code MRAM. If an interrupt occurs during the code MRAM operation, then code MRAM will be accessed to fetch the interrupt's starting address and an error will occur. The simplest work-around is to disable interrupts during code MRAM operations. Another option is to copy the vector table to RAM, update the VTOR (Vector Table Offset Register) accordingly and ensure that any interrupt service routines execute out of RAM. Similarly, you must ensure that if in a multi-threaded environment, threads running from code MRAM cannot become active while a code MRAM operation is in progress.

Erase condsiderations

The erase API was designed with flash blocks in mind. The Erase API provides a mechanism for quickly overwriting blocks of data at a single time. The block size is determined by the MRAM Unit of Programming size.

Anti Rollback Counter

Anti-rollback counters are available on select MCUs and can be used to prevent or limit firmware downgrade. The counters can only be incremented and never decremented or reset, even with an external programming tool.

Note: The OEM bootloader anti-rollback counter is protected by the security engine and cannot be incremented past the version number specified in the code certificate. This counter works with the First Stage Bootloader (FSBL) set to enabled. For more information, read the 'Secure Boot' section in the 'Security Features' chapter of the user manual of the target MCU and refer to Application Note R11AN0774.

Anti-Rollback Counter Configuration Setting

When anti-rollback counters are used for one or more non-secure applications, the Anti-Rollback Counter Configuration Setting for ARC_NSEC (ARCCS) must be configured as either a single line (1xn bits) or multi-line counter (mxn bits). Single line is suitable when there is only one non-secure application using the anti-rollback counter. Multi-line is suitable when there are multiple non-secure applications. Before the counter is configured, it can't be used.

This configuration setting is permanent and must be performed with an external programming tool such as Renesas Flash Programmer (RFP). It cannot be configured in e2 studio.

The secure application and OEM bootloader anti-rollback counters do not require any initial configuration.

Anti-Rollback Counter Lock Setting

Select MCUs have the ability to permanently lock the anti-rollback counters using the Anti-Rollback Counter Lock Setting (ARCLS). It cannot be set with e2 studio, but if needed, it can be configured with an external programming tool such as Renesas Flash Programmer (RFP). Once the lock protection is applied to a counter, the counter value can never be incremented again. It is still possible to read the value of a locked counter.

Viewing MRAM contents in e2 studio

By default, the contents of code MRAM are cached by e² studio. This means that during a debug session, modifications to these memory regions will not be observed by e² studio. When debugging applications using e² studio, disable the "Allow caching of flash contents" option in the debug configuration in order to view modified MRAM contents (Debug Configuration > Debugger > Debug Tool Settings > Allow caching of flash contents).

Examples

MRAM Basic Example

This is a basic example of writing to MRAM.

uint8_t g_dest[TRANSFER_LENGTH];
uint8_t g_src[TRANSFER_LENGTH];
void r_mram_basic_example (void)
{
    /* Initialize p_src to known data */
    for (uint32_t i = 0; i < TRANSFER_LENGTH; i++)
    {
        g_src[i] = (uint8_t) ('A' + (i % 26));
    }
    /* Open the MRAM instance. */
    fsp_err_t err = R_MRAM_Open(&g_mram_ctrl, &g_mram_cfg);
    assert(FSP_SUCCESS == err);
    /* Disable interrupts to prevent vector table access while MRAM is programming. */
    __disable_irq();
    /* Write 32 bytes to an area of MRAM. */
    err = R_MRAM_Write(&g_mram_ctrl, (uint32_t) g_src, MRAM_WRITE_ADDRESS, MRAM_EXAMPLE_WRITE_SIZE);
    /* Enable interrupts after MRAM operations are complete. */
    __enable_irq();
    assert(FSP_SUCCESS == err);
    assert(0 == memcmp(g_src, (uint8_t *) MRAM_WRITE_ADDRESS, MRAM_EXAMPLE_WRITE_SIZE));
}

Anti-Rollback Counter Basic Example

This example demonstrates basic usage of the anti-rollback counter functions.

void r_mram_anti_rollback_counter_example (void)
{
    /* Open the MRAM instance. */
    fsp_err_t err = R_MRAM_Open(&g_mram_ctrl, &g_mram_cfg);
    /* Handle any errors. */
    assert(FSP_SUCCESS == err);
    uint32_t current_count;
    /* Read the current counter value for the secure application */
    err = R_MRAM_AntiRollbackCounterRead(&g_mram_ctrl, FLASH_ARC_SEC, &current_count);
    assert(FSP_SUCCESS == err);
    /* Read the current counter value for the OEM bootloader */
    err = R_MRAM_AntiRollbackCounterRead(&g_mram_ctrl, FLASH_ARC_OEMBL, &current_count);
    assert(FSP_SUCCESS == err);
    /* Read the current counter value for the non-secure application if counter is configured as 1xn bits */
    err = R_MRAM_AntiRollbackCounterRead(&g_mram_ctrl, FLASH_ARC_NSEC_0, &current_count);  // NSEC App
    assert(FSP_SUCCESS == err);
    /* Read the current counter value for 4 non-secure applications if counter is configured as mxn bits */
    err  = R_MRAM_AntiRollbackCounterRead(&g_mram_ctrl, FLASH_ARC_NSEC_0, &current_count); // NSEC App 0
    err |= R_MRAM_AntiRollbackCounterRead(&g_mram_ctrl, FLASH_ARC_NSEC_1, &current_count); // NSEC App 1
    err |= R_MRAM_AntiRollbackCounterRead(&g_mram_ctrl, FLASH_ARC_NSEC_2, &current_count); // NSEC App 2
    err |= R_MRAM_AntiRollbackCounterRead(&g_mram_ctrl, FLASH_ARC_NSEC_3, &current_count); // NSEC App 3
    assert(FSP_SUCCESS == err);
    /* Increment the counter value for the secure application. Caution: The increment cannot be reversed. */
    err = R_MRAM_AntiRollbackCounterIncrement(&g_mram_ctrl, FLASH_ARC_SEC);
    assert(FSP_SUCCESS == err);
}

Data Structures
struct	mram_instance_ctrl_t

Data Structure Documentation

◆ mram_instance_ctrl_t

struct mram_instance_ctrl_t

MRAM instance control block. DO NOT INITIALIZE.

Function Documentation

◆ R_MRAM_Open()

fsp_err_t R_MRAM_Open	(	flash_ctrl_t *const	p_api_ctrl,
		flash_cfg_t const *const	p_cfg
	)

Initializes the MRAM peripheral. Implements flash_api_t::open.

The Open function initializes the MRAM.

Example:

    /* Open the MRAM instance. */
    fsp_err_t err = R_MRAM_Open(&g_mram_ctrl, &g_mram_cfg);

Return values

FSP_SUCCESS	Initialization was successful.
FSP_ERR_ALREADY_OPEN	The MRAM control block is already open.
FSP_ERR_ASSERTION	NULL provided for p_ctrl or p_cfg.
FSP_ERR_IRQ_BSP_DISABLED	Caller is requesting BGO but the MRAM interrupts are not supported.

◆ R_MRAM_Write()

fsp_err_t R_MRAM_Write	(	flash_ctrl_t *const	p_api_ctrl,
		uint32_t const	src_address,
		uint32_t	mram_address,
		uint32_t const	num_bytes
	)

Writes to the specified MRAM memory area. Implements flash_api_t::write.

Example:

    /* Disable interrupts to prevent vector table access while MRAM is programming. */
    __disable_irq();
    /* Write 32 bytes to an area of MRAM. */
    err = R_MRAM_Write(&g_mram_ctrl, (uint32_t) g_src, MRAM_WRITE_ADDRESS, MRAM_EXAMPLE_WRITE_SIZE);
    /* Enable interrupts after MRAM operations are complete. */
    __enable_irq();

Return values

FSP_SUCCESS	Operation successful.
FSP_ERR_IN_USE	The MRAM peripheral is busy with a prior on-going transaction.
FSP_ERR_NOT_OPEN	The MRAM API is not Open.
FSP_ERR_CMD_LOCKED	MRAM Application Command Interface is in locked state
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation. This may be returned if the requested MRAM area is not blank.
FSP_ERR_TIMEOUT	Timed out waiting for write operation to complete.
FSP_ERR_INVALID_SIZE	Number of bytes provided was invalid
FSP_ERR_INVALID_ADDRESS	Invalid address was input or address not on programming boundary.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_PE_FAILURE	Failed to enter or exit P/E mode.

◆ R_MRAM_Erase()

fsp_err_t R_MRAM_Erase	(	flash_ctrl_t *const	p_api_ctrl,
		uint32_t const	address,
		uint32_t const	num_blocks
	)

Erases the specified MRAM blocks. Implements flash_api_t::erase by the block_erase_address.

Example:

    /* Disable interrupts to prevent vector table access while MRAM is programming. */
    __disable_irq();
    /* Erase 10 programmable units of MRAM */
    fsp_err_t err = R_MRAM_Erase(&g_mram_ctrl, MRAM_ERASE_ADDRESS, 10);
    /* Enable interrupts after MRAM operations are complete. */
    __enable_irq();

Return values

FSP_SUCCESS	Successful open.
FSP_ERR_INVALID_BLOCKS	Invalid number of blocks specified
FSP_ERR_INVALID_ADDRESS	Invalid address specified.
FSP_ERR_IN_USE	Other MRAM operation in progress, or API not initialized
FSP_ERR_CMD_LOCKED	MRAM Application Command Interface is in locked state
FSP_ERR_ASSERTION	NULL provided for p_ctrl
FSP_ERR_NOT_OPEN	The MRAM API is not Open.
FSP_ERR_ERASE_FAILED	Status is indicating a Erase error.
FSP_ERR_TIMEOUT	Timed out waiting for the MACI to become ready.
FSP_ERR_PE_FAILURE	Failed to enter or exit P/E mode.

◆ R_MRAM_BlankCheck()

fsp_err_t R_MRAM_BlankCheck	(	flash_ctrl_t *const	p_api_ctrl,
		uint32_t const	address,
		uint32_t	num_bytes,
		flash_result_t *	p_blank_check_result
	)

Stub function Implements flash_api_t::blankCheck.

Return values

FSP_ERR_UNSUPPORTED Blank Check is not supported on this MCU.

◆ R_MRAM_StatusGet()

fsp_err_t R_MRAM_StatusGet	(	flash_ctrl_t *const	p_api_ctrl,
		flash_status_t *const	p_status
	)

Query the MRAM peripheral for its status. Implements flash_api_t::statusGet.

Return values

FSP_SUCCESS	MRAM peripheral is ready to use.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_NOT_OPEN	The MRAM API is not Open.

◆ R_MRAM_IdCodeSet()

fsp_err_t R_MRAM_IdCodeSet	(	flash_ctrl_t *const	p_api_ctrl,
		uint8_t const *const	p_id_code,
		flash_id_code_mode_t	mode
	)

Stub function Implements flash_api_t::idCodeSet.

Return values

FSP_ERR_UNSUPPORTED ID Code is not supported on this MCU.

◆ R_MRAM_AccessWindowSet()

fsp_err_t R_MRAM_AccessWindowSet	(	flash_ctrl_t *const	p_api_ctrl,
		uint32_t const	start_addr,
		uint32_t const	end_addr
	)

Stub function Implements flash_api_t::accessWindowSet.

Return values

FSP_ERR_UNSUPPORTED Access window is not supported on this MCU.

◆ R_MRAM_AccessWindowClear()

fsp_err_t R_MRAM_AccessWindowClear ( flash_ctrl_t *const p_api_ctrl )

Stub function Implements flash_api_t::accessWindowClear.

Return values

FSP_ERR_UNSUPPORTED Access window is not supported on this MCU.

◆ R_MRAM_Reset()

fsp_err_t R_MRAM_Reset ( flash_ctrl_t *const p_api_ctrl )

Reset the MRAM peripheral. Implements flash_api_t::reset.

No attempt is made to check if the MRAM is busy before executing the reset since the assumption is that a reset will terminate any existing operation.

Return values

FSP_SUCCESS	MRAM circuit successfully reset.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_PE_FAILURE	Failed to enter or exit P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the MACI to become ready.
FSP_ERR_CMD_LOCKED	MRAM Application Command Interface is in locked state

◆ R_MRAM_StartUpAreaSelect()

fsp_err_t R_MRAM_StartUpAreaSelect	(	flash_ctrl_t *const	p_api_ctrl,
		flash_startup_area_swap_t	swap_type,
		bool	is_temporary
	)

Selects which block, Default (Block 0) or Alternate (Block 1), is used as the startup area block. The provided parameters determine which block will become the active startup block and whether that action will be immediate (but temporary), or permanent subsequent to the next reset. Implements flash_api_t::startupAreaSelect.

Return values

FSP_SUCCESS	Start-up area successfully toggled.
FSP_ERR_IN_USE	MRAM peripheral is busy with a prior operation.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_PE_FAILURE	Failed to enter or exit MRAM P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the MACI to become ready.
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation.
FSP_ERR_CMD_LOCKED	MRAM Application Command Interface is in locked state

◆ R_MRAM_BankSwap()

fsp_err_t R_MRAM_BankSwap ( flash_ctrl_t *const p_api_ctrl )

Stub function flash_api_t::bankSwap.

Return values

FSP_ERR_UNSUPPORTED Bank Swap is not supported on this MCU.

◆ R_MRAM_UpdateFlashClockFreq()

fsp_err_t R_MRAM_UpdateFlashClockFreq ( flash_ctrl_t *const p_api_ctrl )

Indicate to the MRAM module that the system clock has changed. Implements flash_api_t::updateFlashClockFreq.

This should be the case if the application has changed the system clock.

Return values

FSP_SUCCESS	Start-up area successfully toggled.
FSP_ERR_IN_USE	MRAM is busy with an on-going operation.
FSP_ERR_ASSERTION	NULL provided for p_ctrl
FSP_ERR_NOT_OPEN	MRAM API has not yet been opened.

◆ R_MRAM_InfoGet()

fsp_err_t R_MRAM_InfoGet	(	flash_ctrl_t *const	p_api_ctrl,
		flash_info_t *const	p_info
	)

Returns the information about the MRAM regions. Implements flash_api_t::infoGet.

Return values

FSP_SUCCESS	Successful retrieved the request information.
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_ASSERTION	NULL provided for p_ctrl or p_info.

◆ R_MRAM_Close()

fsp_err_t R_MRAM_Close ( flash_ctrl_t *const p_api_ctrl )

Releases any resources that were allocated by the Open() or any subsequent MRAM operations. Implements flash_api_t::close.

Return values

FSP_SUCCESS	Successful close.
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_ASSERTION	NULL provided for p_ctrl or p_cfg.

◆ R_MRAM_CallbackSet()

fsp_err_t R_MRAM_CallbackSet	(	flash_ctrl_t *const	p_api_ctrl,
		void()(flash_callback_args_t )	p_callback,
		void *const	p_context,
		flash_callback_args_t *const	p_callback_memory
	)

Stub function Implements flash_api_t::callbackSet.

Return values

FSP_ERR_UNSUPPORTED Interrupt driven operation is not supported on this MCU.

◆ R_MRAM_AntiRollbackCounterIncrement()

fsp_err_t R_MRAM_AntiRollbackCounterIncrement	(	flash_ctrl_t *const	p_api_ctrl,
		flash_arc_t	counter
	)

Increments the selected anti-rollback counter.

Note: The counter is read internally before increment.

Implements flash_api_t::antiRollbackCounterIncrement

Return values

FSP_SUCCESS	Counter incremented successfully
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_ASSERTION	NULL provided for p_api_ctrl
FSP_ERR_NOT_ENABLED	The specified counter has not been configured (configuration is only required for ARC_NSEC)
FSP_ERR_OVERFLOW	The counter cannot be incremented because it is already at its max value
FSP_ERR_PE_FAILURE	Failed to enter or exit MRAM P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the MACI to become ready.
FSP_ERR_CMD_LOCKED	MRAM Application Command Interface is in locked state
FSP_ERR_UNSUPPORTED	Selected anti-rollback counter is not supported on this MCU

◆ R_MRAM_AntiRollbackCounterRefresh()

fsp_err_t R_MRAM_AntiRollbackCounterRefresh	(	flash_ctrl_t *const	p_api_ctrl,
		flash_arc_t	counter
	)

Stub function Implements flash_api_t::antiRollbackCounterRefresh

Return values

FSP_ERR_UNSUPPORTED Anti-Rollback counter refresh is not supported on this MCU

◆ R_MRAM_AntiRollbackCounterRead()

fsp_err_t R_MRAM_AntiRollbackCounterRead	(	flash_ctrl_t *const	p_api_ctrl,
		flash_arc_t	counter,
		uint32_t *const	p_count
	)

Reads the selected anti-rollback counter and returns the number of counter bits set.

Implements flash_api_t::antiRollbackCounterRead

Return values

FSP_SUCCESS	Counter read successfully into p_count
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_ASSERTION	NULL provided for p_api_ctrl or p_count
FSP_ERR_NOT_ENABLED	The specified counter has not been configured (configuration is only required for ARC_NSEC)
FSP_ERR_PE_FAILURE	Failed to enter or exit MRAM P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the MACI to become ready.
FSP_ERR_CMD_LOCKED	MRAM Application Command Interface is in locked state

◆ R_MRAM_UserLockableAreaWrite()

fsp_err_t R_MRAM_UserLockableAreaWrite	(	flash_ctrl_t *const	p_api_ctrl,
		uint32_t const	src_address,
		uint32_t	mram_address,
		uint32_t const	num_bytes
	)

Stub function Implements flash_api_t::userLockableAreaWrite

Return values

FSP_ERR_UNSUPPORTED User Lockable Area is not supported on this MCU

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for r_mram

Configurations for Storage > MRAM (r_mram)

Clock Configuration

Pin Configuration

Usage Notes

Code MRAM Precautions

Erase condsiderations

Anti Rollback Counter

Anti-Rollback Counter Configuration Setting

Anti-Rollback Counter Lock Setting

Viewing MRAM contents in e2 studio

Examples

MRAM Basic Example

Anti-Rollback Counter Basic Example

Data Structures

Data Structure Documentation

◆ mram_instance_ctrl_t

Function Documentation

◆ R_MRAM_Open()

◆ R_MRAM_Write()

◆ R_MRAM_Erase()

◆ R_MRAM_BlankCheck()

◆ R_MRAM_StatusGet()

◆ R_MRAM_IdCodeSet()

◆ R_MRAM_AccessWindowSet()

◆ R_MRAM_AccessWindowClear()

◆ R_MRAM_Reset()

◆ R_MRAM_StartUpAreaSelect()

◆ R_MRAM_BankSwap()

◆ R_MRAM_UpdateFlashClockFreq()

◆ R_MRAM_InfoGet()

◆ R_MRAM_Close()

◆ R_MRAM_CallbackSet()

◆ R_MRAM_AntiRollbackCounterIncrement()

◆ R_MRAM_AntiRollbackCounterRefresh()

◆ R_MRAM_AntiRollbackCounterRead()

◆ R_MRAM_UserLockableAreaWrite()