Data Structures | Macros | Typedefs | Enumerations | Functions
Watchdog.h File Reference

Detailed Description

Watchdog driver interface.


Overview

A watchdog timer can be used to generate a reset signal if a system has become unresponsive. The Watchdog driver simplifies configuring and starting the watchdog peripherals. The watchdog peripheral can be configured with resets either on or off and a user-specified timeout period.

When the watchdog peripheral is configured not to generate a reset, it can be used to cause a hardware interrupt at a programmable interval. The driver provides the ability to specify a user-provided callback function that is called when the watchdog causes an interrupt.

The Watchdog driver simplifies configuring and starting the Watchdog peripherals. The Watchdog can be set up to produce a reset signal after a timeout, or simply cause a hardware interrupt at a programmable interval. The driver provides the ability to specify a callback function that is called when the Watchdog causes an interrupt.

When resets are turned on, it is the user application's responsibility to call Watchdog_clear() in order to clear the Watchdog and prevent a reset. Watchdog_clear() can be called at any time.

Usage

This section will cover driver usage.

Synopsis

Open the driver with default settings:

Watchdog_Handle watchdogHandle;
watchdogHandle = Watchdog_open(WATCHDOG_INDEX, NULL);
if (watchdogHandle == NULL) {
// Spin forever
while(1);
}

The Watchdog driver must be initialized by calling Watchdog_init(), before any other Watchdog APIs can be called. Once the watchdog is initialized, a Watchdog object can be created through the following steps:

To have a user-defined function run at the hardware interrupt caused by a watchdog timer timeout, define a function of the following type:

typedef void (*Watchdog_Callback)(uintptr_t);

Then pass the function to Watchdog_open() through the Watchdog_Params structure.

An example of the Watchdog creation process that uses a callback function:

void UserCallbackFxn(Watchdog_Handle handle)
{
printf("Watchdog timer triggered!\n");
releaseResources();
}
...
Watchdog_Params params;
Watchdog_Handle watchdogHandle;
params.resetMode = Watchdog_RESET_ON;
params.callbackFxn = (Watchdog_Callback) UserCallbackFxn;
watchdogHandle = Watchdog_open(CONFIG_WATCHDOG0, &params);
if (watchdogHandle == NULL) {
// Error opening Watchdog
while (1);
}

If no Watchdog_Params structure is passed to Watchdog_open(), the default values are used. By default, the Watchdog driver has resets turned on, no callback function specified, and stalls the timer at breakpoints during debugging.

Options for the resetMode parameter are Watchdog_RESET_ON and Watchdog_RESET_OFF. The latter allows the watchdog to be used like another timer interrupt. When resetMode is Watchdog_RESET_ON, it is up to the application to call Watchdog_clear() to clear the Watchdog interrupt flag to prevent a reset. Watchdog_clear() can be called at any time.

Examples

Configuration

Refer to the Driver's Configuration section for more information.

#include <stdint.h>
Include dependency graph for Watchdog.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  Watchdog_Params
 Watchdog Parameters. More...
 
struct  Watchdog_FxnTable
 The definition of a Watchdog function table that contains the required set of functions to control a specific Watchdog driver implementation. More...
 
struct  Watchdog_Config_
 Watchdog Global configuration. More...
 

Macros

#define Watchdog_CMD_RESERVED   (32)
 
#define Watchdog_STATUS_RESERVED   (-32)
 
#define Watchdog_STATUS_SUCCESS   (0)
 Successful status code returned by Watchdog_control(). More...
 
#define Watchdog_STATUS_ERROR   (-1)
 Generic error status code returned by Watchdog_control(). More...
 
#define Watchdog_STATUS_UNDEFINEDCMD   (-2)
 An error status code returned by Watchdog_control() for undefined command codes. More...
 
#define Watchdog_STATUS_UNSUPPORTED   (-3)
 An error status code returned by Watchdog_setReload() for drivers which do not support the aforementioned API. More...
 

Typedefs

typedef struct Watchdog_Config_Watchdog_Handle
 Watchdog Handle. More...
 
typedef void(* Watchdog_Callback) (uintptr_t handle)
 Watchdog callback pointer. More...
 
typedef void(* Watchdog_ClearFxn) (Watchdog_Handle handle)
 A function pointer to a driver specific implementation of Watchdog_clear(). More...
 
typedef void(* Watchdog_CloseFxn) (Watchdog_Handle handle)
 A function pointer to a driver specific implementation of Watchdog_close(). More...
 
typedef int_fast16_t(* Watchdog_ControlFxn) (Watchdog_Handle handle, uint_fast16_t cmd, void *arg)
 A function pointer to a driver specific implementation of Watchdog_control(). More...
 
typedef void(* Watchdog_InitFxn) (Watchdog_Handle handle)
 A function pointer to a driver specific implementation of Watchdog_init(). More...
 
typedef Watchdog_Handle(* Watchdog_OpenFxn) (Watchdog_Handle handle, Watchdog_Params *params)
 A function pointer to a driver specific implementation of Watchdog_open(). More...
 
typedef int_fast16_t(* Watchdog_SetReloadFxn) (Watchdog_Handle handle, uint32_t ticks)
 A function pointer to a driver specific implementation of Watchdog_setReload(). More...
 
typedef uint32_t(* Watchdog_ConvertMsToTicksFxn) (Watchdog_Handle handle, uint32_t milliseconds)
 A function pointer to a driver specific implementation of Watchdog_ConvertMsToTicksFxn(). More...
 
typedef struct Watchdog_Config_ Watchdog_Config
 Watchdog Global configuration. More...
 

Enumerations

enum  Watchdog_DebugMode { Watchdog_DEBUG_STALL_ON, Watchdog_DEBUG_STALL_OFF }
 Watchdog debug stall settings. More...
 
enum  Watchdog_ResetMode { Watchdog_RESET_OFF, Watchdog_RESET_ON }
 Watchdog reset mode settings. More...
 

Functions

void Watchdog_clear (Watchdog_Handle handle)
 Clears the Watchdog. More...
 
void Watchdog_close (Watchdog_Handle handle)
 Function to close a Watchdog peripheral specified by the Watchdog handle.It stops (holds) the Watchdog counting on applicable platforms. More...
 
int_fast16_t Watchdog_control (Watchdog_Handle handle, uint_fast16_t cmd, void *arg)
 Function performs implementation specific features on a given Watchdog_Handle. More...
 
void Watchdog_init (void)
 Initializes the Watchdog module. More...
 
Watchdog_Handle Watchdog_open (uint_least8_t index, Watchdog_Params *params)
 Opens a Watchdog. More...
 
void Watchdog_Params_init (Watchdog_Params *params)
 Function to initialize the Watchdog_Params structure to its defaults. More...
 
int_fast16_t Watchdog_setReload (Watchdog_Handle handle, uint32_t ticks)
 Sets the Watchdog reload value. More...
 
uint32_t Watchdog_convertMsToTicks (Watchdog_Handle handle, uint32_t milliseconds)
 Converts milliseconds to Watchdog clock ticks. More...
 

Typedef Documentation

§ Watchdog_Handle

Watchdog Handle.

§ Watchdog_Callback

typedef void(* Watchdog_Callback) (uintptr_t handle)

Watchdog callback pointer.

This is the typedef for the function pointer that will allow a callback function to be specified in the Watchdog_Params structure. The function will take a Watchdog_Handle of the Watchdog causing the interrupt (cast as a uintptr_t) as an argument.

§ Watchdog_ClearFxn

typedef void(* Watchdog_ClearFxn) (Watchdog_Handle handle)

A function pointer to a driver specific implementation of Watchdog_clear().

§ Watchdog_CloseFxn

typedef void(* Watchdog_CloseFxn) (Watchdog_Handle handle)

A function pointer to a driver specific implementation of Watchdog_close().

§ Watchdog_ControlFxn

typedef int_fast16_t(* Watchdog_ControlFxn) (Watchdog_Handle handle, uint_fast16_t cmd, void *arg)

A function pointer to a driver specific implementation of Watchdog_control().

§ Watchdog_InitFxn

typedef void(* Watchdog_InitFxn) (Watchdog_Handle handle)

A function pointer to a driver specific implementation of Watchdog_init().

§ Watchdog_OpenFxn

typedef Watchdog_Handle(* Watchdog_OpenFxn) (Watchdog_Handle handle, Watchdog_Params *params)

A function pointer to a driver specific implementation of Watchdog_open().

§ Watchdog_SetReloadFxn

typedef int_fast16_t(* Watchdog_SetReloadFxn) (Watchdog_Handle handle, uint32_t ticks)

A function pointer to a driver specific implementation of Watchdog_setReload().

§ Watchdog_ConvertMsToTicksFxn

typedef uint32_t(* Watchdog_ConvertMsToTicksFxn) (Watchdog_Handle handle, uint32_t milliseconds)

A function pointer to a driver specific implementation of Watchdog_ConvertMsToTicksFxn().

§ Watchdog_Config

Watchdog Global configuration.

The Watchdog_Config structure contains a set of pointers used to characterize the Watchdog driver implementation.

This structure needs to be defined before calling Watchdog_init() and it must not be changed thereafter.

See also
Watchdog_init()

Enumeration Type Documentation

§ Watchdog_DebugMode

Watchdog debug stall settings.

This enumeration defines the debug stall modes for the Watchdog. On some targets, the Watchdog timer will continue to count down while a debugging session is halted. To avoid unwanted resets, the Watchdog can be set to stall while the processor is stopped by the debugger.

Enumerator
Watchdog_DEBUG_STALL_ON 

Watchdog will be stalled at breakpoints

Watchdog_DEBUG_STALL_OFF 

Watchdog will keep running at breakpoints

§ Watchdog_ResetMode

Watchdog reset mode settings.

This enumeration defines the reset modes for the Watchdog. The Watchdog can be configured to either generate a reset upon timeout or simply produce a periodic interrupt.

Enumerator
Watchdog_RESET_OFF 

Timeouts generate interrupts only

Watchdog_RESET_ON 

Generates reset after timeout

Function Documentation

§ Watchdog_clear()

void Watchdog_clear ( Watchdog_Handle  handle)

Clears the Watchdog.

Clears the Watchdog to to prevent a reset signal from being generated if the module is in Watchdog_RESET_ON reset mode.

Parameters
handleA Watchdog_Handle

§ Watchdog_close()

void Watchdog_close ( Watchdog_Handle  handle)

Function to close a Watchdog peripheral specified by the Watchdog handle.It stops (holds) the Watchdog counting on applicable platforms.

Precondition
Watchdog_open() has to be called first.
Parameters
handleA Watchdog_Handle returned from Watchdog_open()
See also
Watchdog_open()

§ Watchdog_control()

int_fast16_t Watchdog_control ( Watchdog_Handle  handle,
uint_fast16_t  cmd,
void *  arg 
)

Function performs implementation specific features on a given Watchdog_Handle.

Commands for Watchdog_control can originate from Watchdog.h or from implementation specific Watchdog*.h files. While commands from Watchdog.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific Watchdog*.h files add unique driver capabilities but are not API portable across all Watchdog driver implementations.

Commands supported by Watchdog.h follow a Watchdog_CMD_<cmd> naming convention.
Commands supported by Watchdog*.h follow a Watchdog*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See Watchdog_control command codes for command codes.

See Watchdog_control return status codes for status codes.

Precondition
Watchdog_open() has to be called first.
Parameters
handleA Watchdog_Handle returned from Watchdog_open()
cmdWatchdog.h or Watchdog*.h commands.
argAn optional R/W (read/write) command argument accompanied with cmd
Returns
Implementation specific return codes. Negative values indicate unsuccessful operations.
See also
Watchdog_open()

§ Watchdog_init()

void Watchdog_init ( void  )

Initializes the Watchdog module.

The application-provided Watchdog_config must be present before the Watchdog_init() function is called. The Watchdog_config must be persistent and not changed after Watchdog_init is called. This function must be called before any of the other Watchdog driver APIs.

§ Watchdog_open()

Watchdog_Handle Watchdog_open ( uint_least8_t  index,
Watchdog_Params params 
)

Opens a Watchdog.

Opens a Watchdog object with the index and parameters specified, and returns a Watchdog_Handle.

Parameters
indexLogical peripheral number for the Watchdog indexed into the Watchdog_config table
paramsPointer to a Watchdog_Params, if NULL it will use default values. All the fields in this structure are RO (read-only).
Returns
A Watchdog_Handle on success or a NULL on an error or if it has been opened already.
See also
Watchdog_init()
Watchdog_close()

§ Watchdog_Params_init()

void Watchdog_Params_init ( Watchdog_Params params)

Function to initialize the Watchdog_Params structure to its defaults.

Parameters
paramsAn pointer to Watchdog_Params structure for initialization

Default parameters: callbackFxn = NULL resetMode = Watchdog_RESET_ON debugStallMode = Watchdog_DEBUG_STALL_ON

§ Watchdog_setReload()

int_fast16_t Watchdog_setReload ( Watchdog_Handle  handle,
uint32_t  ticks 
)

Sets the Watchdog reload value.

Sets the value from which the Watchdog will countdown after it reaches zero. This is how the reload value can be changed after the Watchdog has already been opened. The new reload value will be loaded into the Watchdog timer when this function is called. Watchdog_setReload is not reentrant. For CC13XX/CC26XX, if the parameter 'ticks' is set to zero (0), a Watchdog interrupt is immediately generated.

This API is not applicable for all platforms. See the page for your specific driver implementation for details.

Parameters
handleA Watchdog_Handle
ticksValue to be loaded into Watchdog timer Unit is in Watchdog clock ticks
Returns
Watchdog_STATUS_SUCCESS on success, Watchdog_STATUS_UNSUPPORTED if driver does not support this API.

§ Watchdog_convertMsToTicks()

uint32_t Watchdog_convertMsToTicks ( Watchdog_Handle  handle,
uint32_t  milliseconds 
)

Converts milliseconds to Watchdog clock ticks.

Converts the input value into number of Watchdog clock ticks as close as possible. If the converted value exceeds 32 bits, a zero (0) will be returned to indicate overflow. The converted value can be used as the function parameter 'ticks' in Watchdog_setReload().

This API is not applicable for all platforms. See the page for your specific driver implementation for details.

Parameters
handleA Watchdog_Handle
millisecondsValue to be converted
Returns
Converted value in number of Watchdog clock ticks A value of zero (0) means the converted value exceeds 32 bits or that the operation is not supported for the specific device.
See also
Watchdog_setReload()
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale