Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Watchdog (WDT) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Watchdog Timer module, including the enabling, disabling, and kicking within the device.

The following driver API modes are covered by this manual:

The following peripherals are used by this module:

The following devices can use this module:

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The Watchdog module (WDT) is designed to give an added level of safety in critical systems, to ensure a system reset is triggered in the case of a deadlock or other software malfunction that prevents normal device operation.

At a basic level, the Watchdog is a system timer with a fixed period; once enabled, it will continue to count ticks of its asynchronous clock until it is periodically reset, or the timeout period is reached. In the event of a Watchdog timeout, the module will trigger a system reset identical to a pulse of the device's reset pin, resetting all peripherals to their power-on default states and restarting the application software from the reset vector.

In many systems, there is an obvious upper bound to the amount of time each iteration of the main application loop can be expected to run, before a malfunction can be assumed (either due to a deadlock waiting on hardware or software, or due to other means). When the Watchdog is configured with a timeout period equal to this upper bound, a malfunction in the system will force a full system reset to allow for a graceful recovery.

Locked Mode

The Watchdog configuration can be set in the device fuses and locked in hardware, so that no software changes can be made to the Watchdog configuration. Additionally, the Watchdog can be locked on in software if it is not already locked, so that the module configuration cannot be modified until a power on reset of the device.

The locked configuration can be used to ensure that faulty software does not cause the Watchdog configuration to be changed, preserving the level of safety given by the module.

Window Mode

Just as there is a reasonable upper bound to the time the main program loop should take for each iteration, there is also in many applications a lower bound, i.e. a minimum time for which each loop iteration should run for under normal circumstances. To guard against a system failure resetting the Watchdog in a tight loop (or a failure in the system application causing the main loop to run faster than expected) a "Window" mode can be enabled to disallow resetting of the Watchdog counter before a certain period of time. If the Watchdog is not reset after the window opens but not before the Watchdog expires, the system will reset.

Early Warning

In some cases it is desirable to receive an early warning that the Watchdog is about to expire, so that some system action (such as saving any system configuration data for failure analysis purposes) can be performed before the system reset occurs. The Early Warning feature of the Watchdog module allows such a notification to be requested; after the configured early warning time (but before the expiry of the Watchdog counter) the Early Warning flag will become set, so that the user application can take an appropriate action.

Note
It is important to note that the purpose of the Early Warning feature is not to allow the user application to reset the Watchdog; doing so will defeat the safety the module gives to the user application. Instead, this feature should be used purely to perform any tasks that need to be undertaken before the system reset occurs.

Physical Connection

The figure below shows how this module is interconnected within the device.

Note
Watchdog Counter of SAM L21/L22/R30/R34/R35 is not provided by GCLK, but it uses an internal 1KHz OSCULP32K output clock.

Special Considerations

On some devices the Watchdog configuration can be fused to be always on in a particular configuration; if this mode is enabled the Watchdog is not software configurable and can have its count reset and early warning state checked/cleared only.

Extra Information

For extra information, see Extra Information for WDT Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for WDT Driver.

API Overview

Data Structures

struct  wdt_conf
 Watchdog Timer configuration structure. More...
 

Enumerations

enum  wdt_period {
  WDT_PERIOD_NONE = 0,
  WDT_PERIOD_8CLK = 1,
  WDT_PERIOD_16CLK = 2,
  WDT_PERIOD_32CLK = 3,
  WDT_PERIOD_64CLK = 4,
  WDT_PERIOD_128CLK = 5,
  WDT_PERIOD_256CLK = 6,
  WDT_PERIOD_512CLK = 7,
  WDT_PERIOD_1024CLK = 8,
  WDT_PERIOD_2048CLK = 9,
  WDT_PERIOD_4096CLK = 10,
  WDT_PERIOD_8192CLK = 11,
  WDT_PERIOD_16384CLK = 12
}
 Watchdog Timer period configuration enum. More...
 

Configuration and Initialization

static bool wdt_is_syncing (void)
 Determines if the hardware module(s) are currently synchronizing to the bus. More...
 
static void wdt_get_config_defaults (struct wdt_conf *const config)
 Initializes a Watchdog Timer configuration structure to defaults. More...
 
enum status_code wdt_set_config (const struct wdt_conf *const config)
 Sets up the WDT hardware module based on the configuration. More...
 
static bool wdt_is_locked (void)
 Determines if the Watchdog timer is currently locked in an enabled state. More...
 

Timeout and Early Warning Management

static void wdt_clear_early_warning (void)
 Clears the Watchdog timer early warning period elapsed flag. More...
 
static bool wdt_is_early_warning (void)
 Determines if the Watchdog timer early warning period has elapsed. More...
 
void wdt_reset_count (void)
 Resets the count of the running Watchdog Timer that was previously enabled. More...
 

Callback Configuration and Initialization

enum  wdt_callback { WDT_CALLBACK_EARLY_WARNING }
 Enum for the possible callback types for the WDT module. More...
 
typedef void(* wdt_callback_t )(void)
 Type definition for a WDT module callback function. More...
 
enum status_code wdt_register_callback (const wdt_callback_t callback, const enum wdt_callback type)
 Registers an asynchronous callback function with the driver. More...
 
enum status_code wdt_unregister_callback (const enum wdt_callback type)
 Unregisters an asynchronous callback function with the driver. More...
 

Callback Enabling and Disabling

enum status_code wdt_enable_callback (const enum wdt_callback type)
 Enables asynchronous callback generation for a given type. More...
 
enum status_code wdt_disable_callback (const enum wdt_callback type)
 Disables asynchronous callback generation for a given type. More...
 

typedef void(* wdt_callback_t)(void)

Type definition for a WDT module callback function.

Enum for the possible callback types for the WDT module.

Enumerator
WDT_CALLBACK_EARLY_WARNING 

Callback type for when an early warning callback from the WDT module is issued.

enum wdt_period

Watchdog Timer period configuration enum.

Enum for the possible period settings of the Watchdog timer module, for values requiring a period as a number of Watchdog timer clock ticks.

Enumerator
WDT_PERIOD_NONE 

No Watchdog period.

This value can only be used when setting the Window and Early Warning periods; its use as the Watchdog Reset Period is invalid.

WDT_PERIOD_8CLK 

Watchdog period of 8 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_16CLK 

Watchdog period of 16 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_32CLK 

Watchdog period of 32 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_64CLK 

Watchdog period of 64 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_128CLK 

Watchdog period of 128 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_256CLK 

Watchdog period of 256 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_512CLK 

Watchdog period of 512 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_1024CLK 

Watchdog period of 1024 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_2048CLK 

Watchdog period of 2048 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_4096CLK 

Watchdog period of 4096 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_8192CLK 

Watchdog period of 8192 clocks of the Watchdog Timer Generic Clock.

WDT_PERIOD_16384CLK 

Watchdog period of 16384 clocks of the Watchdog Timer Generic Clock.

static void wdt_clear_early_warning ( void  )
inlinestatic

Clears the Watchdog timer early warning period elapsed flag.

Clears the Watchdog timer early warning period elapsed flag, so that a new early warning period can be detected.

Referenced by run_wdt_early_warning_test(), and WDT_Handler().

enum status_code wdt_disable_callback ( const enum wdt_callback  type)

Disables asynchronous callback generation for a given type.

Disables asynchronous callbacks for a given callback type.

Parameters
[in]typeType of callback function to disable
Returns
Status of the callback disable operation.
Return values
STATUS_OKThe callback was disabled successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, and WDT_CALLBACK_EARLY_WARNING.

enum status_code wdt_enable_callback ( const enum wdt_callback  type)

Enables asynchronous callback generation for a given type.

Enables asynchronous callbacks for a given callback type. This must be called before an external interrupt channel will generate callback events.

Parameters
[in]typeType of callback function to enable
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, system_interrupt_enable(), SYSTEM_INTERRUPT_MODULE_WDT, and WDT_CALLBACK_EARLY_WARNING.

static void wdt_get_config_defaults ( struct wdt_conf *const  config)
inlinestatic

Initializes a Watchdog Timer configuration structure to defaults.

Initializes a given Watchdog Timer configuration structure to a set of known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

  • Not locked, to allow for further (re-)configuration
  • Enable WDT
  • Watchdog timer sourced from Generic Clock Channel 4
  • A timeout period of 16384 clocks of the Watchdog module clock
  • No window period, so that the Watchdog count can be reset at any time
  • No early warning period to indicate the Watchdog will soon expire
Parameters
[out]configConfiguration structure to initialize to default values

References wdt_conf::always_on, Assert, wdt_conf::early_warning_period, wdt_conf::enable, GCLK_GENERATOR_4, wdt_conf::timeout_period, WDT_PERIOD_16384CLK, WDT_PERIOD_NONE, and wdt_conf::window_period.

Referenced by main().

static bool wdt_is_early_warning ( void  )
inlinestatic

Determines if the Watchdog timer early warning period has elapsed.

Determines if the Watchdog timer early warning period has elapsed.

Note
If no early warning period was configured, the value returned by this function is invalid.
Returns
Current Watchdog Early Warning state.

Referenced by run_wdt_early_warning_test().

static bool wdt_is_locked ( void  )
inlinestatic

Determines if the Watchdog timer is currently locked in an enabled state.

Determines if the Watchdog timer is currently enabled and locked, so that it cannot be disabled or otherwise reconfigured.

Returns
Current Watchdog lock state.

Referenced by wdt_set_config().

static bool wdt_is_syncing ( void  )
inlinestatic

Determines if the hardware module(s) are currently synchronizing to the bus.

Checks to see if the underlying hardware peripheral module(s) are currently synchronizing across multiple clock domains to the hardware bus. This function can be used to delay further operations on a module until such time that it is ready, to prevent blocking delays for synchronization in the user application.

Returns
Synchronization status of the underlying hardware module(s).
Return values
falseIf the module has completed synchronization
trueIf the module synchronization is ongoing

Referenced by wdt_reset_count(), and wdt_set_config().

enum status_code wdt_register_callback ( const wdt_callback_t  callback,
const enum wdt_callback  type 
)

Registers an asynchronous callback function with the driver.

Registers an asynchronous callback with the WDT driver, fired when a given criteria (such as an Early Warning) is met. Callbacks are fired once for each event.

Parameters
[in]callbackPointer to the callback function to register
[in]typeType of callback function to register
Returns
Status of the registration operation.
Return values
STATUS_OKThe callback was registered successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, WDT_CALLBACK_EARLY_WARNING, and wdt_early_warning_callback.

void wdt_reset_count ( void  )

Resets the count of the running Watchdog Timer that was previously enabled.

Resets the current count of the Watchdog Timer, restarting the timeout period count elapsed. This function should be called after the window period (if one was set in the module configuration) but before the timeout period to prevent a reset of the system.

References wdt_is_syncing().

Referenced by main().

enum status_code wdt_set_config ( const struct wdt_conf *const  config)

Sets up the WDT hardware module based on the configuration.

Writes a given configuration of a WDT configuration to the hardware module, and initializes the internal device struct.

Parameters
[in]configPointer to the configuration struct
Returns
Status of the configuration procedure.
Return values
STATUS_OKIf the module was configured correctly
STATUS_ERR_INVALID_ARGIf invalid argument(s) were supplied
STATUS_ERR_IOIf the Watchdog module is locked to be always on

References wdt_conf::always_on, Assert, wdt_conf::early_warning_period, wdt_conf::enable, system_gclk_chan_config::source_generator, STATUS_ERR_INVALID_ARG, STATUS_ERR_IO, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBA, system_gclk_chan_enable(), system_gclk_chan_lock(), system_gclk_chan_set_config(), wdt_conf::timeout_period, wdt_is_locked(), wdt_is_syncing(), WDT_PERIOD_NONE, and wdt_conf::window_period.

Referenced by main().

enum status_code wdt_unregister_callback ( const enum wdt_callback  type)

Unregisters an asynchronous callback function with the driver.

Unregisters an asynchronous callback with the WDT driver, removing it from the internal callback registration table.

Parameters
[in]typeType of callback function to unregister
Returns
Status of the de-registration operation.
Return values
STATUS_OKThe callback was Unregistered successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, WDT_CALLBACK_EARLY_WARNING, and wdt_early_warning_callback.