RA Flexible Software Package Documentation
Release v5.5.0
|
|
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) |
Driver for the flash memory on RA high-performance MCUs. This module implements the Flash Interface.
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.
The R_FLASH_HP module has the following key features:
Configuration | Options | Default | Description |
---|---|---|---|
Parameter Checking |
| Default (BSP) | If selected code for parameter checking is included in the build. |
Code Flash Programming Enable |
| 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 | Controls whether or not data-flash programming is enabled. Disabling reduces the amount of ROM used by the API. |
Configuration | Options | Default | Description |
---|---|---|---|
Name | Name must be a valid C symbol | g_flash0 | Module name. |
Data Flash Background Operation |
| 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. |
Flash uses FCLK as the clock source depending on the MCU. When writing and erasing the clock source must be at least 4 MHz.
This module does not use I/O pins.
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.
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.
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.
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.
By default, the contents of data flash and code flash are cached by e2 studio. This means that during a debug session, modifications to these memory regions will not be observed by e2 studio. When debugging applications using e2 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).
This is a basic example of erasing and writing to data flash and code flash.
This example demonstrates using BGO to do non-blocking operations on the data flash.
This example demonstrates swapping which flash bank is located at address 0. This feature is only on select MCUs.
Data Structures | |
struct | flash_hp_instance_ctrl_t |
Enumerations | |
enum | flash_bgo_operation_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. | |
Possible Flash operation states
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:
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. |
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:
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. |
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.
Example:
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. |
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:
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. |
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:
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. |
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.
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. |
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.
Implements flash_api_t::accessWindowSet.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |