Line data Source code
1 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : int task_wdt_feed(int channel_id);
104 :
105 : /**
106 : * @brief Pause all channels before changing system power mode.
107 : *
108 : * Stop the internal timer and feed the hardware watchdog a last time
109 : * (if enabled). It is expected that the system enters a low-power
110 : * mode quite fast after this call.
111 : *
112 : * @note To pause the hardware watchdog (if this is supported),
113 : * enable @kconfig{CONFIG_TASK_WDT_HW_FALLBACK_PAUSE_IN_SLEEP} in your
114 : * configuration.
115 : */
116 1 : void task_wdt_suspend(void);
117 :
118 : /**
119 : * @brief Resume all channels execution.
120 : *
121 : * Resume the internal timer and feed all channels. Also feed the hardware
122 : * watchdog (if enabled) to let enough time to the application to resume
123 : * feeding the channels by itself.
124 : */
125 1 : void task_wdt_resume(void);
126 :
127 : #ifdef __cplusplus
128 : }
129 : #endif
130 :
131 : /**
132 : * @}
133 : */
134 :
135 : #endif /* ZEPHYR_INCLUDE_TASK_WDT_H_ */
|
