 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
This section describes how to use the Renesas e2 studio Integrated Solutions Development Environment (ISDE) to develop applications with the Renesas Synergy Software Package (SSP). The architecture of the SSP directly determines how you use the e2 studio ISDE to develop a Synergy application. See the following documents for details on the SSP architecture included in this manual:
For simple example projects generated and built with e2 studio, see:
All User Guides in this manual show how to configure a driver and develop an application using the e2 studio ISDE. See:
The Renesas e2 studio ISDE, or Integrated Solution Development Environment, is a development tool encompassing code development, build, and debug. The ISDE is based on the open-source Eclipse IDE and the associated C/C++ Development Tooling (CDT). Specifically for Synergy MCUs, the ISDE provides a Graphical User Interface (GUI) with numerous wizards for configuring and auto-generating code using the Synergy Software Package (SSP). The ISDE also incorporates a smart manual so that driver and device documentation is available in the form of tooltips right in the code.
The e2 studio ISDE and the Synergy Project Configurator have been developed to make it as easy as possible to quickly select the SSP modules required for a particular application, include them in a project, and configure them. The ISDE provides a graphical user interface to configure all elements of the SSP for the Synergy MCU applications. In addition to HAL and Framework modules, the ISDE can add and configure RTOS threads, semaphores, mutexes, event flags, and queues. This makes adding RTOS support to an application very straightforward. Once a project has been generated, you can go back and reconfigure any of the modules and settings if required. The ISDE generates the complete and correct configuration code from the selections in the configuration views, so you can focus on writing the application code.
The elements of the SSP are shown in the Project Explorer view of the e2 studio ISDE. All SSP configuration structures and parameters are mapped to XML files. The XML files enable the ISDE to present a visual list of configurable options that you can select from. In addition to generating code to configure the modules, the XML also provides dependency information for modules.
When you add an SSP module to your project, the e2 studio ISDE checks the dependencies of this module and adds all necessary drivers and framework modules to create the appropriate stack. If there is a dependency that requires you to make a choice, this module is highlighted in the Stack window and the ISDE guides your selection by showing the available options.
Errors are flagged next to the Driver name in the HAL/Common Modules or New Thread Modules pane. You can also review errors in the Problems window.
To develop applications with the SSP, start with one of the Renesas Synergy Kits. The Renesas Synergy Kits are designed to seamlessly integrate with the e2 studio ISDE. Several types of kits are available:
Ordering information, Quick Start Guides, User Manuals, and other related documents for all Synergy Kits are available at http://renesassynergy.com.
To use the e2 studio ISDE, ensure that your PC meets the following minimum requirements:
Detailed installation instructions and installers for the e2 studio ISDE and the SSP are available on the Renesas Synergy Gallery website https://synergygallery.renesas.com. Review the release notes for e2 studio to ensure that the e2 studio version supports the selected SSP version.
The e2 studio ISDE can work with several toolchains and toolchain versions such as the GNU ARM compiler and the IAR toolchain. A version of the GNU ARM compiler is included in the e2 studio installer and has been verified to run with the SSP version.
To use the IAR toolchain for ARM, install IAR Embedded Workbench for Renesas Synergy (EWSYN) (a license from IAR is required). Before starting a Synergy project with IAR, also install the IAR Embedded Workbench for ARM Eclipse plugin (using the IAR Embedded Workbench plugin manager in the 'Help' menu).
The IAR Embedded Workbench for Renesas Synergy compiler (IAR compiler) can now be used from within 2 studio. This allows the developer to have the advantages provided by the IAR compiler without the need to also use the IAR EW for Renesas Synergy ISDE. The installation process involves installing IAR EW for Renesas Synergy, installing e2 studio, and installing the associated IAR plugins for e2 studio. The process is described in the application note found with this search: https://www.renesas.com/eu/en/document/apn/installing-iar-compiler-e2-studio-application-note
The application note also includes a description of how to migrate a project that originally used e2 studio and GCC. It also includes a description of how to migrate a project from IAR 7.x to IAR 8.x so it will be successfully opened when using e2 studio.
In e2 studio, all SSP applications are organized in Synergy projects. Setting up a Synergy project involves:
The e2 studio ISDE has many project wizards and configuration windows specifically for Synergy projects. You can create a new Synergy Project with the Synergy Project Generator or edit the configuration of an existing project in the Synergy Project Editor.
When you launch e2 studio and select a workspace, all projects previously saved in the selected workspace are loaded and displayed in the Project Explorer view. Each project has an associated configuration file named configuration.xml which is located in the project’s root directory.
Double-click on the configuration.xml file to open the Synergy Project Editor and view or modify all configuration settings associated with this project. To edit the project configuration, make sure that the Synergy Configuration perspective is selected in the upper right hand corner of the e2 studio window.
The Synergy Project Editor has a number of tabs. The configuration steps and options for individual tabs are discussed in the following sections.
This section includes step-by-step instructions for creating a Synergy Project. Once you have created the project, you can easily configure the hardware (clocks, pins, interrupts) and the parameters of all modules that are part of your application.
To create a new Synergy Project with the Synergy Project Generator, select the project name, select the hardware for your application, select the toolchain and choose from preconfigured clock, pin, and MCU related settings by selecting a project template.
For Synergy applications, always generate a new project as a Synergy Project in the following way:
In the next Project Configuration window select the hardware and software environment:
Select the Board for your application. You can select an existing Synergy Kit or select Custom User Board for any of the Synergy devices with your own BSP definition.
In the next window, select a project template from the list of available templates and click Finish.
By default, this screen shows the templates that are included in your current SSP pack.
When the project is created, the ISDE displays a summary of the current project configuration in the Synergy Project Editor.
On the bottom of the Synergy Project Editor view, you can find the tabs for configuring multiple aspects of your project:
A project has two levels of configuration.
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.
The Properties view shows the configurable options available for the BSP. These can be changed as required. The BSP is the SSP layer above the MCU hardware. The ISDE checks the entry fields to flag invalid entries. For example, only valid numeric values can be entered for the stack size.
When you press the Generate Project Content button, the BSP configuration contents are written to
synergy_cfg/ssp_cfg/bsp/bsp_cfg.h
This file is created if it does not already exist.
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 divider has been changed so the resulting clock frequency is 60 MHz instead of the required 48 MHz. This parameter is colored red.
When you press the Generate Project Content button, the clock configuration contents are written to:
synergy_cfg/ssp_cfg/bsp/bsp_clock_cfg.h
This file will be created if it does not already exist.
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.
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 DK-S7G2, some peripherals connected on the board are preselected.
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 P105 is already used by the External Memory peripheral, 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 External Memory peripheral in the Pin Selection pane on the left side of the tab.
The pin configurator also shows a package view and the selected electrical or functional characteristics of each pin.
When you press the Generate Project Content button, the pin configuration contents are written to:
synergy_cfg/ssp_cfg/bsp/bsp_pin_cfg.h
This file will be created if it does not already exist.
To make it easy to share pinning information for your project, the ISDE exports your pin configuration settings to a csv format and copies the csv file to synergy_cfg/ssp_cfg/bsp/pincfg_< MCU package>.csv.
Every ThreadX-based Synergy Project includes at least one RTOS Thread and a stack of SSP modules running in that thread. The Threads 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, the ISDE automatically generates the code reflecting your configuration choices.
For any driver or, more generally, any module that you add to a thread, the ISDE automatically resolves all dependencies with other modules and creates the appropriate stack. This stack is displayed in the Threads pane, which the ISDE populates with the selected modules and module options for the selected thread. If there is more than one module that can fulfill a dependency requirement, the ISDE prompts you to choose a module from a dropdown menu.
For example, when you add the Audio Playback Framework to a thread, you also must pick either the DAC or the I2S framework for playback:
The default view of the Threads tab includes a Common Thread called HAL/Common. This thread includes the drivers for I/O control (IOPORT), clock generation circuit (CGC), and the event link controller (ELC). The default stack is shown in the HAL/Common Stacks pane. The default modules added to the HAL/Common thread are special in that the SSP only requires a single instance of each, which the ISDE 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 threads, 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
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:
Click on the HAL/Common icon in the Threads pane. The Modules pane changes to HAL/Common Stacks.
The ISDE adds the following files when you click the Generate Project Content button:
| File | Contents | Overwritten by Generate Project Content? |
|---|---|---|
| src/synergy_gen/main.c | Contains main() calling generated and user code. When called, the BSP already has initialized the MCU. | Yes |
| src/synergy_gen/hal_data.c | Configuration structures for HAL Driver only modules. | Yes |
| src/synergy_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:
synergy_cfg/ssp_cfg/driver
For an application that uses the ThreadX 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 either the Driver or Framework dropdown menu. To add modules to a thread, follow these steps:
In the Properties view, click on the Name and Symbol entries and enter a distinctive name and symbol for the new thread.
When you press the Generate Project Content button for the example above, the ISDE creates the files as shown in the following table:
| File | Contents | Overwritten by Generate Project Content? |
|---|---|---|
| src/synergy_gen/main.c | Contains main() calling generated and user code. When called the BSP will have initialized the MCU. | Yes |
| src/synergy_gen/my_thread.c | Generated thread “my_thread” and configuration structures for modules added to this thread. | Yes |
| src/synergy_gen/my_thread.h | Header file for thread “my_thread” | Yes |
| src/synergy_gen/hal_data.c | Configuration structures for HAL Driver only modules. | Yes |
| src/synergy_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:
synergy_cfg/ssp_cfg/driver
synergy_cfg/ssp_cfg/framework
If the application uses the ThreadX RTOS, the Threads tab can be used to simplify the creation of ThreadX threads, semaphores, mutexes, and event flags.
The components of each thread can be configured from the Properties view as shown below.
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. The ISDE checks that the entries in the property field are valid. For example, the ISDE ensures that the field Priority, which requires an integer value, only contains numeric values between 0 and 9.
To add ThreadX 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.
Make sure to give each thread object a unique name and symbol by updating the Name and Symbol entries in the Properties view.
You can use the Properties view in the Threads tab to enable interrupts by setting the interrupt priority. Select the thread in the Threads pane to view and edit its properties.
The Messaging Framework extends the ThreadX messaging queue functionality and is one of the most important SSP modules. It provides the mechanism for threads to communicate with each other through exchanging messages. The Messaging Framework allows threads to send (publish) or listen to (pend on) messages when preconfigured or user-configured Events happen. Any thread can publish a message with an attached Event Class that all threads subscribing to this Event class can listen to and act upon. The list of Threads that can listen to a specific Event Class is called the Subscriber List for that Event Class.
To use the Messaging Framework, you first must add one Messaging Framework instance in the Threads tab. You may add the Messaging Framework to any thread which is not the HAL/Common thread. All threads in your project can use this instance to communicate with each other. Some modules like the Audio Playback Framework require the Messaging Framework and add it automatically to the stack as shown below for the Audio Playback Framework. If your project includes a thread with such a module, you do not need to add another instance of the Messaging Framework even if you add more threads to your application. All threads can share one instance of the Messaging framework.
Once you have added a Messaging Framework instance in the Threads tab, you can use the Messaging tab to define your own event classes and events and determine which threads can listen to which event class. The SSP contains a predefined event class and events for the Audio Playback Framework module. If you have added the Audio Playback Framework module, the predefined event class and events appear in the Messaging tab as well, as shown below.
To add your own user-defined Event Class to the messaging system, follow these steps:
Click OK.
To add your own user-defined Event to the messaging system, follow these steps:
Click OK.
In the Subscriber List, you select the threads that are listening to messages from the message publisher. The connection between the publishing thread and the listening thread is established through the Event Class. Therefore you define a subscriber list for each of the Event Classes in your project. All threads in the Subscriber List then can listen and act upon messages belonging to the selected Event Class.
To following assumes that you have two threads defined in the Threads tab, one of which uses the Audio Playback Framework:
To configure the Subscriber List for an Event Class, follow these steps:
In the Messaging tab, select the Event Classes in the Event Classes Pane.
The Subscriber List pane takes its name from the selected Event Class.
Click the Add Icon.
The New Subscriber Dialog box opens.
Fill out the instance range by selecting Start and End.
If you only have one instance of an Event Class, keep the Start and End values at their default value (0). See the Messaging Framework User Guide for selecting an instance range if you have more than one Event Class instance. Multiple Event Class instances can be useful in an application that uses the same Event Class multiple times for example for audio streaming on multiple channels.
The ISDE generates the following files for the configured Messaging Framework when you click the Generate Project button:
| File | Contents | Overwritten by Generate Project Content? |
|---|---|---|
| synergy_cfg/ssp_cfg/framework/sf_message_port.h | Contains the event class and event enumerations | Yes |
| synergy_cfg/ssp_cfg/framework/sf_message_payloads.h | Contains pointers to the event class payloads. | Yes |
| synergy_cfg/ssp_cfg/framework/sf_message_payloads.h | Compiler options for the Messaging Framework | Yes |
The Components tab enables the individual modules required by the application to be included or excluded. Modules common to all Synergy 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 Threads tab are included automatically. You can include or exclude additional modules by ticking the box next to the required component.
Components at the HAL and Framework layers are available as are components from Azure RTOS such as the RTOS ThreadX, file system FileX, TCP/IP networking NetX. In addition, you can select documentation to be added to a project or include complete projects.
While the components tab selects modules for a project, you must configure the modules themselves in the other tabs. Pressing the Generate Project Content button copies the .c and .h files for each component for a Pack file into the following folders:
synergy/ssp/inc/bsp
synergy/ssp/inc/driver
synergy/ssp/inc/framework
synergy/ssp/src/bsp
synergy/ssp/src/driver
synergy/ssp/src/framework
The ISDE also creates configuration files in the synergy_cfg/ssp_cfg folder with configuration options included from the remaining Threads tabs.
Once you have added Modules and drivers and set their configuration parameters in the Threads tab, you can add the application code that calls the Modules and drivers.
To write application code:
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.
To write RTOS-aware application code using ThreadX, follow these steps:
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:
TraceX™ is a host-based analysis tool that provides a graphical view of real-time system events. TraceX collects data on the target device and displays the data for inspection and analysis. A TraceX version for Synergy devices is available for downloading from the Microsoft Store.
To use TraceX, do the following:
In the TraceX Debugging window, set Buffer Start Address to &g_tx_trace_buffer.
In the TraceX Debugging window, set Buffer Size (bytes) to the buffer size selected in the Properties Window in step 2. The default is 65536.
You can find more information on using TraceX on the Renesas TraceX webpage https://www.renesas.com/synergy/tracex.
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 the ISDE through the menu Project > Renesas C/C++ Project 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.
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/S7G2.ld).
You can use the Theads tab to include ThreadX source code in your project as follows:
The e2 studio ISDE extracts the ThreadX source code into the following directory: synergy/ssp/src/framework/el/tx
This section describes a new feature, “Synergy Developer Assistance” included in e2 studio.
A new node Developer Assistance is now available in the project explorer. When expanded, the Developer Assistance tree shows you the threads and module stacks and their respective API information of the saved Synergy configuration.
The Developer Assistance node is available regardless of whether the Synergy Configuration Editor is open. This allows a user to easily consult the Developer Assistance for a project’s stack modules while application code is being written. It assists by providing code templates and an autocompletion tool.
Create a new project. In the Synergy configurator thread’s tab create a thread and add a new stack.
For example, Framework Device on sf_i2c:
Once the project is saved, expand the Developer Assistance node. Notice that the node is updated with the new thread New Thread Information. Clicking on the module instance under the thread will expand all the child nodes and show the API information of the modules.
Selecting the module instance in the thread tab or in the project explorer will show the module and module API information in the API info tab of properties view.
Tip: If the Properties view is not present in the current e2 studio perspective, you can open it by selecting Window -> Show View -> Properties
Selecting the code template node shows the preview of the function in the Properties view
The API function code templates or callbacks can be dragged and dropped to the source file. This will autofill the parameters and return type of the function
Please also refer to Help-> Help Contents -> Synergy Contents -> Synergy Developer Assistance page in e2 studio for any further information.