The BSP is responsible for getting the MCU from reset to the user's application. Before reaching the user's application, the BSP sets up the stacks, heap, clocks, interrupts, C runtime environment, and stack monitor.
Overview
BSP Features
BSP Clock Configuration
All system clocks are set up during BSP initialization based on the settings in bsp_clock_cfg.h. These settings are derived from clock configuration information provided from the RA Configuration editor Clocks tab.
- Clock configuration is performed prior to initializing the C runtime environment to speed up the startup process, as it is possible to start up on a relatively slow (that is, 32 kHz) clock.
- The BSP implements the required delays to allow the selected clock to stabilize.
- The BSP will configure the CMSIS SystemCoreClock variable after clock initialization with the current system clock frequency.
BSP Weak Symbols
You might wonder how the BSP is able to place ISR addresses in the NVIC table without the user having explicitly defined one. All that is required by the BSP is that the interrupt event be given a priority.
This is accomplished through the use of the 'weak' attribute. The weak attribute causes the declaration to be emitted as a weak symbol rather than a global. A weak symbol is one that can be overridden by an accompanying strong reference with the same name. When the BSP declares a function as weak, user code can define the same function and it will be used in place of the BSP function. By defining all possible interrupt sources as weak, the vector table can be built at compile time and any user declarations (strong references) will be used at runtime.
Weak symbols are supported for ELF targets and also for a.out targets when using the GNU assembler and linker.
Note that in CMSIS system.c
, there is also a weak definition (and a function body) for the Warm Start callback function R_BSP_WarmStart(). Because this function is defined in the same file as the weak declaration, it will be called as the 'default' implementation. The function may be overridden by the user by copying the body into their user application and modifying it as necessary. The linker identifies this as the 'strong' reference and uses it.
Warm Start Callbacks
As the BSP is in the process of bringing up the board out of reset, there are three points where the user can request a callback. These are defined as the 'Pre Clock Init', 'Post Clock Init' and 'Post C' warm start callbacks.
As described above, this function is already weakly defined as R_BSP_WarmStart(), so it is a simple matter of redefining the function or copying the existing body from CMSIS system.c into the application code to get a callback. R_BSP_WarmStart() takes an event parameter of type bsp_warm_start_event_t
which describes the type of warm start callback being made.
This function is not enabled/disabled and is always called for both events as part of the BSP startup. Therefore it needs a function body, which will not be called if the user is overriding it. The function body is located in system.c. To use this function just copy this function into your own code and modify it to meet your needs.
C Runtime Initialization
This BSP configuration allows the user to skip the FSP C runtime initialization code by setting the "C Runtime Initialization" to "Disabled" on the BSP tab of the RA Configuration editor. Disabling this option is useful in cases where a non-standard linker script is being used or other modifications to the runtime initialization are desired. If this macro is disabled, the user must use the 'Post Clock Init' event from the warm start (described above) to run their own runtime initialization code.
Heap Allocation
The relatively low amount of on-chip SRAM available and lack of memory protection in an MCU means that heap use must be very carefully controlled to avoid memory leaks, overruns and attempted overallocation. Further, many RTOSes provide their own dynamic memory allocation system. For these reasons the default heap size is set at 0 bytes, effectively disabling dynamic memory. If it is required for an application setting a positive value to the "Heap size (bytes)" option in the RA Common configurations on the BSP tab will allocate a heap.
- Note
- When using printf/sprintf (and other variants) to output floating point numbers a heap is required. A minimum size of 0x1000 (4096) bytes is recommended when starting development in this case.
Error Logging
When error logging is enabled, the error logging function can be redefined on the command line by defining FSP_ERROR_LOG(err) to the desired function call. The default function implementation is FSP_ERROR_LOG(err)=fsp_error_log(err, FILE, LINE). This implementation uses the predefined macros FILE and LINE to help identify the location where the error occurred. Removing the line from the function call can reduce code size when error logging is enabled. Some compilers may support other predefined macros like FUNCTION, which could be helpful for customizing the error logger.
Software Delay
Implements a blocking software delay. A delay can be specified in microseconds, milliseconds or seconds. The delay is implemented based on the system clock rate.
Critical Section Macros
Implements a critical section. Some MCUs (MCUs with the BASEPRI register) support allowing high priority interrupts to execute during critical sections. On these MCUs, interrupts with priority less than or equal to BSP_CFG_IRQ_MASK_LEVEL_FOR_CRITICAL_SECTION are not serviced in critical sections. Interrupts with higher priority than BSP_CFG_IRQ_MASK_LEVEL_FOR_CRITICAL_SECTION still execute in critical sections.
FSP_CRITICAL_SECTION_DEFINE;
Data transfer to RAM at startup
After starting FSP, the memory copy process is executed according to the rules described in sections.c of the src folder. The implementation of sections.c is described below. User can modify existing memory initialization rules and add new rules.
Default copy settings
sections.c generated by creating a new project performs the following operations by default.
Action | From | To | Size | When |
Copy | __sram_load_start | __sram_exec_start | __sram_load_end - __sram_load_start | End of Reset_Handler |
Copy | __data_load_start | __data_exec_start | __data_load_end - __data_load_start | End of Reset_Handler(If you choose the eXecute-In-Place board pack) |
Initialize to Zero | __bss_start | - | __bss_end - __bss_start | End of Reset_Handler |
Initialize to Zero | __bss2_start | - | __bss2_end - __bss2_start | End of Reset_Handler |
The above symbols are defined in the linker script.
Tables describing memory initialization rules
There are four tables in sections.c: Select the table to use according to the copy conditions.
Table name | Action | When |
DTBL_F | Take a copy action on the specified memory. | The action is executed in the first half of Reset_Handler. |
DTBL | Take a copy action on the specified memory. | The action is executed in the end part of Reset_Handler. |
BTBL_F | Take a zero assignment action on the specified memory. | The action is executed in the first half of Reset_Handler. |
BTBL | Take a zero assignment action on the specified memory. | The action is executed in the end part of Reset_Handler. |
DTBL and BTBL are used for the normal program area. If there is an area to be used in the subroutine called from Reset_Handler, use DTBL_F and BTBL_F.
Format of Copy Memory Table (DTBL_F, DTBL)
The table represents one copy rule in one row. The size of the array is variable length, and the end is determined by all zero row. The elements on one line are "Top address on ROM", "Bottom address on ROM", "Top address on RAM" in order from the left, and the input rules are shown below.
Elements | Description |
Top address on ROM | Start address of copy source area. Usually refers to the area on the flash ROM. |
Bottom address on ROM | End address of copy source area. |
Top address on RAM | Start address of copy destination area. Usually refers to the area on the DDR. |
Format of Initialize to Zero Table (BTBL_F, BTBL)
The table represents one zero assignment rule in one row. The size of the array is variable length, and the end is determined by all zero row. The elements on one line are "Top address", "Bottom address" in order from the left, and the input rules are shown below.
Elements | Description |
Top address | Start address of zero assignment area. |
Bottom address | End address of zero assignment area. |
Configuration
The BSP is heavily data driven with most features and functionality being configured based on the content from configuration files. Configuration files represent the settings specified by the user and are generated when the project is built and/or when the Generate Project Content button is clicked in the RA Configuration editor.
Build Time Configurations for fsp_common
The following build time configurations are defined in fsp_cfg/bsp/bsp_cfg.h:
Configuration | Options | Default | Description |
Secure stack size (bytes) | Value must be an integer multiple of 8 and between 8 and 0xFFFFFFFF | 0x200 | Set the size of the secure program stack.
NOTE: This entry is for the secure stack. |
Main stack size (bytes) | Value must be an integer multiple of 8 and between 8 and 0xFFFFFFFF | 0x200 | Set the size of the main program stack.
NOTE: This entry is for the main stack. When using an RTOS, thread stacks can be configured in the properties for each thread. |
Heap size (bytes) | Value must be 0 or an integer multiple of 8 between 8 and 0xFFFFFFFF. | 0 | The main heap is disabled by default. Set the heap size to a positive integer divisible by 8 to enable it.
A minimum of 4K (0x1000) is recommended if standard library functions are to be used. |
MCU Vcc (mV) | Value must between 0 and 5500 (5.5V) | 3300 | Some peripherals require different settings based on the supplied voltage. Entering Vcc here (in mV) allows the relevant driver modules to configure the associated peripherals accordingly. |
Parameter checking |
| Disabled | When enabled, parameter checking for the BSP is turned on. In addition, any modules whose parameter checking configuration is set to 'Default (BSP)' will perform parameter checking as well. |
Assert Failures |
-
Return FSP_ERR_ASSERTION
-
Call fsp_error_log then Return FSP_ERR_ASSERTION
-
Use assert() to Halt Execution
-
Disable checks that would return FSP_ERR_ASSERTION
| Return FSP_ERR_ASSERTION | Define the behavior of the FSP_ASSERT() macro. |
Error Log |
-
No Error Log
-
Errors Logged via fsp_error_log
| No Error Log | Specify error logging behavior. |
PFS Protect |
| Enabled | Keep the PFS registers locked when they are not being modified. If disabled they will be unlocked during startup. |
C Runtime Initialization |
| Enabled | Select if the C runtime initialization in the BSP is to be used. If disabled, use the BSP_WARM_START_POST_CLOCK event to run user defined equivalent. |
◆ R_BSP_MODULE_CLKON
#define R_BSP_MODULE_CLKON |
( |
|
ip, |
|
|
|
channel |
|
) |
| |
Start clock supply
- Parameters
-
ip | fsp_ip_t enum value for the clock is supplied. |
channel | The channel. Use ch 0 for ips without channels. Only single bit can be set. |
◆ R_BSP_MODULE_CLKOFF
#define R_BSP_MODULE_CLKOFF |
( |
|
ip, |
|
|
|
channel |
|
) |
| |
Stop clock supply
- Parameters
-
ip | fsp_ip_t enum value for the ip to stop clock. |
channel | The channel. Use ch 0 for ips without channels. Only single bit can be set. |
◆ R_BSP_MODULE_RSTON
#define R_BSP_MODULE_RSTON |
( |
|
ip, |
|
|
|
channel |
|
) |
| |
Reset ip
- Parameters
-
ip | fsp_ip_t enum value for the ip to be reset. |
channel | The channel. Use ch 0 for ips without channels. Only single bit can be set. |
◆ R_BSP_MODULE_RSTOFF
#define R_BSP_MODULE_RSTOFF |
( |
|
ip, |
|
|
|
channel |
|
) |
| |
Reset ip
- Parameters
-
ip | fsp_ip_t enum value for the ip to be reset. |
channel | The channel. Use ch 0 for ips without channels. Only single bit can be set. |
◆ BSP_IRQ_DISABLED
Used to signify that an ELC event is not able to be used as an interrupt.
◆ FSP_LOG_PRINT
#define FSP_LOG_PRINT |
( |
|
X | ) |
|
Macro that can be defined in order to enable logging in FSP modules.
◆ FSP_RETURN
#define FSP_RETURN |
( |
|
err | ) |
|
Macro to log and return error without an assertion.
◆ FSP_ERROR_LOG
#define FSP_ERROR_LOG |
( |
|
err | ) |
|
This function is called before returning an error code. To stop on a runtime error, define fsp_error_log in user code and do required debugging (breakpoints, stack dump, etc) in this function.
◆ FSP_ASSERT
Default assertion calls FSP_ERROR_RETURN if condition "a" is false. Used to identify incorrect use of API's in FSP functions.
◆ FSP_ERROR_RETURN
#define FSP_ERROR_RETURN |
( |
|
a, |
|
|
|
err |
|
) |
| |
All FSP error codes are returned using this macro. Calls FSP_ERROR_LOG function if condition "a" is false. Used to identify runtime errors in FSP functions.
◆ FSP_CRITICAL_SECTION_ENTER
#define FSP_CRITICAL_SECTION_ENTER |
This macro temporarily saves the current interrupt state and disables interrupts.
◆ FSP_CRITICAL_SECTION_EXIT
#define FSP_CRITICAL_SECTION_EXIT |
This macro restores the previously saved interrupt state, reenabling interrupts.
◆ FSP_INVALID_VECTOR
#define FSP_INVALID_VECTOR |
Used to signify that the requested IRQ vector is not defined in this system.
◆ BSP_CFG_HANDLE_UNRECOVERABLE_ERROR
#define BSP_CFG_HANDLE_UNRECOVERABLE_ERROR |
( |
|
x | ) |
|
In the event of an unrecoverable error the BSP will by default call the __BKPT() intrinsic function which will alert the user of the error. The user can override this default behavior by defining their own BSP_CFG_HANDLE_UNRECOVERABLE_ERROR macro.
◆ BSP_STACK_ALIGNMENT
#define BSP_STACK_ALIGNMENT |
Stacks (and heap) must be sized and aligned to an integer multiple of this number.
◆ R_BSP_MODULE_START
#define R_BSP_MODULE_START |
( |
|
ip, |
|
|
|
channel |
|
) |
| |
Cancels the module stop state.
- Parameters
-
ip | fsp_ip_t enum value for the module to be started |
channel | The channel. Use channel 0 for modules without channels. |
◆ R_BSP_MODULE_STOP
#define R_BSP_MODULE_STOP |
( |
|
ip, |
|
|
|
channel |
|
) |
| |
Enables the module stop state.
- Parameters
-
ip | fsp_ip_t enum value for the module to be stopped |
channel | The channel. Use channel 0 for modules without channels. |
◆ fsp_ip_t
Available modules.
Enumerator |
---|
FSP_IP_GTM | General Timer.
|
FSP_IP_PORT | I/O Ports.
|
FSP_IP_IA55 | IA55 (Interrupt controller)
|
FSP_IP_SCIF | Serial Communications Interface with FIFO.
|
FSP_IP_RIIC | I2C Bus Interface.
|
FSP_IP_RSPI | Renesas Serial Peripheral Interface.
|
FSP_IP_DMAC | Direct Memory Access Controller.
|
FSP_IP_SSI | Serial Sound Interface.
|
FSP_IP_CANFD | CANFD Interface (RS-CANFD)
|
FSP_IP_ETHER | Ethernet MAC Controller.
|
FSP_IP_EDMAC | Ethernet DMA Controller.
|
FSP_IP_CRU | Camera Data Receiving Unit.
|
FSP_IP_LCDC | LCD Controller.
|
FSP_IP_USB | USB 2.0.
|
FSP_IP_ADC | A/D Converter.
|
FSP_IP_WDT | Watchdog Timer.
|
FSP_IP_SDHI | SD/MMC Host Interface.
|
FSP_IP_ISU | Image Scaling Unit.
|
◆ bsp_warm_start_event_t
Different warm start entry locations in the BSP.
Enumerator |
---|
BSP_WARM_START_RESET | Called almost immediately after reset. No C runtime environment, clocks, or IRQs.
|
BSP_WARM_START_POST_CLOCK | Called after clock initialization. No C runtime environment or IRQs.
|
BSP_WARM_START_POST_C | Called after clocks and C runtime environment have been set up.
|
◆ bsp_delay_units_t
Available delay units for R_BSP_SoftwareDelay(). These are ultimately used to calculate a total # of microseconds
Enumerator |
---|
BSP_DELAY_UNITS_SECONDS | Requested delay amount is in seconds.
|
BSP_DELAY_UNITS_MILLISECONDS | Requested delay amount is in milliseconds.
|
BSP_DELAY_UNITS_MICROSECONDS | Requested delay amount is in microseconds.
|
◆ bsp_grp_irq_t
Which interrupts can have callbacks registered.
Enumerator |
---|
BSP_GRP_IRQ_UNSUPPORTED | NMI Group IRQ are not supported in RZ/A3UL.
|
◆ R_FSP_VersionGet()
Get the FSP version based on compile time macros.
- Parameters
-
[out] | p_version | Memory address to return version information to. |
- Return values
-
FSP_SUCCESS | Version information stored. |
FSP_ERR_ASSERTION | The parameter p_version is NULL. |
◆ Default_Handler()
void Default_Handler |
( |
void |
| ) |
|
Default exception handler.
◆ SystemInit()
Initialize the MCU and the runtime environment.
◆ R_BSP_WarmStart()
This function is called at various points during the startup process. This function is declared as a weak symbol higher up in this file because it is meant to be overridden by a user implemented version. One of the main uses for this function is to call functional safety code during the startup process. To use this function just copy this function into your own code and modify it to meet your needs.
- Parameters
-
[in] | event | Where the code currently is in the start up process |
◆ R_BSP_HardwareInit()
void R_BSP_HardwareInit |
( |
void |
| ) |
|
Function Name: R_BSP_HardwareInit This function is called at various points during the startup process. This function is declared as a weak symbol higher up in this file because it is meant to be overridden by a user implemented version. One of the main uses for this function is to call functional safety code during the startup process. To use this function just copy this function into your own code and modify it to meet your needs.
◆ R_FSP_SystemClockHzGet()
uint32_t R_FSP_SystemClockHzGet |
( |
fsp_priv_clock_t |
clock | ) |
|
Get the system clock frequency.
- Parameters
-
[in] | clock | Element number of the array that defines the frequency of the bus clock. |
- Return values
-
g_clock_freq[clock] | System clock frequency. |
◆ R_FSP_CurrentIrqGet()
__STATIC_INLINE fsp_err_t R_FSP_CurrentIrqGet |
( |
void |
| ) |
|
Return active interrupt vector number value
- Returns
- Active interrupt vector number value
◆ R_BSP_UniqueIdGet()
__STATIC_INLINE fsp_err_t R_BSP_UniqueIdGet |
( |
| ) |
|
Get unique ID is not supported for this RZ MCU.
- Returns
- A pointer to the unique identifier structure
◆ R_BSP_SoftwareDelay()
Delay for at least the specified duration in units and return.
- Parameters
-
[in] | delay | The number of 'units' to delay. |
[in] | units | The 'base' (bsp_delay_units_t) for the units specified. Valid values are: BSP_DELAY_UNITS_SECONDS, BSP_DELAY_UNITS_MILLISECONDS, BSP_DELAY_UNITS_MICROSECONDS.
For example:
At 1 MHz one cycle takes 1 microsecond (.000001 seconds).
At 12 MHz one cycle takes 1/12 microsecond or 83 nanoseconds.
Therefore one run through bsp_prv_software_delay_loop() takes: ~ (83 * BSP_DELAY_LOOP_CYCLES) or 332 ns. A delay of 2 us therefore requires 2000ns/332ns or 6 loops. |
The 'theoretical' maximum delay that may be obtained is determined by a full 32 bit loop count and the system clock rate. @120MHz: ((0xFFFFFFFF loops * 4 cycles /loop) / 120000000) = 143 seconds. @32MHz: ((0xFFFFFFFF loops * 4 cycles /loop) / 32000000) = 536 seconds
Note that requests for very large delays will be affected by rounding in the calculations and the actual delay achieved may be slightly longer. @32 MHz, for example, a request for 532 seconds will be closer to 536 seconds.
Note also that if the calculations result in a loop_cnt of zero, the bsp_prv_software_delay_loop() function is not called at all. In this case the requested delay is too small (nanoseconds) to be carried out by the loop itself, and the overhead associated with executing the code to just get to this point has certainly satisfied the requested delay.
- Note
- This function uses SystemCoreClock and therefore requires that the BSP has already initialized the CGC (which it does as part of the Sysinit). Care should be taken to ensure this remains the case if in the future this function were to be called as part of the BSP initialization.
◆ R_BSP_GroupIrqWrite()
Register a callback function for supported interrupts. If NULL is passed for the callback argument then any previously registered callbacks are unregistered.
- Parameters
-
[in] | irq | Interrupt for which to register a callback. |
[in] | p_callback | Pointer to function to call when interrupt occurs. |
- Return values
-
FSP_ERR_UNSUPPORTED | NMI Group IRQ are not supported in RZ/A3UL. |
◆ __sinf()
BSP_TFU_INLINE float __sinf |
( |
float |
angle | ) |
|
Calculates sine of the given angle.
- Parameters
-
[in] | angle | The value of an angle in radian. |
- Return values
-
◆ __cosf()
BSP_TFU_INLINE float __cosf |
( |
float |
angle | ) |
|
Calculates cosine of the given angle.
- Parameters
-
[in] | angle | The value of an angle in radian. |
- Return values
-
◆ __sincosf()
BSP_TFU_INLINE void __sincosf |
( |
float |
angle, |
|
|
float * |
sin, |
|
|
float * |
cos |
|
) |
| |
Calculates sine and cosine of the given angle.
- Parameters
-
[in] | angle | The value of an angle in radian. |
[out] | sin | Sine value of an angle. |
[out] | cos | Cosine value of an angle. |
◆ __atan2f()
BSP_TFU_INLINE float __atan2f |
( |
float |
y_cord, |
|
|
float |
x_cord |
|
) |
| |
Calculates the arc tangent based on given X-cordinate and Y-cordinate values.
- Parameters
-
[in] | y_cord | Y-Axis cordinate value. |
[in] | x_cord | X-Axis cordinate value. |
- Return values
-
Arc | tangent for given values. |
◆ __hypotf()
BSP_TFU_INLINE float __hypotf |
( |
float |
x_cord, |
|
|
float |
y_cord |
|
) |
| |
Calculates the hypotenuse based on given X-cordinate and Y-cordinate values.
- Parameters
-
[in] | y_cord | Y-cordinate value. |
[in] | x_cord | X-cordinate value. |
- Return values
-
Hypotenuse | for given values. |
◆ __atan2hypotf()
BSP_TFU_INLINE void __atan2hypotf |
( |
float |
y_cord, |
|
|
float |
x_cord, |
|
|
float * |
atan2, |
|
|
float * |
hypot |
|
) |
| |
Calculates the arc tangent and hypotenuse based on given X-cordinate and Y-cordinate values.
- Parameters
-
[in] | y_cord | Y-cordinate value. |
[in] | x_cord | X-cordinate value. |
[out] | atan2 | Arc tangent for given values. |
[out] | hypot | Hypotenuse for given values. |
◆ SystemCoreClock
System Clock Frequency (Core Clock)