1 /*
2  * Copyright (c) 2020 Libre Solar Technologies GmbH
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 /**
8  * @file
9  * @brief Task watchdog header file
10  *
11  * This header file declares prototypes for the task watchdog APIs.
12  *
13  * The task watchdog can be used to monitor correct operation of individual
14  * threads. It can be used together with a hardware watchdog as a fallback.
15  */
16 
17 #ifndef ZEPHYR_INCLUDE_TASK_WDT_H_
18 #define ZEPHYR_INCLUDE_TASK_WDT_H_
19 
20 #include <zephyr/types.h>
21 #include <zephyr/kernel.h>
22 #include <zephyr/device.h>
23 
24 /**
25  * @brief Task Watchdog APIs
26  * @defgroup task_wdt_api Task Watchdog APIs
27  * @since 2.5
28  * @version 0.8.0
29  * @ingroup os_services
30  * @{
31  */
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
37 /** Task watchdog callback. */
38 typedef void (*task_wdt_callback_t)(int channel_id, void *user_data);
39 
40 /**
41  * @brief Initialize task watchdog.
42  *
43  * This function sets up necessary kernel timers and the hardware watchdog (if
44  * desired as fallback). It has to be called before task_wdt_add() and
45  * task_wdt_feed().
46  *
47  * @param hw_wdt Pointer to the hardware watchdog device used as fallback.
48  *               Pass NULL if no hardware watchdog fallback is desired.
49  *
50  * @retval 0 If successful.
51  * @retval -ENOTSUP If assigning a hardware watchdog is not supported.
52  * @retval -Errno Negative errno if the fallback hw_wdt is used and the
53  *                install timeout API fails.  See wdt_install_timeout()
54  *                API for possible return values.
55  */
56 int task_wdt_init(const struct device *hw_wdt);
57 
58 /**
59  * @brief Install new timeout.
60  *
61  * Adds a new timeout to the list of task watchdog channels.
62  *
63  * @param reload_period Period in milliseconds used to reset the timeout
64  * @param callback Function to be called when watchdog timer expired. Pass
65  *                 NULL to use system reset handler.
66  * @param user_data User data to associate with the watchdog channel.
67  *
68  * @retval channel_id If successful, a non-negative value indicating the index
69  *                    of the channel to which the timeout was assigned. This
70  *                    ID is supposed to be used as the parameter in calls to
71  *                    task_wdt_feed().
72  * @retval -EINVAL If the reload_period is invalid.
73  * @retval -ENOMEM If no more timeouts can be installed.
74  */
75 int task_wdt_add(uint32_t reload_period, task_wdt_callback_t callback,
76 		 void *user_data);
77 
78 /**
79  * @brief Delete task watchdog channel.
80  *
81  * Deletes the specified channel from the list of task watchdog channels. The
82  * channel is now available again for other tasks via task_wdt_add() function.
83  *
84  * @param channel_id Index of the channel as returned by task_wdt_add().
85  *
86  * @retval 0 If successful.
87  * @retval -EINVAL If there is no installed timeout for supplied channel.
88  */
89 int task_wdt_delete(int channel_id);
90 
91 /**
92  * @brief Feed specified watchdog channel.
93  *
94  * This function loops through all installed task watchdogs and updates the
95  * internal kernel timer used as for the software watchdog with the next due
96  * timeout.
97  *
98  * @param channel_id Index of the fed channel as returned by task_wdt_add().
99  *
100  * @retval 0 If successful.
101  * @retval -EINVAL If there is no installed timeout for supplied channel.
102  */
103 int task_wdt_feed(int channel_id);
104 
105 #ifdef __cplusplus
106 }
107 #endif
108 
109 /**
110  * @}
111  */
112 
113 #endif /* ZEPHYR_INCLUDE_TASK_WDT_H_ */
114