Flash (r_flash_hp)

Functions
fsp_err_t	R_FLASH_HP_Open (flash_ctrl_t *const p_api_ctrl, flash_cfg_t const *const p_cfg)
fsp_err_t	R_FLASH_HP_Write (flash_ctrl_t *const p_api_ctrl, uint32_t const src_address, uint32_t flash_address, uint32_t const num_bytes)
fsp_err_t	R_FLASH_HP_Erase (flash_ctrl_t *const p_api_ctrl, uint32_t const address, uint32_t const num_blocks)
fsp_err_t	R_FLASH_HP_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_FLASH_HP_StatusGet (flash_ctrl_t *const p_api_ctrl, flash_status_t *const p_status)
fsp_err_t	R_FLASH_HP_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_FLASH_HP_AccessWindowSet (flash_ctrl_t *const p_api_ctrl, uint32_t const start_addr, uint32_t const end_addr)
fsp_err_t	R_FLASH_HP_AccessWindowClear (flash_ctrl_t *const p_api_ctrl)
fsp_err_t	R_FLASH_HP_Reset (flash_ctrl_t *const p_api_ctrl)
fsp_err_t	R_FLASH_HP_StartUpAreaSelect (flash_ctrl_t *const p_api_ctrl, flash_startup_area_swap_t swap_type, bool is_temporary)
fsp_err_t	R_FLASH_HP_BankSwap (flash_ctrl_t *const p_api_ctrl)
fsp_err_t	R_FLASH_HP_UpdateFlashClockFreq (flash_ctrl_t *const p_api_ctrl)
fsp_err_t	R_FLASH_HP_InfoGet (flash_ctrl_t *const p_api_ctrl, flash_info_t *const p_info)
fsp_err_t	R_FLASH_HP_Close (flash_ctrl_t *const p_api_ctrl)
fsp_err_t	R_FLASH_HP_CallbackSet (flash_ctrl_t *const p_api_ctrl, void(*p_callback)(flash_callback_args_t *), void const *const p_context, flash_callback_args_t *const p_callback_memory)
fsp_err_t	R_FLASH_HP_AntiRollbackCounterIncrement (flash_ctrl_t *const p_api_ctrl, flash_arc_t counter)
fsp_err_t	R_FLASH_HP_AntiRollbackCounterRefresh (flash_ctrl_t *const p_api_ctrl, flash_arc_t counter)
fsp_err_t	R_FLASH_HP_AntiRollbackCounterRead (flash_ctrl_t *const p_api_ctrl, flash_arc_t counter, uint32_t *const p_count)
fsp_err_t	R_FLASH_HP_UserLockableAreaWrite (flash_ctrl_t *const p_api_ctrl, uint32_t const src_address, uint32_t flash_address, uint32_t const num_bytes)

Detailed Description

Driver for the flash memory on RA high-performance MCUs. This module implements the Flash Interface.

Overview

The Flash HAL module APIs allow an application to write, erase and blank check both the data and ROM flash areas that reside within the MCU. The amount of flash memory available varies across MCU parts.

Features

The R_FLASH_HP module has the following key features:

• Blocking and non-blocking erasing, writing and blank-checking of data flash.
• Blocking erasing, writing and blank-checking of code flash.
• Callback functions for completion of non-blocking data flash operations.
• Access window (write protection) for ROM Flash, allowing only specified areas of code flash to be erased or written.
• Boot block-swapping.
• ID code programming support.
• Anti-rollback counter support (select MCUs).
• Blocking writing of user lockable data flash option setting memory area (select MCUs).

Configuration

Build Time Configurations for r_flash_hp

The following build time configurations are defined in fsp_cfg/r_flash_hp_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.
Code Flash Programming Enable	Enabled Disabled	Disabled	Controls whether or not code-flash programming is enabled. Disabling reduces the amount of ROM and RAM used by the API.
Data Flash Programming Enable	Enabled Disabled	Enabled	Controls whether or not data-flash programming is enabled. Disabling reduces the amount of ROM used by the API.

Configurations for Storage > Flash (r_flash_hp)

This module can be added to the Stacks tab via New Stack > Storage > Flash (r_flash_hp). 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_flash0	Module name.
Data Flash Background Operation	Enabled Disabled	Enabled	Enabling allows Flash API calls that reference data-flash to return immediately, with the operation continuing in the background.
Callback	Name must be a valid C symbol	NULL	A user callback function can be specified. Callback function called when a Data Flash Background Operation completes or errors.
Flash Ready Interrupt Priority	MCU Specific Options		Select the flash ready interrupt priority.
Flash Error Interrupt Priority	MCU Specific Options		Select the flash error interrupt priority.

Clock Configuration

Flash uses FCLK as the clock source depending on the MCU. When writing and erasing the clock source must be at least 4 MHz.

Pin Configuration

This module does not use I/O pins.

Usage Notes

Warning

It is highly recommended that the developer reviews sections 5 and 6 of the Flash Memory section of the target MCUs Hardware User’s Manual prior to using the r_flash_hp module. In particular, understanding ID Code and Access Window functionality can help avoid unrecoverable flash scenarios.

Data Flash Background Operation (BGO) Precautions

When using the data flash BGO (Background Operation) mode, you can still access the user ROM, RAM and external memory. You must ensure that the data flash is not accessed during a data flash operation. This includes interrupts that may access the data flash.

Data flash BGO is not supported during anti-rollback counter operations or writes to the user lockable area.

Code Flash Precautions

Code flash cannot be accessed while writing, erasing or blank checking code flash. Code flash cannot be accessed while modifying the access window, selecting the startup area or setting the ID code. In order to support modifying code flash all supporting code must reside in RAM. This is only done when code flash programming is enabled. BGO mode is not supported for code flash, so a code flash operation will not return before the operation has completed. By default, the vector table resides in the code flash. If an interrupt occurs during the code flash operation, then code flash 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 flash 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 insure that if in a multi-threaded environment, threads running from code flash cannot become active while a code flash operation is in progress.

Flash Clock (FCLK)

The flash clock source is the clock used by the Flash peripheral in performing all Flash operations. As part of the flash_api_t::open function the Flash clock source is checked will return FSP_ERR_FCLK if it is invalid. Once the Flash API has been opened, if the flash clock source frequency is changed, the flash_api_t::updateFlashClockFreq API function must be called to inform the API of the change. Failure to do so could result in flash operation failures and possibly damage the part.

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.

Anti-Rollback Counter Recovery from Power Loss or other Counter Increment Error

If an error is returned by R_FLASH_HP_AntiRollbackCounterIncrement or power loss occurs during increment command processing, a successful call to R_FLASH_HP_AntiRollbackCounterRefresh is required before reading or incrementing the counter again. Otherwise, the counter flash may be in an invalid state.

User Lockable Area

The user lockable area of the data flash configuration area neither requires nor supports erase before rewriting.

Locked sections of the user lockable area cannot be rewritten.

If lockable area is available on the MCU, start address, end address, and write size can be read at runtime in the second element of the data flash block information array (p_info->data_flash.p_block_array[1]) returned by R_FLASH_HP_InfoGet.

Interrupts

Enable the flash ready interrupt only if you plan to use the data flash BGO. In this mode, the application can initiate a data flash operation and then be asynchronously notified of its completion, or an error, using a user supplied-callback function. The callback function is passed a structure containing event information that indicates the source of the callback event (for example, flash_api_t::FLASH_EVENT_ERASE_COMPLETE) When the FLASH FRDYI interrupt is enabled, the corresponding ISR will be defined in the flash driver. The ISR will call a user-callback function if one was registered with the flash_api_t::open API.

Note

The Flash HP supports an additional flash-error interrupt and if the BGO mode is enabled for the FLASH HP then both the Flash Ready Interrupt and Flash Error Interrupts must be enabled (assigned a priority).

Viewing flash contents in e2 studio

By default, the contents of data flash and code flash 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 flash contents (Debug Configuration > Debugger > Debug Tool Settings > Allow caching of flash contents).

Debug Configuration

Limitations

• Write operations must be aligned on page boundaries and must be a multiple of the page boundary size.
• Erase operations will erase the entire block the provided address resides in.
• Data flash is better suited for storing data as it can be erased and written to while code is still executing from code flash. Data flash is also guaranteed for a larger number of reprogramming/erasure cycles than code flash.
• Read values of erased data flash blocks are not guaranteed to be 0xFF. Blank check should be used to determine if memory has been erased but not yet programmed.
• Runtime locking of the user lockable area is not currently supported. The area can be locked by an external programming tool. Do not write to locked areas of user lockable area.

Examples

High-Performance Flash Basic Example

This is a basic example of erasing and writing to data flash and code flash.

#define FLASH_DF_BLOCK_0               0x40100000U /*   64 B:  0x40100000 - 0x4010003F */
#define FLASH_CF_BLOCK_8               0x00010000  /*   32 KB: 0x00010000 - 0x00017FFF */
#define FLASH_DATA_BLOCK_SIZE          (1024)
#define FLASH_HP_EXAMPLE_WRITE_SIZE    32

uint8_t        g_dest[TRANSFER_LENGTH];
uint8_t        g_src[TRANSFER_LENGTH];
flash_result_t blank_check_result;
void r_flash_hp_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 flash hp instance. */
    fsp_err_t err = R_FLASH_HP_Open(&g_flash_ctrl, &g_flash_cfg);

    assert(FSP_SUCCESS == err);


    /* Erase 1 block of data flash starting at block 0. */
    err = R_FLASH_HP_Erase(&g_flash_ctrl, FLASH_DF_BLOCK_0, 1);

    assert(FSP_SUCCESS == err);


    /* Check if block 0 is erased. */
    err = R_FLASH_HP_BlankCheck(&g_flash_ctrl, FLASH_DF_BLOCK_0, FLASH_DATA_BLOCK_SIZE, &blank_check_result);
    assert(FSP_SUCCESS == err);


    /* Verify the previously erased area is blank */
    assert(FLASH_RESULT_BLANK == blank_check_result);


    /* Write 32 bytes to the first block of data flash. */
    err = R_FLASH_HP_Write(&g_flash_ctrl, (uint32_t) g_src, FLASH_DF_BLOCK_0, FLASH_HP_EXAMPLE_WRITE_SIZE);


    assert(FSP_SUCCESS == err);

    assert(0 == memcmp(g_src, (uint8_t *) FLASH_DF_BLOCK_0, FLASH_HP_EXAMPLE_WRITE_SIZE));

    /* Disable interrupts to prevent vector table access while code flash is in P/E mode. */
    __disable_irq();

    /* Erase 1 block of code flash starting at block 10. */
    err = R_FLASH_HP_Erase(&g_flash_ctrl, FLASH_CF_BLOCK_8, 1);
    assert(FSP_SUCCESS == err);

    /* Write 32 bytes to the first block of data flash. */
    err = R_FLASH_HP_Write(&g_flash_ctrl, (uint32_t) g_src, FLASH_CF_BLOCK_8, FLASH_HP_EXAMPLE_WRITE_SIZE);
    assert(FSP_SUCCESS == err);

    /* Enable interrupts after code flash operations are complete. */
    __enable_irq();

    assert(0 == memcmp(g_src, (uint8_t *) FLASH_CF_BLOCK_8, FLASH_HP_EXAMPLE_WRITE_SIZE));
}

High-Performance Flash Advanced Example

This example demonstrates using BGO to do non-blocking operations on the data flash.

bool               interrupt_called;
flash_event_t      flash_event;
static flash_cfg_t g_flash_bgo_example_cfg =
{
    .p_callback     = flash_callback,
    .p_context      = 0,
    .p_extend       = NULL,
    .data_flash_bgo = true,            
    .ipl            = 5,
    .irq            = BSP_VECTOR_FLASH_HP_FRDYI_ISR,
};

void r_flash_hp_bgo_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 flash hp instance. */
    fsp_err_t err = R_FLASH_HP_Open(&g_flash_ctrl, &g_flash_bgo_example_cfg);

    /* Handle any errors. */
    assert(FSP_SUCCESS == err);

    interrupt_called = false;

    /* Erase 1 block of data flash starting at block 0. */
    err = R_FLASH_HP_Erase(&g_flash_ctrl, FLASH_DF_BLOCK_0, 1);
    assert(FSP_SUCCESS == err);

    while (!interrupt_called)
    {
        ;
    }

    assert(FLASH_EVENT_ERASE_COMPLETE == flash_event);

    interrupt_called = false;

    /* Write 32 bytes to the first block of data flash. */
    err = R_FLASH_HP_Write(&g_flash_ctrl, (uint32_t) g_src, FLASH_DF_BLOCK_0, FLASH_HP_EXAMPLE_WRITE_SIZE);
    assert(FSP_SUCCESS == err);


    flash_status_t status;

    /* Wait until the current flash operation completes. */
    do
    {
        err = R_FLASH_HP_StatusGet(&g_flash_ctrl, &status);
    } while ((FSP_SUCCESS == err) && (FLASH_STATUS_BUSY == status));


    /* If the interrupt wasn't called process the error. */
    assert(interrupt_called);

    /* If the event wasn't a write complete process the error. */
    assert(FLASH_EVENT_WRITE_COMPLETE == flash_event);

    /* Verify the data was written correctly. */
    assert(0 == memcmp(g_src, (uint8_t *) FLASH_DF_BLOCK_0, FLASH_HP_EXAMPLE_WRITE_SIZE));
}

void flash_callback (flash_callback_args_t * p_args)
{
    interrupt_called = true;
    flash_event      = p_args->event;
}

High-Performance Flash Bank Swap Example

This example demonstrates swapping which flash bank is located at address 0. This feature is only on select MCUs.

void r_flash_hp_bankswap_example (void)
{
    /* Open the flash hp instance. */
    fsp_err_t err = R_FLASH_HP_Open(&g_flash_ctrl, &g_flash_cfg);

    /* Handle any errors. */
    assert(FSP_SUCCESS == err);

    /* Write the new application starting at 0x00200000. */

    /* Swap the block at address 0 with the one at 0x00200000 after the next restart.
     * The application at 0x00200000 must be written there by application code. */
    err = R_FLASH_HP_BankSwap(&g_flash_ctrl);

    /* Handle any errors. */
    assert(FSP_SUCCESS == err);

    /* Handle any pre-reset operations here */

    /* Reset the MCU to swap to the other bank */
    __NVIC_SystemReset();
}

High-Performance Anti-Rollback Counter Basic Example

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

void r_flash_hp_anti_rollback_counter_example (void)
{
    /* Open the flash hp instance. */
    fsp_err_t err = R_FLASH_HP_Open(&g_flash_ctrl, &g_flash_cfg);

    /* Handle any errors. */
    assert(FSP_SUCCESS == err);


    uint32_t current_count;

    /* Read the current counter value for the secure application */
    err = R_FLASH_HP_AntiRollbackCounterRead(&g_flash_ctrl, FLASH_ARC_SEC, &current_count);
    assert(FSP_SUCCESS == err);


    /* Read the current counter value for the OEM bootloader */
    err = R_FLASH_HP_AntiRollbackCounterRead(&g_flash_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_FLASH_HP_AntiRollbackCounterRead(&g_flash_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_FLASH_HP_AntiRollbackCounterRead(&g_flash_ctrl, FLASH_ARC_NSEC_0, &current_count); // NSEC App 0
    err |= R_FLASH_HP_AntiRollbackCounterRead(&g_flash_ctrl, FLASH_ARC_NSEC_1, &current_count); // NSEC App 1
    err |= R_FLASH_HP_AntiRollbackCounterRead(&g_flash_ctrl, FLASH_ARC_NSEC_2, &current_count); // NSEC App 2
    err |= R_FLASH_HP_AntiRollbackCounterRead(&g_flash_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_FLASH_HP_AntiRollbackCounterIncrement(&g_flash_ctrl, FLASH_ARC_SEC);

    /* If error occurred during increment, refresh the counter flash to ensure a valid state */
    if (FSP_SUCCESS != err)
    {
        err = R_FLASH_HP_AntiRollbackCounterRefresh(&g_flash_ctrl, FLASH_ARC_SEC);
        assert(FSP_SUCCESS == err);

    }

    assert(FSP_SUCCESS == err);

}

High-Performance User Lockable Area Basic Example

This example demonstrates writing the user lockable area.

void r_flash_hp_user_lockable_area_example (void)
{
    /* Open the flash hp instance. */
    fsp_err_t err = R_FLASH_HP_Open(&g_flash_ctrl, &g_flash_cfg);
    assert(FSP_SUCCESS == err);

    flash_info_t flash_info;
    err = R_FLASH_HP_InfoGet(&g_flash_ctrl, &flash_info);
    assert(FSP_SUCCESS == err);
    assert(flash_info.data_flash.num_regions >= 2);
    flash_block_info_t const * const p_user_area_info = &flash_info.data_flash.p_block_array[1];

    /* Select initial value to write to the lockable area */
    uint32_t update_complete_flag = 0;

    /* Set parameters for writing update_complete_flag to start of lockable area */
    uint32_t const flash_address    = p_user_area_info->block_section_st_addr;
    uint32_t const write_size_bytes = sizeof(update_complete_flag);

    /* Ensure write size is a multiple of the programming size */
    uint32_t const programming_size_bytes = p_user_area_info->block_size_write;
    assert(write_size_bytes % programming_size_bytes == 0);


    /* Write data to the beginning of User Lockable Area 0 */
    err = R_FLASH_HP_UserLockableAreaWrite(&g_flash_ctrl,
                                           (uint32_t) &update_complete_flag,
                                           flash_address,
                                           write_size_bytes);


    assert(FSP_SUCCESS == err);

    /* Confirm the data was written */
    assert(0 == memcmp(&update_complete_flag, (uint8_t *) flash_address, write_size_bytes));

    /* Select new value to write to the lockable area */
    update_complete_flag = 1;

    /* Write new data to the beginning of User Lockable Area 0 */
    err = R_FLASH_HP_UserLockableAreaWrite(&g_flash_ctrl,
                                           (uint32_t) &update_complete_flag,
                                           flash_address,
                                           write_size_bytes);

    assert(FSP_SUCCESS == err);

    /* Confirm the data was written */
    assert(0 == memcmp(&update_complete_flag, (uint8_t *) flash_address, write_size_bytes));
}

Data Structures
struct	flash_hp_instance_ctrl_t

Enumerations
enum	flash_bgo_operation_t

---

Data Structure Documentation

flash_hp_instance_ctrl_t

struct flash_hp_instance_ctrl_t

Flash HP instance control block. DO NOT INITIALIZE.

Data Fields
uint32_t	opened
	To check whether api has been opened or not.
flash_bgo_operation_t	current_operation
	Operation in progress, for example, FLASH_OPERATION_CF_ERASE.

Enumeration Type Documentation

flash_bgo_operation_t

enum flash_bgo_operation_t

Possible Flash operation states

Function Documentation

R_FLASH_HP_Open()

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

Initializes the high performance flash peripheral. Implements flash_api_t::open.

The Open function initializes the Flash.

Example:

    /* Open the flash hp instance. */
    fsp_err_t err = R_FLASH_HP_Open(&g_flash_ctrl, &g_flash_cfg);

Return values

FSP_SUCCESS	Initialization was successful and timer has started.
FSP_ERR_ALREADY_OPEN	The flash 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 Flash interrupts are not enabled.
FSP_ERR_FCLK	FCLK must be a minimum of 4 MHz for Flash operations.

R_FLASH_HP_Write()

fsp_err_t R_FLASH_HP_Write	(	flash_ctrl_t *const	p_api_ctrl,
		uint32_t const	src_address,
		uint32_t	flash_address,
		uint32_t const	num_bytes
	)

Writes to the specified Code or Data Flash memory area. Implements flash_api_t::write.

Example:

    /* Write 32 bytes to the first block of data flash. */
    err = R_FLASH_HP_Write(&g_flash_ctrl, (uint32_t) g_src, FLASH_DF_BLOCK_0, FLASH_HP_EXAMPLE_WRITE_SIZE);

Return values

FSP_SUCCESS	Operation successful. If BGO is enabled this means the operation was started successfully.
FSP_ERR_IN_USE	The Flash peripheral is busy with a prior on-going transaction.
FSP_ERR_NOT_OPEN	The Flash API is not Open.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of attempting to Write an area that is protected by an Access Window.
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation. This may be returned if the requested Flash area is not blank.
FSP_ERR_TIMEOUT	Timed out waiting for FCU operation to complete.
FSP_ERR_INVALID_SIZE	Number of bytes provided was not a multiple of the programming size or exceeded the maximum range.
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_FLASH_HP_Erase()

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

Erases the specified Code or Data Flash blocks. Implements flash_api_t::erase by the block_erase_address.

Note

Code flash may contain blocks of different sizes. When erasing code flash it is important to take this into consideration to prevent erasing a larger address space than desired.

Example:

    /* Erase 1 block of data flash starting at block 0. */
    err = R_FLASH_HP_Erase(&g_flash_ctrl, FLASH_DF_BLOCK_0, 1);

Return values

FSP_SUCCESS	Successful open.
FSP_ERR_INVALID_BLOCKS	Invalid number of blocks specified
FSP_ERR_INVALID_ADDRESS	Invalid address specified. If the address is in code flash then code flash programming must be enabled.
FSP_ERR_IN_USE	Other flash operation in progress, or API not initialized
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of attempting to Erase an area that is protected by an Access Window.
FSP_ERR_ASSERTION	NULL provided for p_ctrl
FSP_ERR_NOT_OPEN	The Flash API is not Open.
FSP_ERR_ERASE_FAILED	Status is indicating a Erase error.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_PE_FAILURE	Failed to enter or exit P/E mode.

R_FLASH_HP_BlankCheck()

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

Performs a blank check on the specified address area. Implements flash_api_t::blankCheck.

Example:

    /* Check if block 0 is erased. */
    err = R_FLASH_HP_BlankCheck(&g_flash_ctrl, FLASH_DF_BLOCK_0, FLASH_DATA_BLOCK_SIZE, &blank_check_result);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	Blank check operation completed with result in p_blank_check_result, or blank check started and in-progess (BGO mode).
FSP_ERR_INVALID_ADDRESS	Invalid data flash address was input.
FSP_ERR_INVALID_SIZE	'num_bytes' was either too large or not aligned for the CF/DF boundary size.
FSP_ERR_IN_USE	Other flash operation in progress or API not initialized.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of attempting to Erase an area that is protected by an Access Window.
FSP_ERR_NOT_OPEN	The Flash API is not Open.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_PE_FAILURE	Failed to enter or exit P/E mode.
FSP_ERR_BLANK_CHECK_FAILED	Blank check operation failed.

R_FLASH_HP_StatusGet()

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

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

Example:

    flash_status_t status;

    /* Wait until the current flash operation completes. */
    do
    {
        err = R_FLASH_HP_StatusGet(&g_flash_ctrl, &status);
    } while ((FSP_SUCCESS == err) && (FLASH_STATUS_BUSY == status));

Return values

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

R_FLASH_HP_IdCodeSet()

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

Implements flash_api_t::idCodeSet.

Return values

FSP_SUCCESS	ID Code successfully configured.
FSP_ERR_IN_USE	FLASH peripheral is busy with a prior operation.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_UNSUPPORTED	Code Flash Programming is not enabled.
FSP_ERR_NOT_OPEN	Flash API has not yet been opened.
FSP_ERR_PE_FAILURE	Failed to enter or exit Code Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command.

R_FLASH_HP_AccessWindowSet()

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

Configure an access window for the Code Flash memory using the provided start and end address. An access window defines a contiguous area in Code Flash for which programming/erase is enabled. This area is on block boundaries. The block containing start_addr is the first block. The block containing end_addr is the last block. The access window then becomes first block –> last block inclusive. Anything outside this range of Code Flash is then write protected.

Note

If the start address and end address are set to the same value, then the access window is effectively removed. This accomplishes the same functionality as R_FLASH_HP_AccessWindowClear().

Implements flash_api_t::accessWindowSet.

Return values

FSP_SUCCESS	Access window successfully configured.
FSP_ERR_INVALID_ADDRESS	Invalid settings for start_addr and/or end_addr.
FSP_ERR_IN_USE	FLASH peripheral is busy with a prior operation.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_UNSUPPORTED	Code Flash Programming is not enabled.
FSP_ERR_NOT_OPEN	Flash API has not yet been opened.
FSP_ERR_PE_FAILURE	Failed to enter or exit Code Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command.

R_FLASH_HP_AccessWindowClear()

fsp_err_t R_FLASH_HP_AccessWindowClear

(

flash_ctrl_t *const

p_api_ctrl

)

Remove any access window that is currently configured in the Code Flash. Subsequent to this call all Code Flash is writable. Implements flash_api_t::accessWindowClear.

Return values

FSP_SUCCESS	Access window successfully removed.
FSP_ERR_IN_USE	FLASH peripheral is busy with a prior operation.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_UNSUPPORTED	Code Flash Programming is not enabled.
FSP_ERR_NOT_OPEN	Flash API has not yet been opened.
FSP_ERR_PE_FAILURE	Failed to enter or exit Code Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command.

R_FLASH_HP_Reset()

fsp_err_t R_FLASH_HP_Reset

(

flash_ctrl_t *const

p_api_ctrl

)

Reset the FLASH peripheral. Implements flash_api_t::reset.

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

Return values

FSP_SUCCESS	Flash 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 FCU to become ready.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command.

R_FLASH_HP_StartUpAreaSelect()

fsp_err_t R_FLASH_HP_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. Doing a temporary switch might appear to have limited usefulness. If there is an access window in place such that Block 0 is write protected, then one could do a temporary switch, update the block and switch them back without having to touch the access window. Implements flash_api_t::startupAreaSelect.

Return values

FSP_SUCCESS	Start-up area successfully toggled.
FSP_ERR_IN_USE	FLASH 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_UNSUPPORTED	Code Flash Programming is not enabled.
FSP_ERR_PE_FAILURE	Failed to enter or exit Code Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command.

R_FLASH_HP_BankSwap()

fsp_err_t R_FLASH_HP_BankSwap

(

flash_ctrl_t *const

p_api_ctrl

)

Swaps the flash bank located at address 0x00000000 and address 0x00200000. This can only be done when in dual bank mode. Dual bank mode can be enabled in the FSP Configuration Tool under BSP Properties. After a bank swap is done the MCU will need to be reset for the changes to take place. flash_api_t::bankSwap.

Return values

FSP_SUCCESS	Start-up area successfully toggled.
FSP_ERR_IN_USE	FLASH 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_UNSUPPORTED	Code Flash Programming is not enabled.
FSP_ERR_PE_FAILURE	Failed to enter or exit Code Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_INVALID_MODE	Cannot switch banks while flash is in Linear mode.
FSP_ERR_WRITE_FAILED	Flash write operation failed.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command.

R_FLASH_HP_UpdateFlashClockFreq()

fsp_err_t R_FLASH_HP_UpdateFlashClockFreq

(

flash_ctrl_t *const

p_api_ctrl

)

Indicate to the already open Flash API that the FCLK has changed. Implements flash_api_t::updateFlashClockFreq.

This could be the case if the application has changed the system clock, and therefore the FCLK. Failure to call this function subsequent to changing the FCLK could result in damage to the flash macro.

Return values

FSP_SUCCESS	Start-up area successfully toggled.
FSP_ERR_IN_USE	Flash is busy with an on-going operation.
FSP_ERR_ASSERTION	NULL provided for p_ctrl
FSP_ERR_NOT_OPEN	Flash API has not yet been opened.
FSP_ERR_FCLK	FCLK is not within the acceptable range.

R_FLASH_HP_InfoGet()

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

Returns the information about the flash 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_FLASH_HP_Close()

fsp_err_t R_FLASH_HP_Close

(

flash_ctrl_t *const

p_api_ctrl

)

Releases any resources that were allocated by the Open() or any subsequent Flash 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_FLASH_HP_CallbackSet()

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

Updates the user callback with the option to provide memory for the callback argument structure. Implements flash_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.

R_FLASH_HP_AntiRollbackCounterIncrement()

fsp_err_t R_FLASH_HP_AntiRollbackCounterIncrement	(	flash_ctrl_t *const	p_api_ctrl,
		flash_arc_t	counter
	)

Increments the selected anti-rollback counter.

Warning

If this function returns an error code other than FSP_SUCCESS, or power loss occurs during a call to this function, call R_FLASH_HP_AntiRollbackCounterRefresh to ensure the counter flash is in a valid state following the error.

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 Data Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command
FSP_ERR_UNSUPPORTED	Data flash programming is not enabled or selected anti-rollback counter is not supported on this MCU

R_FLASH_HP_AntiRollbackCounterRefresh()

fsp_err_t R_FLASH_HP_AntiRollbackCounterRefresh	(	flash_ctrl_t *const	p_api_ctrl,
		flash_arc_t	counter
	)

Refreshes the selected anti-rollback counter flash area to ensure the flash is in a valid state even if an error occured during counter increment processing.

This function must be called if errors or power failure occured during counter increment.

Power failure can be detected by the application code by management of user-defined non-voltile flags during counter increment.

Until a refresh completes successfully, the value of the anti-rollback counter cannot be guaranteed and should not be read.

Implements flash_api_t::antiRollbackCounterRefresh

Return values

FSP_SUCCESS	Counter refreshed successfully
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_ASSERTION	NULL provided for p_ctrl
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 Data Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command
FSP_ERR_UNSUPPORTED	Data flash programming is not enabled or Anti-Rollback counter is not supported on this MCU

R_FLASH_HP_AntiRollbackCounterRead()

fsp_err_t R_FLASH_HP_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 Data Flash P/E mode.
FSP_ERR_TIMEOUT	Timed out waiting for the FCU to become ready.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of having received an illegal command
FSP_ERR_UNSUPPORTED	Data flash programming is not enabled or Anti-Rollback counter is not supported on this MCU

R_FLASH_HP_UserLockableAreaWrite()

fsp_err_t R_FLASH_HP_UserLockableAreaWrite	(	flash_ctrl_t *const	p_api_ctrl,
		uint32_t const	src_address,
		uint32_t	flash_address,
		uint32_t const	num_bytes
	)

Write to the user lockable area in flash

Implements flash_api_t::userLockableAreaWrite

Note

BGO is not supported for user lockable area flash operations.

Return values

FSP_SUCCESS	Operation successful.
FSP_ERR_IN_USE	The Flash peripheral is busy with a prior on-going transaction.
FSP_ERR_NOT_OPEN	The Flash API is not Open.
FSP_ERR_CMD_LOCKED	FCU is in locked state, typically as a result of attempting to Write an area that is protected by an Access Window.
FSP_ERR_WRITE_FAILED	Status is indicating a Programming error for the requested operation.
FSP_ERR_TIMEOUT	Timed out waiting for FCU operation to complete.
FSP_ERR_INVALID_SIZE	Number of bytes provided was not a multiple of the programming size or exceeded the maximum range.
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.