Watchdog.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2017, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*!*****************************************************************************
33  * @file Watchdog.h
34  *
35  * @brief Watchdog driver interface
36  *
37  * The Watchdog header file should be included in an application as follows:
38  * @code
39  * #include <ti/drivers/Watchdog.h>
40  * @endcode
41  *
42  * # Overview #
43  *
44  * A watchdog timer can be used to generate a reset signal if a system has
45  * become unresponsive. The Watchdog driver simplifies configuring and
46  * starting the watchdog peripherals. The watchdog peripheral can be
47  * configured with resets either on or off and a user-specified timeout
48  * period.
49  *
50  * When the watchdog peripheral is configured not to generate a reset, it
51  * can be used to cause a hardware interrupt at a programmable interval.
52  * The driver provides the ability to specify a user-provided callback
53  * function that is called when the watchdog causes an interrupt.
54  *
55  * # Operation #
56  *
57  * The Watchdog driver simplifies configuring and starting the Watchdog
58  * peripherals. The Watchdog can be set up to produce a reset signal after a
59  * timeout, or simply cause a hardware interrupt at a programmable interval.
60  * The driver provides the ability to specify a callback function that is
61  * called when the Watchdog causes an interrupt.
62  *
63  * When resets are turned on, it is the user application's responsibility to
64  * call Watchdog_clear() in order to clear the Watchdog and prevent a reset.
65  * Watchdog_clear() can be called at any time.
66  *
67  * # Usage #
68  *
69  * The Watchdog driver must be initialized by calling Watchdog_init(),
70  * before any other Watchdog APIs can be called.
71  * Once the watchdog is initialized, a Watchdog object can be created
72  * through the following steps:
73  * - Create and initialize the Watchdog_Params structure.
74  * - Assign desired values to parameters.
75  * - Call Watchdog_open().
76  * - Save the Watchdog_Handle returned by Watchdog_open(). This will be
77  * used to interact with the Watchdog object just created.
78  *
79  * To have a user-defined function run at the hardware interrupt caused by
80  * a watchdog timer timeout, define a function of the following type:
81  * @code
82  * typedef void (*Watchdog_Callback)(uintptr_t);
83  * @endcode
84  * Then pass the function to Watchdog_open() through the Watchdog_Params
85  * structure.
86  *
87  * An example of the Watchdog creation process that uses a callback
88  * function:
89  * @code
90  * Watchdog_Params params;
91  * Watchdog_Handle watchdog;
92  *
93  * Watchdog_init();
94  *
95  * Watchdog_Params_init(&params);
96  * params.resetMode = Watchdog_RESET_ON;
97  * params.callbackFxn = UserCallbackFxn;
98  *
99  * watchdog = Watchdog_open(Board_WATCHDOG, &params);
100  * if (watchdog == NULL) {
101  * `Error opening watchdog`
102  * }
103  * @endcode
104  *
105  * If no Watchdog_Params structure is passed to Watchdog_open(), the
106  * default values are used. By default, the Watchdog driver has resets
107  * turned on, no callback function specified, and stalls the timer at
108  * breakpoints during debugging.
109  *
110  * Options for the resetMode parameter are Watchdog_RESET_ON and
111  * Watchdog_RESET_OFF. The latter allows the watchdog to be used like
112  * another timer interrupt. When resetMode is Watchdog_RESET_ON, it is up
113  * to the application to call Watchdog_clear() to clear the Watchdog
114  * interrupt flag to prevent a reset. Watchdog_clear() can be called at
115  * any time.
116  *
117  * # Implementation #
118  *
119  * This module serves as the main interface for TI-RTOS applications. Its
120  * purpose is to redirect the module's APIs to specific peripheral
121  * implementations which are specified using a pointer to a
122  * Watchdog_FxnTable.
123  *
124  * The Watchdog driver interface module is joined (at link time)
125  * to a NULL-terminated array of Watchdog_Config data structures named
126  * *Watchdog_config*. *Watchdog_config* is implemented in the application with
127  * each entry being an instance of a Watchdog peripheral. Each entry in
128  * *Watchdog_config* contains a:
129  * - (Watchdog_FxnTable *) to a set of functions that implement a Watchdog
130  * peripheral
131  * - (void *) data object that is associated with the Watchdog_FxnTable
132  * - (void *) hardware attributes that are associated to the Watchdog_FxnTable
133  *
134  *******************************************************************************
135  */
136 
137 #ifndef ti_drivers_Watchdog__include
138 #define ti_drivers_Watchdog__include
139 
140 #ifdef __cplusplus
141 extern "C" {
142 #endif
143 
144 #include <stdint.h>
145 
163 #define Watchdog_CMD_RESERVED (32)
164 
177 #define Watchdog_STATUS_RESERVED (-32)
178 
192 #define Watchdog_STATUS_SUCCESS (0)
193 
200 #define Watchdog_STATUS_ERROR (-1)
201 
209 #define Watchdog_STATUS_UNDEFINEDCMD (-2)
210 
218 #define Watchdog_STATUS_UNSUPPORTED (-3)
219 
229 /* Add Watchdog_CMD_<commands> here */
230 
239 
248 typedef enum Watchdog_DebugMode_ {
252 
260 typedef enum Watchdog_ResetMode_ {
264 
273 typedef void (*Watchdog_Callback)(uintptr_t handle);
274 
283 typedef struct Watchdog_Params_ {
286  Watchdog_ResetMode resetMode;
288  Watchdog_DebugMode debugStallMode;
290  void *custom;
293 
298 typedef void (*Watchdog_ClearFxn) (Watchdog_Handle handle);
299 
304 typedef void (*Watchdog_CloseFxn) (Watchdog_Handle handle);
305 
310 typedef int_fast16_t (*Watchdog_ControlFxn) (Watchdog_Handle handle,
311  uint_fast16_t cmd,
312  void *arg);
313 
318 typedef void (*Watchdog_InitFxn) (Watchdog_Handle handle);
319 
324 typedef Watchdog_Handle (*Watchdog_OpenFxn) (Watchdog_Handle handle,
325  Watchdog_Params *params);
326 
331 typedef int_fast16_t (*Watchdog_SetReloadFxn)(Watchdog_Handle handle,
332  uint32_t ticks);
333 
338 typedef uint32_t (*Watchdog_ConvertMsToTicksFxn) (Watchdog_Handle handle,
339  uint32_t milliseconds);
340 
346 typedef struct Watchdog_FxnTable_ {
355 
367 typedef struct Watchdog_Config_ {
372 
374  void *object;
375 
377  void const *hwAttrs;
379 
388 extern void Watchdog_clear(Watchdog_Handle handle);
389 
401 extern void Watchdog_close(Watchdog_Handle handle);
402 
440 extern int_fast16_t Watchdog_control(Watchdog_Handle handle,
441  uint_fast16_t cmd,
442  void *arg);
443 
452 extern void Watchdog_init(void);
453 
473 extern Watchdog_Handle Watchdog_open(uint_least8_t index, Watchdog_Params *params);
474 
486 extern void Watchdog_Params_init(Watchdog_Params *params);
487 
509 extern int_fast16_t Watchdog_setReload(Watchdog_Handle handle, uint32_t ticks);
510 
532 extern uint32_t Watchdog_convertMsToTicks(Watchdog_Handle handle,
533  uint32_t milliseconds);
534 
535 #ifdef __cplusplus
536 }
537 #endif
538 
539 #endif /* ti_drivers_Watchdog__include */
Watchdog Parameters.
Definition: Watchdog.h:283
void Watchdog_clear(Watchdog_Handle handle)
Clears the Watchdog.
enum Watchdog_ResetMode_ Watchdog_ResetMode
Watchdog reset mode settings.
Watchdog_Handle(* Watchdog_OpenFxn)(Watchdog_Handle handle, Watchdog_Params *params)
A function pointer to a driver specific implementation of Watchdog_open().
Definition: Watchdog.h:324
void(* Watchdog_Callback)(uintptr_t handle)
Watchdog callback pointer.
Definition: Watchdog.h:273
Definition: Watchdog.h:261
void * object
Definition: Watchdog.h:374
Watchdog_OpenFxn watchdogOpen
Definition: Watchdog.h:351
Watchdog_CloseFxn watchdogClose
Definition: Watchdog.h:348
Watchdog_ResetMode resetMode
Definition: Watchdog.h:286
void(* Watchdog_InitFxn)(Watchdog_Handle handle)
A function pointer to a driver specific implementation of Watchdog_init().
Definition: Watchdog.h:318
Watchdog_DebugMode_
Watchdog debug stall settings.
Definition: Watchdog.h:248
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().
Definition: Watchdog.h:310
Watchdog_InitFxn watchdogInit
Definition: Watchdog.h:350
void const * hwAttrs
Definition: Watchdog.h:377
Watchdog Global configuration.
Definition: Watchdog.h:367
void Watchdog_Params_init(Watchdog_Params *params)
Function to initialize the Watchdog_Params structure to its defaults.
Definition: Watchdog.h:250
int_fast16_t Watchdog_control(Watchdog_Handle handle, uint_fast16_t cmd, void *arg)
Function performs implementation specific features on a given Watchdog_Handle.
Watchdog_ResetMode_
Watchdog reset mode settings.
Definition: Watchdog.h:260
void(* Watchdog_CloseFxn)(Watchdog_Handle handle)
A function pointer to a driver specific implementation of Watchdog_close().
Definition: Watchdog.h:304
struct Watchdog_Config_ * Watchdog_Handle
Watchdog Handle.
Definition: Watchdog.h:238
Watchdog_Callback callbackFxn
Definition: Watchdog.h:284
int_fast16_t(* Watchdog_SetReloadFxn)(Watchdog_Handle handle, uint32_t ticks)
A function pointer to a driver specific implementation of Watchdog_setReload().
Definition: Watchdog.h:331
void * custom
Definition: Watchdog.h:290
Definition: Watchdog.h:249
void Watchdog_close(Watchdog_Handle handle)
Function to close a Watchdog peripheral specified by the Watchdog handle.It stops (holds) the Watchdo...
void Watchdog_init(void)
Initializes the Watchdog module.
The definition of a Watchdog function table that contains the required set of functions to control a ...
Definition: Watchdog.h:346
void(* Watchdog_ClearFxn)(Watchdog_Handle handle)
A function pointer to a driver specific implementation of Watchdog_clear().
Definition: Watchdog.h:298
uint32_t(* Watchdog_ConvertMsToTicksFxn)(Watchdog_Handle handle, uint32_t milliseconds)
A function pointer to a driver specific implementation of Watchdog_ConvertMsToTicksFxn().
Definition: Watchdog.h:338
uint32_t Watchdog_convertMsToTicks(Watchdog_Handle handle, uint32_t milliseconds)
Converts milliseconds to Watchdog clock ticks.
Watchdog_ConvertMsToTicksFxn watchdogConvertMsToTicks
Definition: Watchdog.h:353
struct Watchdog_Params_ Watchdog_Params
Watchdog Parameters.
Watchdog_ControlFxn watchdogControl
Definition: Watchdog.h:349
Watchdog_SetReloadFxn watchdogSetReload
Definition: Watchdog.h:352
enum Watchdog_DebugMode_ Watchdog_DebugMode
Watchdog debug stall settings.
Watchdog_ClearFxn watchdogClear
Definition: Watchdog.h:347
struct Watchdog_Config_ Watchdog_Config
Watchdog Global configuration.
Definition: Watchdog.h:262
Watchdog_FxnTable const * fxnTablePtr
Definition: Watchdog.h:371
Watchdog_Handle Watchdog_open(uint_least8_t index, Watchdog_Params *params)
Opens a Watchdog.
Watchdog_DebugMode debugStallMode
Definition: Watchdog.h:288
int_fast16_t Watchdog_setReload(Watchdog_Handle handle, uint32_t ticks)
Sets the Watchdog reload value.
struct Watchdog_FxnTable_ Watchdog_FxnTable
The definition of a Watchdog function table that contains the required set of functions to control a ...
Copyright 2017, Texas Instruments Incorporated