Watchdog.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2019, 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  * @anchor ti_drivers_Watchdog_Overview
38  * # Overview #
39  *
40  * A watchdog timer can be used to generate a reset signal if a system has
41  * become unresponsive. The Watchdog driver simplifies configuring and
42  * starting the watchdog peripherals. The watchdog peripheral can be
43  * configured with resets either on or off and a user-specified timeout
44  * period.
45  *
46  * When the watchdog peripheral is configured not to generate a reset, it
47  * can be used to cause a hardware interrupt at a programmable interval.
48  * The driver provides the ability to specify a user-provided callback
49  * function that is called when the watchdog causes an interrupt.
50  *
51  * The Watchdog driver simplifies configuring and starting the Watchdog
52  * peripherals. The Watchdog can be set up to produce a reset signal after a
53  * timeout, or simply cause a hardware interrupt at a programmable interval.
54  * The driver provides the ability to specify a callback function that is
55  * called when the Watchdog causes an interrupt.
56  *
57  * When resets are turned on, it is the user application's responsibility to
58  * call Watchdog_clear() in order to clear the Watchdog and prevent a reset.
59  * Watchdog_clear() can be called at any time.
60  *
61  * @anchor ti_drivers_Watchdog_Usage
62  * # Usage #
63  *
64  * This section will cover driver usage.
65  * @anchor ti_drivers_Watchdog_Synopsis
66  * ## Synopsis #
67  *
68  * Open the driver with default settings:
69  * @code
70  * Watchdog_Handle watchdogHandle;
71  *
72  * Watchdog_init();
73  * watchdogHandle = Watchdog_open(WATCHDOG_INDEX, NULL);
74  * if (watchdogHandle == NULL) {
75  * // Spin forever
76  * while(1);
77  * }
78  * @endcode
79  *
80  * The Watchdog driver must be initialized by calling Watchdog_init(),
81  * before any other Watchdog APIs can be called.
82  * Once the watchdog is initialized, a Watchdog object can be created
83  * through the following steps:
84  * - Create and initialize the #Watchdog_Params structure.
85  * - Assign desired values to parameters.
86  * - Call Watchdog_open().
87  * - Save the Watchdog_Handle returned by Watchdog_open(). This will be
88  * used to interact with the Watchdog object just created.
89  *
90  * To have a user-defined function run at the hardware interrupt caused by
91  * a watchdog timer timeout, define a function of the following type:
92  * @code
93  * typedef void (*Watchdog_Callback)(uintptr_t);
94  * @endcode
95  * Then pass the function to Watchdog_open() through the #Watchdog_Params
96  * structure.
97  *
98  * An example of the Watchdog creation process that uses a callback
99  * function:
100  * @anchor ti_drivers_Watchdog_example_callback
101  * @code
102  * void UserCallbackFxn(Watchdog_Handle handle)
103  * {
104  * printf("Watchdog timer triggered!\n");
105  * releaseResources();
106  * }
107  *
108  * ...
109  *
110  * Watchdog_Params params;
111  * Watchdog_Handle watchdogHandle;
112  *
113  * Watchdog_init();
114  *
115  * Watchdog_Params_init(&params);
116  * params.resetMode = Watchdog_RESET_ON;
117  * params.callbackFxn = (Watchdog_Callback) UserCallbackFxn;
118  *
119  * watchdogHandle = Watchdog_open(CONFIG_WATCHDOG0, &params);
120  * if (watchdogHandle == NULL) {
121  * // Error opening Watchdog
122  * while (1);
123  * }
124  *
125  * @endcode
126  *
127  * If no #Watchdog_Params structure is passed to Watchdog_open(), the
128  * default values are used. By default, the Watchdog driver has resets
129  * turned on, no callback function specified, and stalls the timer at
130  * breakpoints during debugging.
131  *
132  * Options for the resetMode parameter are #Watchdog_RESET_ON and
133  * #Watchdog_RESET_OFF. The latter allows the watchdog to be used like
134  * another timer interrupt. When resetMode is #Watchdog_RESET_ON, it is up
135  * to the application to call Watchdog_clear() to clear the Watchdog
136  * interrupt flag to prevent a reset. Watchdog_clear() can be called at
137  * any time.
138  *
139  * @anchor ti_drivers_Watchdog_Examples
140  * # Examples
141  * - @ref ti_drivers_Watchdog_Synopsis "Default Example"
142  * - @ref ti_drivers_Watchdog_example_callback "Callback Function before watchdog reset"
143  *
144  * @anchor ti_drivers_Watchdog_Configuration
145  * # Configuration
146  *
147  * Refer to the @ref driver_configuration "Driver's Configuration" section
148  * for more information.
149  *
150  *******************************************************************************
151  */
152 
153 #ifndef ti_drivers_Watchdog__include
154 #define ti_drivers_Watchdog__include
155 
156 #include <stdint.h>
157 
158 #ifdef __cplusplus
159 extern "C" {
160 #endif
161 
179 #define Watchdog_CMD_RESERVED (32)
180 
193 #define Watchdog_STATUS_RESERVED (-32)
194 
208 #define Watchdog_STATUS_SUCCESS (0)
209 
216 #define Watchdog_STATUS_ERROR (-1)
217 
225 #define Watchdog_STATUS_UNDEFINEDCMD (-2)
226 
234 #define Watchdog_STATUS_UNSUPPORTED (-3)
235 
245 /* Add Watchdog_CMD_<commands> here */
246 
255 
264 typedef enum {
268 
276 typedef enum {
280 
289 typedef void (*Watchdog_Callback)(uintptr_t handle);
290 
299 typedef struct {
302  Watchdog_ResetMode resetMode;
304  Watchdog_DebugMode debugStallMode;
306  void *custom;
309 
314 typedef void (*Watchdog_ClearFxn) (Watchdog_Handle handle);
315 
320 typedef void (*Watchdog_CloseFxn) (Watchdog_Handle handle);
321 
326 typedef int_fast16_t (*Watchdog_ControlFxn) (Watchdog_Handle handle,
327  uint_fast16_t cmd,
328  void *arg);
329 
334 typedef void (*Watchdog_InitFxn) (Watchdog_Handle handle);
335 
340 typedef Watchdog_Handle (*Watchdog_OpenFxn) (Watchdog_Handle handle,
341  Watchdog_Params *params);
342 
347 typedef int_fast16_t (*Watchdog_SetReloadFxn)(Watchdog_Handle handle,
348  uint32_t ticks);
349 
354 typedef uint32_t (*Watchdog_ConvertMsToTicksFxn) (Watchdog_Handle handle,
355  uint32_t milliseconds);
356 
362 typedef struct {
371 
383 typedef struct Watchdog_Config_ {
388 
390  void *object;
391 
393  void const *hwAttrs;
395 
404 extern void Watchdog_clear(Watchdog_Handle handle);
405 
417 extern void Watchdog_close(Watchdog_Handle handle);
418 
456 extern int_fast16_t Watchdog_control(Watchdog_Handle handle,
457  uint_fast16_t cmd,
458  void *arg);
459 
468 extern void Watchdog_init(void);
469 
489 extern Watchdog_Handle Watchdog_open(uint_least8_t index, Watchdog_Params *params);
490 
502 extern void Watchdog_Params_init(Watchdog_Params *params);
503 
525 extern int_fast16_t Watchdog_setReload(Watchdog_Handle handle, uint32_t ticks);
526 
548 extern uint32_t Watchdog_convertMsToTicks(Watchdog_Handle handle,
549  uint32_t milliseconds);
550 
551 #ifdef __cplusplus
552 }
553 #endif
554 
555 #endif /* ti_drivers_Watchdog__include */
Watchdog_Callback callbackFxn
Definition: Watchdog.h:300
Watchdog_DebugMode debugStallMode
Definition: Watchdog.h:304
void Watchdog_clear(Watchdog_Handle handle)
Clears the Watchdog.
void * custom
Definition: Watchdog.h:306
Watchdog_ControlFxn watchdogControl
Definition: Watchdog.h:365
Watchdog_Handle(* Watchdog_OpenFxn)(Watchdog_Handle handle, Watchdog_Params *params)
A function pointer to a driver specific implementation of Watchdog_open().
Definition: Watchdog.h:340
Watchdog_ConvertMsToTicksFxn watchdogConvertMsToTicks
Definition: Watchdog.h:369
void(* Watchdog_Callback)(uintptr_t handle)
Watchdog callback pointer.
Definition: Watchdog.h:289
Watchdog_ResetMode resetMode
Definition: Watchdog.h:302
void * object
Definition: Watchdog.h:390
Watchdog Parameters.
Definition: Watchdog.h:299
void(* Watchdog_InitFxn)(Watchdog_Handle handle)
A function pointer to a driver specific implementation of Watchdog_init().
Definition: Watchdog.h:334
Definition: Watchdog.h:277
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:326
void const * hwAttrs
Definition: Watchdog.h:393
Watchdog Global configuration.
Definition: Watchdog.h:383
void Watchdog_Params_init(Watchdog_Params *params)
Function to initialize the Watchdog_Params structure to its defaults.
int_fast16_t Watchdog_control(Watchdog_Handle handle, uint_fast16_t cmd, void *arg)
Function performs implementation specific features on a given Watchdog_Handle.
void(* Watchdog_CloseFxn)(Watchdog_Handle handle)
A function pointer to a driver specific implementation of Watchdog_close().
Definition: Watchdog.h:320
Watchdog_DebugMode
Watchdog debug stall settings.
Definition: Watchdog.h:264
struct Watchdog_Config_ * Watchdog_Handle
Watchdog Handle.
Definition: Watchdog.h:254
Watchdog_OpenFxn watchdogOpen
Definition: Watchdog.h:367
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:347
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.
void(* Watchdog_ClearFxn)(Watchdog_Handle handle)
A function pointer to a driver specific implementation of Watchdog_clear().
Definition: Watchdog.h:314
uint32_t(* Watchdog_ConvertMsToTicksFxn)(Watchdog_Handle handle, uint32_t milliseconds)
A function pointer to a driver specific implementation of Watchdog_ConvertMsToTicksFxn().
Definition: Watchdog.h:354
uint32_t Watchdog_convertMsToTicks(Watchdog_Handle handle, uint32_t milliseconds)
Converts milliseconds to Watchdog clock ticks.
Watchdog_ClearFxn watchdogClear
Definition: Watchdog.h:363
Watchdog_SetReloadFxn watchdogSetReload
Definition: Watchdog.h:368
Definition: Watchdog.h:278
The definition of a Watchdog function table that contains the required set of functions to control a ...
Definition: Watchdog.h:362
Watchdog_ResetMode
Watchdog reset mode settings.
Definition: Watchdog.h:276
Definition: Watchdog.h:265
struct Watchdog_Config_ Watchdog_Config
Watchdog Global configuration.
Watchdog_InitFxn watchdogInit
Definition: Watchdog.h:366
Definition: Watchdog.h:266
Watchdog_FxnTable const * fxnTablePtr
Definition: Watchdog.h:387
Watchdog_Handle Watchdog_open(uint_least8_t index, Watchdog_Params *params)
Opens a Watchdog.
Watchdog_CloseFxn watchdogClose
Definition: Watchdog.h:364
int_fast16_t Watchdog_setReload(Watchdog_Handle handle, uint32_t ticks)
Sets the Watchdog reload value.
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale