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:

Polled APIs
Callback APIs

The following peripherals are used by this module:

WDT (Watchdog Timer)

The following devices can use this module:

Atmel | SMART SAM D20/D21
Atmel | SMART SAM R21
Atmel | SMART SAM D09/D10/D11
Atmel | SMART SAM L21/L22
Atmel | SMART SAM DA1
Atmel | SMART SAM C20/C21
Atmel | SMART SAM HA1
Atmel | SMART SAM R30
Atmel | SMART SAM R34
Atmel | SMART SAM R35

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 wdt_callback

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] type Type of callback function to disable

Returns: Status of the callback disable operation.

Return values

STATUS_OK	The callback was disabled successfully
STATUS_ERR_INVALID_ARG	If 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] type Type of callback function to enable

Returns: Status of the callback enable operation.

Return values

STATUS_OK	The callback was enabled successfully
STATUS_ERR_INVALID_ARG	If 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] config Configuration 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.

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

false	If the module has completed synchronization
true	If 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]	callback	Pointer to the callback function to register
[in]	type	Type of callback function to register

Returns: Status of the registration operation.

Return values

STATUS_OK	The callback was registered successfully
STATUS_ERR_INVALID_ARG	If 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] config Pointer to the configuration struct

Returns: Status of the configuration procedure.

Return values

STATUS_OK	If the module was configured correctly
STATUS_ERR_INVALID_ARG	If invalid argument(s) were supplied
STATUS_ERR_IO	If 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] type Type of callback function to unregister

Returns: Status of the de-registration operation.

Return values

STATUS_OK	The callback was Unregistered successfully
STATUS_ERR_INVALID_ARG	If an invalid callback type was supplied

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

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Locked Mode

Window Mode

Early Warning

Physical Connection

Special Considerations

Extra Information

Examples

API Overview

Data Structures

Enumerations

Configuration and Initialization

Timeout and Early Warning Management

Callback Configuration and Initialization

Callback Enabling and Disabling