cc13x2x7_cc26x2x7/driverlib/watchdog_doc.h

/******************************************************************************
*  Filename:       watchdog_doc.h
*
*  Copyright (c) 2015 - 2022, Texas Instruments Incorporated
*  All rights reserved.
*
*  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) Neither the name of the ORGANIZATION nor the names of its contributors may
*     be used to endorse or promote products derived from this software without
*     specific prior written permission.
*
*  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
*  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
*  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
*  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS 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.
*
******************************************************************************/
//! \addtogroup wdt_api
//! @{
//! \section sec_wdt Introduction
//!
//! The Watchdog Timer (WDT) allows the application to regain control if the system stalls due to
//! unexpected software behavior. The WDT can generate a normal interrupt or a non-maskable interrupt
//! on the first time-out and a system reset on the following time-out if the application fails to
//! restart the WDT.
//!
//! WDT has the following features:
//! - 32-bit down counter with a configurable load register.
//! - Configurable interrupt generation logic with interrupt masking and optional NMI function.
//! - Optional reset generation.
//! - Register protection from runaway software (lock).
//! - User-enabled stalling when the system CPU asserts the CPU Halt flag during debug.
//!
//! The WDT runs at system HF clock divided by 32; however, when in powerdown it runs at
//! LF clock (32 kHz) - if the LF clock to the MCU domain is enabled.
//!
//! If application does not restart the WDT, using \ref WatchdogIntClear(), before a time-out:
//! - At the first time-out the WDT asserts the interrupt, reloads the 32-bit counter with the load
//!   value, and resumes counting down from that value.
//! - If the WDT counts down to zero again before the application clears the interrupt, and the
//!   reset signal has been enabled, the WDT asserts its reset signal to the system.
//!
//! \note By default, a "warm reset" triggers a pin reset and thus reboots the device.
//!
//! A reset caused by the WDT can be detected as a "warm reset" using \ref SysCtrlResetSourceGet().
//! However, it is not possible to detect which of the warm reset sources that caused the reset.
//!
//! Typical use case:
//! - Use \ref WatchdogIntTypeSet() to select either standard interrupt or non-maskable interrupt on
//!   first time-out.
//!   - The application must implement an interrupt handler for the selected interrupt type. If
//!     application uses the \e static vector table (see startup_<compiler>.c) the interrupt
//!     handlers for standard interrupt and non-maskable interrupt are named WatchdogIntHandler()
//!     and NmiSR() respectively. For more information about \e static and \e dynamic vector table,
//!     see \ref sec_interrupt_table.
//! - Use \ref WatchdogResetEnable() to enable reset on second time-out.
//! - Use \ref WatchdogReloadSet() to set (re)load value of the counter.
//! - Use \ref WatchdogEnable() to start the WDT counter. The WDT counts down from the load value.
//! - Use \ref WatchdogLock() to lock WDT configuration to prevent unintended re-configuration.
//! - Application must use \ref WatchdogIntClear() to restart the counter before WDT times out.
//! - If application does not restart the counter before it reaches zero (times out) the WDT asserts
//!   the selected type of interrupt, reloads the counter, and starts counting down again.
//!   - The interrupt handler triggered by the first time-out can be used to log debug information
//!     or try to enter a safe "pre-reset" state in order to have a more graceful reset when the WDT
//!     times out the second time.
//!   - It is \b not recommended that the WDT interrupt handler clears the WDT interrupt and thus
//!     reloads the WDT counter. This means that the WDT interrupt handler never returns.
//! - If the application does not clear the WDT interrupt and the WDT times out when the interrupt
//!   is still asserted then WDT triggers a reset (if enabled).
//!
//! \section sec_wdt_api API
//!
//! The API functions can be grouped like this:
//!
//! Watchdog configuration:
//! - \ref WatchdogIntTypeSet()
//! - \ref WatchdogResetEnable()
//! - \ref WatchdogResetDisable()
//! - \ref WatchdogReloadSet()
//! - \ref WatchdogEnable()
//!
//! Status:
//! - \ref WatchdogRunning()
//! - \ref WatchdogValueGet()
//! - \ref WatchdogReloadGet()
//! - \ref WatchdogIntStatus()
//!
//! Interrupt configuration:
//! - \ref WatchdogIntEnable()
//! - \ref WatchdogIntClear()
//! - \ref WatchdogIntRegister()
//! - \ref WatchdogIntUnregister()
//!
//! Register protection:
//! - \ref WatchdogLock()
//! - \ref WatchdogLockState()
//! - \ref WatchdogUnlock()
//!
//! Stall configuration for debugging:
//! - \ref WatchdogStallDisable()
//! - \ref WatchdogStallEnable()
//!
//! @}