Synergy Software Package User's Manual
Watchdog Driver

Table of Contents

Watchdog Timer HAL Module Introduction

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

Watchdog Timer HAL Module Features

The WDT HAL module has 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 Watchdog Timer (WDT) peripheral, which uses an external clock.
  • The WDT can be configured in register start mode through the WDT registers.
  • Supports automatic hardware configuration after reset.
  • The WDT can be started from the application.
WDT_BD.png
Watchdog Timer HAL Module Block Diagram

Watchdog Timer Hardware Support Details

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

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 

 

MCU Group Clock Divide by 4, 64, 128, 512, 2,048, or 8,192 Count down Register start mode Auto start 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/under flow
refresh error 		Refresh error and under flow error detect Reading the counter value
S124 ⌧ ⌧ ✓ ✓ ✓ ✓
S128 ⌧ ⌧ ✓ ✓ ✓ ✓
S1JA ⌧ ⌧ ✓ ✓ ✓ ✓
S3A1 ⌧ ⌧ ✓ ✓ ✓ ✓
S3A3 ⌧ ⌧ ✓ ✓ ✓ ✓
S3A6 ⌧ ⌧ ✓ ✓ ✓ ✓
S3A7 ⌧ ⌧ ✓ ✓ ✓ ✓
S5D3 ⌧ ⌧ ✓ ✓ ✓ ✓
S5D5 ⌧ ⌧ ✓ ✓ ✓ ✓
S5D9 ⌧ ⌧ ✓ ✓ ✓ ✓
S7G2 ⌧ ⌧ ✓ ✓ ✓ ✓

Watchdog Timer HAL Module APIs Overview

The WDT HAL module defines APIs for opening, refreshing, reading and getting 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.

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 WDT 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 WDT 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 WDT.
statusClear g_wdt0.p_api->statusClear( g_wdt0.p_ctrl, clear);
Clear the status flags of the WDT.
counterGet g_wdt0.p_api->counterGet(g_wdt0.p_ctrl, &counter);
Read the current WDT counter value.
timeoutGet 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.

Watchdog Timer HAL Module Operational Overview

Synergy MCUs have two watchdog peripherals- the watchdog timer (WDT) and the independent watchdog timer (IWDT). When selecting between them, consider these factors:

  • The WDT can be started from the application.
  • The WDT can be configured in register start mode through the WDT registers. The WDT can also be configured by hardware automatically after reset using parameters stored in Option Function Select Register 0 (OFS0).
  • The IWDT has its own clock source which improves safety.
  • The IWDT is configured by hardware automatically after reset using parameters stored in the Option Function Select Register 0 (OFS0).

Watchdog Timer HAL Module Important Operational Notes and Limitations

Watchdog Timer HAL Module Operational Notes

The WDT HAL module configures the WDT Interface. 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

The following figure shows an example of the operation of the WDT. 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 WDT resets the device or generates an NMI.

WDT_OD.png
Watchdog Timer HAL Module Operational Diagram

The WDT can be configured in register start mode through the WDT registers. The WDT can also be configured by hardware automatically after reset using parameters stored in Option Function Select Register 0 (OFS0) as displayed in the following table.

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 figures below.

WDT_CS.png
Watchdog Timer HAL Module Configuration Screens

WDT HAL Module Period Calculation

The WDT operates from PCLKB. Assuming largest parameters for the WDT and a PCLKB of 60 MHz, the time from the last refresh to device reset or NMI generation will be just over 2.2 seconds as detailed below.

PLCKB = 60 MHz

Clock division ratio = PCLKB/8192

Timeout period = 16384 cycles

WDT clock frequency = 60 MHz / 8192 = 7.324 kHz

Cycle time = 1 / 7.324 kHz = 136.53 us

Timeout = 136.53 us x 16384 cycles = 2.23 seconds

Triggering DMAC/DTC with the WDT HAL Module

To trigger a transfer of data using the DMAC or DTC peripheral when the WDT counter underflows or when a refresh is attempted outside of the valid refresh period, configure the WDT to generate an NMI and configure the DMAC/DTC transfer with activation_source set to ELC_EVENT_WDT_UNDERFLOW. See the associated User Guide (DMAC, DTC) for further information.

Triggering Event Link Controller Events with the WDT HAL Module

The WDT can trigger the start of another peripheral using the Event Link Controller (ELC). Refer to the ELC User Guide for a complete list of available peripherals.

Watchdog Timer HAL Module Limitations

  • When using a J-Link debugger the WDT 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 WDT 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 Watchdog Timer HAL Module in an Application

This section describes how to include the 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 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 Watchdog Timer Driver is g_wdt0. This name can be changed in the associated Properties window.)

Watchdog Timer HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_wdt0 Watchdog Driver on r_wdt Threads New Stack>Driver> Monitoring> Watchdog Driver on r_wdt

When the Watchdog Timer Driver on r_wdt 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.

WDT_MS.png
Watchdog Timer HAL Module Stack

Configuring the Watchdog Timer HAL Module

The 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 Watchdog Timer HAL Module on r_wdt

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
Name g_wdt0 Module name.
Start Mode Register, Auto

Default: Register 		Configures the start mode as register start or auto-start.
Start Watchdog After Configuration True, False

Default: True 		Controls whether WDT is started during initialization.
Timeout 1024 cycles, 4096 cycles, 8192 cycles, 16384 cycles

Default: 16384 cycles 		WDT timeout period.
Clock Division Ratio PCLK/4, PCLK/64, PCLK/128, PCLK/512, PCLK/2048, PCLK/8192

Default: PCLK/8192 		WDT clock divider.
Window Start Position 100% (Window Position Not Specified), 75%, 50%, 25%

Default: 100% (Window Position Not Specified) 		Permitted refresh period start postion.
Window End Position 0% (Window Position Not Specified), 25%, 50%, 75%

Default: 0% (Window Position Not Specified) 		Permitted refresh period end postion.
Reset Control Reset Outpout, NMI Generated

Default: Reset Output 		Select whether WDT should reset the MCU or generate an NMI.
Stop Control WDT Count Enabled in Low Power Mode, WDT Count Disabled in Low Power Mode

Default: WDT Count Disabled in Low Power Mode 		Select whether the WDT should stop counting in low power modes.
NMI Callback NULL Callback. A user callback function can be registered in 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 WDT 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. See the description in the operational overview section earlier in this document.

Configuring the Interrupts for the WDT HAL Module

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

To enable interrupts, set the priority of the CWDT> CWDT NMIUNDF N n. This sets BSP_IRQ_CFG_WDT_UNDERFLOW in ssp_cfg/bsp/bsp_irq_cfg.h to the priority level selected.

When the CWDT 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.

Watchdog Timer HAL Module Clock Configuration

The WDT clock is based on the PCLKB frequency. You can set the PCLKB frequency using the clock configurator in the ISDE or using the CGC Interface at run-time. The maximum timeout period with PCLKB running at 60 MHz is approximately 2.2 seconds.

Watchdog Timer HAL Module Pin Configuration

The WDT does not require pins for its operation.

Using the Watchdog Timer HAL Module in an Application

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

  1. Initialize the WDT HAL module in either register start mode or auto-start mode using the wdt_api_t::open API.
  2. Read the configuration of the WDT HAL module in either register start mode or auto start mode with the wdt_api_t::cfgGet API.
  3. Refresh the watchdog timer using the wdt_api_t::refresh API.
  4. Read the WDT status flags using the wdt_api_t::statusGet API.
  5. Clear the status flags and error flags of the WDT HAL module using the wdt_api_t::statusClear API.
  6. Read the current WDT counter value using the wdt_api_t::counterGet API.
  7. Read the watchdog timeout values using the wdt_api_t::timeoutGet API.

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

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