libs/rt-thread-official
libs
/
rt-thread-official
mirror of https://github.com/RT-Thread/rt-thread.git
4
0
Fork 0
Code Issues Releases Wiki Activity
rt-thread-official/bsp/samd21/sam_d2x_asflib/sam0/drivers/wdt/wdt.h

504 lines
17 KiB
C
Raw Blame History

/**
* \file
*
* \brief SAM Watchdog Driver
*
* Copyright (c) 2012-2016 Atmel Corporation. All rights reserved.
*
* \asf_license_start
*
* \page License
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. The name of Atmel may not be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* 4. This software may only be redistributed and used in connection with an
* Atmel microcontroller product.
*
* THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
* EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
* \asf_license_stop
*
*/
/*
* Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
*/
#ifndef WDT_H_INCLUDED
#define WDT_H_INCLUDED
/**
* \defgroup asfdoc_sam0_wdt_group SAM Watchdog (WDT) Driver
*
* This driver for Atmel&reg; | SMART ARM&reg;-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
* \if WDT_CALLBACK_MODE
* - Callback APIs
* \endif
*
* 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
*
* The outline of this documentation is as follows:
* - \ref asfdoc_sam0_wdt_prerequisites
* - \ref asfdoc_sam0_wdt_module_overview
* - \ref asfdoc_sam0_wdt_special_considerations
* - \ref asfdoc_sam0_wdt_extra_info
* - \ref asfdoc_sam0_wdt_examples
* - \ref asfdoc_sam0_wdt_api_overview
*
*
* \section asfdoc_sam0_wdt_prerequisites Prerequisites
*
* There are no prerequisites for this module.
*
*
* \section asfdoc_sam0_wdt_module_overview 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.
*
* \subsection asfdoc_sam0_wdt_module_locked_mode 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.
*
* \subsection asfdoc_sam0_wdt_module_window_mode 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 \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 \a after the window opens but not \a before the
* Watchdog expires, the system will reset.
*
* \subsection asfdoc_sam0_wdt_module_early_warning 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 \a 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.
*
* \subsection asfdoc_sam0_wdt_module_overview_physical Physical Connection
*
* \ref asfdoc_sam0_wdt_module_int_connections "The figure below" shows how
* this module is interconnected within the device.
*
* \anchor asfdoc_sam0_wdt_module_int_connections
* \dot
* digraph overview {
* rankdir=LR;
* node [label="GCLK*\nGeneric Clock" shape=square] wdt_clock;
*
* subgraph driver {
* node [label="<f0> WDT | <f1> Watchdog Counter" shape=record] wdt_module;
* node [label="System Reset Logic" shape=ellipse style=filled fillcolor=lightgray] sys_reset;
* }
*
* wdt_clock -> wdt_module:f1;
* wdt_module:f1 -> sys_reset;
* }
* \enddot
*
* \note Watchdog Counter of SAM L21/L22/R30 is \a not provided by GCLK, but it uses an
* internal 1KHz OSCULP32K output clock.
*
* \section asfdoc_sam0_wdt_special_considerations 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.
*
* \section asfdoc_sam0_wdt_extra_info Extra Information
*
* For extra information, see \ref asfdoc_sam0_wdt_extra. This includes:
* - \ref asfdoc_sam0_wdt_extra_acronyms
* - \ref asfdoc_sam0_wdt_extra_dependencies
* - \ref asfdoc_sam0_wdt_extra_errata
* - \ref asfdoc_sam0_wdt_extra_history
*
*
* \section asfdoc_sam0_wdt_examples Examples
*
* For a list of examples related to this driver, see
* \ref asfdoc_sam0_wdt_exqsg.
*
* \section asfdoc_sam0_wdt_api_overview API Overview
* @{
*/
#include <compiler.h>
#include <clock.h>
#include <gclk.h>
#if WDT_CALLBACK_MODE == true
# include "wdt_callback.h"
#endif
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief 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.
*/
enum wdt_period {
/** 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_NONE = 0,
/** Watchdog period of 8 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_8CLK = 1,
/** Watchdog period of 16 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_16CLK = 2,
/** Watchdog period of 32 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_32CLK = 3,
/** Watchdog period of 64 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_64CLK = 4,
/** Watchdog period of 128 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_128CLK = 5,
/** Watchdog period of 256 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_256CLK = 6,
/** Watchdog period of 512 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_512CLK = 7,
/** Watchdog period of 1024 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_1024CLK = 8,
/** Watchdog period of 2048 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_2048CLK = 9,
/** Watchdog period of 4096 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_4096CLK = 10,
/** Watchdog period of 8192 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_8192CLK = 11,
/** Watchdog period of 16384 clocks of the Watchdog Timer Generic Clock */
WDT_PERIOD_16384CLK = 12,
};
/**
* \brief Watchdog Timer configuration structure.
*
* Configuration structure for a Watchdog Timer instance. This
* structure should be initialized by the \ref wdt_get_config_defaults()
* function before being modified by the user application.
*/
struct wdt_conf {
/** If \c true, the Watchdog will be locked to the current configuration
* settings when the Watchdog is enabled */
bool always_on;
/** Enable/Disable the Watchdog Timer */
bool enable;
#if !(SAML21) && !(SAML22) && !(SAMC20) && !(SAMC21) && !(SAMR30)
/** GCLK generator used to clock the peripheral except SAM L21/L22/C21/C20/R30*/
enum gclk_generator clock_source;
#endif
/** Number of Watchdog timer clock ticks until the Watchdog expires */
enum wdt_period timeout_period;
/** Number of Watchdog timer clock ticks until the reset window opens */
enum wdt_period window_period;
/** Number of Watchdog timer clock ticks until the early warning flag is
* set */
enum wdt_period early_warning_period;
};
/** \name Configuration and Initialization
* @{
*/
/**
* \brief 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.
*
* \return Synchronization status of the underlying hardware module(s).
*
* \retval false If the module has completed synchronization
* \retval true If the module synchronization is ongoing
*/
static inline bool wdt_is_syncing(void)
{
Wdt *const WDT_module = WDT;
#if (SAML21) || (SAML22) || (SAMC20) || (SAMC21) || (SAMR30)
if (WDT_module->SYNCBUSY.reg) {
#else
if (WDT_module->STATUS.reg & WDT_STATUS_SYNCBUSY) {
#endif
return true;
}
return false;
}
/**
* \brief 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:
* \li Not locked, to allow for further (re-)configuration
* \li Enable WDT
* \li Watchdog timer sourced from Generic Clock Channel 4
* \li A timeout period of 16384 clocks of the Watchdog module clock
* \li No window period, so that the Watchdog count can be reset at any time
* \li No early warning period to indicate the Watchdog will soon expire
*
* \param[out] config Configuration structure to initialize to default values
*/
static inline void wdt_get_config_defaults(
struct wdt_conf *const config)
{
/* Sanity check arguments */
Assert(config);
/* Default configuration values */
config->always_on = false;
config->enable = true;
#if !(SAML21) && !(SAML22) && !(SAMC20) && !(SAMC21) && !(SAMR30)
config->clock_source = GCLK_GENERATOR_4;
#endif
config->timeout_period = WDT_PERIOD_16384CLK;
config->window_period = WDT_PERIOD_NONE;
config->early_warning_period = WDT_PERIOD_NONE;
}
enum status_code wdt_set_config(
const struct wdt_conf *const config);
/** \brief 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.
*
* \return Current Watchdog lock state.
*/
static inline bool wdt_is_locked(void)
{
Wdt *const WDT_module = WDT;
#if (SAML21) || (SAML22) || (SAMC20) || (SAMC21) || (SAMR30)
return (WDT_module->CTRLA.reg & WDT_CTRLA_ALWAYSON);
#else
return (WDT_module->CTRL.reg & WDT_CTRL_ALWAYSON);
#endif
}
/** @} */
/** \name Timeout and Early Warning Management
* @{
*/
/** \brief 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.
*/
static inline void wdt_clear_early_warning(void)
{
Wdt *const WDT_module = WDT;
WDT_module->INTFLAG.reg = WDT_INTFLAG_EW;
}
/** \brief 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.
*
* \return Current Watchdog Early Warning state.
*/
static inline bool wdt_is_early_warning(void)
{
Wdt *const WDT_module = WDT;
return (WDT_module->INTFLAG.reg & WDT_INTFLAG_EW);
}
void wdt_reset_count(void);
/** @} */
#ifdef __cplusplus
}
#endif
/** @} */
/**
* \page asfdoc_sam0_wdt_extra Extra Information for WDT Driver
*
* \section asfdoc_sam0_wdt_extra_acronyms Acronyms
* The table below presents the acronyms used in this module:
*
* <table>
* <tr>
* <th>Acronym</th>
* <th>Description</th>
* </tr>
* <tr>
* <td>WDT</td>
* <td>Watchdog Timer</td>
* </tr>
* </table>
*
*
* \section asfdoc_sam0_wdt_extra_dependencies Dependencies
* This driver has the following dependencies:
*
* - \ref asfdoc_sam0_system_clock_group "System Clock Driver"
*
*
* \section asfdoc_sam0_wdt_extra_errata Errata
* There are no errata related to this driver.
*
*
* \section asfdoc_sam0_wdt_extra_history Module History
* An overview of the module history is presented in the table below, with
* details on the enhancements and fixes made to the module since its first
* release. The current version of this corresponds to the newest version in
* the table.
*
* <table>
* <tr>
* <th>Changelog</th>
* </tr>
* <tr>
* <td>Driver updated to follow driver type convention:
* \li wdt_init, wdt_enable, wdt_disable functions removed
* \li wdt_set_config function added
* \li WDT module enable state moved inside the configuration struct </td>
* </tr>
* <tr>
* <td>Initial Release</td>
* </tr>
* </table>
*/
/**
* \page asfdoc_sam0_wdt_exqsg Examples for WDT Driver
*
* This is a list of the available Quick Start guides (QSGs) and example
* applications for \ref asfdoc_sam0_wdt_group. QSGs are simple examples with
* step-by-step instructions to configure and use this driver in a selection of
* use cases. Note that a QSG can be compiled as a standalone application or be
* added to the user application.
*
* - \subpage asfdoc_sam0_wdt_basic_use_case
* \if WDT_CALLBACK_MODE
* - \subpage asfdoc_sam0_wdt_callback_use_case
* \endif
*
* \page asfdoc_sam0_wdt_document_revision_history Document Revision History
*
* <table>
* <tr>
* <th>Doc. Rev.</th>
* <th>Date</th>
* <th>Comments</th>
* </tr>
* <tr>
* <td>42124E</td>
* <td>12/2015</td>
* <td>Added support for SAM L21/L22, SAM DA1, SAM D09, SAM R30, and SAM C20/C21</td>
* </tr>
* <tr>
* <td>42124D</td>
* <td>12/2014</td>
* <td>Added SAM R21 and SAM D10/D11 support</td>
* </tr>
* <tr>
* <td>42124C</td>
* <td>01/2014</td>
* <td>Add SAM D21 support</td>
* </tr>
* <tr>
* <td>42124B</td>
* <td>06/2013</td>
* <td>Corrected documentation typos</td>
* </tr>
* <tr>
* <td>42124A</td>
* <td>06/2013</td>
* <td>Initial release</td>
* </tr>
* </table>
*/
#endif /* WDT_H_INCLUDED */
View Git Blame Copy Permalink