Synergy Software Package User's Manual
Tutorial: Using HAL Drivers - Programming the WDT

Table of Contents

Application WDT

This application uses the WDT Interface implemented by the WDT HAL Driver WDT. This document describes how to use the ISDE and SSP to create an application for the Synergy MCU Watchdog Timer (WDT) peripheral. This application makes use of the following SSP modules:

Creating a WDT Application Using the Synergy SSP and ISDE

Using the SSP and the e2 studio ISDE

The Synergy Software Package (SSP) from Renesas provides a complete driver library for developing Synergy applications. The SSP provides Hardware Abstraction Layer (HAL) drivers, Board Support Package (BSP) drivers and higher level Framework applications for the developer to use to create applications. The SSP is integrated into the Renesas e2 studio Integrated Solution Development Environment (ISDE) 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.

figure-app-wdt-image1.png
WDT Application Flow Diagram

WDT Application flow

These are the main parts of the WDT application:

  1. main() calls hal_entry(). The function hal_entry() is created by the SSP with a placeholder for user code. The code for the WDT will be added to this function.
  2. Initialize the WDT, but do not start it.
  3. Start the WDT by refreshing it.
  4. The red LED is flashed 30 times and refreshes the watchdog each time the LED state is changed.
  5. Flash the green LED but DO NOT refresh the watchdog. After the timeout period of the watchdog the device will reset which can be observed by the flashing red LED again as the sequence repeats.

Creating the Project with the ISDE

Start the ISDE and choose a workspace folder in the Workspace Launcher. Configure a new Synergy project as follows.

Note
The e2 studio screens shown in this manual are examples. Some details may differ between different releases of the e2 studio ISDE and the SSP.
  1. Select File > New > Synergy C/C++ Project. Then select the template for the project.
    figure-isde-usage-notes-projectConfiguratorNewProject.png
    figure-isde-usage-notes-projectTemplates.png
    Creating a New Project
  2. In the ISDE Project Configuration (Synergy Project) window, enter a project name (for example, WDT_Application). Select the toolchain. If you want to choose a new location for the project, deselect Use default location. Click Next.
    figure-app-wdt-image3.png
    Project Configuration (Part 1)

  3. This application runs on the Synergy S7G2 based DK-S7G2 board. So, for the Board select S7G2 DK.

    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. No RTOS is being used in this application but it can be left at the default. Click Next to configure the project.

    figure-app-wdt-image4.png
    Project Configuration (Part 2)

    The project template is now selected. As no RTOS is required select BSP.

    figure-app-wdt-image5.png
    Project Configuration (Part 3)
  4. Click Finish.

The ISDE 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 the ISDE

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

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

figure-app-wdt-image6.png
Selecting a Perspective

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

  1. In order to configure the project settings ensure the Synergy 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 Synergy Configuration perspective is selected and double-click on the configuration.xml file in the Project Explorer pane on the right side of the ISDE.
    figure-app-wdt-image7.png
    Synergy 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.
figure-app-wdt-image8.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 Synergy 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. Using 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.

figure-app-wdt-image9.png
Clock Configuration

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.

Threads Tab

You can add any driver to the project using the Threads tab. The HAL drivers for the Clock Generation Circuit, the Event Link Controller, and the IO port pins are added automatically by the ISDE when the project is configured. The WDT application uses no ThreadX Resources, so you only need to add the HAL WDT driver.

figure-app-wdt-image18.png
Threads Tab

The HAL/Common Stacks panel and is populated with the modules preselected by the ISDE.

  1. Click on New Stack to find a pop-up window with the available HAL level drivers.
  2. Select Watchdog Driver on r_wdt.
    figure-app-wdt-image19.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 Synergy Configuration perspective is selected.
figure-app-wdt-image20.png
Module Properties

Change parameter Start Watchdog After Configuration from True to False. The other parameters can be left with their default values. Setting Start Watchdog After Configuration to False instructs the WDT driver (via its open API call) to configure the WDT but not to start it. It will be started later by refreshing it.

figure-app-wdt-image12.png
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.

figure-app-wdt-image14.png
Generate Project Content Button

The ISDE 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 when after they are added in the Threads Tab.

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

  1. HAL_Drivers -> r_cgc
  2. HAL_Drivers -> r_elc
  3. HAL_Drivers -> r_ioport
  4. HAL_Drivers -> r_wdt
  5. HAL_Drivers -> r_fmi
figure-app-wdt-image10.png
Component Selection
Note
The list of modules displayed in the Components tab depends on the installed SSP version.

WDT Generated Project Files

Pressing the Generate Project Content button performs the following tasks.

  • r_wdt folder and WDT driver contents created at:
    • synergy/ssp/src/driver/
  • r_wdt_api.h created in:
    • synergy/ssp/inc/driver/api
  • r_wdt.h created in:
    • synergy/ssp/inc/driver/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:

  • synergy_cfg/ssp_cfg/driver/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.

figure-app-wdt-image15.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 pressed and so any changes will be overwritten.

r_ioport folder is not created at ssp/src/driver 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 src/synergy_gen/hal_data.h – see later in this document for further details. For the same reason the other IOPORT header files – synergy/ssp/inc/api/r_ioport_api.h and synergy/ssp/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 the ISDE also generates files containing configuration data for the WDT and a file where user code can safely be added. These files are shown below.

figure-app-wdt-image16.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
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 ISDE generated project. In addition this file includes external references to the g_wdt 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 pressed 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"
static wdt_instance_ctrl_t g_wdt0_ctrl;
static const wdt_cfg_t g_wdt0_cfg =
{ .start_mode = WDT_START_MODE_REGISTER,
.autostart = false,
.timeout = WDT_TIMEOUT_16384,
.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_wdt_ctrl which is the control structure for this instance of the WDT HAL driver. This structure should not be initialised as this is done by the driver when it is opened.

The contents of g_wdt_cfg are populated in this file using the g_wdt Watchdog Driver on WDT Properties pane in the ISDE Project Configuration HAL tab. If the contents of this structure do not reflect the settings made in the ISDE, ensure the Project Configuration settings are saved in the ISDE before pressing the Generate Project Content button.

Warning
This file is regenerated each time Generate Project Content is pressed 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 */
extern void hal_entry(void);
int main(void)
{
hal_entry ();
return 0;
}
Warning
This file is regenerated each time Generate Project Content is pressed 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.

/* HAL-only entry function */
#include "hal_data.h"
#define RED_LED_NO_OF_FLASHES 30
#define RED_LED_PIN IOPORT_PORT_06_PIN_01 ← In case of SK-S7G2
#define GREEN_LED_PIN IOPORT_PORT_06_PIN_00 ← In case of SK-S7G2
#define RED_LED_DELAY_COUNT 1500000
#define GRN_LED_DELAY_COUNT 1200000
volatile uint32_t delay_counter;
volatile uint16_t loop_counter;
void hal_entry(void)
{
/* TODO: add your own code here */
/* Open the WDT */
g_wdt0.p_api->open(g_wdt0.p_ctrl, (wdt_cfg_t *const)g_wdt0.p_cfg);
/* Start the WDT by refreshing it */
g_wdt0.p_api->refresh(g_wdt0.p_ctrl);
/* Flash the red LED and tickle the WDT for a few seconds */
for(loop_counter=0; loop_counter<RED_LED_NO_OF_FLASHES; loop_counter++)
{
/* Turn red LED on */
g_ioport.p_api->pinWrite(RED_LED_PIN, IOPORT_LEVEL_HIGH);
/* Delay */
for(delay_counter=0; delay_counter<RED_LED_DELAY_COUNT; delay_counter++);
/* Refresh WDT */
g_wdt0.p_api->refresh(g_wdt0.p_ctrl);
/* Turn red off */
g_ioport.p_api->pinWrite(RED_LED_PIN, IOPORT_LEVEL_LOW);
/* Delay */
for(delay_counter=0; delay_counter<RED_LED_DELAY_COUNT; delay_counter++);
/* Refresh WDT */
g_wdt0.p_api->refresh(g_wdt0.p_ctrl);
}
/* Flash green LED but STOP tickling the WDT. WDT should reset the
device */
while(1)
{
/* Turn green LED on */
g_ioport.p_api->pinWrite(GREEN_LED_PIN, IOPORT_LEVEL_HIGH);
/* Delay */
for(delay_counter=0; delay_counter<GRN_LED_DELAY_COUNT; delay_counter++);
/* Turn green off */
g_ioport.p_api->pinWrite(GREEN_LED_PIN, IOPORT_LEVEL_LOW);
/* Delay */
for(delay_counter=0; delay_counter<GRN_LED_DELAY_COUNT; delay_counter++);
}
}

The WDT HAL driver is called through the interface g_wdt_on_wdt defined in r_wdt.h. The WDT HAL driver is opened through the open API call using the instance defined in r_wdt_api.h:

g_wdt0.p_api->open(g_wdt0.p_ctrl, (wdt_cfg_t *const)g_wdt0.p_cfg);

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

The WDT is started and refreshed through the API call:

g_wdt0.p_api->refresh(g_wdt0.p_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 the ISDE Build > Build Project. The project should build without errors.

To debug the project

  1. Connect the JLink debugger between the target board and host PC. Apply power to the board.
  2. In the Project Explorer pane on the right side of the ISDE 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.
    figure-app-wdt-image17.png
    Debug Configuration
  4. Press the Debug button. Switch (Yes) to the Debug perspective if asked.
  5. The code should run to 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. However, this sequence does not occur when using the debugger because the WDT does not run when connected to the debugger.

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