|Hint: Use the tree menu to navigate groups of related pages|
Renesas RZ/T RTOS Demo
Using IAR and GCC embedded compilers
IntroductionThis page documents a FreeRTOS demo application for the Renesas RZ/T embedded processor, which has an ARM Cortex-R4F core. Two projects are provided, allowing the demo to be built with with the IAR Embedded Workbench or GCC embedded development tools. The demo targets the Renesas RZT1 RSK (Renesas Starter Kit).
Both projects include build options that allow the creation of a simple blinky demo or a comprehensive demo, and use:
The FreeRTOS Cortex-R4F kernel port (the version for embedded processors
that do not also include the ARM Generic Interrupt Controller, or GIC),
which supports interrupt nesting.
Either the IAR Embedded Workbench or e2studio IDE (depending on the
project file used)
command line interface. [Note the FreeRTOS+CLI license
is different from the FreeRTOS kernel license]
- The standard demo tasks – including the tasks that test interrupt nesting
IMPORTANT! Notes on using the RTOS Renesas RZ/T demo projectPlease read all the following points before using this RTOS port.
- Source Code Organisation
- The Demo Application Functionality
- Build Instructions (for both Embedded Workbench and e2studio)
- RTOS Configuration and Usage Details, in particular:
Source Code OrganisationThe FreeRTOS zip file contains source code for all the RTOS ports and all the RTOS demo applications. Only a small subset of these files are required by the Renesas RZ/T ARM Cortex-R4F demo. The Source Code Organization page describes the structure of the FreeRTOS zip file download, and provides information on creating a new RTOS project.
The e2studio Eclipse project file used to build the demo with GCC, and the IAR Embedded Workbench project file used to build the demo with the IAR compiler, are both located in the FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR directory.
The e2studio GCC and IAR projects build the same RTOS demo application, and both include files that are contained in the /FreeRTOS-Plus directory, so the projects will not build if the /FreeRTOS-Plus directory has been deleted or moved from its default location.
The Renesas RZ/T ARM Cortex-R4 Demo Application
Hardware and software set upThe demo documented on this page uses the UART to USB converter and LEDs built onto the RZT1 RSK, so no hardware setup is required.
The simply blinky exampleThe blinky example is built when mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 1 in main.c. When this is done, main() calls main_blinky():
The main_blinky() Function:
main_blinky() creates an RTOS queue, a queue send task, and a queue receive task, then starts the scheduler.
The Queue Send Task:
The queue send task is implemented by the prvQueueSendTask() function in main_blinky.c.
prvQueueSendTask() sends the value 100 to the RTOS queue every 200 milliseconds.
The Queue Receive Task:
The queue receive task is implemented by the prvQueueReceiveTask() function in main_blinky.c.
prvQueueReceiveTask() blocks to wait for data to arrive on the RTOS queue. Each time the value 100 is received from the queue it toggles LED 0. As data is sent to the queue every 200ms, the LED will toggle every 200ms.
The comprehensive test and demo applicationThe comprehensive example is created when mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 0 in main.c. When this is done, main() calls main_full():
The main_full() Function:
main_full() creates a set of standard demo tasks, some application specific test tasks, a command line interface (CLI) task, a pseudo randomiser task, and then starts the scheduler. The pseudo randomiser task is just used to ensure some variation is added to the sequence in which the test tasks execute, and in so doing, improve the test coverage.
The command line interface (CLI)
The CLI is implemented using the FreeRTOS+CLI extensible command line interface, and uses the UART to USB converter connector (J8) at 19200 baud for its input and output. As always with FreeRTOS+CLI, type “help” to see a list of registered commands.
The “Reg Test” Tasks:
The reg test tasks test the context switching mechanism by filling each embedded processor register with a known value, then continuously checking that each register maintains its expected value for the lifetime of the task.
The “Check” Task:
The “Check” task monitors the status of all the other tasks in the system, looking for a task either stalling, or reporting an error. It toggles LED 0 each time it iterates around its implementing loop.
If the LED is toggling every three seconds then the check task has not detected any stalled tasks, or detected any errors. If the LED is toggling every 200ms then at least one error has been found.
Building and executing the demo application – IAR Embedded WorkbenchNote that the IAR project references common files from both the /FreeRTOS-Plus and /FreeRTOS/Demo/Common directories, so the project will not compile if either directory has been deleted or moved.
- Open FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR/RTOSDemo.eww from within the IAR Embedded Workbench IDE.
- Open the project’s main.c file, and set mainCREATE_SIMPLE_BLINKY_DEMO_ONLY to generate either the simple blinky demo, or the full test and demo application, as required.
- Select “Build All” from the IDE’s “Project” menu to build the RTOS demo.
- Ensure the target hardware is connected to the host computer using an appropriate debug interface (J-Link, I-Jet, etc.).
- Select “Options” from the IDE’s “Project” menu. The options window will appear. In the options window first select the “Debugger” category, then ensure the “driver” setting is correct for your debugger connection (J-Link, I-Jet, etc.). Close the Options window when the setting is correct.
- Select “Download and Debug” from the IDE’s “Project” window to download the built executable to the ARM Cortex-R4F, and start a debug session.
Building and executing the demo application – e2studioNote that the e2studio Eclipse project uses both virtual folders and links that reference files from both the /FreeRTOS-Plus and /FreeRTOS/Demo/Common directories. The [virtual] file structure viewed in the Eclipse project explorer will not match the [actual] file structure viewed on the disk, and the project will not built if either referenced directory is missing or has been moved.
- Open e2studio and either create a new workspace or select an existing workspace when prompted.
- Select “Import” from the IDE’s “File” menu to bring up the import dialog box.
- In the Import dialog box, select “General->Existing Projects Into Workspace” then browse to and select the FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR directory. A project called “RTOSDemo” will be visible.
Ensure RTOSDemo is checked and that Copy Projects Into Workspace is
not checked before clicking “Finish”.
Import FreeRTOS_Demo into the Eclipse workspace without copying it into the workspace.
- Open main.c and set mainCREATE_SIMPLE_BLINKY_DEMO_ONLY to generate either the simple blinky demo, or the full test and demo application, as required.
- Ensure the target hardware is connected to the host computer using an appropriate debug interface, for example, a J-Link.
- Select “Build All” from the IDE’s “Project” menu.
After the build completes, select “Debug Configurations…” from the
IDE’s “Debug” menu, and configure and run a debug configuration that is
appropriate for your selected connection method.
The clickable screenshots below show a configuration that is using a J-Link
Interrupt service routines
When an interrupt occurs, the RZ/T real time embedded processor hardware will
vector directly to a peripheral specific interrupt handler, rather than to the
ARM Cortex-R IRQ vector. Therefore, each interrupt handler installed by the
application must include an assembly file wrapper that performs some house keeping,
then branches to the FreeRTOS interrupt entry code. The FreeRTOS interrupt entry
code manages interrupt entry, including interrupt nesting, before calling a
standard C function in which the interrupting peripheral is serviced.
For the purpose of this example, assume the C portion of the interrupt handler is called InterruptHandler() – as shown below. A full example is provided after the sections that demonstrate how to write the assembly file wrappers:
For the purposes of this example, assume the assembly wrapper is called InterruptHandlerWrapper(). The wrapper must save a pointer to the C portion of the handler function into a variable called pxISRFunction, then branch to a function called FreeRTOS_IRQ_Handler (which is provided by the RTOS).
The syntax required to add the assembly file wrapper to each C interrupt handler function is dependent on the compiler used (IAR or GCC). Examples and further references are provided below.
Writing an assembly wrapper for an ISR: IARWhen using the IAR tools, the assembly wrapper must be implemented in an assembly file. A generic example is provided below. Further examples can be found in /FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR/System/IAR/Interrupt_Entry_Stubs.asm.
Writing an assembly wrapper for an ISR: GCCWhen using the GCC tools, the GCC inline assembler and the ‘naked’ function attribute can be used to include the assembly wrapper in a C file. A generic example is provided below. Further examples can be found in the /FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR/src/FreeRTOS_tick_config.c, /FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR/src/cg_src/r_cg_scifa_user.c and /FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR/src/full_demo/IntQueueTimer.c source files.
Writing the C portion of an ISR: IAR and GCCIf an ISR causes a task of equal or higher priority than the currently executing task to leave the Blocked state then the ISR must request a context switch before the ISR exits. When this is done the interrupt will interrupt one RTOS task, but return to a different RTOS task.
The macros portYIELD_FROM_ISR() (or portEND_SWITCHING_ISR()) can be used to request a context switch from within an ISR. The following source code snippet is provided as an example. The example ISR uses a direct to task notification to synchronise with a task (not shown), and calls portYIELD_FROM_ISR() to ensure the interrupt returns directly to the task.
Only FreeRTOS API functions that end in “FromISR” can be called from an interrupt service routine.
Generating the RTOS tick interrupt
The RTOS Cortex-R port is a generic port that is tailored to specific embedded
processor implementation using macros and callback functions. The RTOS tick
interrupt is configured using the following two macros, which are defined in
the FreeRTOSConfig.h file supplied with the RTOS demo application:
This must call the function that configures a timer to generate the tick interrupt, and install FreeRTOS_Tick_Handler() as the timers interrupt service routine (via an assembly wrapper, as described above).
In the provided demo application the macro is set to call vConfigureTickInterrupt(), which is defined in FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR/src/FreeRTOS_tick_config.c, and configures the compare match timer 5 (CMT5) to generate the RTOS tick.
This must clear pending interrupts in whichever timer is used to generate the RTOS tick.
In the provided demo application the macro is set to clear the interrupt in CMT5, as the RTOS tick interrupt is generated by CMT5.
Including the IRQ handling function
The RTOS Cortex-R port is a generic port that is tailored to a specific embedded
processor implementation using macros and callback function. In the RZ/T RTOS port
the generic IRQ handling code (the code that manages interrupt entry) calls
vApplicationIRQHandler(), and vApplicationIRQHandler() must be provided by the
In the provided demo application vApplicationIRQHandler() is implemented in FreeRTOS/Demo/CORTEX_R4F_RZ_T_GCC_IAR/src/FreeRTOS_tick_config.c, and replicated below: