6L00IA - Introduction to Synergy Software Package Short Version (SSP v1.2.0) Renesas Synergy Family - S7 Series

Transcription

1 6L00IA - Introduction to Synergy Software Package Short Version (SSP v1.2.0) Renesas Synergy Family - S7 Series LAB PROCEDURE Description: The purpose of this lab is to familiarize the user with the Synergy Software Package (SSP) and how it works with e² studio. The lab will begin by creating a base project with only the BSP. The user will use the features of the SSP and e² studio to add and configure SSP modules that measure the user s response time. The lab will also cover several ways of getting information for the SSP Interfaces from the SSP manual and e² studio. Lab Objectives 1. Create base project with BSP 2. Configure project 3. Add driver layer modules 4. Swap out modules using e² studio Skill Level 1. Knowledge of C 2. Knowledge of SSP Architecture Lab Materials Please verify you have the following materials at your lab station. e² studio v SSP v1.2.0 ARM GCC v Q3 Tera Term SK-S7G2 board Micro USB cable Time to Complete Lab 45 Minutes Lab Sections 1 Create Base Project with BSP Add Driver Layer Modules Using Generated Code Playing the Game Introduction to Synergy Software Package - Short Version v1.0 Page 1 of 24

2 1 Create Base Project with BSP LAB PROCEDURE Overview: This section of the lab will guide the user through the creation of a new project with only the BSP for the SK-S7G2 board. Procedural Steps Step 1.1 Step 1.2 Start e² studio. If there is not a shortcut on your Desktop or in the Start Menu then run C:\Renesas\e2_studio\eclipse\e2studio.exe. The actual folder location may be different on your PC. For the workspace, type or browse to C:\Workspace\6L00IA_Intro_to_SSP and click OK. Step 1.3 If a Toolchain Integration window shows, check the box next to GCC ARM Embedded Click Register. Introduction to Synergy Software Package - Short Version v1.0 Page 2 of 24

3 LAB PROCEDURE Step 1.4 If you see a Welcome window, click on Workbench to continue. Step 1.5 Step 1.6 Step 1.7 Start the Synergy Configuration Project Wizard by clicking File>>New>>Synergy C Project. Set the project name to Intro_to_SSP. We now need to specify a license file. For this training we will use an evaluation license. Click on Change license file in the upper-right of the License section. In the window that pops up click on near the upper-right, then Browse to C:\Renesas\e2_studio\internal\projectgen\arm\Licenses and choose the file SSP_License_Example_EvalLicense_yyyymmdd.xml. The actual folder location and the name of the license file may be different on your PC. Click OK, Apply, OK to save your selection. Introduction to Synergy Software Package - Short Version v1.0 Page 3 of 24

4 LAB PROCEDURE Step 1.8 Confirm the Project Configuration is now filled in as below. Step 1.9 Click Next. Step 1.10 This page of the Project Generator allows us to choose our board, device, toolchain, debugger and SSP version. The device can be selected using the button next to Device but it will also be populated automatically based on the board chosen in the Board drop down. Step 1.11 From the SSP version drop down choose if not already selected. Step 1.12 From the Board drop down choose S7G2 SK. Introduction to Synergy Software Package - Short Version v1.0 Page 4 of 24

5 LAB PROCEDURE Step 1.13 From the Toolchain version drop down choose Your window should look similar to below. Step 1.14 Click Next. Step 1.15 We can now choose a project template to start. Select the S7G2-SK BSP. Introduction to Synergy Software Package - Short Version v1.0 Page 5 of 24

6 LAB PROCEDURE Step 1.16 Click Finish. Step 1.17 If an Open Associated Perspective window shows, click Yes. Step 1.18 Verify that a new editor pane is shown with the title [Intro_to_SSP] Synergy Configuration. At the bottom of this pane you will see multiple tabs that can be chosen. The default tab is Summary which displays information on what features are available. The Synergy Configuration pane shows up in the e² studio editor view just like a file does. You can close the pane by clicking the X next to the title. To reopen it double-click on your project s configuration.xml in Project Explorer. Introduction to Synergy Software Package - Short Version v1.0 Page 6 of 24

7 LAB PROCEDURE Step 1.19 In the Project Explorer pane expand the Intro_to_SSP>>synergy>>ssp>>inc folder and the Intro_to_SSP>>synergy>>ssp>>src folder. Verify your folder structure looks like the below. The modules that have been brought in are the minimum requirements for the SSP to get the MCU to main(). The BSP has code to setup the vector table, stacks, clocks and the C runtime (among other items) and relies on four other modules: r_fmi, r_cgc, r_ioport, and r_elc. The r_cgc and r_ioport modules contain code to configure clocks and port pins, respectively. r_elc provides a list of available Event Link Controller (ELC) events and code to configure them. Step 1.20 Expand the Intro_to_SSP>>src>>synergy_gen folder. Verify the file structure looks like the below. Introduction to Synergy Software Package - Short Version v1.0 Page 7 of 24

8 The synergy_gen folder contains code and header files generated by e² studio. These files are generated whenever the user presses the Generate Project Content button or whenever a project is built. If the user modifies these files and then generates the code again the modifications will be lost. The hal_entry.c file is outside of the synergy_gen folder and therefore it is only generated when the project is created. It contains the function hal_entry() where the user can write code that uses the content generated in synergy_gen. LAB PROCEDURE Step 1.21 Expand all folders underneath Intro_to_SSP>>synergy_cfg>>ssp_cfg. Verify the file structure looks like the below. Introduction to Synergy Software Package - Short Version v1.0 Page 8 of 24

9 e² studio will automatically create configuration files for all modules with default values. These values can then be altered using the Synergy Configurator. Excluding bsp_board_cfg.h, the four remaining configuration files underneath the bsp folder directly relate to four tabs in the Synergy Configurator: bsp_cfg.h o General BSP configuration. o Options are set in the BSP tab. bsp_clock_cfg.h o Sets up system clocks. o Options are set in the Clock tab. bsp_irq_cfg.h o This is an artifact that is left over from previous SSP versions. This file is not used and left for compatibility reasons. bsp_pin_cfg.h o Configures MCU pin settings. o Options are set in the Pins tab. S7G2-SK_BSP.csv o This file is a board pin configuration file generated from the bsp_pin_cfg.h file. It contains Excel CSV format data for the pins used by the project. LAB PROCEDURE Step 1.22 Build the project by selecting Intro_to_SSP in the Project Explorer and then clicking Project>>Build Project. Step 1.23 Verify the project was built successfully by checking for Build Finished in the console pane. The pane should look similar to below. At this point e² studio has generated the required code to get the MCU to main(). The main() function is generated in src>>synergy_gen>>main.c and in turn calls hal_entry() to execute user code. Step 1.24 Double-click on Intro_to_SSP>>src>>hal_entry.c to open the file for editing. Step 1.25 Replace the hal_entry() function with the following. Introduction to Synergy Software Package - Short Version v1.0 Page 9 of 24

10 LAB PROCEDURE void hal_entry(void) { uint32_t i; while (1) { /* Delay */ for (i = 0; i < ; i++); } } /* Toggle LED1 using P6_0. */ R_IOPORT6->PCNTR1 ^= 0x ; Step 1.26 Build the project and verify the build was successful as done previously. You can also build the project by selecting the project from the Project Explorer and clicking the Build button on the toolbar. At this point you may see red underlining on some symbols even though the project built with no errors. If so, right click on the project in the Project Explorer pane and select Index>>Rebuild. This will rebuild the project s symbol index to include the newly generated code eliminating the warnings. We are now ready to debug our project. e² studio automatically creates a debug configuration based on the options you selected when creating the project. Step 1.27 Connect the micro USB cable to your PC and to J19 on the board. Introduction to Synergy Software Package - Short Version v1.0 Page 10 of 24

11 LAB PROCEDURE Step 1.28 Right-click on the Intro_to_SSP project in Project Explorer and click Debug As>>Debug Configurations. Step 1.29 In the Debug Configurations window verify that there is a configuration named Intro_to_SSP Debug underneath Renesas GDB Hardware Debugging. Step 1.30 Select Intro_to_SSP Debug and press the Debug button at the bottom right of the window. Step 1.31 If a Confirm Perspective Switch window shows, click Yes. Step 1.32 After connection the program should halt at the beginning of Reset_Handler(). This is the power on reset address pointed to by the reset vector. Click Run>>Resume to start execution. Step 1.33 Execution will halt at the beginning of main() because e² studio automatically puts a breakpoint there. Click Run>>Resume again and verify that the LED is blinking. Step 1.34 When ready click Run>>Terminate to stop debugging. Click the Synergy Configuration button at the top right of e² studio to switch back to the previous perspective. End of Section Introduction to Synergy Software Package - Short Version v1.0 Page 11 of 24

12 2 Add Driver Layer Modules LAB PROCEDURE Overview: In this section we will add two driver layer modules. These modules will be used to implement a game where the user s response time is measured. When the game is run LED1 will light up at random the goal is to press switch S4 on the board (in the far upper-right corner) as soon as you can once LED1 turns on. Procedural Steps Step 2.1 Verify that you have the Synergy Configuration perspective open. Step 2.2 Step 2.3 Step 2.4 Select the Synergy Configuration tab in the editor pane. If you closed the Synergy Configuration editor tab you can reopen it by double-clicking on Intro_to_SSP>>configuration.xml. Select the Threads tab at the bottom of the Synergy Configuration pane. Verify that there is an entry labeled HAL/Common in the Threads list. The Threads tab is where the user adds and configures SSP modules to be used in their application. As the name indicates, RTOS threads are added in this tab. In this lab we are not using an RTOS so we will only use the HAL/Common thread. The HAL/Common thread is listed for every project and is not a real RTOS thread. It contains the minimum required modules for SSP and could be considered the system thread or super-loop for an RTOSless system. Step 2.5 Click on HAL/Common Stacks in the Threads tab and verify that the FMI, CGC, ELC and I/O Port modules are already added. The FMI, CGC, ELC and I/O Port modules are required by the BSP and therefore required by every project. Only one instance of these modules is allowed. We will use an external interrupt pin for detecting when the switch has been pressed. S4 is connected to Port 00 Pin 06 which is external IRQ11. We will use the r_icu module which implements the external IRQ interface to configure the interrupt and set a callback function. Introduction to Synergy Software Package - Short Version v1.0 Page 12 of 24

13 LAB PROCEDURE Step 2.6 On the right side of the Threads tab in the HAL/Common Stacks section click and select Driver>>Input>>External IRQ Driver on r_icu. Step 2.7 Verify that a new item was added to the HAL/Common Stacks list. Notice the red text inside the new External IRQ module. This alerts the user that something is not configured properly. The user can see what the issue is by hovering their mouse over the module. Step 2.8 Hover your mouse over the g_external_irq0 instance and verify that an error is shown. The error indicates that this module requires an interrupt to be enabled for proper use and the interrupt is currently disabled in the module s properties. Step 2.9 Click on the g_external_irq0 instance and verify that its properties are shown in the Properties pane. Modules come with a default configuration. This configuration will need to be modified by the user to meet the requirements of their design. Introduction to Synergy Software Package - Short Version v1.0 Page 13 of 24

14 Step 2.10 In the Properties window for g_external_irq0 change the Channel option to 11. LAB PROCEDURE Step 2.11 The game expects to be alerted of a switch press by calling the switch_callback function. In the Properties window for g_external_irq0 change the Callback option to switch_callback. Typically when specifying a callback function the user is responsible for defining said function in their own code. In this case the callback is being handled within source files for the game we will be adding in a later step. Step 2.12 The interrupt for External IRQ channel 11 needs to be enabled for proper use (and to eliminate the red text warning). Change Interrupt Priority in the Properties window to Priority 8. Step 2.13 Verify that red text is no longer shown on the g_external_irq0 instance in the HAL/Common Stacks list. Step 2.14 Verify that your Properties window looks like the image below. Updated properties are highlighted below. The game also requires two timers. One timer is used for measuring the response time of the player and the other is used to turn on LED1 at random times. We will start by creating the random timer to play the game. The game is expecting the name of this timer to be g_game_timer. Step 2.15 Add a new timer module to the HAL/Common Stacks list. Click Driver on r_gpt. and select Driver>>Timers>>Timer Introduction to Synergy Software Package - Short Version v1.0 Page 14 of 24

15 LAB PROCEDURE Step 2.16 Configure the timer module instance using the Properties window to match the highlighted settings below. The timer used for measuring the response time of the user should be named g_timer. This timer will be used as a free counting timer and will not have a callback. Step 2.17 Add a new timer module to the HAL/Common Stacks list. Click Driver on r_gpt. and select Driver>>Timers>>Timer Note that immediately after creating the second timer there is no error shown for having two GPT timers that use the same channel. This is because there are cases where the user might wish to have multiple configurations for the same channel. In such a case the user would be responsible for maintaining and using the separate configurations. Introduction to Synergy Software Package - Short Version v1.0 Page 15 of 24

16 LAB PROCEDURE Step 2.18 Configure the module using the Properties window to match the highlighted settings shown below. Setting the Period Value and Period Unit as shown above puts the timer in free run mode as detailed in the documentation for the module. A priority for the interrupt is given because even though the application is not using it the module still needs to it internally. Step 2.19 Press the Generate Project Content button at the top right of the Synergy Configuration pane. End of Section Introduction to Synergy Software Package - Short Version v1.0 Page 16 of 24

17 3 Using Generated Code LAB PROCEDURE Overview: In this section we will use code generated by e² studio for the SSP modules that we configured in the previous section. This section will cover several ways of getting documentation for the SSP Interfaces. Procedural Steps Step 3.1 Step 3.2 Before we start using the generated code we will copy a few files into the project. This will reduce the amount of code you have to write and focus only the parts of the code you need to learn. The default folder for these files is the root workspace folder e.g. C:\Workspace\6L00IA_Intro_to_SSP. Go to the SourceFiles subfolder. Copy the 3 files in this folder into Intro_to_SSP>>src folder. You can also drag the files from the Windows Explorer and drop them into the Project Explorer pane in e² studio. Make sure the src folder looks like below. Step 3.3 Step 3.4 Step 3.5 Open src>>response_time_port.c. This is where we will use the code that was generated by e² studio in the previous section. Find the comment /** OPEN EXTERNAL IRQ HERE */ in the response_port_init() function. Instance structures are given the name the user specifies in the Properties window when configuring the module. For the External IRQ module we provided the name g_external_irq0. Type the following and then hit Control + Space (if the suggestion window does not automatically come up). Make sure you use the dot operator (.) after g_external_irq0. err = g_external_irq0. Step 3.6 Verify that a window pops up similar to the one below. Introduction to Synergy Software Package - Short Version v1.0 Page 17 of 24

18 The autocomplete feature in e² studio is activated by typing in a symbol (or part of a symbol) then pressing Control + Space. e² studio will then provide a list of possible completions. In this example, e² studio lists the members inside of the g_external_irq0 instance structure for quick selection. The autocomplete feature can speed up code development by not requiring the user to constantly keep referring to previous code and other files. As mentioned the autocomplete works on partial symbols too. Type in g_ext and hit Control + Space to quickly get access to g_external_irq0. LAB PROCEDURE Step 3.7 In the pop-up window use the keyboard (arrow keys and Enter) or mouse to choose p_api. Step 3.8 Add the arrow operator ( ) to the end of the line to dereference the pointer. err = g_external_irq0.p_api-> Step 3.9 Use autocomplete to see the functions available for this Interface. Choose open(). Using e² studio s autocomplete feature is an easy and quick way to see all of the functions available for an interface. For more information on API functions and the available interfaces, you can consult the Doxygen manual. Step 3.10 Add an opening parentheses, (, and activate autocomplete. e² studio is now showing us the parameters for the External IRQ open() function. This information is based upon the function prototypes provided in the External IRQ Interface. As with all SSP modules the open() function takes 2 parameters: a pointer to the control structure and a pointer to the configuration structure. Both of these pointers are stored in the instance structure we are using, g_external_irq. Step 3.11 Use the autocomplete feature of e² studio to fill in the parameters to the open() function using the g_external_irq0 instance structure. Introduction to Synergy Software Package - Short Version v1.0 Page 18 of 24

19 LAB PROCEDURE err = g_external_irq0.p_api->open(g_external_irq0.p_ctrl, g_external_irq0.p_cfg); Note that ampersands (&) are not required before the parameters as instance structures store pointers to the structures, not the structures themselves. Pointers are easy to find in Renesas code as they will always have a p_ prefix. Step 3.12 Look directly beneath the line of code you just wrote and find the comment /** OPEN TIMER HERE */. Step 3.13 Type the following. Use the autocomplete feature to complete the call to the open() function. err = g_timer.p_api->open(g_timer.p_ctrl, g_timer.p_cfg); We OR the result into the err variable so as not lose any errors that may have been returned previously. Step 3.14 Hold Control and hover over the word open in the API call that was just written. Verify that the word turns into a link similar to the below. err = g_timer.p_api->open(g_timer.p_ctrl, g_timer.p_cfg); e² studio is able to follow functions, structure members, enumerations to where they were declared. This feature is activated by: Holding Control and clicking on the item OR Highlighting the item, right-clicking on it, and choosing Open Declaration. The user can tell if a link to the declaration is available by holding Control and hovering over the item. Step 3.15 Hold Control and click on the word open in the Timer API call. Verify that e² studio opens up the file synergy>>ssp>>inc>>driver>>api>>r_timer_api.h and places the cursor on the open() function in the timer_api_t structure. All of the interface API functions can be seen in the interface s API structure. There are Doxygen comments above each function pointer in the structure that can help the user understand how the function works. e² studio may fold these comments by default. If this is the case then the user can expand the comments by clicking the plus sign on the left side of the editor next to each comment block. Step 3.16 Switch back to the response_time_port.c editor tab and find the response_timer_start() function. Holding the Alt key and pressing the Left Arrow key is a quick way to navigate back to your last position. Introduction to Synergy Software Package - Short Version v1.0 Page 19 of 24

20 LAB PROCEDURE Step 3.17 We will now add code in response_timer_start() with API calls for resetting and starting the timer that will measure the user s response time. Start by typing the following to reset the timer. g_timer.p_api-> Step 3.18 Use autocomplete to see if there is a function in the interface API that corresponds to resetting the timer. When found use the instance structure g_timer to complete the API call. Step 3.19 Use the same process to add code to start the timer. Verify that your code looks like the code below. /** Start the timer that will be used for measuring response time. */ void response_timer_start (void) { /** Reset timer. */ /** RESET TIMER USING API->RESET FUNCTION */ g_timer.p_api->reset(g_timer.p_ctrl); } /** Start timer. */ /** START TIMER USING API->START FUNCTION */ g_timer.p_api->start(g_timer.p_ctrl); In the previous steps the Timer Interface API functions were simple and required no extra parameters other than a pointer to the control structure. For more complicated API calls the user will likely need to read the documentation. Step 3.20 Scroll down the file and find the response_timer_stop() function. Step 3.21 Type following to stop the timer. g_timer.p_api->stop(g_timer.p_ctrl); Step 3.22 Scroll down the file and find the response_timer_counter_get() function. The response_timer_counter_get() function is responsible for reading the counter value of the g_timer in order to measure the user s response time. This means we need a Timer Interface API function for reading the counter value. We will use the SSP Doxygen documentation to look for this function. Step 3.23 Go to C:\Renesas\Synergy\SSP_Documentation. This is the default installation directory for the SSP User s Manual. The actual folder location may be different on your PC. Step 3.24 Unzip the ssp-user-manual-html-xxx.zip document, where xxx is version numbers of the user s manual and the SSP. Step 3.25 Navigate to the unzipped folder and double-click on the ssp-user-manual-html-xxx.html document. Step 3.26 Verify that a browser window is opened and it looks like the image below. Introduction to Synergy Software Package - Short Version v1.0 Page 20 of 24

21 LAB PROCEDURE Step 3.27 In the search bar at the top right of the page type in the word timer. Step 3.28 Verify that a list of items is shown that resembles the image below. In the list click Timer Interface. The page that is now presented is the Doxygen output of the Timer Interface header file. Along with the information the user can see in the header file directly, Doxygen also provides links making it easy to look up many pieces of the interface. Step 3.29 In the Classes section near the top of the page click on the link for timer_api_t. Step 3.30 In the Public Attributes list look for a function that could be used for getting the counter value. The intuitively named counterget() function seems like a good candidate. Step 3.31 Click on the counterget() function to get more information on the function. From the documentation we can see that the counterget() function takes two parameters: a pointer for the control block and a pointer to store the current counter value. Step 3.32 Switch back to the response_time_port.c editor tab and find the response_timer_counter_get() function. Step 3.33 Type following to get the counter value. g_timer.p_api->counterget(); Introduction to Synergy Software Package - Short Version v1.0 Page 21 of 24

22 LAB PROCEDURE Step 3.34 Hold Shift and hover over the counterget() function call and verify that a window pops up showing the prototype for the function along with its Doxygen comments. From the documentation we can see that the counter value is stored in a pointer provided by the user p_value. In general, when information other than an error status needs to be provided by the function it is done by providing a pointer of where to store the information as an argument. The counterget() Timer Interface function is an example of this. Step 3.35 Finish the API call for reading the counter. Use temp_counter for holding the counter value. g_timer.p_api->counterget(g_timer.p_ctrl, &temp_counter); End of Section Introduction to Synergy Software Package - Short Version v1.0 Page 22 of 24

23 4 Playing the Game LAB PROCEDURE Overview: In this section we will play the game that we created using e² studio. We will be starting with the project as configured at the end of Section 4. Procedural Steps Step 4.1 Open the file src>>hal_entry.c. The game must be initialized by first calling the response_init() function after which the game can be started by calling response_play(). Once the game is started LED1 will turn on five times after a random delay. When LED1 turns on you should press S4 as quickly as possible! After the five measurements the function will return a float that holds the user s average response time in seconds. If the user does not put a breakpoint on the line with response_play() then the game will continue to run indefinitely. Step 4.2 Replace the existing LED blinking code in the file so that it looks like the code below. Remember to use autocomplete. /* HAL-only entry function */ #include "hal_data.h" #include "response_time.h" float g_response_time; void hal_entry(void) { response_init(); } while (1) { g_response_time = response_play(); } Step 4.3 Step 4.4 Step 4.5 Build the project. Start a debug session. Place a breakpoint on the line with the following code: g_response_time = response_play(); Step 4.6 Debug the application. Before the game is run the breakpoint on the response_play() line will be triggered. Click Run>>Resume and play the game! Remember that the LED will light up 5 times (5 response time measurements) before the game is finished and the breakpoint is hit. Introduction to Synergy Software Package - Short Version v1.0 Page 23 of 24

24 LAB PROCEDURE Step 4.7 When the game has finished the breakpoint will be triggered again. You can find your average response time by either hovering over the g_response_time variable or by adding the g_repsonse_time variable to the Expressions pane. Step 4.8 Step 4.9 Click Run>>Resume to play the game again. When done, terminate the debug session. End of Section END OF LAB THANK YOU FOR ATTENDING THIS LAB Introduction to Synergy Software Package - Short Version v1.0 Page 24 of 24