 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
There are two separate Flash modules: the r_flash_lp and the r_flash_hp. These modules implement a high-level API for flash memory programming applications. The High-Performance Flash module (Flash_HP) is used for programming the S7 and S5 family of MCUs. The Low-Power Flash module (Flash_LP) is used for programming the S3 and S1 family of MCUs. The two are not interchangeable, although the APIs and other features of the modules are very similar.
The Flash HAL modules APIs allow an application to read, write and erase both the data and ROM flash areas that reside within the MCU. The amount of flash memory available varies across MCU parts, but the API functions apply to all devices. Key features of the Flash HAL modules include:
The following hardware features are, or are not, supported by SSP for the Flash_HP.
Legend:
| Symbol | Meaning |
|---|---|
| ✓ | Available (Tested) |
| ⌧ | Not Available (Not tested/not functional or both) |
| N/A | Not supported by MCU |
| MCU Group | Programming by dedicated flash memory programmer through a serial interface (serial programming) | Programming of flash memory by user program (self-programming) | Background operations (BGOs) |
|---|---|---|---|
| S124 | N/A | N/A | N/A |
| S128 | N/A | N/A | N/A |
| S1JA | N/A | N/A | N/A |
| S3A1 | N/A | N/A | N/A |
| S3A3 | N/A | N/A | N/A |
| S3A6 | N/A | N/A | N/A |
| S3A7 | N/A | N/A | N/A |
| S5D3 | ✓ | ✓ | ✓ |
| S5D5 | ✓ | ✓ | ✓ |
| S5D9 | ✓ | ✓ | ✓ |
| S7G2 | ✓ | ✓ | ✓ |
The following hardware features are, or are not, supported by SSP for the Flash_LP.
Legend:
| Symbol | Meaning |
|---|---|
| ✓ | Available (Tested) |
| ⌧ | Not Available (Not tested/not functional or both) |
| N/A | Not supported by MCU |
| MCU Group | Programming by dedicated flash memory programmer through a serial interface (serial programming) | Programming of flash memory by user program (self-programming) | Background operations (BGOs) |
|---|---|---|---|
| S124 | ✓ | ✓ | ✓ |
| S128 | ✓ | ✓ | ✓ |
| S1JA | ✓ | ✓ | ✓ |
| S3A1 | ✓ | ✓ | ✓ |
| S3A3 | ✓ | ✓ | ✓ |
| S3A6 | ✓ | ✓ | ✓ |
| S3A7 | ✓ | ✓ | ✓ |
| S5D3 | N/A | N/A | N/A |
| S5D5 | N/A | N/A | N/A |
| S5D9 | N/A | N/A | N/A |
| S7G2 | N/A | N/A | N/A |
The Flash HAL module defines APIs for several operations including opening, reading, erasing and closing the flash memory. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
Flash HAL Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| open | g_flash0.p_api->open(g_flash0.p_ctrl, g_flash0.p_cfg);Open FLASH device. |
| write | g_flash0.p_api->write(g_flash0.p_ctrl,(uint32_t) write_buffer, FLASH_CF_32KB_BLOCK55, CODE_BLOCK_SIZE_32KB);Write FLASH device. |
| read | g_flash0.p_api->read(g_flash0.p_ctrl, read_buffer, DATA_FLASH_ADDR, num_bytes);Read FLASH device. |
| erase | g_flash0.p_api->erase(g_flash0.p_ctrl, FLASH_CF_32KB_BLOCK55,num_sectors);Erase FLASH device. |
| blankCheck | g_flash0.p_api->blankCheck(g_flash0.p_ctrl, FLASH_CF_32KB_BLOCK55, FLASH_DATA_BLOCK_SIZE, &blankCheck);Blank check FLASH device. |
| close | g_flash0.p_api->close(g_flash0.p_ctrl);Close FLASH device. |
| statusGet | g_flash0.p_api->statusGet(g_flash0.p_ctrl);Get Status for FLASH device. |
| accessWindowSet | g_flash0.p_api->accessWindowSet(g_flash0.p_ctrl, FLASH_CF_32KB_BLOCK1, FLASH_CF_32KB_BLOCK3);Set Access Window for FLASH device. |
| accessWindowClear | g_flash0.p_api->accessWindowClear(g_flash0.p_ctrl);Clear any existing Code Flashcode-flash access window for FLASH device. |
| idCodeSet | g_flash0.p_api->idCodeSet(g_flash0.p_ctrl, id_bytes, mode)Write the ID code provided to the id code registers. |
| reset | g_flash0.p_api->reset(g_flash0.p_ctrl);Reset function for FLASH device. |
| updateFlashClockFreq | g_flash0.p_api-> updateFlashClockFreq (g_flash0.p_ctrl);Update Flash clock frequency (FCLK) and recalculate timeout values. |
| startupAreaSelect | g_flash0.p_api->startupAreaSelect(g_flash0.p_ctrl, FLASH_STARTUP_AREA_BLOCK1);Select which block - Default (Block 0) or Alternate (Block 1) is used as the start-up area block. Refer to the following table for all the possible values for parameter2. |
| versionGet | g_flash0.p_api->versionGet(&version);Retrieve the API version using the version pointer. |
startupAreaSelect parameter2 options
| Swap Type | Is_temporary | Operation |
|---|---|---|
| FLASH_STARTUP_AREA_BLOCK0 | False | On next reset, Startup area will be Block 0. |
| FLASH_STARTUP_AREA_BLOCK0 | False | On next reset, Startup area will be Block 0. |
| FLASH_STARTUP_AREA_BLOCK1 | False | On next reset, Startup area will be Block 1. |
| FLASH_STARTUP_AREA_BLOCK1 | True | Startup area is immediately, but temporarily switched to Block 1. |
| FLASH_STARTUP_AREA_BTFLG | True | Startup area is immediately, but temporarily switched to the Block determined by the Configuration BTFLG. |
Status Return Values
| Name | Description |
|---|---|
| SSP_SUCCESS | Function successful. |
| SSP_ERR_IN_USE | Device in use error. |
| SSP_FLASH_ERR_FAILURE | Flash failure error. |
| SSP_ERR_FCLK | FCLK must be a minimum of 4 MHz for Flash operations. |
| SSP_ERR_TIMEOUT | Timeout error. |
| SSP_ERR_INVALID_SIZE | Invalid size error. |
| SSP_ERR_INVALID_ADDRESS | Invalid address error. |
| SSP_ERR_ASSERTION | Assertion error. |
| SSP_ERR_INVALID_BLOCKS | Invalid number of blocks specified. |
| SSP_ERR_INVALID_ARGUMENT | Invalid argument error. |
| SSP_ERR_HW_LOCKED | Peripheral already in use. |
| SSP_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. |
| SSP_ERR_NOT_OPEN | Flash has not yet been opened. |
| SSP_ERR_IRQ_BSP_DISABLED | Caller is requesting BGO (background mode operation) but the Flash interrupt is not enabled. |
| SSP_ERR_WRITE_FAILED | Write operation failed. This may be returned if the requested Flash area is not blank. |
| SSP_ERR_PE_FAILURE | Failed to enter P/E mode |
| false | Supplied address is valid flash address on this MCU. |
| true | Supplied address is valid and p_block info contains the details on this address's block. |
The Flash API makes the process of programming and erasing on-chip flash areas easy. Both code (user ROM) and data-flash areas are supported. The API, in its simplest form, can be used to perform blocking erase and program operations. The term "blocking" means that when a program or erase function is called, the function does not return until the operation has finished. This API supports blocking for both code and data-flash, with non-blocking operation (also known as BGO or Background Operation) available for data-flash operations only. When a code-flash operation is on-going, you cannot access that code-flash area. If you attempt to access the code-flash area while a code-flash operation is in progress, the flash-control unit will transition into an error state.
It is important to keep in mind that even though a code-flash operation is blocking, there are several situations where the code-flash could still end up being accessed while the operation is blocking and these must be prevented. This includes:
A multithreaded application where multiple threads are allowed to continue to run while a code-flash operation is blocking.
Data-Flash BGO Precautions
When using the data-flash BGO, the user ROM, RAM and external memory can still be accessed. 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 Precautions
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 user ROM (code-flash.) If an interrupt occurs during the ROM operation, then ROM 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 multithreaded environment, threads running from ROM cannot become active while a code-flash operation is in progress.
Blank Checking
The flash_api_t::blankCheck API function checks whether code or data-flash contents are blank. Note that it is not possible to write to flash (code or data) without first erasing it. The flash_api_t::blankCheck function determines whether a specified area is blank and therefore writable. In almost all cases, it is not sufficient to compare flash contents to 0xFF to determine whether the area is blank. The one exception is Flash HP code-flash. A 0xFF in Flash_HP code-flash does indicate blank. Renesas strongly recommends using the flash_api_t::blankCheck API function in all cases.
Flash Status
The flash_api_t::statusGet API function allows the application to query the 'Ready' status of the flash. This is useful in data-flash BGO operations when you choose not to use a callback function, so there is no asynchronous notification of a completed data-flash operation. In this case, the data-flash is configured to operate in BGO mode, so once the operation is started (an erase, for example), the call returns immediately with the operation executing in the background. By calling the flash_api_t::statusGet API function, you can determine when the operation has safely completed or generated an error, and it is now safe to proceed with another flash operation.
Swap Blocks
The flash_api_t::startupAreaSelect API function allows the user to select 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; however, if there is an access window in place such that Block 0 is write-protected, then you could do a temporary switch, update the block, and switch them back without having to touch the access window.
Flash Clock (FCLK)
The FCLK is the clock used by the Flash peripheral in performing all Flash operations. It must be >= 4 MHz for successful flash operations. As part of the flash_api_t::open function the Flash clock is checked and if < 4 MHz flash_api_t::open will return SSP_ERR_FCLK. Once the Flash API has been opened, if the FCLK 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.
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 (that is, 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.
Access Window
An access window defines a contiguous area in Code Flash for which programming/erase is enabled. This area is on block boundaries with a starting and ending address being provided to flash_api_t::accessWindowSet. The block containing the start address is the first block. The block containing the end address is the last block. The access window then becomes the first block – last block inclusive. Anything outside this range is write protected. Invalid address information provided to flash_api_t::accessWindowSet will return SSP_ERR_INVALID_ADDRESS. An access window may be removed by calling the flash_api_t::accessWindowClear API function
ID code set
Allows user to program the ID bytes rather than having the pre-programmed ID bytes with S-record.
This section describes how to include the Flash HAL Module in an application using the SSP configurator.
To add the Flash Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Flash Driver is g_flash0. This name can be changed in the associated Properties window.)
Flash HAL Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_flash0 Flash Driver on r_rflash_hp | Threads | New Stack> Driver> Storage> Flash Driver on r_flash_hp |
| g_flash0 Flash Driver on r_rflash_lp | Threads | New Stack> Driver> Storage> Flash Driver on r_flash_lp |
When the Flash Driver on r_flash_hp or r_flash_lp is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
The Flash HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the Flash HAL Module on r_flash_hp
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Controls whether to include code for API parameter checking. |
| Code Flash Programming Enable | Enable, Disabled Default: Disabled | Controls whether or not Code Flash programming is enabled. Disabling reduces the amount of ROM used by the API. |
| Name | g_flash0 | Module name. |
| Data Flash Background Operation | Enabled, Disabled Default: Enabled | Enabling allows Flash API calls that reference Data Flash to return immediately, with the operation continuing in the background. |
| Callback | NULL | Callback function called when a Data Flash BGO operation completes or errors. A user callback function can be registered in open. Warning: Since the callback is called from an ISR, do not use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system. |
| Flash Ready Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Flash ready interrupt priority selection. |
| Flash Error Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Flash error interrupt priority selection. |
Configuration Settings for the Flash HAL Module on r_flash_lp
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Controls whether to include code for API parameter checking. |
| Code Flash Programming Enable | Enable, Disabled Default: Disabled | Controls whether or not Code Flash programming is enabled. Disabling reduces the amount of ROM used by the API. |
| Name | g_flash0 | Module name. |
| Data Flash Background Operation | Enabled, Disabled Default: Enabled | Enabling allows Flash API calls that reference Data Flash to return immediately, with the operation continuing in the background. |
| Callback | NULL | Callback function called when a Data Flash BGO operation completes or errors. A user callback function can be registered in open. Warning: Since the callback is called from an ISR, do not use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system. |
| Flash Ready Interrupt Priority | Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Flash ready interrupt priority selection. |
In some cases, settings other than the defaults can be desirable. For example, it might be useful to disable code-flash programming to reduce the code size of the driver.
Enable the flash-ready interrupt only if you plan to use the data-flash BGO (background mode operation.) 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_EVENT_ERASE_COMPLETE.)
To enable interrupts, set the priority of the FCU > FRDYI interrupt on the ICU tab of the Project Configurator in e2 studio. This sets BSP_IRQ_CFG_FCU_FRDYI in synergy_cfg/ssp_cfg/bsp/bsp_irq_cfg.h to the priority level selected.
When the FLASH FRDYI interrupt is enabled in the BSP, the corresponding ISR will be defined in the Flash driver. The ISR will call a user-callback function if one was registered in open.
The flash circuit uses FCLK as its clock. FCLK must be <= 4 MHz. If this clock rate changes after the flash_api_t::open API is called, then you must call flash_api_t::updateFlashClockFreq API to inform the flash API of the change.
The typical steps in using the Flash HAL module in an application are:
These common steps are illustrated in a typical operational flow diagram in the following figure:
