Line data Source code
1 1 : /*
2 : * Copyright (c) 2017 Nordic Semiconductor ASA
3 : * Copyright (c) 2015 Intel Corporation
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file
10 : * @ingroup watchdog_interface
11 : * @brief Main header file for watchdog driver API.
12 : */
13 :
14 : #ifndef ZEPHYR_INCLUDE_DRIVERS_WATCHDOG_H_
15 : #define ZEPHYR_INCLUDE_DRIVERS_WATCHDOG_H_
16 :
17 : /**
18 : * @brief Interfaces for watchdog devices.
19 : * @defgroup watchdog_interface Watchdog
20 : * @since 1.0
21 : * @version 1.0.0
22 : * @ingroup io_interfaces
23 : * @{
24 : */
25 :
26 : #include <zephyr/types.h>
27 : #include <zephyr/sys/util.h>
28 : #include <zephyr/device.h>
29 :
30 : #ifdef __cplusplus
31 : extern "C" {
32 : #endif
33 :
34 : /**
35 : * @name Watchdog options
36 : * @anchor WDT_OPT
37 : * @{
38 : */
39 :
40 : /** @brief Pause watchdog timer when CPU is in sleep state. */
41 1 : #define WDT_OPT_PAUSE_IN_SLEEP BIT(0)
42 :
43 : /** @brief Pause watchdog timer when CPU is halted by the debugger. */
44 1 : #define WDT_OPT_PAUSE_HALTED_BY_DBG BIT(1)
45 :
46 : /** @} */
47 :
48 : /**
49 : * @name Watchdog behavior flags
50 : * @anchor WDT_FLAGS
51 : * @{
52 : */
53 :
54 : /** @cond INTERNAL_HIDDEN */
55 : /** @brief Watchdog reset flag bit field mask shift. */
56 : #define WDT_FLAG_RESET_SHIFT (0)
57 : /** @brief Watchdog reset flag bit field mask. */
58 : #define WDT_FLAG_RESET_MASK (0x3 << WDT_FLAG_RESET_SHIFT)
59 : /** @endcond */
60 :
61 : /** Reset: none */
62 1 : #define WDT_FLAG_RESET_NONE (0 << WDT_FLAG_RESET_SHIFT)
63 : /** Reset: CPU core */
64 1 : #define WDT_FLAG_RESET_CPU_CORE (1 << WDT_FLAG_RESET_SHIFT)
65 : /** Reset: SoC */
66 1 : #define WDT_FLAG_RESET_SOC (2 << WDT_FLAG_RESET_SHIFT)
67 :
68 : /** @} */
69 :
70 : /**
71 : * @brief Watchdog timeout window.
72 : *
73 : * Each installed timeout needs feeding within the specified time window,
74 : * otherwise the watchdog will trigger. If the watchdog instance does not
75 : * support window timeouts then min value must be equal to 0.
76 : *
77 : * @note If specified values can not be precisely set they are always rounded
78 : * up.
79 : */
80 1 : struct wdt_window {
81 : /** Lower limit of watchdog feed timeout in milliseconds. */
82 1 : uint32_t min;
83 : /** Upper limit of watchdog feed timeout in milliseconds. */
84 1 : uint32_t max;
85 : };
86 :
87 : /**
88 : * @brief Watchdog callback.
89 : *
90 : * @param dev Watchdog device instance.
91 : * @param channel_id Channel identifier.
92 : */
93 1 : typedef void (*wdt_callback_t)(const struct device *dev, int channel_id);
94 :
95 : /** @brief Watchdog timeout configuration. */
96 1 : struct wdt_timeout_cfg {
97 : /** Timing parameters of watchdog timeout. */
98 1 : struct wdt_window window;
99 : /** Timeout callback (can be `NULL`). */
100 1 : wdt_callback_t callback;
101 : #if defined(CONFIG_WDT_MULTISTAGE) || defined(__DOXYGEN__)
102 : /**
103 : * Pointer to the next timeout configuration.
104 : *
105 : * This field is only available if @kconfig{CONFIG_WDT_MULTISTAGE} is
106 : * enabled (watchdogs with staged timeouts functionality). Value must be
107 : * `NULL` for single stage timeout.
108 : */
109 1 : struct wdt_timeout_cfg *next;
110 : #endif
111 : /** Flags (see @ref WDT_FLAGS). */
112 1 : uint8_t flags;
113 : };
114 :
115 : /** @cond INTERNAL_HIDDEN */
116 :
117 : /**
118 : * @brief Callback API for setting up watchdog instance.
119 : * @see wdt_setup().
120 : */
121 : typedef int (*wdt_api_setup)(const struct device *dev, uint8_t options);
122 :
123 : /**
124 : * @brief Callback API for disabling watchdog instance.
125 : * @see wdt_disable().
126 : */
127 : typedef int (*wdt_api_disable)(const struct device *dev);
128 :
129 : /**
130 : * @brief Callback API for installing new timeout.
131 : * @see wdt_install_timeout().
132 : */
133 : typedef int (*wdt_api_install_timeout)(const struct device *dev,
134 : const struct wdt_timeout_cfg *cfg);
135 :
136 : /**
137 : * @brief Callback API for feeding specified watchdog timeout.
138 : * @see wdt_feed().
139 : */
140 : typedef int (*wdt_api_feed)(const struct device *dev, int channel_id);
141 :
142 : __subsystem struct wdt_driver_api {
143 : wdt_api_setup setup;
144 : wdt_api_disable disable;
145 : wdt_api_install_timeout install_timeout;
146 : wdt_api_feed feed;
147 : };
148 : /**
149 : * @endcond
150 : */
151 :
152 : /**
153 : * @brief Set up watchdog instance.
154 : *
155 : * This function is used for configuring global watchdog settings that
156 : * affect all timeouts. It should be called after installing timeouts.
157 : * After successful return, all installed timeouts are valid and must be
158 : * serviced periodically by calling wdt_feed().
159 : *
160 : * @param dev Watchdog device instance.
161 : * @param options Configuration options (see @ref WDT_OPT).
162 : *
163 : * @retval 0 If successful.
164 : * @retval -ENOTSUP If any of the set options is not supported.
165 : * @retval -EBUSY If watchdog instance has been already setup.
166 : * @retval -errno In case of any other failure.
167 : */
168 1 : __syscall int wdt_setup(const struct device *dev, uint8_t options);
169 :
170 : static inline int z_impl_wdt_setup(const struct device *dev, uint8_t options)
171 : {
172 : const struct wdt_driver_api *api =
173 : (const struct wdt_driver_api *)dev->api;
174 :
175 : return api->setup(dev, options);
176 : }
177 :
178 : /**
179 : * @brief Disable watchdog instance.
180 : *
181 : * This function disables the watchdog instance and automatically uninstalls all
182 : * timeouts. To set up a new watchdog, install timeouts and call wdt_setup()
183 : * again. Not all watchdogs can be restarted after they are disabled.
184 : *
185 : * @param dev Watchdog device instance.
186 : *
187 : * @retval 0 If successful.
188 : * @retval -EFAULT If watchdog instance is not enabled.
189 : * @retval -EPERM If watchdog can not be disabled directly by application code.
190 : * @retval -errno In case of any other failure.
191 : */
192 1 : __syscall int wdt_disable(const struct device *dev);
193 :
194 : static inline int z_impl_wdt_disable(const struct device *dev)
195 : {
196 : const struct wdt_driver_api *api =
197 : (const struct wdt_driver_api *)dev->api;
198 :
199 : return api->disable(dev);
200 : }
201 :
202 : /**
203 : * @brief Install a new timeout.
204 : *
205 : * @note This function must be used before wdt_setup(). Changes applied here
206 : * have no effects until wdt_setup() is called.
207 : *
208 : * @param dev Watchdog device instance.
209 : * @param[in] cfg Timeout configuration.
210 : *
211 : * @retval channel_id If successful, a non-negative value indicating the index
212 : * of the channel to which the timeout was assigned. This value is supposed to
213 : * be used as the parameter in calls to wdt_feed().
214 : * @retval -EBUSY If timeout can not be installed while watchdog has already
215 : * been setup.
216 : * @retval -ENOMEM If no more timeouts can be installed.
217 : * @retval -ENOTSUP If any of the set flags is not supported.
218 : * @retval -EINVAL If any of the window timeout value is out of possible range.
219 : * This value is also returned if watchdog supports only one timeout value for
220 : * all timeouts and the supplied timeout window differs from windows for alarms
221 : * installed so far.
222 : * @retval -errno In case of any other failure.
223 : */
224 1 : static inline int wdt_install_timeout(const struct device *dev,
225 : const struct wdt_timeout_cfg *cfg)
226 : {
227 : const struct wdt_driver_api *api =
228 : (const struct wdt_driver_api *) dev->api;
229 :
230 : return api->install_timeout(dev, cfg);
231 : }
232 :
233 : /**
234 : * @brief Feed specified watchdog timeout.
235 : *
236 : * @param dev Watchdog device instance.
237 : * @param channel_id Channel index.
238 : *
239 : * @retval 0 If successful.
240 : * @retval -EAGAIN If completing the feed operation would stall the caller, for
241 : * example due to an in-progress watchdog operation such as a previous
242 : * wdt_feed() call.
243 : * @retval -EINVAL If there is no installed timeout for supplied channel.
244 : * @retval -errno In case of any other failure.
245 : */
246 1 : __syscall int wdt_feed(const struct device *dev, int channel_id);
247 :
248 : static inline int z_impl_wdt_feed(const struct device *dev, int channel_id)
249 : {
250 : const struct wdt_driver_api *api =
251 : (const struct wdt_driver_api *)dev->api;
252 :
253 : return api->feed(dev, channel_id);
254 : }
255 :
256 : #ifdef __cplusplus
257 : }
258 : #endif
259 :
260 : /** @} */
261 :
262 : #include <zephyr/syscalls/watchdog.h>
263 :
264 : #endif /* ZEPHYR_INCLUDE_DRIVERS_WATCHDOG_H_ */
|
