[watchdog.h] Watchdog Timer

Functions
static bool	WatchdogRunning (void)
	Determines if the watchdog timer is enabled. More...
static void	WatchdogEnable (void)
	Enables the watchdog timer. More...
static void	WatchdogResetEnable (void)
	Enables the watchdog timer reset. More...
static void	WatchdogResetDisable (void)
	Disables the watchdog timer reset. More...
static void	WatchdogLock (void)
	Enables the watchdog timer lock mechanism. More...
static void	WatchdogUnlock (void)
	Disables the watchdog timer lock mechanism. More...
static bool	WatchdogLockState (void)
	Gets the state of the watchdog timer lock mechanism. More...
static void	WatchdogReloadSet (uint32_t ui32LoadVal)
	Sets the watchdog timer reload value. More...
static uint32_t	WatchdogReloadGet (void)
	Gets the watchdog timer reload value. More...
static uint32_t	WatchdogValueGet (void)
	Gets the current watchdog timer value. More...
static void	WatchdogIntRegister (void(*pfnHandler)(void))
	Registers an interrupt handler for the watchdog timer interrupt in the dynamic interrupt table. More...
static void	WatchdogIntUnregister (void)
	Unregisters an interrupt handler for the watchdog timer interrupt in the dynamic interrupt table. More...
static void	WatchdogIntEnable (void)
	Enables the watchdog timer. More...
static uint32_t	WatchdogIntStatus (void)
	Gets the current watchdog timer interrupt status. More...
static void	WatchdogIntClear (void)
	Clears the watchdog timer interrupt. More...
static void	WatchdogIntTypeSet (uint32_t ui32Type)
	Sets the type of interrupt generated by the watchdog. More...
static void	WatchdogStallEnable (void)
	Enables stalling of the watchdog timer during debug events. More...
static void	WatchdogStallDisable (void)
	Disables stalling of the watchdog timer during debug events. More...

Detailed Description

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 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 SysCtrlResetSourceGet(). However, it is not possible to detect which of the warm reset sources that caused the reset.

Typical use case:

• Use 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 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 static and dynamic vector table, see Interrupt Vector Table.
• Use WatchdogResetEnable() to enable reset on second time-out.
• Use WatchdogReloadSet() to set (re)load value of the counter.
• Use WatchdogEnable() to start the WDT counter. The WDT counts down from the load value.
• Use WatchdogLock() to lock WDT configuration to prevent unintended re-configuration.
• Application must use 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 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).

API

The API functions can be grouped like this:

Watchdog configuration:

• WatchdogIntTypeSet()
• WatchdogResetEnable()
• WatchdogResetDisable()
• WatchdogReloadSet()
• WatchdogEnable()

Status:

• WatchdogRunning()
• WatchdogValueGet()
• WatchdogReloadGet()
• WatchdogIntStatus()

Interrupt configuration:

• WatchdogIntEnable()
• WatchdogIntClear()
• WatchdogIntRegister()
• WatchdogIntUnregister()

Register protection:

• WatchdogLock()
• WatchdogLockState()
• WatchdogUnlock()

Stall configuration for debugging:

• WatchdogStallDisable()
• WatchdogStallEnable()

Function Documentation

static void WatchdogEnable ( void  )

inlinestatic

Enables the watchdog timer.

This function enables the watchdog timer counter and interrupt.

Once enabled, the watchdog interrupt can only be disabled by a hardware reset.

Note

This function has no effect if the watchdog timer has been locked.

Returns

None

See also

WatchdogLock(), WatchdogUnlock()

Referenced by WatchdogIntEnable().

{
    // Enable the watchdog timer module.
    HWREGBITW(WDT_BASE + WDT_O_CTL, WDT_CTL_INTEN_BITN) = 1;
}

static void WatchdogIntClear ( void  )

inlinestatic

Clears the watchdog timer interrupt.

The watchdog timer interrupt source is cleared, so that it no longer asserts.

Note

Due to write buffers and synchronizers in the system it may take several clock cycles from a register write clearing an event in a module and until the event is actually cleared in the NVIC of the system CPU. It is recommended to clear the event source early in the interrupt service routine (ISR) to allow the event clear to propagate to the NVIC before returning from the ISR. At the same time, an early event clear allows new events of the same type to be pended instead of ignored if the event is cleared later in the ISR. It is the responsibility of the programmer to make sure that enough time has passed before returning from the ISR to avoid false re-triggering of the cleared event. A simple, although not necessarily optimal, way of clearing an event before returning from the ISR is:

1. Write to clear event (interrupt source). (buffered write)
2. Dummy read from the event source module. (making sure the write has propagated)
3. Wait two system CPU clock cycles (user code or two NOPs). (allowing cleared event to propagate through any synchronizers)

Returns

None

{
    // Clear the interrupt source.
    HWREG(WDT_BASE + WDT_O_ICR) = WATCHDOG_INT_TIMEOUT;
}

static void WatchdogIntEnable ( void  )

inlinestatic

Enables the watchdog timer.

This function enables the watchdog timer interrupt by calling WatchdogEnable().

Returns

None

See also

WatchdogEnable()

{
    // Enable the Watchdog interrupt.
    WatchdogEnable();
}

Here is the call graph for this function:

static void WatchdogIntRegister ( void(*)(void)  pfnHandler )

inlinestatic

Registers an interrupt handler for the watchdog timer interrupt in the dynamic interrupt table.

Note

Only use this function if you want to use the dynamic vector table (in SRAM)!

This function registers a function as the interrupt handler for a specific interrupt and enables the corresponding interrupt in the interrupt controller.

The watchdog timer interrupt must be enabled via WatchdogIntEnable(). It is the interrupt handler's responsibility to clear the interrupt source via WatchdogIntClear().

Note

This function registers the standard watchdog interrupt handler. To register the NMI watchdog handler, use IntRegister() to register the handler for the INT_NMI_FAULT interrupt.

Parameters

pfnHandler

is a pointer to the function to be called when the watchdog timer interrupt occurs.

Returns

None

See also

IntRegister() for important information about registering interrupt handlers.

{
    // Register the interrupt handler.
    IntRegister(INT_WDT_IRQ, pfnHandler);

    // Enable the watchdog timer interrupt.
    IntEnable(INT_WDT_IRQ);
}

Here is the call graph for this function:

static uint32_t WatchdogIntStatus ( void  )

inlinestatic

Gets the current watchdog timer interrupt status.

This function returns the interrupt status for the watchdog timer module.

Returns

Returns the interrupt status.

• 1 : Watchdog time-out has occurred.
• 0 : Watchdog time-out has not occurred.

See also

WatchdogIntClear();

{
    // Return either the interrupt status or the raw interrupt status as
    // requested.
    return(HWREG(WDT_BASE + WDT_O_RIS));
}

static void WatchdogIntTypeSet ( uint32_t  ui32Type )

inlinestatic

Sets the type of interrupt generated by the watchdog.

This function sets the type of interrupt that is generated if the watchdog timer expires.

When configured to generate an NMI, the watchdog interrupt must still be enabled with WatchdogIntEnable(), and it must still be cleared inside the NMI handler with WatchdogIntClear().

Parameters

ui32Type

is the type of interrupt to generate. WATCHDOG_INT_TYPE_INT : Generate a standard interrupt (default). WATCHDOG_INT_TYPE_NMI : Generate a non-maskable interrupt (NMI).

Returns

None

{
    // Check the arguments.
    ASSERT((ui32Type == WATCHDOG_INT_TYPE_INT) ||
           (ui32Type == WATCHDOG_INT_TYPE_NMI));

    // Set the interrupt type.
    HWREGBITW(WDT_BASE + WDT_O_CTL, WDT_CTL_INTTYPE_BITN) = (ui32Type == WATCHDOG_INT_TYPE_INT)? 0 : 1;
}

static void WatchdogIntUnregister ( void  )

inlinestatic

Unregisters an interrupt handler for the watchdog timer interrupt in the dynamic interrupt table.

This function does the actual unregistering of the interrupt handler. This function clears the handler to be called when a watchdog timer interrupt occurs. This function also masks off the interrupt in the interrupt controller so that the interrupt handler no longer is called.

Note

This function registers the standard watchdog interrupt handler. To register the NMI watchdog handler, use IntRegister() to register the handler for the INT_NMI_FAULT interrupt.

Returns

None

See also

IntRegister() for important information about registering interrupt handlers.

{
    // Disable the interrupt.
    IntDisable(INT_WDT_IRQ);

    // Unregister the interrupt handler.
    IntUnregister(INT_WDT_IRQ);
}

Here is the call graph for this function:

static void WatchdogLock ( void  )

inlinestatic

Enables the watchdog timer lock mechanism.

This function locks out write access to the watchdog timer configuration registers.

Returns

None

{
    // Lock out watchdog register writes. Writing anything to the WDT_O_LOCK
    // register causes the lock to go into effect.
    HWREG(WDT_BASE + WDT_O_LOCK) = WATCHDOG_LOCK_LOCKED;
}

static bool WatchdogLockState ( void  )

inlinestatic

Gets the state of the watchdog timer lock mechanism.

This function returns the lock state of the watchdog timer registers.

Returns

Returns state of lock mechanism.

• true : Watchdog timer registers are locked.
• false : Registers are not locked.

{
    // Get the lock state.
    return((HWREG(WDT_BASE + WDT_O_LOCK) == WATCHDOG_LOCK_LOCKED) ?
               true : false);
}

static uint32_t WatchdogReloadGet ( void  )

inlinestatic

Gets the watchdog timer reload value.

This function gets the value that is loaded into the watchdog timer when the count reaches zero for the first time.

Returns

None

See also

WatchdogReloadSet()

{
    // Get the load register.
    return(HWREG(WDT_BASE + WDT_O_LOAD));
}

static void WatchdogReloadSet ( uint32_t  ui32LoadVal )

inlinestatic

Sets the watchdog timer reload value.

This function configures the value to load into the watchdog timer when the count reaches zero for the first time; if the watchdog timer is running when this function is called, then the value is immediately loaded into the watchdog timer counter. If the ui32LoadVal parameter is 0, then an interrupt is immediately generated.

Note

This function has no effect if the watchdog timer has been locked.

Parameters

ui32LoadVal

is the load value for the watchdog timer.

Returns

None

See also

WatchdogLock(), WatchdogUnlock(), WatchdogReloadGet()

{
    // Set the load register.
    HWREG(WDT_BASE + WDT_O_LOAD) = ui32LoadVal;
}

static void WatchdogResetDisable ( void  )

inlinestatic

Disables the watchdog timer reset.

This function disables the capability of the watchdog timer to issue a reset to the processor after a second timeout condition.

Note

This function has no effect if the watchdog timer has been locked.

Returns

None

See also

WatchdogLock(), WatchdogUnlock()

{
    // Disable the watchdog reset.
    HWREGBITW(WDT_BASE + WDT_O_CTL, WDT_CTL_RESEN_BITN) = 0;
}

static void WatchdogResetEnable ( void  )

inlinestatic

Enables the watchdog timer reset.

This function enables the capability of the watchdog timer to issue a reset to the processor after a second timeout condition.

Note

This function has no effect if the watchdog timer has been locked.

Returns

None

See also

WatchdogLock(), WatchdogUnlock()

{
    // Enable the watchdog reset.
    HWREGBITW(WDT_BASE + WDT_O_CTL, WDT_CTL_RESEN_BITN) = 1;
}

static bool WatchdogRunning ( void  )

inlinestatic

Determines if the watchdog timer is enabled.

This function checks to see if the watchdog timer is enabled.

Returns

Returns status of Watchdog Timer:

• true : Watchdog timer is enabled.
• false : Watchdog timer is disabled.

{
    // See if the watchdog timer module is enabled, and return.
    return((HWREG(WDT_BASE + WDT_O_CTL) & WDT_CTL_INTEN) ? true : false);
}

static void WatchdogStallDisable ( void  )

inlinestatic

Disables stalling of the watchdog timer during debug events.

This function disables the debug mode stall of the watchdog timer. By doing so, the watchdog timer continues to count regardless of the processor debug state.

Returns

None

{
    // Disable timer stalling.
    HWREGBITW(WDT_BASE + WDT_O_TEST, WDT_TEST_STALL_BITN) = 0;
}

static void WatchdogStallEnable ( void  )

inlinestatic

Enables stalling of the watchdog timer during debug events.

This function allows the watchdog timer to stop counting when the processor is stopped by the debugger. By doing so, the watchdog is prevented from expiring and resetting the system (if reset is enabled). The watchdog instead expires after the appropriate number of processor cycles have been executed while debugging (or at the appropriate time after the processor has been restarted).

Returns

None

{
    // Enable timer stalling.
    HWREGBITW(WDT_BASE + WDT_O_TEST, WDT_TEST_STALL_BITN) = 1;
}

static void WatchdogUnlock ( void  )

inlinestatic

Disables the watchdog timer lock mechanism.

This function enables write access to the watchdog timer configuration registers.

Returns

None

{
    // Unlock watchdog register writes.
    HWREG(WDT_BASE + WDT_O_LOCK) = WATCHDOG_LOCK_UNLOCK;
}

static uint32_t WatchdogValueGet ( void  )

inlinestatic

Gets the current watchdog timer value.

This function reads the current value of the watchdog timer.

Returns

Returns the current value of the watchdog timer.

{
    // Get the current watchdog timer register value.
    return(HWREG(WDT_BASE + WDT_O_VALUE));
}

Macro Definition Documentation

#define WATCHDOG_INT_TIMEOUT   0x00000001

Referenced by WatchdogIntClear().

#define WATCHDOG_INT_TYPE_INT   0x00000000

Referenced by WatchdogIntTypeSet().

#define WATCHDOG_INT_TYPE_NMI   0x00000004

Referenced by WatchdogIntTypeSet().

#define WATCHDOG_LOCK_LOCKED   0x00000001

Referenced by WatchdogLock(), and WatchdogLockState().

#define WATCHDOG_LOCK_UNLOCK   0x1ACCE551

Referenced by WatchdogUnlock().

#define WATCHDOG_LOCK_UNLOCKED   0x00000000