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:
There are no prerequisites for this module.
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.
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.
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.
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.
The figure below shows how this module is interconnected within the device.
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.
For extra information, see Extra Information for WDT Driver. This includes:
For a list of examples related to this driver, see Examples for WDT Driver.
Modules | |
| Related Project(s) | |
| In this section you can find all the projects related to the SAM Watchdog (WDT) Driver. | |
| Quick Start Guide(s) | |
| In this section you can find a list of all Quick Start guides related to the SAM Watchdog (WDT) Driver. | |
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... | |
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... | |
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... | |
| typedef void(* wdt_callback_t)(void) |
Type definition for a WDT module callback function.
| enum wdt_callback |
| 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. |
|
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.
| [in] | type | Type of callback function to disable |
| 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.
| [in] | type | Type of callback function to enable |
| 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.
Referenced by configure_wdt_callbacks().
|
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:
| [out] | config | Configuration structure to initialize to default values |
References wdt_conf::always_on, Assert, wdt_conf::clock_source, 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 configure_wdt(), main(), and start_application().
|
inlinestatic |
Determines if the Watchdog timer early warning period has elapsed.
Determines if the Watchdog timer early warning period has elapsed.
Referenced by run_wdt_early_warning_test().
|
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.
Referenced by wdt_set_config().
|
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.
| 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.
| [in] | callback | Pointer to the callback function to register |
| [in] | type | Type of callback function to register |
| STATUS_OK | The callback was registered successfully |
| STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
References Assert, callback, STATUS_ERR_INVALID_ARG, STATUS_OK, WDT_CALLBACK_EARLY_WARNING, and wdt_early_warning_callback.
Referenced by configure_wdt_callbacks().
| 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.
| [in] | config | Pointer to the configuration struct |
| 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::clock_source, 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 configure_wdt(), main(), and start_application().
| 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.
| [in] | type | Type of callback function to unregister |
| STATUS_OK | The callback was Unregistered successfully |
| STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
References Assert, NULL, STATUS_ERR_INVALID_ARG, STATUS_OK, WDT_CALLBACK_EARLY_WARNING, and wdt_early_warning_callback.
1.8.5