Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
watchdog_api.h
1 /** \addtogroup hal */
2 /** @{*/
3 
4 /*
5  * Copyright (c) 2018-2019 Arm Limited and affiliates.
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 
21 #ifndef MBED_WATCHDOG_API_H
22 #define MBED_WATCHDOG_API_H
23 
24 #if DEVICE_WATCHDOG
25 
26 #include <stdbool.h>
27 #include <stdint.h>
28 
29 /**
30  * \defgroup hal_watchdog Watchdog HAL API
31  * Low-level interface to the Independent Watchdog Timer of a target.
32  *
33  * This module provides platform independent access to the system watchdog timer
34  * which is an embedded peripheral that will reset the system in the case of
35  * system failures or malfunctions.
36  *
37  * The watchdog timer initializes a system timer with a time period specified in
38  * the configuration. This timer counts down and triggers a system reset when it
39  * wraps. To prevent the system reset the timer must be continually
40  * kicked/refreshed by calling ::hal_watchdog_kick which will reset the countdown
41  * to the user specified reset value.
42  *
43  * # Defined behavior
44  * * Sleep and debug modes don't stop the watchdog timer from counting down.
45  * * The function ::hal_watchdog_init is safe to call repeatedly. The
46  * function's implementation must not do anything if ::hal_watchdog_init has
47  * already initialized the hardware watchdog timer.
48  * * Maximum supported timeout is `UINT32_MAX` milliseconds; minimum timeout
49  * is 1 millisecond.
50  * * The uncalibrated watchdog should trigger at or after the timeout value
51  * multiplied by the frequency accuracy ratio of its oscillator (typical_frequency / max_frequency).
52  * * The calibrated watchdog should trigger at or after the timeout value.
53  * * The watchdog should trigger before twice the timeout value.
54  *
55  * # Undefined behavior
56  * * Calling any function other than ::hal_watchdog_init or
57  * ::hal_watchdog_get_platform_features before you have initialized the watchdog.
58  *
59  * # Notes
60  * * A software reset may not stop the watchdog timer; the behavior is platform specific.
61  *
62  * @{
63  */
64 
65 /**
66  * \defgroup hal_watchdog_tests Watchdog HAL tests
67  * Greentea tests for the Watchdog HAL.
68  *
69  * To run the Watchdog HAL tests use the command:
70  *
71  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-watchdog*
72  *
73  */
74 
75 /** Watchdog configuration.
76  */
77 typedef struct {
78  /**
79  * Refresh value for the watchdog in milliseconds. The maximum value of this
80  * setting is platform dependent, to find the maximum value for the current
81  * platform call hal_watchdog_get_features() and check the timeout value
82  * member. The minimum valid value for this setting is 1. Attempting to
83  * initialize the watchdog with a timeout of 0 ms returns
84  * WATCHDOG_STATUS_INVALID_ARGUMENT.
85  */
86  uint32_t timeout_ms;
87 } watchdog_config_t;
88 
89 /** Watchdog features.
90  */
91 typedef struct {
92  /**
93  * Maximum timeout value for the watchdog in milliseconds.
94  */
95  uint32_t max_timeout;
96  /**
97  * You can update the watchdog configuration after the watchdog has started.
98  */
99  bool update_config;
100  /**
101  * You can stop the watchdog after it starts without a reset.
102  */
103  bool disable_watchdog;
104  /**
105  * Typical frequency of not calibrated watchdog clock in Hz.
106  */
107  uint32_t clock_typical_frequency;
108  /**
109  * Maximum frequency of not calibrated watchdog clock in Hz.
110  */
111  uint32_t clock_max_frequency;
112 } watchdog_features_t;
113 
114 
115 /** Status of a watchdog operation.
116 */
117 typedef enum {
118  WATCHDOG_STATUS_OK, /**< Operation successful. **/
119  WATCHDOG_STATUS_NOT_SUPPORTED, /**< Operation not supported. **/
120  WATCHDOG_STATUS_INVALID_ARGUMENT /**< Invalid argument. **/
121 } watchdog_status_t;
122 
123 #ifdef __cplusplus
124 extern "C" {
125 #endif
126 
127 /** Initialize and start a watchdog timer with the given configuration.
128  *
129  * If the watchdog timer is configured and starts successfully, this
130  * function returns ::WATCHDOG_STATUS_OK.
131  *
132  * If the timeout specified is outside the range supported by the platform,
133  * it returns ::WATCHDOG_STATUS_INVALID_ARGUMENT.
134  *
135  * @param[in] config Configuration settings for the watchdog timer
136  *
137  * @return ::WATCHDOG_STATUS_OK if the watchdog is configured correctly and
138  * has started. Otherwise a status indicating the fault.
139  */
140 watchdog_status_t hal_watchdog_init(const watchdog_config_t *config);
141 
142 /** Refreshes the watchdog timer.
143  *
144  * Call this function periodically before the watchdog times out.
145  * Otherwise, the system resets.
146  *
147  * If a watchdog is not running, this function does nothing.
148  */
149 void hal_watchdog_kick(void);
150 
151 /** Stops the watchdog timer.
152  *
153  * Calling this function disables any running watchdog
154  * timers if the current platform supports them.
155  *
156  * @return Returns ::WATCHDOG_STATUS_OK if the watchdog timer was succesfully
157  * stopped, or if the timer was never started. Returns
158  * ::WATCHDOG_STATUS_NOT_SUPPORTED if the watchdog cannot be disabled on
159  * the current platform.
160  */
161 watchdog_status_t hal_watchdog_stop(void);
162 
163 /** Get the watchdog timer refresh value.
164  *
165  * This function returns the configured refresh timeout of the watchdog timer.
166  *
167  * @return Reload value for the watchdog timer in milliseconds.
168  */
169 uint32_t hal_watchdog_get_reload_value(void);
170 
171 /** Get information on the current platforms supported watchdog functionality.
172  *
173  * @return watchdog_feature_t indicating supported watchdog features on the
174  * current platform
175  */
176 watchdog_features_t hal_watchdog_get_platform_features(void);
177 
178 /**@}*/
179 
180 #ifdef __cplusplus
181 }
182 #endif
183 
184 #endif // DEVICE_WATCHDOG
185 
186 #endif // MBED_WATCHDOG_API_H
187 
188 /** @}*/
watchdog_features_t::max_timeout
uint32_t max_timeout
Maximum timeout value for the watchdog in milliseconds.
Definition: watchdog_api.h:95
watchdog_status_t
watchdog_status_t
Status of a watchdog operation.
Definition: watchdog_api.h:117
WATCHDOG_STATUS_OK
Operation successful.
Definition: watchdog_api.h:118
watchdog_features_t::disable_watchdog
bool disable_watchdog
You can stop the watchdog after it starts without a reset.
Definition: watchdog_api.h:103
hal_watchdog_get_reload_value
uint32_t hal_watchdog_get_reload_value(void)
Get the watchdog timer refresh value.
hal_watchdog_init
watchdog_status_t hal_watchdog_init(const watchdog_config_t *config)
Initialize and start a watchdog timer with the given configuration.
WATCHDOG_STATUS_INVALID_ARGUMENT
Invalid argument.
Definition: watchdog_api.h:120
watchdog_features_t
Watchdog features.
Definition: watchdog_api.h:91
hal_watchdog_get_platform_features
watchdog_features_t hal_watchdog_get_platform_features(void)
Get information on the current platforms supported watchdog functionality.
hal_watchdog_stop
watchdog_status_t hal_watchdog_stop(void)
Stops the watchdog timer.
watchdog_config_t::timeout_ms
uint32_t timeout_ms
Refresh value for the watchdog in milliseconds.
Definition: watchdog_api.h:86
hal_watchdog_kick
void hal_watchdog_kick(void)
Refreshes the watchdog timer.
watchdog_features_t::clock_max_frequency
uint32_t clock_max_frequency
Maximum frequency of not calibrated watchdog clock in Hz.
Definition: watchdog_api.h:111
watchdog_features_t::update_config
bool update_config
You can update the watchdog configuration after the watchdog has started.
Definition: watchdog_api.h:99
watchdog_features_t::clock_typical_frequency
uint32_t clock_typical_frequency
Typical frequency of not calibrated watchdog clock in Hz.
Definition: watchdog_api.h:107
WATCHDOG_STATUS_NOT_SUPPORTED
Operation not supported.
Definition: watchdog_api.h:119
watchdog_config_t
Watchdog configuration.
Definition: watchdog_api.h:77
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.