Synergy Software Package User's Manual
Watchdog Driver on r_iwdt

Table of Contents

Independent Watchdog Timer HAL Module Introduction

The Independent Watchdog Timer (IWDT) HAL module provides a high-level API for watchdog timer applications and uses the IWDT peripheral on the Synergy MCU. A user-defined callback can be created to respond to event notifications.

Independent Watchdog Timer HAL Module Features

The IWDT HAL module supports the following key features:

  • When the WDT underflows or is refreshed outside of the permitted refresh window, one of the following events can occur:
    • Resetting of the device
    • Generation of an NMI
  • Supports the internal Watchdog timer peripheral (IWDT), which has its own clock source which improves safety.
  • Supports automatic hardware configuration after reset.
IWDT_BD.png
Independent Watchdog Timer HAL Module Block Diagram

Independent Watchdog Timer Hardware Support Details

The following hardware features are, or are not, supported by SSP for IWDT:

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU Group Count down Autostart mode Reset output Interrupt request output
S124 ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓
MCU Group Sleep mode
count stop
control output 		Event link
function through
ELC HAL driver 		Window
function 		Conditions for stopping
the Counter –
reset/underflow-
refresh error 		Refresh
error and
under flow
error detect 		Reading
the counter
value
S124 ⌧ ⌧ ✓ ✓ ✓ ✓
S128 ⌧ ⌧ ✓ ✓ ✓ ✓
S1JA ⌧ ⌧ ✓ ✓ ✓ ✓
S3A1 ⌧ ⌧ ✓ ✓ ✓ ✓
S3A3 ⌧ ⌧ ✓ ✓ ✓ ✓
S3A6 ⌧ ⌧ ✓ ✓ ✓ ✓
S3A7 ⌧ ⌧ ✓ ✓ ✓ ✓
S5D3 ⌧ ⌧ ✓ ✓ ✓ ✓
S5D5 ⌧ ⌧ ✓ ✓ ✓ ✓
S5D9 ⌧ ⌧ ✓ ✓ ✓ ✓
S7G2 ⌧ ⌧ ✓ ✓ ✓ ✓
MCU Group Selecting the clock frequency
division ratio after a reset 		Selecting the timeout period of the
independent watchdog timer
S124 ⌧ ✓ Set by the OFS registers in the BSP
S128 ⌧ ✓ Set by the OFS registers in the BSP
S1JA ⌧ ✓ Set by the OFS registers in the BSP
S3A1 ⌧ ✓ Set by the OFS registers in the BSP
S3A3 ⌧ ✓ Set by the OFS registers in the BSP
S3A6 ⌧ ✓ Set by the OFS registers in the BSP
S3A7 ⌧ ✓ Set by the OFS registers in the BSP
S5D3 ⌧ ✓ Set by the OFS registers in the BSP
S5D5 ⌧ ✓ Set by the OFS registers in the BSP
S5D9 ⌧ ✓ Set by the OFS registers in the BSP
S7G2 ⌧ ✓ Set by the OFS registers in the BSP

Independent Watchdog Timer HAL Module APIs Overview

The IWDT HAL module defines APIs for open, refresh, read and get status. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

Independent Watchdog Timer HAL Module API Summary

Function Name Example API Call and Description
cfgGet g_wdt0.p_api->cfgGet(g_wdt0.p_ctrl, g_wdt0.p_cfg);
Initialize the iWDT in register start mode. In auto-start mode with NMI output it registers the NMI callback.
open g_wdt0.p_api->open(g_wdt0.p_ctrl, g_wdt0.p_cfg);
Initialize the iWDT in register start mode. In auto-start mode with NMI output it registers the NMI callback.
refresh g_wdt0.p_api->refresh(g_wdt0.p_ctrl);
Refresh the watchdog timer.
statusGet g_wdt0.p_api->statusGet( g_wdt0.p_ctrl, &status);
Read the status of the iWDT.
statusClear g_wdt0.p_api->statusClear( g_wdt0.p_ctrl, clear);
Clear the status flags of the iWDT.
counterGet g_wdt0.p_api->counterGet(g_wdt0.p_ctrl, &counter);
Read the current iWDT counter value.
tiimeoutGet g_wdt0.p_api->timeoutGet(g_wdt0.p_ctrl, &timeout);
Read the watchdog timeout values.
versionGet g_wdt0.p_api->versionGet(&version);
Retrieve the API version using the version pointer.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS Function successfully executed.
SSP_ERR_ASSERTION Null Pointer(s).
SSP_ERR_INVALID_ARGUMENT One or more configuration options is invalid.
SSP_ERR_INVALID_MODE An attempt to open the WDT in register-start mode when the OFS0 register is configured for auto-start mode. Or to open the WDT in auto-start mode when the OSF0 is configured for register start mode.
SSP_ERR_ABORTED Invalid clock divider for this watchdog.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

Independent Watchdog Timer HAL Module Operational Overview

The IWDT HAL module configures the IWDT Interface. When the IWDT underflows or is refreshed outside of the permitted refresh window, one of the following events can occur:

  • Resetting of the device
  • Generation of an NMI

The following figure shows an example of the operation of the IWDT. When refreshed in the valid refresh period of the counter the timer count value is reset. If the count is allowed to underflow or refresh occurs outside of the valid refresh period, the IWDT resets the device or generates an NMI.

IWDT_OD.png
Independent Watchdog Timer HAL Module Operational Diagram

All series of Synergy microcontrollers have an option-setting Memory which can be used to set the operating state of peripherals after a reset. The OFS can be used to set the state of the IWDT, WDT, LVD and CGC HOCO.

The following table details which parameters of the IWDT can be configured by the OFS registers.

Note
The IWDT can only be configured via the OFS registers.  The IWDT does not support Register Start mode.
Control Description
IWDT Start Mode Select Automatically starts the IWDT after a Reset, if enabled.
IWDT Timeout Period Specifies the IWDT timeout (number of clock cycles)
128 cycles
512 cycles
1024 cycles
2048 cycles
IWDT-Dedicated Clock Frequency Division Ratio 1
1/16
1/32
1/64
1/128
1/256
IWDT Window End Position 25
%50
%75
%100% (no window end position set)
IWDT Window Start Position 25
%50
%75
%100% (no window start position set)
IWDT Reset Interrupt Request The IWDT can either generate an Interrupt Signal or a Reset signal.
IWDT Stop Control The IWDT can continue to count or Stop counting in Low Power Mode.
Note
For further information on the contents of the OFS0 register, see the Synergy MCU hardware manual.

The OFS register values are set via the properties dialog of the BSP tab of Synergy Configuration editor as shown in the following figures:

IWDT_CS.png
Independent Watchdog Timer HAL Module Configuration Screens

Independent Watchdog Timer HAL Module Important Operational Notes and Limitations

Independent Watchdog Timer HAL Module Operational Notes

IWDT HAL Module Period Calculation

The IWDT operates from IWDTCLK. Assuming largest parameters for the WDT and an IWDTCLK frequency of 15 kHz, the time from the last refresh to device reset or NMI generation will be just under 35 seconds as detailed below.

IWDTLCK = 15 kHz

Clock division ratio = IWTCLK/256

Timeout period = 2048 cycles

IWDT clock frequency = 15 kHz / 256 = 58.59 Hz

Cycle time = 1 / 58.59 Hz = 17.07 ms

Timeout = 17.07 ms x 2048 cycles = 34.95 seconds

Triggering DMAC/DTC with the IWDT HAL Module

To trigger a transfer of data using the DMAC or DTC peripheral when the watchdog counter underflows or when a refresh is attempted outside of the valid refresh period, configure the DMAC/DTC transfer with activation_source set to ELC_EVENT_IWDT_UNDERFLOW. See the appropriate module guide for additional information.

Triggering ELC Events with the IWDT HAL Module

The IWDT can trigger the start of other peripherals as available with the Event Link Controller (ELC). See the ELC HAL module guide for additional information.

Independent Watchdog Timer HAL Module Limitations

  • When using a J-Link debugger, the IWDT counter does not count and therefore will not reset the device or generate an NMI.
  • When there is no active task ready to run, ThreadX puts the MCU into sleep mode. If the IWDT is configured to stop the counter in low-power mode, then your application must restart the timer when used with the ThreadX RTOS.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the Independent Watchdog Timer HAL Module in an Application

This section describes how to include the Independent Watchdog Timer HAL Module in an application using the SSP configurator.

Note
This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Independent Watchdog Timer Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Independent Watchdog Timer Driver is g_iwdt0. This name can be changed in the associated Properties window.)

Independent Watchdog Timer HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_wdt0 IWDT HAL on r_iwdt Threads New Stack> Driver> Monitoring> IWDT HAL on r_iwdt

When the Independent Watchdog Timer Driver on r_iwdt is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

IWDT_MS.png
Independent Watchdog Timer HAL Module Stack

Configuring the Independent Watchdog Timer HAL Module

The Independent Watchdog Timer HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the Independent Watchdog Timer HAL Module on r_iwdt

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
Name g_wdt0 Module name.
NMI Callback NULL Callback. A user callback function can be registered in external_irq_api_t::open. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time the IRQn triggers.

Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configure Option Function Select Register 0 (OFS0) for the IWDT HAL Module

All series of Synergy microcontrollers have an Option-Setting Memory which can be used to set the operating state of peripherals after a reset. The OFS can be used to set the state of the IWDT, WDT, LVD and CGC HOCO.

Configure the Interrupts for the IWDT HAL Module

Use the ISDE to configure the IWDT interrupts in the same way as configuring the other options for the IWDT module. If the IWDT is configured to generate an NMI interrupt on underflow or invalid refresh the interrupt must be enabled in the BSP.

Note
To enable interrupts, set the priority of the IWDT > IWDT NMIUNDF N. This sets BSP_IRQ_CFG_IWDT_UNDERFLOW in ssp_cfg/bsp/bsp_irq_cfg.h to the priority level selected.

When the IWDT NMIUNDF N interrupt is enabled in the BSP, the corresponding ISR will be defined. The ISR will call a user callback function if one was registered in the wdt_api_t::open API.

Independent Watchdog Timer HAL Module Clock Configuration

The IWDT has its own dedicated clock operating at a set frequency which cannot be modified.

Independent Watchdog Timer HAL Module Pin Configuration

The IWDT does not require pins for its operation.

Using the Independent Watchdog Timer HAL Module in an Application

The typical steps in using the Independent Watchdog Timer HAL module in an application are:

  1. Register the IWDT NMI callback using the wdt_api_t::open API.
  2. Read the configuration of the IWDT HAL module using the wdt_api_t::cfgGet API.
  3. Refresh the independent watchdog timer using the wdt_api_t::refresh API.
  4. Read the IWDT status flags using the wdt_api_t::statusGet API.
  5. Clear the IWDT Status and error flags using the wdt_api_t::statusClear API.
  6. Read the current count value of the IWDT using the wdt_api_t::counterGet API.
  7. Read the timeout values of the IWDT HAL module using the wdt_api_t::timeoutGet API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

IWDT_TA.png
Flow Diagram of a Typical Independent Watchdog Timer HAL Module Application