RA Flexible Software Package Documentation  Release v3.1.0

 
Starting Development

Table of Contents

Starting Development Introduction

The wealth of resources available to learn about and use e2 studio and FSP can be overwhelming on first inspection, so this section provides a Starting Development Guide with a list of the most important initial steps. Following these highly recommended first 11 steps will bring you up to speed on the development environment in record time. Even experienced developers can benefit from the use of this guide, to learn the terminology that might be unfamiliar or different from previous environments.

  1. Read the section What is e2 studio?, up to but not including e2 studio Prerequisites. This will provide a description of the various windows and views to use e2 studio to create a project, add modules and threads, configure module properties, add code, and debug a project. It also describes how to use key coding 'accelerators' like Developer Assist (to drag and drop parameter populated API function calls right into your code), a context aware Autocomplete (to easily find and select from suggested enumerations, functions, types, and many other coding elements), and many other similar productivity enhancers.
  2. Read the FSP Architecture, FSP Modules and FSP Stacks sections. These provide the basic background on how FSP modules and stacks are used to construct your application. Understanding their definitions and the theory behind how they combine will make it easier to develop with FSP.
  3. Read a few Modules sections to see how to use API function calls, structures, enumerations, types and callbacks. These module guides provide the information you will use to implement your project code.
  4. After you have a Kit and you have downloaded and installed e2 studio and FSP, you can build and debug a simple project to test your installation, tool flow, and the kit. (If you do not have a Kit or have not yet installed the development software, use the links included in the e2 studio Prerequisites for more information.) The simple Tutorial: Your First RA MCU Project - Blinky will Blink an LED on and off. Follow the instructions for importing and running this project in section Create a New Project for Blinky. It will use some of the key steps for managing projects within e2 studio and is a good way to learn the basics.
  5. Once you have successfully run Blinky you have a good starting point for using FSP for more complex projects. The Using HAL Drivers Tutorial, available at Tutorial: Using HAL Drivers - Programming the WDT, shows how to create a project from scratch, using FSP API functions. Do this next.
  6. Several Hands-on Quick FSP Labs are available that cover key development topics with short 15-minute Do it Yourself (DiY) activities targeting the EK-RA6M3. Topics covered include code development accelerators like Developer Assistance, Autocomplete, Help, Visual Expressions and using Example Projects. The complete list of available Quick FSP Labs can be found here: https://en-support.renesas.com/knowledgeBase/category/31087/subcategory/31090. Doing a couple of these labs provides further details on using FSP, and is also good practice. Running these labs is highly recommended.
  7. The balance of the FSP Architecture sections (that is, those not called out in step 2 above) contain additional reference material that may be helpful in the future. Scan them so you know what they contain, in case you need them.
  8. The balance of the e2 studio User Guide, starting with the What is a Project? section up to, but not including, Writing the Application section, provides a detailed description of each of the key steps, windows, and entries used to create, manage, configure, build and debug a project. Much of this may be familiar after running through the tutorials and Quick Labs. However, it is important to have a good grasp of what each of the configuration tabs are used for as that is where the bulk of the project preparation work takes place prior to writing code. Skim over this section as it may help with any questions in the future.
  9. Read the Writing the Application section to get a short introduction to the steps used when creating application code with FSP. It covers both RTOS-independent and RTOS-dependent applications. It also includes a short description for several of the code accelerators you should be familiar with by now. Using additional Quick FSP Labs is a good way to become familiar with the application development process and links to them are included in the appropriate places in this section. You can find the complete list of available Quick FSP Labs here: https://en-support.renesas.com/knowledgeBase/19308277.
  10. Scan the Debugging the Project section to see the steps required to download and start a debug session.
  11. Explore the additional material available on the following web pages and bookmark the resources that look most valuable to you:
    1. RA Landing Page: https://www.renesas.com/ra
    2. FSP Landing Page: https://www.renesas.com/fsp
    3. Example Projects on GitHub: https://github.com/renesas/ra-fsp-examples
    4. Quick FSP Labs Listing: https://en-support.renesas.com/knowledgeBase/19308277
    5. RA and FSP Knowledge Base (with articles of interest on RA and FSP): https://en-support.renesas.com/knowledgeBase/category/31087
    6. RA and FSP Renesas Rulz site (Community posted and answered questions): https://renesasrulz.com/ra/
    7. FSP Releases: https://github.com/renesas/fsp/releases
    8. FSP Documentation: https://renesas.github.io/fsp
    9. Online Technical Support: https://www.renesas.com/us/en/support/contact.html

e2 studio User Guide

What is e2 studio?

Renesas e2 studio is a development tool encompassing code development, build, and debug. e2 studio is based on the open-source Eclipse IDE and the associated C/C++ Development Tooling (CDT).

When developing for RA MCUs, e2 studio hosts the Renesas Flexible Software Package (FSP). FSP provides a wide range of time saving tools to simplify the selection, configuration, and management of modules and threads, to easily implement complex applications. The time saving tools available in e2 studio and FSP include the following:

  • A Graphical User Interface (GUI) (see Adding Threads and Drivers) with numerous wizards for configuring and auto-generating code
  • A context sensitive Autocomplete (see Tutorial: Using HAL Drivers - Programming the WDT) feature that provides intelligent options for completing a programming element
  • A Developer Assistance tool for selection of and drag and drop placement of API functions directly in application code
  • A Welcome Window with links to example projects, application notes and a variety of other self-help support resources
  • An Information Icon from each module is provided in the graphic configuration viewer that links to specific design resources, including code 'cheat sheets' that provide useful starting points for common application implementations.
sd-splash.png
e2 studio Splash Screen

e2 studio organizes project work based on Perspectives, Views, Windows, Panes, and Pages (sometimes called Tabs). A window is a section of the e2 studio GUI that presents information on a key topic. Windows often use tabs to select sub-topics. For example, an editor window might have a tab available for each open file, so it is easy to switch back and forth between them. A window Pane is a section of a window. Within a window, multiple Panes can be opened and viewed simultaneously, as opposed to a tabbed window, where only individual content is displayed. A memory-display Window, for example, might have multiple Panes that allow the data to be displayed in different formats, simultaneously. A Perspective is a collection of Views and Windows typical for a specific stage of development. The default perspectives are a C/C++ Perspective, an FSP Configuration Perspective and a Debug Perspective. These provide specific Views, Windows, Tabs, and Panes tailored for the common tasks needed during the specific development stage.

sd-default-perspective.png
Default Perspective

In addition to managing project development, selecting modules, configuring them and simplifying code development, e2 studio also hosts the engine for automatically generating code based on module selections and configurations. The engine continually checks for dependencies and automatically adds any needed lower level modules to the module stack. It also identifies any lower level modules that require configuration (for example, an interrupt that needs to have a priority assigned). It also provides a guide for selecting between multiple choices or options to make it easy to complete a fully functional module stack.

The Generate Project Content function takes the selected and configured modules and automatically generates the complete and correct configuration code. The code is added to the folders visible in the Project Explorer window in e2 studio. The configuration.xml file in the project folder holds all the generated configuration settings. This file can be opened in the GUI-based RA Configuration editor to make further edits and changes. Once a project has been generated, you can go back and reconfigure any of the modules and settings if required using this editor.

sd-e2studio-proj-config.jpg
Project Explorer Window showing generated folders and configuration.xml file

e2 studio Prerequisites

Obtaining an RA MCU Kit

To develop applications with FSP, start with one of the Renesas RA MCU Evaluation Kits. The Renesas RA MCU Evaluation Kits are designed to seamlessly integrate with the e2 studio.

Ordering information, Quick Start Guides, User Manuals, and other related documents for all RA MCU Evaluation Kits are available at https://www.renesas.com/ra.

PC Requirements

The following are the minimum PC requirements to use e2 studio:

  • Windows 10 with Intel i5 or i7, or AMD A10-7850K or FX
  • Memory: 8-GB DDR3 or DDR4 DRAM (16-GB DDR4/2400-MHz RAM is preferred)
  • Minimum 250-GB hard disk

Installing e2 studio, platform installer and the FSP package

Detailed installation instructions for the e2 studio and the FSP are available on the Renesas website https://www.renesas.com/fsp. Review the release notes for e2 studio to ensure that the e2 studio version supports the selected FSP version. The starting version of the installer includes all features of the RA MCUs.

Choosing a Toolchain

e2 studio can work with several toolchains and toolchain versions such as the GNU Arm compiler and Arm AC6. A version of the GNU Arm compiler is included in the e2 studio installer and has been verified to run with the FSP version.

Licensing

FSP licensing includes full source code, limited to Renesas hardware only.

What is a Project?

In e2 studio, all FSP applications are organized in RA MCU projects. Setting up an RA MCU project involves:

  1. Creating a Project
  2. Configuring a Project

These steps are described in detail in the next two sections. When you have existing projects already, after you launch e2 studio and select a workspace, all projects previously saved in the selected workspace are loaded and displayed in the Project Explorer window. Each project has an associated configuration file named configuration.xml, which is located in the project's root directory.

sd-e2studio-proj-config.jpg
e2 studio Project Configuration file

Double-click on the configuration.xml file to open the RA MCU Project Editor. To edit the project configuration, make sure that the FSP Configuration perspective is selected in the upper right hand corner of the e2 studio window. Once selected, you can use the editor to view or modify the configuration settings associated with this project.

sd-e2studio-ra-config.png
e2 studio FSP Configuration Perspective
Note
Whenever the RA project configuration (that is, the configuration.xml file) is saved, a verbose RA Project Report file (ra_cfg.txt) with all the project settings is generated. The format allows differences to be easily viewed using a text comparison tool. The generated file is located in the project root directory.
sd-ra-mcu-proj-rpt.jpg
RA Project Report

The RA Project Editor has a number of tabs. The configuration steps and options for individual tabs are discussed in the following sections.

Note
The tabs available in the RA Project Editor depend on the e2 studio version and the layout may vary slightly, however the functionality should be easy to follow..
sd-proj-ed-tabs.png
RA Project Editor tabs
  • Click on the YouTube icon to visit the Renesas FSP playlist on YouTube
  • Click on the Support icon to visit RA support pages at Renesas.com
  • Click on the user manual (owl) icon to open the RA software package User's Manual

Creating a Project

During project creation, you specify the type of project, give it a project name and location, and configure the project settings for version, target board, whether an RTOS is included, the toolchain version, and the beginning template. This section includes easy-to-follow step-by-step instructions for all of the project creation tasks. Once you have created the project, you can move to configuring the project hardware (clocks, pins, interrupts) and the parameters of all the modules that are part of your application.

Creating a New Project

For RA MCU applications, generate a new project using the following steps:

  1. Click on File > New > RA C/C++ Project.

    sd-new-ra-proj.png
    New RA MCU Project

    Then click on the type of template for the type of project you are creating.

    sd-new-proj-template.png
    New Project Templates
  2. Select a project name and location.

    sd-ra-proj-1.png
    RA MCU Project Generator (Screen 1)
  3. Click Next.

Selecting a Board and Toolchain

In the Project Configuration window select the hardware and software environment:

  1. Select the FSP version.
  2. Select the Board for your application. You can select an existing RA MCU Evaluation Kit or select Custom User Board for any of the RA MCU devices with your own BSP definition.
  3. Select the Device. The Device is automatically populated based on the Board selection. Only change the Device when using the Custom User Board (Any Device) board selection.
  4. To add threads, select RTOS, or No RTOS if an RTOS is not being used.
  5. The Toolchain selection defaults to GCC Arm Embedded.
  6. Select the Toolchain version. This should default to the installed toolchain version.
  7. Select the Debugger. The J-Link Arm Debugger is preselected.
  8. Click Next.

    sd-ra-proj-2.png
    RA MCU Project Generator (Screen 2)
    Note
    Click on the Help icon (?) for user guides, RA contents, and other documents.

Selecting Flat or Arm® TrustZone® Project

If you selected a device or tool based on an Arm® Cortex®-M33, you next select whether to use Arm® TrustZone® in your project. For normal, non-TrustZone projects, select "Flat".

sd-flat-non-trustzone.png
Flat, Secure, or Non-Secure Project

For more information on Arm® TrustZone®, see Primer: ARM® TrustZone® Project Development.

Selecting a Project Template

In the next window, select the buiild artifact and RTOS.

sd-ra-proj-2a.png
RA MCU Project Generator (Screen 3)

In the next window, select a project template from the list of available templates. By default, this screen shows the templates that are included in your current RA MCU pack. Once you have selected the appropriate template, click Finish.

Note
If you want to develop your own application, select the basic template for your board, Bare Metal - Minimal.
sd-ra-proj-3.png
RA MCU Project Generator (Screen 4)

When the project is created, e2 studio displays a summary of the current project configuration in the RA MCU Project Editor.

sd-proj-ed-tabs.png
RA MCU Project Editor and available editor tabs

On the bottom of the RA MCU Project Editor view, you can find the tabs for configuring multiple aspects of your project:

  • With the Summary tab, you can see all they key characteristics of the project: board, device, toolchain, and more.
  • With the BSP tab, you can change board specific parameters from the initial project selection.
  • With the Clocks tab, you can configure the MCU clock settings for your project.
  • With the Pins tab, you can configure the electrical characteristics and functions of each port pin.
  • With the Interrupts tab, you can add new user events/interrupts.
  • With the Event Links tab, you can configure events used by the Event Link Controller.
  • With the Stacks tab, you can add and configure FSP modules. For each module selected in this tab, the Properties window provides access to the configuration parameters, interrupt priorities, and pin selections.
  • The Components tab provides an overview of the selected modules. Although you can also add drivers for specific FSP releases and application sample code here, this tab is normally only used for reference.

The functions and use of each of these tabs is explained in detail in the next section.

Configuring a Project

Each of the configurable elements in an FSP project can be edited using the appropriate tab in the RA Configuration editor window. Importantly, the initial configuration of the MCU after reset and before any user code is executed is set by the configuration settings in the BSP, Clocks and Pins tabs. When you select a project template during project creation, e2 studio configures default values that are appropriate for the associated board. You can change those default values as needed. The following sections detail the process of configuring each of the project elements for each of the associated tabs.

Summary Tab

sd-e2-summary-tab.png
Configuration Summary tab

The Summary tab, seen in the above figure, identifies all the key elements and components of a project. It shows the target board, the device, toolchain and FSP version. Additionally, it provides a list of all the selected software components and modules used by the project. This is a more convenient summary view when compared to the Components tab.

The summary tab also includes handy icons with links to the Renesas YouTube channel, the Renesas support page and to the RA FSP User Manual that was downloaded during the installation process.

Configuring the BSP

The BSP tab shows the currently selected board (if any) and device. The Properties view is located in the lower left of the Project Configurations view as shown below.

Note
If the Properties view is not visible, click Window > Show View > Properties in the top menu bar.
sd-e2-bsp-tab.png
Configuration BSP tab

The Properties view shows the configurable options available for the BSP. These can be changed as required. The BSP is the FSP layer above the MCU hardware. e2 studio checks the entry fields to flag invalid entries. For example, only valid numeric values can be entered for the stack size.

When you click the Generate Project Content button, the BSP configuration contents are written to ra_cfg/fsp_cfg/bsp/bsp_cfg.h

This file is created if it does not already exist.

Warning
Do not edit this file as it is overwritten whenever the Generate Project Content button is clicked.

Configuring Clocks

The Clocks tab presents a graphical view of the MCU's clock tree, allowing the various clock dividers and sources to be modified. If a clock setting is invalid, the offending clock value is highlighted in red. It is still possible to generate code with this setting, but correct operation cannot be guaranteed. In the figure below, the USB clock UCLK has been changed so the resulting clock frequency is 60 MHz instead of the required 48 MHz. This parameter is colored red.

sd-clocks-tab.png
Configuration Clocks tab

When you click the Generate Project Content button, the clock configuration contents are written to: ra_gen/bsp_clock_cfg.h

This file will be created if it does not already exist.

Warning
Do not edit this file as it is overwritten whenever the Generate Project Content button is clicked.

Configuring Pins

The Pins tab provides flexible configuration of the MCU's pins. As many pins are able to provide multiple functions, they can be configured on a peripheral basis. For example, selecting a serial channel via the SCI peripheral offers multiple options for the location of the receive and transmit pins for that module and channel. Once a pin is configured, it is shown as green in the Package view.

Note
If the Package view window is not open in e2 studio, select Window > Show View > Pin Configurator > Package from the top menu bar to open it.

The Pins tab simplifies the configuration of large packages with highly multiplexed pins by highlighting errors and presenting the options for each pin or for each peripheral. If you selected a project template for a specific board such as the EK-RA6M3, some peripherals connected on the board are preselected.

sd-pins-tab.jpg
Pins Configuration

The pin configurator includes a built-in conflict checker, so if the same pin is allocated to another peripheral or I/O function the pin will be shown as red in the package view and also with white cross in a red square in the Pin Selection pane and Pin Configuration pane in the main Pins tab. The Pin Conflicts view provides a list of conflicts, so conflicts can be quickly identified and fixed.

In the example shown below, port P611 is already used by the CAC, and the attempt to connect this port to the Serial Communications Interface (SCI) results in a dangling connection error. To fix this error, select another port from the pin drop-down list or disable the CAC in the Pin Selection pane on the left side of the tab.

sd-e2-pin-config.png
e2 studio Pin configurator

The pin configurator also shows a package view and the selected electrical or functional characteristics of each pin.

sd-pin-config-pkg-view.png
e2 studio Pin configurator package view

When you click the Generate Project Content button, the pin configuration contents are written to: ra_gen\bsp_pin_cfg.h

This file will be created if it does not already exist.

Warning
Do not edit this file as it is overwritten whenever the Generate Project Content button is clicked.

To make it easy to share pinning information for your project, e2 studio exports your pin configuration settings to a csv format and copies the csv file to ra_gen/<MCU package>.csv.

Configuring Interrupts from the Stacks Tab

You can use the Properties view in the Stacks tab to enable interrupts by setting the interrupt priority. Select the driver in the Stacks pane to view and edit its properties.

sd-config-interrupts-on-stack.png
Configuring Interrupts in the Stacks tab

Creating Interrupts from the Interrupts Tab

On the Interrupts tab, the user can bypass a peripheral interrupt set by the FSP by setting a user-defined ISR. This can be done by adding a new event via the New User Event button.

sd-config-int-in-interrupt-tab.png
Configuring interrupt in Interrupt Tab
sd-adding-user-defined-event.png
Adding user-defined event

Enter the name of ISR for the new user event.

sd-new-user-event-isr.jpg
User-defined event ISR
sd-new-user-event.jpg
Using a user-defined event

Viewing Event Links

The Event Links tab can be used to view the Event Link Controller events. The events are sorted by peripheral to make it easy to find and verify them.

sd-viewing-event-links.PNG
Viewing Event Links

Like the Interrupts tab, user-defined event sources and destinations (producers and consumers) can be defined by clicking the relevant New User Event button. Once a consumer is linked to a producer the link will appear in the Allocations section at the bottom.

Note
When selecting an ELC event to receive for a module (or when manually defining an event link), only the events that are made available by the modules configured in the project will be shown.

Adding Threads and Drivers

Every RTOS-based RA Project includes at least one RTOS Thread and a stack of FSP modules running in that thread. The Stacks tab is a graphical user interface which helps you to add the right modules to a thread and configure the properties of both the threads and the modules associated with each thread. Once you have configured the thread, e2 studio automatically generates the code reflecting your configuration choices.

For any driver, or, more generally, any module that you add to a thread, e2 studio automatically resolves all dependencies with other modules and creates the appropriate stack. This stack is displayed in the Stacks pane, which e2 studio populates with the selected modules and module options for the selected thread.

The default view of the Stacks tab includes a Common Thread called HAL/Common. This thread includes the driver for I/O control (IOPORT). The default stack is shown in the HAL/Common Stacks pane. The default modules added to the HAL/Common driver are special in that the FSP only requires a single instance of each, which e2 studio then includes in every user-defined thread by default.

In applications that do not use an RTOS or run outside of the RTOS, the HAL/Common thread becomes the default location where you can add additional drivers to your application.

For a detailed description on how to add and configure modules and stacks, see the following sections:

Once you have added a module either to HAL/Common or to a new thread, you can access the driver's configuration options in the Properties view. If you added thread objects, you can access the objects configuration options in the Properties view in the same way.

You can find details about how to configure threads here: Configuring Threads

Note
Driver and module selections and configuration options are defined in the FSP pack and can therefore change when the FSP version changes.

Adding and Configuring HAL Drivers

For applications that run outside or without the RTOS, you can add additional HAL drivers to your application using the HAL/Common thread. To add drivers, follow these steps:

  1. Click on the HAL/Common icon in the Stacks pane. The Modules pane changes to HAL/Common Stacks.

    sd-proj-config-add-drivers.png
    e2 studio Project configurator - Adding drivers
  2. Click New Stack to see a drop-down list of HAL level drivers available in the FSP.
  3. Select a driver from the menu New Stack > Driver.

    sd-select-driver.png
    Select a driver
  4. Select the driver module in the HAL/Common Modules pane and configure the driver properties in the Properties view.

e2 studio adds the following files when you click the Generate Project Content button:

  • The selected driver module and its files to the ra/fsp directory
  • The main() function and configuration structures and header files for your application as shown in the table below.
File Contents Overwritten by Generate Project Content?
ra_gen/main.c Contains main() calling generated and user code. When called, the BSP already has Initialized the MCU. Yes
ra_gen/hal_data.c Configuration structures for HAL Driver only modules. Yes
ra_gen/hal_data.h Header file for HAL driver only modules. Yes
src/hal_entry.c User entry point for HAL Driver only code. Add your code here. No

The configuration header files for all included modules are created or overwritten in this folder: ra_cfg/fsp_cfg

Adding Drivers to a Thread and Configuring the Drivers

For an application that uses the RTOS, you can add one or more threads, and for each thread at least one module that runs in the thread. You can select modules from the Driver dropdown menu. To add modules to a thread, follow these steps:

  1. In the Threads pane, click New Thread to add a Thread.

    sd-add-new-rtos-thread.png
    Adding a new RTOS Thread on the Stacks tab
  2. In the Properties view, click on the Name and Symbol entries and enter a distinctive name and symbol for the new thread.

    Note
    e2 studio updates the name of the thread stacks pane to My Thread Stacks.
  3. In the My Thread Stacks pane, click on New Stack to see a list of modules and drivers. HAL-level drivers can be added here.

    sd-adding-modules-drivers-to-thread.png
    Adding Modules and Drivers to a thread
  4. Select a module or driver from the list.
  5. Click on the added driver and configure the driver as required by the application by updating the configuration parameters in the Properties view. To see the selected module or driver and be able to edit its properties, make sure the Thread containing the driver is highlighted in the Threads pane.

    sd-config-module-or-driver-props.png
    Configuring Module or Driver properties
  6. If needed, add another thread by clicking New Thread in the Threads pane.

When you press the Generate Project Content button for the example above, e2 studio creates the files as shown in the following table:

File Contents Overwritten by Generate Project Content?
ra_gen/main.c Contains main() calling generated and user code. When called the BSP will have initialized the MCU. Yes
ra_gen/my_thread.c Generated thread "my_thread" and configuration structures for modules added to this thread. Yes
ra_gen/my_thread.h Header file for thread "my_thread" Yes
ra_gen/hal_data.c Configuration structures for HAL Driver only modules. Yes
ra_gen/hal_data.h Header file for HAL Driver only modules. Yes
src/hal_entry.c User entry point for HAL Driver only code. Add your code here. No
src/my_thread_entry.c User entry point for thread "my_thread". Add your code here. No

The configuration header files for all included modules and drivers are created or overwritten in the following folders: ra_cfg/fsp_cfg/<header files>

Configuring Threads

If the application uses an RTOS, the Stacks tab can be used to simplify the creation of RTOS threads, semaphores, mutexes, and event flags.

The components of each thread can be configured from the Properties view as shown below.

sd-new-thread-properties.png
New Thread Properties

The Properties view contains settings common for all Threads (Common) and settings for this particular thread (Thread).

For this thread instance, the thread's name and properties (such as priority level or stack size) can be easily configured. e2 studio checks that the entries in the property field are valid. For example, it will verify that the field Priority, which requires an integer value, only contains numeric values between 0 and 9.

To add RTOS resources to a Thread, select a thread and click on New Object in the Thread Objects pane. The pane takes on the name of the selected thread, in this case My Thread Objects.

sd-configuring-thread-object-properties.png
Configuring Thread Object Properties

Make sure to give each thread object a unique name and symbol by updating the Name and Symbol entries in the Properties view.

Reviewing and Adding Components

The Components tab enables the individual modules required by the application to be included or excluded. Modules common to all RA MCU projects are preselected (for example: BSP > BSP > Board-specific BSP and HAL Drivers > all > r_cgc). All modules that are necessary for the modules selected in the Stacks tab are included automatically. You can include or exclude additional modules by ticking the box next to the required component.

sd-components-tab.png
Components Tab

Clicking the Generate Project Content button copies the .c and .h files for each selected component into the following folders:

  • ra/fsp/inc/api
  • ra/fsp/inc/instances
  • ra/fsp/src/bsp
  • ra/fsp/src/<Driver_Name>

e2 studio also creates configuration files in the ra_cfg/fsp_cfg folder with configuration options set in the Stacks tab.

Writing the Application

Once you have added Modules and drivers and set their configuration parameters in the Stacks tab, you can add the application code that calls the Modules and drivers.

Note
To check your configuration, build the project once without errors before adding any of your own application code.

Coding Features

e2 studio provides several efficiency improving features that help write code. Review these features prior to digging into the code development step-by-step sections that follow.

Autocomplete

Autocomplete is a context aware coding accelerator that suggests possible completions for partially typed-in code elements. If you can 'guess' the first part of a macro, for example, the Autocomplete function can suggest options for completing the rest of the macro.

In the following example, a macro related to a BSP_IO setting needs to be found. After typing BSP_IO_ in a source code file, pressing Ctrl + Space opens the Autocomplete list. This list shows a selection of context aware options for completing the macro. Scroll through the window to find the desired macro (in this case BSP_IO_LEVEL_HIGH) and click on it to add it to your code.

sd-autocomplete-example.png
Autocomplete example

Other code elements can use autocomplete too. Some of the more common uses for Autocomplete include Enumerations, Types, and API functions - but try it in any situation you think the tool may have enough context to determine what you might be looking for.

For a hands-on experience using Autocomplete use the Quick FSP Labs for Creating Blinky from Scratch and Creating an RTC Blinky from Scratch. These 15-minute Do it Yourself labs take you through the step-by-step process of using Autocomplete, Developer Assistance, and the Help system.

Welcome Window

The e2 studio Welcome window displays useful information and common links to assist in development. Check out these resources to see what is available. They are updated with each release, so check back to see what has been added after a new release.

sd-welcome-window.png
Welcome window

Cheat Sheets

Cheat sheets are macro driven illustrations of some common tasks. They show, step-by-step, what commands and menus are used. These will be populated with more examples on each release. Cheat Sheets are available from the Help menu.

sd-cheat-sheets.png
Cheat Sheets

Developer Assistance

FSP Developer Assistance provides developers with module and Application Programming Interface (API) reference documentation in e2 studio. After configuring the threads and software stacks for an FSP project with the RA Configuration editor, Developer Assistance quickly helps you get started writing C/C++ application code for the project using the configured stack modules.

  1. Expand the project explorer to view Developer Assistance

    sd-dev-assist.png
    Developer Assistance
  2. Expand a stack module to show its APIs

    sd-dev-assist-apis.png
    Developer Assistance APIs
  3. Dragging and dropping an API from Develop Assistance to a source file helps to write source code quickly.
sd-dev-assist-drag-drop.png
Dragging and Dropping an API in Developer Assistance

For a hands-on experience using Developer Assistance use the Quick FSP Labs for An Introduction to Developer Assistance, Creating Blinky from Scratch and Creating an RTC Blinky from Scratch. These 15-minute Do it Yourself labs take you through the step-by-step process of using Autocomplete, Developer Assistance, and the Help system.

Information Icon

Information icons are available on each module in the thread stack. Clicking on these icons opens a module folder on GitHub that contains additional information on the module. An example information Icon is shown below:

sd-info-icon.png
Information icon

IDE Help

A good source of additional information for many FSP topics is the Help system. To get to the Help system, click on Help and then select Help Contents as seen below.

sd-opening-help-system.png
Opening the Help System

Once the Help system is open, select the RA Contents entry in the left side Guide-bar. Expand it to see the main RA Topics.

sd-ra-content-help.png
RA Content Help

You can also search for help topics by using the Search bar. Below is an example searching for Visual Expressions, a helpful feature in the e2 studio debugger.

sd-e2-studio-help-from-search-bar.png
e2 studio Help from the Search Bar

For a hands-on experience using the Help system use the Quick FSP Labs for An Introduction to Developer Assistance, Creating Blinky from Scratch and Creating an RTC Blinky from Scratch. These 15-minute Do it Yourself labs take you through the step-by-step process of using Autocomplete, Developer Assistance, and the Help system.

HAL Modules in FSP: A Practical Description

The FSP Architecture section describes FSP stacks, modules and interfaces in significant detail, providing an understanding of the theory behind them. The following sections provides a quick and practical introduction on how to use API functions when writing code and where in the API reference sections you can find useful API related information.

Introduction to HAL Modules

In FSP, HAL module drivers provide convenient API functions that access RA processor peripheral features. Module properties are defined in the RA GUI configurator, eliminating the tedious and error prone process of setting peripheral control registers. When configuration is complete, the generator automatically creates the code needed to implement the associated API functions. API functions are the main way a developer interacts with the target processor and peripherals.

HAL Driver API Function Call Formats

HAL driver API functions all have a similar format. They all start with "R_" to indicate they are HAL related functions. Next comes the module name followed by the function and any parameters. This format is illustrated below:

R_<module>_<function>(<parameters>);

Here are some examples:

status = R_GPT_Open(&g_timer0_ctrl, &g_timer0_cfg);
status = R_GPT_Start(&g_timer0_ctrl);
status = R_GPT_PeriodSet(&g_timer0_ctrl, period);
status = R_ADC_Open(&g_adc0_ctrl, &g_adc0_cfg);
status = R_ADC_InfoGet(&g_adc0_ctrl, &adc_info);

HAL Driver API Call Reference Information

Each HAL module has a useful API Reference section that includes key details on each function. The function prototype is presented first, showing the return type (usually fsp_status_t for HAL functions) and the function parameters. A short description and any warnings or notes follow the function definition. In some cases, a code snippet is included to illustrate use of the function. Finally, all possible return values are provided to assist in debugging and error management.

sd-module-api-ref-example.png
Module Api Reference Section Example

RTOS-Independent Applications

To write application code:

  1. Add all drivers and modules in the Stacks tab and resolve all dependencies flagged by e2 studio such as missing interrupts or drivers.
  2. Configure the drivers in the Properties view.
  3. In the Project Configuration view, click the Generate Project Content button.
  4. In the Project Explorer view, double-click on the src/hal_entry.c file to edit the source file.

    sd-hal-entry-c.png
    Note
    All configuration structures necessary for the driver to be called in the application are initialized in ra_gen/hal_data.c.
    Warning
    Do not modify the files in the directory ra_gen. These files are overwritten every time you push the Generate Project Content button.
  5. Add your application code here:

    sd-add-user-code.png
    Adding user code to hal_entry.c
  6. Build the project without errors by clicking on Project > Build Project.

The following tutorial shows how execute the steps above and add application code: Tutorial: Using HAL Drivers - Programming the WDT.

The WDT example is a HAL level application which does not use an RTOS. The user guides for each module also include basic application code that you can add to hal_entry.c.

RTOS Applications

To write RTOS-aware application code using RTOS, follow these steps:

  1. Add a thread using the Stacks tab.
  2. Provide a unique name for the thread in the Properties view for this thread.
  3. Configure all drivers and resources for this thread and resolve all dependencies flagged by e2 studio such as missing interrupts or drivers.
  4. Configure the thread objects.
  5. Provide unique names for each thread object in the Properties view for each object.
  6. Add more threads if needed and repeat steps 1 to 5.
  7. In the RA Project Editor, click the Generate Project Content button.
  8. In the Project Explorer view, double-click on the src/my_thread_1_entry.c file to edit the source file.

    sd-gen-files-for-rtos.png
    Generated files for an RTOS application
    Note
    All configuration structures necessary for the driver to be called in the application are initialized in ra_gen/my_thread_1.c and my_thread_2.c
    Warning
    Do not modify the files in the directory ra_gen. These files are overwritten every time you push the Generate Project Content button.
  9. Add your application code here:

    sd-add-user-code-my-thread.png
    Adding user code to my_thread_1.entry
  10. Repeat steps 1 to 9 for the next thread.
  11. Build your project without errors by clicking on Project > Build Project.

Additional Resources for Application Development

Example Projects

A wide variety of Example Projects for FSP and RA MCUs is available on the GitHub site here: https://github.com/renesas/ra-fsp-examples. Example projects are organized by target kit so it is easy to find all the examples for your kit of choice.

sd-fsp-ex-proj-org-by-kit.png
FSP Example Projects Organized by Kit

Projects are available as both downloadable zip files and as project source files. Typically, there is a project for each module. New example projects are being added periodically, so check back if a particular module isn't yet available.

sd-selection-of-ex-proj-avail-on-github.png
A Selection of Example Projects Available on GitHub

Quick Labs

A variety of Hands-on Do It Yourself labs are available on the Renesas RA and FSP Knowledge Base. Quick FSP Labs target the EK-RA6M3 kit and typically require only 15 minutes to complete. Each lab covers a couple related development tools and techniques like Autocomplete, Developer Assistance, console I/O over RTT, and Visual Expressions, that can speed up the development process. A list of all available Quick Labs can be found here: https://en-support.renesas.com/knowledgeBase/19450948

Debugging the Project

Once your project builds without errors, you can use the Debugger to download your application to the board and execute it.

To debug an application follow these steps:

  1. On the drop-down list next to the debug icon, select Debug Configurations.

    sd-debug-config.png
  2. In the Debug Configurations view, click on your project listed as MyProject Debug.

    sd-my-proj-debug.png
  3. Connect the board to your PC via either a standalone Segger J-Link debugger, a Segger J-Link On-Board (included on all RA EKs), or an E2 or E2 Lite and click Debug.
Note
For details on using J-Link and connecting the board to the PC, see the Quick Start Guide included in the RA MCU Kit.

Modifying Toolchain Settings

There are instances where it may be necessary to make changes to the toolchain being used (for example, to change optimization level of the compiler or add a library to the linker). Such modifications can be made from within e2 studio through the menu Project > Properties > Settings when the project is selected. The following screenshot shows the settings dialog for the GNU Arm toolchain. This dialog will look slightly different depending upon the toolchain being used.

sd-e2-proj-toolchain.png
e2 studio Project toolchain settings

The scope for the settings is project scope which means that the settings are valid only for the project being modified.

The settings for the linker which control the location of the various memory sections are contained in a script file specific for the device being used. This script file is included in the project when it is created and is found in the script folder (for example, /script/a6m3.ld).

Creating RA project with ARM Compiler 6 in e2 studio

e2 studio does not include the ARM Compiler 6 (AC6) toolchain by default. Follow the steps below to integrate AC6 into e2 studio and create an AC6 RA project.

Note
It is assumed that the user is already familiar with RA project creation in e2 studio. e2 studio does not include ARM Compiler 6 (AC6) toolchain by default.

Steps 1 through 8 describe the process for integrating ARM Compiler 6 into e2 studio.

  1. Download, install, and configure license for the AC6 toolchain (https://developer.arm.com/tools-and-software/embedded/arm-compiler/downloads/version-6).
  2. Launch e2 studio.
  3. Go to Window > Preferences > Toolchains.
  4. Click Add.

    sd-ac6-add.png
    Add Toolchain
  5. Browse to the path where AC6 toolchain is installed and select the \bin folder. Click Next.

    sd-ac6-select-path.png
    Browse to AC6 Compiler
  6. Toolchain information in displayed. Click Finish.

    sd-ac6-toolchain-info.png
    Toolchain Information
  7. Click Apply and Close.

    sd-ac6-apply-close.png
    Apply and Close
  8. Click Restart Eclipse when prompted.

    sd-ac6-restart.png
    Restart Eclipse
  9. When creating a new RA C/C++ project, select ARM Compiler 6 included in the Toolchains section.

    sd-ac6-select-arm-compiler.png
    Select Arm Compiler

Importing an Existing Project into e2 studio

  1. Start by opening e2 studio.
  2. Open an existing Workspace to import the project and skip to step d. If the workspace doesn't exist, proceed with the following steps:
    1. At the end of e2 studio startup, you will see the Workspace Launcher Dialog box as shown in the following figure.

      sd-workspace-launcher-dialog.png
      Workspace Launcher dialog
    2. Enter a new workspace name in the Workspace Launcher Dialog as shown in the following figure. e2 studio creates a new workspace with this name.

      sd-workspace-launcher-select-workspace.png
      Workspace Launcher dialog - Select Workspace
    3. Click Launch.
    4. When the workspace is opened, you may see the Welcome Window. Click on the Workbench arrow button to proceed past the Welcome Screen as seen in the following figure.

      sd-workbench-arrow-button.png
      Workbench arrow button
  3. You are now in the workspace that you want to import the project into. Click the File menu in the menu bar, as shown in the following figure.

    sd-menu-and-tool-bar.png
    Menu and tool bar
  4. Click Import on the File menu or in the menu bar, as shown in the following figure.

    sd-file-menu.png
    File drop-down menu
  5. In the Import dialog box, as shown in the following figure, choose the General option, then Existing Projects into Workspace, to import the project into the current workspace.

    sd-project-import-with-existing-project.png
    Project Import dialog with "Existing Projects into Workspace" option selected
  6. Click Next.
  7. To import the project, use either Select archive file or Select root directory.
    1. Click Select archive file as shown in the following figure.

      sd-import-existing-project-dialog-1.png
      Import Existing Project dialog 1 - Select archive file
    2. Click Select root directory as shown in the following figure.

      sd-import-existing-project-dialog-1b.png
      Import Existing Project dialog 1 - Select root directory
  8. Click Browse.
  9. For Select archive file, browse to the folder where the zip file for the project you want to import is located. For Select root directory, browse to the project folder that you want to import.
  10. Select the file for import. In our example, it is CAN_HAL_MG_AP.zip or CAN_HAL_MG_AP.
  11. Click Open.
  12. Select the project to import from the list of Projects, as shown in the following figure.

    sd-import-existing-project-dialog-2.png
    Import Existing Project dialog 2
  13. Click Finish to import the project.

Tutorial: Your First RA MCU Project - Blinky

Tutorial Blinky

The goal of this tutorial is to quickly get acquainted with the Flexible Platform by moving through the steps of creating a simple application using e2 studio and running that application on an RA MCU board.

What Does Blinky Do?

The application used in this tutorial is Blinky, traditionally the first program run in a new embedded development environment.

Blinky is the "Hello World" of microcontrollers. If the LED blinks you know that:

  • The toolchain is setup correctly and builds a working executable image for your chip.
  • The debugger has installed with working drivers and is properly connected to the board.
  • The board is powered up and its jumper and switch settings are probably correct.
  • The microcontroller is alive, the clocks are running, and the memory is initialized.

The Blinky example application used in this tutorial is designed to run the same way on all boards offered by Renesas that hold the RA microcontroller. The code in Blinky is completely board independent. It does the work by calling into the BSP (board support package) for the particular board it is running on. This works because:

  • Every board has at least one LED connected to a GPIO pin.
  • That one LED is always labelled LED1 on the silk screen.
  • Every BSP supports an API that returns a list of LEDs on a board, and their port and pin assignments.

Prerequisites

To follow this tutorial, you need:

  • Windows based PC
  • e2 studio
  • Flexible Software Package
  • An RA MCU board kit

Create a New Project for Blinky

The creation and configuration of an RA MCU project is the first step in the creation of an application. The base RA MCU pack includes a pre-written Blinky example application that is simple and works on all Renesas RA MCU boards.

Follow these steps to create an RA MCU project:

  1. In e2 studio, click File > New > C/C++ Project and select Renesas RA and Renesas RA C/C++ Project.
  2. Assign a name to this new project. Blinky is a good name to use for this tutorial.
  3. Click Next. The Project Configuration window shows your selection.

    sd-proj-config-1-blinky.png
    e2 studio Project Configuration window (part 1)
  4. Select the board support package by selecting the name of your board from the Device Selection drop-down list and click Next.

    sd-proj-config-2.png
    e2 studio Project Configuration window (part 2)
  5. Select the build artifact and RTOS.

    sd-proj-config-2a.png
    e2 studio Project Configuration window (part 3)
  6. Select the Blinky template for your board and click Finish.

    sd-proj-config-3.png
    e2 studio Project Configuration window (part 4)

    Once the project has been created, the name of the project will show up in the Project Explorer window of e2 studio. Now click the Generate Project Content button in the top right corner of the Project Configuration window to generate your board specific files.

    sd-proj-config-tab.png
    e2 studio Project Configuration tab

    Your new project is now created, configured, and ready to build.

Details about the Blinky Configuration

The Generate Project Content button creates configuration header files, copies source files from templates, and generally configures the project based on the state of the Project Configuration screen.

For example, if you check a box next to a module in the Components tab and click the Generate Project Content button, all the files necessary for the inclusion of that module into the project will be copied or created. If that same check box is then unchecked those files will be deleted.

Configuring the Blinky Clocks

By selecting the Blinky template, the clocks are configured by e2 studio for the Blinky application. The clock configuration tab (see Configuring Clocks) shows the Blinky clock configuration. The Blinky clock configuration is stored in the BSP clock configuration file (see BSP Clock Configuration).

Configuring the Blinky Pins

By selecting the Blinky template, the GPIO pins used to toggle the LED1 are configured by e2 studio for the Blinky application. The pin configuration tab shows the pin configuration for the Blinky application (see Configuring Pins). The Blinky pin configuration is stored in the BSP configuration file (see BSP Pin Configuration).

Configuring the Parameters for Blinky Components

The Blinky project automatically selects the following HAL components in the Components tab:

  • r_ioport

To see the configuration parameters for any of the components, check the Properties tab in the HAL window for the respective driver (see Adding and Configuring HAL Drivers).

Where is main()?

The main function is located in < project >/ra_gen/main.c. It is one of the files that are generated during the project creation stage and only contains a call to hal_entry(). For more information on generated files, see Adding and Configuring HAL Drivers.

Blinky Example Code

The blinky application is stored in the hal_entry.c file. This file is generated by e2 studio when you select the Blinky Project template and is located in the project's src/ folder.

The application performs the following steps:

  1. Get the LED information for the selected board by bsp_leds_t structure.
  2. Define the output level HIGH for the GPIO pins controlling the LEDs for the selected board.
  3. Get the selected system clock speed and scale down the clock, so the LED toggling can be observed.
  4. Toggle the LED by writing to the GPIO pin with R_BSP_PinWrite((bsp_io_port_pin_t) pin, pin_level);

Build the Blinky Project

Highlight the new project in the Project Explorer window by clicking on it and build it.

There are three ways to build a project:

  1. Click on Project in the menu bar and select Build Project.
  2. Click on the hammer icon.
  3. Right-click on the project and select Build Project.
sd-proj-explorer.jpg
e2 studio Project Explorer window

Once the build is complete a message is displayed in the build Console window that displays the final image file name and section sizes in that image.

sd-proj-build-console.png
e2 studio Project Build console

Debug the Blinky Project

Debug prerequisites

To debug the project on a board, you need

  • The board to be connected to e2 studio
  • The debugger to be configured to talk to the board
  • The application to be programmed to the microcontroller

Applications run from the internal flash of your microcontroller. To run or debug the application, the application must first be programmed to the microcontroller's flash. There are two ways to do this:

  • JTAG debugger
  • Built-in boot-loader via UART or USB

Some boards have an on-board JTAG debugger and others require an external JTAG debugger connected to a header on the board.

Refer to your board's user manual to learn how to connect the JTAG debugger to e2 studio.

Debug steps

To debug the Blinky application, follow these steps:

  1. Configure the debugger for your project by clicking Run > Debugger Configurations ...

    sd-debug-icon.png
    e2 studio Debug icon

    or by selecting the drop-down menu next to the bug icon and selecting Debugger Configurations ...

    sd-debug-config-window.jpg
    e2 studio Debugger Configurations selection option
  2. Select your debugger configuration in the window. If it is not visible then it must be created by clicking the New icon in the top left corner of the window. Once selected, the Debug Configuration window displays the Debug configuration for your Blinky project.

    sd-debug-config-with-blinky.jpg
    e2 studio Debugger Configurations window with Blinky project
  3. Click Debug to begin debugging the application.
  4. Extracting RA Debug.

    sd-extracting-ra-debug.png

Details about the Debug Process

In debug mode, e2 studio executes the following tasks:

  1. Downloading the application image to the microcontroller and programming the image to the internal flash memory.
  2. Setting a breakpoint at main().
  3. Setting the stack pointer register to the stack.
  4. Loading the program counter register with the address of the reset vector.
  5. Displaying the startup code where the program counter points to.
sd-debug-mem-window.png
e2 studio Debugger memory window

Run the Blinky Project

While in Debug mode, click Run > Resume or click on the Play icon twice.

sd-debug-play-icon.jpg
e2 studio Debugger Play icon

The LEDs on the board marked LED1, LED2, and LED3 should now be blinking.

Tutorial: Using HAL Drivers - Programming the WDT

Application WDT

This tutorial illustrates the creation of a simple application that uses the Watchdog Timer module to monitor program operation. The tutorial shows each step in the development process and in particular identifies the auto-generated files and project structure created when using FSP and its GUI based configurator. The level of detail provided here is more than is normally needed during development but can be helpful in explaining how FSP works behind the scenes to simplify your work.

This application makes use of the following FSP modules:

Creating a WDT Application Using the RA MCU FSP and e2 studio

Using the FSP and e2 studio

The Flexible Software Package (FSP) from Renesas provides a complete driver library for developing RA MCU applications. The FSP provides Hardware Abstraction Layer (HAL) drivers, Board Support Package (BSP) drivers for the developer to use to create applications. The FSP is integrated into Renesas e2 studio based on eclipse providing build (editor, compiler and linker) and debug phases with an extended GNU Debug (GDB) interface.

The WDT Application

The flowchart for the WDT application is shown below.

sd-wdt-app-flow.png
WDT Application flow diagram

WDT Application flow

The main sections of the WDT application are:

  1. The BSP initializes the clocks, pins and other elements of the MCU readying the application to run.
  2. main() calls hal_entry(). The function hal_entry() is created by the FSP with a placeholder for user code. The code for the WDT is added to this function.
  3. Initialize the WDT, but do not start it.
  4. Start the WDT by refreshing it.
  5. In the first loop the red LED flashes 30 times and refreshes the watchdog each time the LED state is changed.
  6. In the second loop, the green LED flashes, but the program DOES NOT refresh the watchdog. After the watchdog timeout period the device will reset which can be observed by the red LED flashing again as the sequence repeats.

Creating the Project with e2 studio

Start e2 studio and choose a workspace folder in the Workspace Launcher. Configure a new RA MCU project as follows.

  1. Select File > New > RA C/C++ Project. Then select the template for the project.

    sd-create-new-proj1.png
    sd-create-new-proj2.jpg
    Creating a new project
  2. In the e2 studio Project Configuration (RA Project) window enter a project name, for example, WDT_Application. In addition, select the toolchain. If you want to choose new locations for the project unselect Use default location. Click Next.

    sd-proj-config-1.png
    Project configuration (part 1)
  3. This application runs on the EK-RA6M3 board. So, for the Board select EK-RA6M3.

    This will automatically populate the Device drop-down with the correct device used on this board. Select the Toolchain version. Select J-Link ARM as the Debugger. Click Next to configure the project.

    sd-proj-config-2.png
    Project configuration (part 2)

    The project template is now selected. As no RTOS is required select Bare Metal - Blinky.

    sd-proj-config-3.png
    Project configuration (part 3)
  4. Click Finish.

    e2 studio creates the project and opens the Project Explorer and Project Configuration Settings views with the Summary page showing a summary of the project configuration.

Configuring the Project with e2 studio

e2 studio simplifies and accelerates the project configuration process by providing a GUI interface for selecting the options to configure the project.

e2 studio offers a selection of perspectives presenting different windows to the user depending on the operation in progress. The default perspectives are C/C++, FSP Configuration and Debug. The perspective can be changed by selecting a new one from the buttons at the top right.

sd-select-param.jpg
Selecting a perspective

The C/C++ perspective provides a layout selected for code editing. The FSP Configuration perspective provides elements for configuring a RA MCU project, and the Debug perspective provides a view suited for debugging.

  1. In order to configure the project settings ensure the FSP Configuration perspective is selected.
  2. Ensure the Project Configuration [WDT Application] is open. It is already open if the Summary information is visible. To open the Project Configuration now or at any time make sure the RA Configuration perspective is selected and double-click on the configuration.xml file in the Project Explorer pane on the right side of e2 studio.
sd-ra-proj-config.jpg
RA MCU Project Configuration Settings

At the base of the Project Configuration view there are several tabs for configuring the project. A project may require changes to some or all of these tabs. The tabs are shown below.

sd-proj-config-tabs.png
Project Configuration Tabs

BSP Tab

The BSP tab allows the Board Support Package (BSP) options to be modified from their defaults. For this particular WDT project no changes are required. However, if you want to use the WDT in auto-start mode, you can configure the settings of the OFS0 (Option Function Select Register 0) register in the BSP tab. See the RA Hardware User's Manual for details on the WDT autostart mode.

Clocks Tab

The Clocks tab presents a graphical view of the clock tree of the device. The drop-down boxes in the GUI enables configuration of the various clocks. The WDT uses PCLCKB. The default output frequency for this clock is 60 MHz. Ensure this clock is outputting this value.

sd-clock-config.png
Clock configuration

Interrupts Tab

The Interrupts tab is used to add new user events or interrupts. No new interrupts or events are needed by the application, so no edits in this tab are required.

Event Links Tab

The Event Links tab is used to configure events used by the Event Link Controller (ELC). This project doesn't use the ELC, so no edits in this tab are required.

Pins Tab

The Pins tab provides a graphical tool for configuring the functionality of the pins of the device. For the WDT project no pin configuration is required. Although the project uses two LEDs connected to pins on the device, these pins are pre-configured as output GPIO pins by the BSP.

Stacks Tab

You can add any driver to the project using the Stacks tab. The HAL driver IO port pins are added automatically by e2 studio when the project is configured. The WDT application uses no RTOS Resources, so you only need to add the HAL WDT driver.

sd-stacks-tab.jpg
Stacks tab
  1. Click on the HAL/Common Panel in the Threads Window as indicated in the figure above.

    The Stacks Panel becomes a HAL/Common Stacks panel and is populated with the modules preselected by e2 studio.

  2. Click on New Stack to find a pop-up window with the available HAL level drivers.
  3. Select WATCHDOG Driver on r_wdt.
sd-module-select.png
Module Selection

The selected HAL WDT driver is added to the HAL/Common Stacks Panel and the Property Window shows all configuration options for the selected module. The Property tab for the WDT should be visible at the bottom left of the screen. If it is not visible, check that the FSP Configuration perspective is selected.

sd-module-properties.png
Module Properties

All parameters can be left with their default values.

sd-g-wdt-on-wdt-prop.jpg
g_wdt WATCHDOG Driver on WDT properties

With PCLKB running at 60 MHz the WDT will reset the device 2.23 seconds after the last refresh.

WDT clock = 60 MHz / 8192 = 7.32 kHz

Cycle time = 1 / 7.324 kHz = 136.53 us

Timeout = 136.53 us x 16384 = 2.23 seconds

Save the Project Configuration file and click the Generate Project Content button in the top right corner of the Project Configuration pane.

gen-proj-content.png
Generate Project Content button

e2 studio generates the project files.

Components Tab

The components tab is included for reference to see which modules are included in the project. Modules are selected automatically in the Components view after they are added in the Stacks Tab.

For the WDT project ensure that the following modules are selected:

  1. HAL_Drivers -> r_ioport
  2. HAL_Drivers -> r_wdt
sd-component-select.png
Component Selection
Note
The list of modules displayed in the Components tab depends on the installed FSP version.

WDT Generated Project Files

Clicking the Generate Project Content button performs the following tasks.

  • r_wdt folder and WDT driver contents created at:

    ra/fsp/src

  • r_wdt_api.h created in:

    ra/fsp/inc/api

  • r_wdt.h created in:

    ra/fsp/inc/instances

The above files are the standard files for the WDT HAL module. They contain no specific project contents. They are the driver files for the WDT. Further information on the contents of these files can be found in the documentation for the WDT HAL module.

Configuration information for the WDT HAL module in the WDT project is found in:

ra_cfg/fsp_cfg/r_wdt_cfg.h

The above file's contents are based upon the Common settings in the g_wdt WATCHDOG Driver on WDT Properties pane.

sd-r_wdt_cfg.h-contents.png
r_wdt_cfg.h contents
Warning
Do not edit any of these files as they are recreated every time the Generate Project Content button is clicked and so any changes will be overwritten.

The r_ioport folder is not created at ra/fsp/src as this module is required by the BSP and so already exists. It is included in the WDT project in order to include the correct header file in ra_gen/hal_data.c–see later in this document for further details. For the same reason the other IOPORT header files– ra/fsp/inc/api/r_ioport_api.handra/fsp/inc/instances/r_ioport.h–are not created as they already exist.

In addition to generating the HAL driver files for the WDT and IOPORT files e2 studio also generates files containing configuration data for the WDT and a file where user code can safely be added. These files are shown below.

sd-wdt-proj-files.png
WDT project files

WDT hal_data.h

The contents of hal_data.h are shown below.

/* generated HAL header file - do not edit */
#ifndef HAL_DATA_H_
#define HAL_DATA_H_
#include <stdint.h>
#include "bsp_api.h"
#include "common_data.h"
#include "r_wdt.h"
#include "r_wdt_api.h"
#ifdef __cplusplus
extern "C"
{
#endif
extern const wdt_instance_t g_wdt0;
#ifndef NULL
void NULL(wdt_callback_args_t * p_args);
#endif
extern wdt_instance_ctrl_t g_wdt0_ctrl;
extern const wdt_cfg_t g_wdt0_cfg;
void hal_entry(void);
void g_hal_init(void);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* HAL_DATA_H_ */

hal_data.h contains the header files required by the generated project. In addition this file includes external references to the g_wdt0 instance structure which contains pointers to the configuration, control, api structures used for WDT HAL driver.

Warning
This file is regenerated each time Generate Project Content is clicked and must not be edited.

WDT hal_data.c

The contents of hal_data.c are shown below.

/* generated HAL source file - do not edit */
#include "hal_data.h"
wdt_instance_ctrl_t g_wdt0_ctrl;
const wdt_cfg_t g_wdt0_cfg =
{
.clock_division = WDT_CLOCK_DIVISION_8192,
.window_start = WDT_WINDOW_START_100,
.window_end = WDT_WINDOW_END_0,
.reset_control = WDT_RESET_CONTROL_RESET,
.stop_control = WDT_STOP_CONTROL_ENABLE,
.p_callback = NULL,
};
/* Instance structure to use this module. */
const wdt_instance_t g_wdt0 =
{.p_ctrl = &g_wdt0_ctrl, .p_cfg = &g_wdt0_cfg, .p_api = &g_wdt_on_wdt};
void g_hal_init (void)
{
g_common_init();
}

hal_data.c contains g_wdt0_ctrl which is the control structure for this instance of the WDT HAL driver. This structure should not be initialized as this is done by the driver when it is opened.

The contents of g_wdt0_cfg are populated in this file using the Watchdog Driver on g_wdt0 pane in the Project Configuration Stacks tab. If the contents of this structure do not reflect the settings made in the IDE, ensure the Project Configuration settings are saved before clicking the Generate Project Content button.

Warning
This file is regenerated each time Generate Project Content is clicked and so should not be edited.

WDT main.c

Contains main() called by the BSP start-up code. main() calls hal_entry() which contains user developed code (see next file). Here are the contents of main.c.

/* generated main source file - do not edit*/
#include "hal_data.h"
int main (void)
{
hal_entry();
return 0;
}
Warning
This file is regenerated each time Generate Project Content is clicked and so should not be edited.

WDT hal_entry.c

This file contains the function hal_entry() called from main(). User developed code should be placed in this file and function.

For the WDT project edit the contents of this file to contain the code below. This code implements the flowchart in overview section of this document.

#include "hal_data.h"
#include "bsp_pin_cfg.h"
#include "r_ioport.h"
#define RED_LED_NO_OF_FLASHES 30
#define RED_LED_PIN BSP_IO_PORT_01_PIN_00
#define GREEN_LED_PIN BSP_IO_PORT_04_PIN_00
#define RED_LED_DELAY_MS 125
#define GREEN_LED_DELAY_MS 250
volatile uint32_t delay_counter;
volatile uint16_t loop_counter;
/*******************************************************************************************************************/
void hal_entry (void)
{
/* Allow the WDT to run when the debugger is connected */
R_DEBUG->DBGSTOPCR_b.DBGSTOP_WDT = 0;
/* Open the WDT */
R_WDT_Open(&g_wdt0_ctrl, &g_wdt0_cfg);
/* Start the WDT by refreshing it */
R_WDT_Refresh(&g_wdt0_ctrl);
/* Flash the red LED and feed the WDT for a few seconds */
for (loop_counter = 0; loop_counter < RED_LED_NO_OF_FLASHES; loop_counter++)
{
/* Turn red LED on */
R_IOPORT_PinWrite(&g_ioport_ctrl, RED_LED_PIN, BSP_IO_LEVEL_LOW);
/* Delay */
/* Refresh WDT */
R_WDT_Refresh(&g_wdt0_ctrl);
R_IOPORT_PinWrite(&g_ioport_ctrl, RED_LED_PIN, BSP_IO_LEVEL_HIGH);
/* Delay */
/* Refresh WDT */
R_WDT_Refresh(&g_wdt0_ctrl);
}
/* Flash green LED but STOP feeding the WDT. WDT should reset the
* device */
while (1)
{
/* Turn green LED on */
R_IOPORT_PinWrite(&g_ioport_ctrl, GREEN_LED_PIN, BSP_IO_LEVEL_LOW);
/* Delay */
/* Turn green off */
R_IOPORT_PinWrite(&g_ioport_ctrl, GREEN_LED_PIN, BSP_IO_LEVEL_HIGH);
/* Delay */
}
}
/*******************************************************************************************************************/
{
if (BSP_WARM_START_RESET == event)
{
#if BSP_FEATURE_FLASH_LP_VERSION != 0
/* Enable reading from data flash. */
R_FACI_LP->DFLCTL = 1U;
/* Would normally have to wait for tDSTOP(6us) for data flash recovery. Placing the enable here, before clock and
* C runtime initialization, should negate the need for a delay since the initialization will typically take more than 6us. */
#endif
}
if (BSP_WARM_START_POST_C == event)
{
/* C runtime environment and system clocks are setup. */
/* Configure pins. */
R_IOPORT_Open(&g_ioport_ctrl, &g_bsp_pin_cfg);
}
}

The WDT HAL driver API functions are defined in r_wdt.h. The WDT HAL driver is opened through the open API call using the instance structure defined in r_wdt_api.h:

/* Open the WDT */
R_WDT_Open(&g_wdt0_ctrl, &g_wdt0_cfg);

The first passed parameter is the pointer to the control structure g_wdt0_ctrl instantiated in hal_data.c. The second parameter is the pointer to the configuration data g_wdto_cfg instantiated in the same hal_data.c file.

The WDT is started and refreshed through the API call:

/* Start the WDT by refreshing it */
R_WDT_Refresh(&g_wdt0_ctrl);

Again the first (and only in this case) parameter passed to this API is the pointer to the control structure of this instance of the driver.

Building and Testing the Project

Build the project in e2 studio by clicking Build > Build Project or by clicking the build icon. The project should build without errors.

To debug the project

  1. Connect the USB cable between the target board debug port and host PC.
  2. In the Project Explorer pane on the left side of e2 studio, right-click on the WDT project WDT_Application and select Debug As > Debug Configurations.
  3. Under Renesas GDB Hardware Debugging select WDT_Application Debug as shown below.

    sd-debug-config.jpg
    Debug configuration
  4. Click the Debug button. Click Yes to the debug perspective if asked.

    sd-extracting-ra-debug.png
  5. The code should run the Reset_Handler() function.
  6. Resume execution via Run > Resume. Execution will stop in main() at the call to hal_entry().
  7. Resume execution again.

The red LED should start flashing. After 30 flashes the green LED will start flashing and the red LED will stop flashing.

While the green LED is flashing the WDT will underflow and reset the device resulting in the red LED to flash again as the sequence repeats.

  1. Stop the debugger in e2 studio via Run > Terminate.
  2. Click the reset button on the target board. The LEDs begin flashing.

Primer: ARM® TrustZone® Project Development

This section will introduce the user to the tools supporting ARM® TrustZone® configuration for the RA Family of microcontrollers. It is intended to be read by development engineers implementing RA ARM® TrustZone® projects for the first time. It will introduce basic concepts followed by workflow and tooling functions designed to simplify and accelerate their first ARM® TrustZone® development. A background knowledge of e2 studio and RA device hardware is expected.

Target Device

RA Cortex®-M33 or Cortex®-M23 devices with ARM® TrustZone® security extension.

Renesas Implementation of ARM® TrustZone® Technology

For brevity, ARM® TrustZone® will be abbreviated to TZ in this document.

The following section is supplied for reference only. For full details of TZ implementation, refer to Arm documentation (https://developer.arm.com/ip-products/security-ip/trustzone) and the RA6M4 device manual.

Arm TZ technology divides the MCU and therefore the application into Secure and Non-Secure partitions. Secure applications can access both Secure and Non-Secure memory and resources. Non-Secure code can access Non-Secure memory and resources as well as Secure resources through a set of so-called veneers located in the Non-Secure Callable (NSC) region. This ensures a single access point for Secure code when called from the Non-Secure partition. The MCU starts up in the Secure partition by default. The security state of the CPU can be either Secure or Non-Secure.

The MCU code flash, data flash, and SRAM are divided into Secure (S) and Non-Secure (NS) regions. Code flash and SRAM include a further region known as Non-Secure Callable (NSC). These memory security attributes are set into the non-volatile memory via SCI or USB boot mode commands when the device lifecycle is Secure Software Debug (SSD) state. The memory security attributes are loaded into the Implementation Defined Attribution Unit (IDAU) peripheral and the memory controller before application execution and cannot be updated by application code.

tz-secure-nonsecure.png
Secure and Non-Secure Regions

Note: All external memory accesses are considered to be Non-Secure.

Code Flash and SRAM can be divided into Secure, Non-Secure, and Non-Secure Callable. All secure memory accesses from the Non-Secure region MUST go through the Non-Secure Callable gateway and target a specific Secure Gateway (SG) assembler instruction. This forces access to Secure APIs at a fixed location and prevents calls to sub-functions and so on. Failing to target an SG instruction will generate a TZ exception.

TZ enabled compilers will manage generation of the NSC veneer automatically using CMSE extensions.

Calling from Non-Secure to Secure

A new instruction SG (Secure Gateway) has been added to the Armv8-M architecture. This MUST be the destination instruction for any branch within the Non-Secure Callable region. If an attempt is made to branch to any other instruction from the Non-Secure partition, a TZ exception will be thrown.

tz-non-secure-to-secure-calling.png
Calling from Non-Secure to Secure Functions

Calling from Secure to Non-Secure

Secure code uses B(L)XNS instructions to make direct calls to Non-Secure functions. While this is certainly possible, it can create a security vulnerability in the application. It is also challenging for the Secure application to determine the address of the non-secure function during build phase. From the RA Tools and FSP point view, calling directly from Secure to Non-Secure via FSP API is not supported.

Preference is for the Secure code to initialise as necessary from reset, then pass control to the Non-Secure partition. It will manage any data transfers and so forth via FSP call-backs as security checks. For example, secure data can be copied to Non-Secure RAM.

tz-secure-to-non-secure-calling.png
Calling from Secure to Non-Secure Functions

Workflow

ARM® TrustZone® MCU development normally consists of two projects within a workspace, Secure and Non-Secure. General project workflows are described in the following sections. The Renesas project generator also supports development with "Flat project" model with no ARM® TrustZone® awareness.

Secure Project

  1. Start a new Secure project in e2 studio.
  2. Select and configure pins and drivers/stacks that need to be initialized and used in Secure mode. This should be kept to a minimum to reduce the security attack surface.
  3. Expose top of stacks as Non-Secure Callable (NSC) if they need to be accessed from Non-Secure partition. Again, this should be kept to a minimum.
  4. Generate project content and write Secure code such as key handling and opening drives as needed.
  5. Modify/remove any unnecessary "Guard" functions as needed to control access via NSC.
  6. Build project.
  7. A Non-Secure project will be needed before debugging. If necessary, prepare a "dummy" Non-Secure project or replace R_BSP_NonSecureEnter(); with while(1); in hal_entry.c.

Non-Secure Project

  1. Start a new Non-Secure project.
  2. If you have access to the Secure project, choose this option. However, if you only have access to a device with pre-programmed Secure code (commonly referred to as provisioned device) choose "Secure Bundle".
  3. Select and configure pins and drivers/stacks that need to be initialized and used in Non-Secure mode.
  4. Note that you can add NSC drivers and stacks as needed.
  5. Generate project content and write Non-Secure code as needed
  6. Access NSC drivers and Stacks via Guard functions.
  7. Build and debug project.

Flat Project

A flat project does not technically use ARM® TrustZone® as the developer has made a decision to place the entire application in Secure partition from restart.

Notes:

  • Any code placed in external memory (such as OSPI or QSPI) will be Non-Secure.
  • The Ethernet EDMAC is designed to be a Non-Secure bus master so associated Ethernet RAM buffers will be placed in Non-Secure RAM. The tooling will automatically manage this.

The workflow is as follows:

  1. Start a new Flat project.
  2. Select and configure pins and drivers/stacks as needed.
  3. Generate project content and write code as needed.
  4. Build and debug project.

RA Project Generator (PG)

The RA project generators have been created to help users through setting up new TZ enabled projects. User will be prompted for project settings such as Project Type (Secure, Non-Secure, or Flat), compiler, RTOS and debugger. Care is needed when setting up a TZ project to ensure that the connection between Secure and Non-Secure partitions are managed correctly.

tz-secure-proj.png
Secure Project (following Arm notation as green)
tz-non-secure-proj.png
Non-Secure Project (following Arm notation as red)
tz-flat-proj.png
Flat Project

Secure Project Set Up

All code, data, and peripherals in this project will be configured as Secure using the device Peripheral Security Attribution (PSA) registers. Although it is very application specific, we recommend keeping the Secure project code as small as possible to reduce the attack surface. For example, secure key handling may be the only application code in the secure project.

Necessary values to set up the TZ memory partition (IDAU registers) will be automatically calculated after the project is built to ensure they match the code and data size, keeping the attack surface as small as possible.

Typically, ANSI C start up code (clearing of RAM, variable initialisation, etc) , clock, and secure peripheral initialisation will occur in this project.

At the end of the Secure code, a call will be made to R_BSP_NonSecureEnter(); to pass control to the Non-Secure partition.

Non-Secure Callable (NSC) "Guard" functions are added to the project and expose selected modules to Non-Secure projects. User can add application-specific access checks as needed in these functions.

Output of this project type will be an elf file that must be either pre-programmed (provisioned) into a device or referenced by a Non-Secure project (via Secure bundle *.SBD) to build a final image.

This project type will NOT typically be debugged in isolation and will normally require a Non-Secure project such as a call to a R_BSP_NonSecureEnter() to be made. This can be replaced with while(1); if needed.

RTOS Support in TZ Project

Although the RTOS kernel and user tasks will reside in the Non-Secure partition, the Secure partition needs to allocate stack space and so on. It is essential when starting a new RTOS project that the TrustZone Secure RTOS-Minimal template is selected. This will add the Arm TrustZone Context RA Port as below.

tz-secure-rtos-min-a.png
tz-secure-rtos-min-b.png
Secure RTOS-Minimal Template

Peripheral Security Attribution

Each peripheral can be configured to be Secure or Non-Secure. Peripherals are divided into two types.

Type-1 peripherals have one security attribute. Access to all registers is controlled by one security attribute. The Type-1 peripheral security attribute is set in the PSARx (x = B to E) register by the secure application.

Type-2 peripherals have the security attribute for each register or for each bit. Access to each register or bit field is controlled according to these security attributes. The Type-2 peripheral security attribute is set in the Security Attribution register in each module by the Secure application. For more information about the Security Attribution register, see sections in the Appropriate MCU’s User’s Manual for each peripheral.

Table 1. Secure and Non-Secure Peripherals

Type Peripheral
Type 1 SCI, SPI, USBFS, CAN, IIC, SCE9, DOC, SDHI, SSIE, CTSU, CRC, CAC, TSN, ADC12, DAC12, POEG, AGT, GPT, RTC, IWDT, WDT
Type 2 System control (Resets, LVD, Clock Generation Circuit, Low Power Modes, Battery Backup Function), FLASH CACHE, SRAM controller, CPU CACHE, DMAC, DTC, ICU, MPU, BUS, Security setting, ELC, I/O ports
Always Non-Secure CS Area Controller, QSPI, OSPI, ETHERC, EDMAC

FSP will initialise the arbitration registers during Secure project BSP start up. User code may also be written to set or clear further arbitration. However care must be taken not to undermine FSP.

Non-Secure

All code, data, and peripherals in this project will be configured as Non-Secure. This project type must be associated with a Secure project to enable access to secure code, peripherals, linker scripts and others.

Flat Project Type

All code, data, and peripherals are configured in a Secure single partition except for the EDMAC RAM buffers that will remain in the Non-Secure partition. Effectively, TZ is disabled.

Secure Connection to Non-Secure Project

When starting a new Non-Secure Project, the user will be prompted for either a Secure Project or Secure Bundle. In each case, details of the linker settings, Non-Secure Callable functions, and Secure peripherals will be read to enable the Non-Secure project setup.

Should the Secure project or bundle be rebuilt, the Non-Secure editor will detect this and prompt user to regenerate the Non-Secure project configuration.

tz-secure-proj-or-bundle.png
Secure Project or Bundle Selection

Secure Project (Combined)

A Secure project must reside in the same Workspace as the Non-Secure project and will typically be used when a design engineer has access to both the Secure and Non-Secure project sources. This is sometimes known as "Combined model".

A Secure .elf file will be referenced and included in the debug configuration for download to the target device. The development engineer will have visibility of Secure and Non-Secure project source code and configuration.

Secure Bundle (Split)

A Secure Bundle will ONLY include linker memory ranges, symbol references, and details of locked Secure peripheral configuration settings but no access to Secure source code (API header files will be included as necessary).

The Secure bundle file (*.SBD) must be supplied to the Non-Secure developer by the Secure project developer.

The development engineer will typically not have access to the Secure project or .elf file which MUST be pre-programmed or provisioned into the target MCU.

The DLM state of target device should then be switched to NSECSD (see section 6.2) before the device is provided to the non-secure developer.

This is often referred to as "Split model" where a basic security set up is developed by a Secure team and then passed to the Non-Secure team in the same facility or at a third party. The Non-Secure team has no access to the Secure source code and cannot directly access Secure peripherals, data, or APIs.

Debug Configurations

After each project type has been selected, a suitable debug configuration will be generated.

Non-Secure with Secure Project (Combined)

Both Secure and Non-Secure .elf files will be downloaded.

A debug configuration called <project name>_SSD will be generated.

Non-Secure with Secure Bundle (Split)

Only a Non-Secure elf will be downloaded. This configuration must be used with a pre-provisioned device (Secure project pre-programmed into MCU Flash).

A debug configuration called <project name>_NSECSD will be generated.

Flat Debug

A single .elf file will be downloaded.

A debug configuration called <project name>_FLAT will be generated.

Secure Projects

As mentioned, Secure code will be called immediately after device reset and run ANSI C start up, clock, interrupt vector table, and secure peripheral initialization before starting user code. All selected peripheral configuration settings will be automatically initialised as Secure.

Secure Clock

Device clock settings are the possible exception in that they will be initialised in the Secure project (to enable faster start up from reset) but can be set as Secure or Non-Secure as user application may need to change settings during execution (for low-power mode and so on). The Secure and Non-Secure FSP BSPs can both change the clock settings.

However, clock settings can be locked as Secure should the developer choose to do so.

tz-secure-clock-setting.png
Secure Clock Setting

Setting Drivers as NSC

Some driver and middleware stacks in the Secure project may need to be accessed by the Non-Secure partition. To enable generation of NSC veneers, set "Non-Secure Callable" from the right-click context menu for the selected modules in the Configurator.

Note: It is only possible to "expose" top of stacks as NSC.

tz-generate-nsc-veneers-a.png
tz-generate-nsc-veneers-b.png
Generate NSC Veneers

The top of the stack will be marked with a new icon and tool tip to signify NSC access.

Guard Functions

Access to NSC drivers from a Non-Secure project is possible through the Guard APIs. FSP will automatically generate Guard functions for all the top of stack/driver APIs added to the project as Non-Secure Callable.

User can choose to add further levels of access control or delete guard function if they wish to only expose a limited range of APIs to a Non-Secure developer.

BSP_CMSE_NONSECURE_ENTRY fsp_err_t g_uart0_open_guard(
uart_ctrl_t *const p_api_ctrl, uart_cfg_t const *const p_cfg) {
/* TODO: add your own security checks here */
FSP_PARAMETER_NOT_USED(p_api_ctrl);
FSP_PARAMETER_NOT_USED(p_cfg);
return R_SCI_UART_Open(&g_uart0_ctrl, &g_uart0_cfg);
}

For example, an SCI channel may be opened and configured for a desired baud rate by the Secure developer, but only enable the Write API to the Non-Secure developer. In which case, all but g_uart0_write_guard() could be deleted. CTRL structures are not required as they will be added on the Secure side.

For example, the call from the Non-Secure partition would be as follows:

err = g_uart0_open_guard(0,0);

Non-Secure projects

Configuration of the project can continue as for other RA devices, but certain resources will be locked if they have been previously set up as Secure.

The Non-Secure project will be called from the Secure project via R_BSP_NonSecureEnter();

Clock Set Up

You may recall that clocks can be set as Secure or Non-Secure. If they are set as Secure, settings will only be available to view, and user will not be able to change them. The Override button will be greyed. This is useful to preserve CGC sync with secure project by not overriding unless necessary. If it is NOT set as Secure, user can choose to override the initial Secure settings

tz-clock-setting-non-secure.png
Clock Setting as Non-Secure
tz-clock-setting-secure.png
Clock Setting as Secure

Selecting NSC Drivers

Drivers declared as NSC in a Secure project can be selected and added to Non-Secure project and will be decorated as before.

tz-selecting-nsc-drivers-a.png
tz-selecting-nsc-drivers-b.png
Selecting NSC Drivers

Locked Resources

When a NSC Secure driver is added to a Non-Secure project, the configuration settings are locked and are available for information only. A padlock is added for indication.

tz-locked-resources.png
Locked Resources

Locked Channels

In a peripheral with multiple channels, for example, DMA, if a Non-Secure developer tries to select a channel that has already been defined as Secure, the following error message type will be displayed.

tz-error-msg-selecting-secure.png
Error Message when Selecting a Secure Channel

IDAU registers

Renesas RA TZ-enabled devices include a set of registers known as Implementation Defined Attribution Unit (IDAU) that are used to set up partitions between Secure, Non-Secure Callable, and Non-Secure regions. The IDAU registers can only be programmed during MCU boot mode and NOT through the debug interfaces. Because of this, special debugger firmware has been developed to manage bringing the device up in SCI boot mode to set up the IDAU registers (automatically drives MD pin) and then switch back to debug mode as needed.

Note: Please be aware of the extra signal connection (MD pin) needed on the debug interface connector. The Renesas Evaluation Kit (EK) for your selected device is a good reference.

tz-debug-iface-connector.png

The e2 studio build phase automatically extracts the IDAU partition register settings from the Secure .elf file and programs them into the device during debug connection, which can be observed in the console.

This is an important phase of TZ development as the Secure partitions should be set as small as possible to ensure that the security attack surface is as small as possible.

However, should the developer wish to make these partitions larger to accommodate, for example during field firmware updates, const or data arrays should be placed in the Secure project as needed.

tz-ra-current-status.png
RA TrustZone Device Current Status

It is also possible to manually set up the partition registers through the Renesas Device Partition Manager.

tz-ren-dev-partition-mgr-a.png
tz-ren-dev-partition-mgr-b.png
Renesas Device Partition Manager

SCI Boot Mode

Example of MD mode pin connection to debugger connector (from EK schematic).

tz-md-mode-pin-ex.png
Example of MD Mode Pin Connection to Debugger Connector (from EK schematic

DLM States

Device lifecycle defines the current phase of the device and controls the capabilities of the debug interface, the serial programming interface and Renesas test mode. The following illustration shows the lifecycle definitions and capability in each lifecycle.

tz-lifecycle-stages.png
Lifecycle Stages

Note: All authentication key exchange and transitioning to LCK_DBG, LCK_BOOT, RMA_REQ is only managed by Renesas Flash Programmer (RFP) and NOT within e2 studio.

tz-lifecycle-stages-debug-levels.png
Lifecycle Stages and Debug Levels

There are three debug access levels. The debug access level changes according to the lifecycle state.

  • DBG2: The debugger connection is allowed, and no restriction to access memories and peripherals
  • DBG1: The debugger connection is allowed, and restricted to access only Non-Secure memory regions and peripherals
  • DBG0: The debugger connection is not allowed

Transitions for one state to another can be performed using the Renesas Flash Programmer (RFP, see section below) or using the Renesas Device Partition Manager (limited number of states possible). It is possible to secure transitions between states using authentication keys. For more information on DLM states and transitions (device specific), please refer to device user manual.

Debug

By default, the device will be in SSD mode and so allow access to Secure and Non-Secure partitions. In this mode both Secure and Non-Secure .elf files will be downloaded.

The current debugger status is displayed in the lower left corner and includes the DLM state (SSD or NSECSD) and current partition (Secure, Non-Secure, or Non-Secure Callable) when the debugger is stopped, for example.

tz-current-debugger-status-a.png
tz-current-debugger-status-b.png
tz-current-debugger-status-c.png
Current Debugger Status

Non-Secure Debug

Once the device is transitioned to NSECSD mode, only Non-Secure Flash, RAM and Peripherals can be accessed. In this mode, a Secure .elf must be pre-programmed (provisioned) into the device, and only a Non-Secure .elf file will be downloaded.

When in NSECSD mode access to Secure elements will be blocked and data displayed as ????????.

In NSECSD mode, it is not possible to set breakpoints on Secure code or data.

It is not possible to step into Secure code; the debugger will perform a step-over of any Secure function calls. Should the user press the Suspend button during execution, the debugger will stop at the next Non-Secure code access.

Assuming Secure memory region finishes at 32K (0x8000) in NSECSD debug mode (colour coding added for indication only), memory will be displayed as shown in the following figure.

tz-mem-display-nsecsd-debug-mode.png
Memory Display in NSECSD Debug Mode

Disassembly will be displayed as shown in the following figure.

tz-disassembly-display-nsecsd-debug-mode.png
Disassembly Display in NSECSD Debug Mode

Debugger support

Renesas E2, E2 Lite, and SEGGER J-Link are supported in e2 studio for TZ projects.

Debugger Support for TZ Projects

Feature E2 Lite E2 J-Link J-Link OB ULINK IAR i-Jet
JTAG Yes Yes Yes No Yes Yes
SWD Yes Yes Yes Yes Yes Yes
ETB trace Yes Yes Yes Yes Yes Yes
ETM trace No Yes Yes No Yes Yes
TZ partition programming Yes Yes Yes Yes No No
Non secure debug Yes Yes Yes Yes Yes Yes
e2 studio Yes Yes Yes Yes No TBC
IAR EW Arm Under consideration Under consideration Yes Yes No Yes
Keil MDK Under consideration Under consideration Yes Yes Yes No

Third-Party IDEs

Third-party IDEs such as IAR Systems EWARM and Keil MDK (uVision) are supported by the RA Smart Configurator (RA SC).

In general, RA SC offers the same configurator functionality as e2 studio documented above. Project generators are available to initialise workspaces in the target IDEs as well as setting up debug configurations and so forth. However, there are some limitations that need to be noted especially with regards to IDAU TZ partition register programming. See the specific RA SC documentation for usage details.

Renesas Flash Programmer (RFP)

Updated versions of Renesas Flash Programmer (RFP) are available to support setting of partitions, DLM state and Authentication keys.

RFP can be downloaded free of charge on the Renesas web site.

A new mode has been added to Program Flash Options as shown in the following graphics.

tz-rfp-program-flash-options.png
RFP Program Flash Options

Options to set partition boundaries are shown in the following figure.

tz-rfp-partition-boundaries.png
RFP Partition Boundaries

Options to set DLM state, Authentication keys, and Security settings are shown in the following figure.

tz-rfp-dlm-authent-keys-security-settings.png
RFP DLM State, Authentication Keys, and Security Settings

Great care is needed here as some DLM states can **permanently** turn off debug and boot mode on the devices. Equally programming a security access authentication key can lead to permanently locked devices if the key is lost.

Glossary

IDAU

Implementation Defined Attribute Unit. Used to program TZ partitions in SCI book mode.

NSECSD

Non-Secure Software Development mode

SSD

Secure Software Development mode

NSC

Non-Secure Callable. Special Secure memory region used for Veneer to allow access to Secure APIs from Non-Secure code.

Provisioned

Device with Secure code pre-programmed and DLM state set to NSECSD

Flat project

All code, data and peripherals are configured as secure with the exception of the EDMAC RAM buffer which are placed in Non-Secure RAM due to the configuration of the internal bus masters.

Veneer

Code that resides in Non-Secure Callable region

Combined model

Development engineer has access to both Secure and Non-Secure project and source code

Split model

Development Engineer has access to only the Non-Secure partition. No visibility of Secure source code. Secure code will be provisioned into device.

Configurator Icon Glossary

tz-config-icons-a.png
tz-config-icons-b.png
Configurator Icons

RA SC User Guide for MDK and IAR

What is RA SC?

The Renesas RA Smart Configurator (RA SC) is a desktop application designed to configure device hardware such as clock set up and pin assignment as well as initialization of FSP software components for a Renesas RA microcontroller project when using a 3rd-party IDE and toolchain.

The RA Smart Configurator can currently be used with

  1. Keil MDK and the Arm compiler toolchain.
  2. IAR EWARM with IAR toolchain for Arm

Projects can be configured and the project content generated in the same way as in e2 studio. Please refer to Configuring a Project section for more details.

Using RA Smart Configurator with Keil MDK

Prerequisites

  • Keil MDK and Arm compiler are installed and licensed. Please refer to the RASC Release notes for the version to be installed.
  • Import the RA device pack. Download the RA device pack archive file (ex: MDK_Device_Packs_2.x.x.zip) from the FSP GitHub release page. Extract the archive file to locate the RA device pack. To import the RA device pack, launch the PackInstaller.exe from <keil_mdk_install_dir>\UV4. Select the menu item File > Import... and browse to the extracted .pack file.
  • Verify that the latest updates for RA devices are included in Keil MDK. To verify, select the menu "Packs" in Pack Installer and verify that the menu item Check for Updates on Launch is selected. If not, select Check for Updates on Launch and relaunch Pack Installer.
  • For flashing and debugging, the latest Segger J-Link DLL is installed into Keil MDK.
  • Install RA SC and FSP using the Platform Installer from the GitHub release page.

Create new RA project

The following steps are required to create an RA project using Keil MDK, RA SC and FSP:

  1. Start the RA Smart Configurator.
  2. Enter a project folder and project name.

    image009.png
    RA SC project settings
  3. Select the target device and IDE.

    image010.png
    Target device and IDE selection
  4. The rest of the project generator and FSP configuration is the same as e2 studio. Please refer to the previous sections for details.
  5. On completion of the FSP configuration, press "Generate Project Content"
  6. A new Keil MDK project file will be generated in the project path. Double click this file to open MDK and continue development as usual.

    uVision-imported-data.png
    uVision project workspace with imported project data

Modify existing RA project

Once an initial project has been generated and configured, it is also possible to make changes using RA SC as follows.

Note
This setup only needs to be done once per project.

Set up the following links to RA SC:

  1. In Keil MDK uVision, select Tools > Customize Tools Menu....
  2. Select the new icon and fill in the fields as follows for each tool:
    1. RA Smart Configurator:
      • Menu item name: Enter: RA Smart Configurator
      • Command: Select "..." and navigate to rasc.exe
      • Initial Folder: Enter: $P
      • Arguments: Enter: --device $D –-compiler ARMv6 configuration.xml
    2. Device Partition Manager:
      • Menu item name: Enter: Device Partition Manager
      • Command: Select "..." and navigate to rasc.exe
      • Initial Folder: Enter: $P
      • Arguments: Enter: -application com.renesas.cdt.ddsc.dpm.ui.dpmapplication configuration.xml "SL%L"

To reconfigure an existing project select Tools > RA Smart Configurator

To reconfigure the TrustZone partitions select Tools > Device Partition Manager

Build and Debug RA project

The project can be built by selecting the menu item Project > Build Target or tool bar item Rebuild or the keyboard shortcut F7.

Assembler, Compiler, Linker and Debugger settings can be changed in Options for Target dialog, which can be launched using the menu item Project > Options for Target, the tool bar item Options for Target or the keyboard shortcut Alt+F7.

uVision-target-options.png
Options for Target

RA SC will set up the uVision project to debug the selected device using J-Link or J-Link OB debugger by default.

A Debug session can be started or stopped by selecting the menu item Debug > Start/Stop Debug Session or keyboard shortcut CTRL+F5. When debugging for the first time, J-Link firmware update may be needed if requested by the tool.

Refer to the documentation from Keil to get more information on the debug features in uVision. Note that not all features supported by uVision debugger are implemented in the J-Link interface. Consult SEGGER J-Link documentation for more information.

Notes and Restrictions

  1. When debugging a TrustZone based project, the Secure project image MUST be downloaded before the Non Secure project.
  2. For TrustZone enabled devices, the user will need to manually set up the memory partitions using the "Renesas Device Partition Manager" from inside RA SC before downloading.

    image007.png
    Renesas Device partition Manager
  3. RA FSP contains a full set of drivers and middleware and may not be compatible with other CMSIS packs from Keil, Arm or third parties.
  4. Flash programming is currently only supported through the debugger connection.

Using RA Smart Configurator with IAR EWARM

IAR Systems Embedded Workbench for Arm (EWARM) includes support for Renesas RA devices. These can be set up as bare metal designs within EWARM. However, most RA developers will want to integrate RA FSP drivers and middleware into their designs. RA SC will facilitate this.

RA SC generates a "Project Connection" file that can be loaded directly into EWARM to update project files.

Prerequisites

  • IAR EWARM installed and licensed. Pleae refer to the Release notes for the version to be installed.
  • RA SC and FSP Installed

Create new RA project

The following steps are required to create an RA project using IAR EWARM, RA SC and FSP:

  1. Start the RA Smart Configurator.
  2. Enter a project folder and project name.

    image014.png
    RA SC project settings
  3. Select the target device and IDE.

    image016.png
    Target device and IDE selection
  4. The rest of the project generator and FSP configuration operates the same as e2 studio. Refer to the previous sections for details.
  5. On completion of the FSP configuration, press Generate Project Content.
  6. A new IAR EWARM project file will be generated in the project path. Double click this file to open IAR EWARM and continue development as usual.
  7. To Use RA SC with EWARM, RA SC needs to configured as a tool in EWARM by selecting the menu item Tools > Configure Tools.... Select New to create a new tool in the dialog shown and add the following information:
    • Menu Text: RA Smart Configurator
      1. Command: Select Browse... and navigate to rasc.exe in the installed RA SC
      2. Argument: –compiler IAR configuration.xml
      3. Initial Directory: $PROJ_DIR$
      4. Tool Available: Always
    • Menu Text: Device Partition Manager
      1. Command: Select Browse... and navigate to rasc.exe in the installed RA SC
      2. Argument: -application com.renesas.cdt.ddsc.dpm.ui.dpmapplication configuration.xml "$TARGET_PATH$"
      3. Initial Directory: $PROJ_DIR$
      4. Tool Available: Always
  8. RA SC can now be re-launched from EWARM using the menu item Tools > RA Smart Configurator.
  9. A Project connection needs to be set up in EWARM to build the project. Select Project > Add Project Connection in EWARM and select IAR Project Connection. Navigate to the project folder and select buildinfo.ipcf and click Open. The project can now build in EWARM.

Notes and Restrictions

When starting a TrustZone enabled debug session Partition sizes are checked automatically.

  • If partition sizes are set correctly, the debug session will launch as normal.
  • If partition sizes need to be changed, IAR EWARM will prompt to run the Renesas Device Partition Manager. Select Yes. The Device Partition Manager will start with the required partition sizes prefilled.
  • Select Set TrustZone secure / non-secure boundaries as the only action.
  • Enter debugger details, if required.
  • Select Run to program the partitions.
  • Return to the IDE and relaunch the debug session