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;
Watchdog_init();
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:

Create and initialize the Watchdog_Params structure.
Assign desired values to parameters.
Call Watchdog_open().
Save the Watchdog_Handle returned by Watchdog_open(). This will be used to interact with the Watchdog object just created.

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;
Watchdog_init();
Watchdog_Params_init(&params);
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

typedef struct Watchdog_Config_* 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

typedef struct Watchdog_Config_ 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

enum 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

enum 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

handle A 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

handle A 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

handle	A Watchdog_Handle returned from Watchdog_open()
cmd	Watchdog.h or Watchdog*.h commands.
arg	An 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

index	Logical peripheral number for the Watchdog indexed into the Watchdog_config table
params	Pointer 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

params An 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

handle	A Watchdog_Handle
ticks	Value 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

handle	A Watchdog_Handle
milliseconds	Value 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()

Detailed Description

Overview

Usage

Synopsis

Examples

Configuration

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

§ Watchdog_Handle

§ Watchdog_Callback

§ Watchdog_ClearFxn

§ Watchdog_CloseFxn

§ Watchdog_ControlFxn

§ Watchdog_InitFxn

§ Watchdog_OpenFxn

§ Watchdog_SetReloadFxn

§ Watchdog_ConvertMsToTicksFxn

§ Watchdog_Config

Enumeration Type Documentation

§ Watchdog_DebugMode

§ Watchdog_ResetMode

Function Documentation

§ Watchdog_clear()

§ Watchdog_close()

§ Watchdog_control()

§ Watchdog_init()

§ Watchdog_open()

§ Watchdog_Params_init()

§ Watchdog_setReload()

§ Watchdog_convertMsToTicks()