watchdog_api.h

00001 /** \addtogroup hal */
00002 /** @{*/
00003 
00004 /*
00005  * Copyright (c) 2018-2019 Arm Limited and affiliates.
00006  * SPDX-License-Identifier: Apache-2.0
00007  *
00008  * Licensed under the Apache License, Version 2.0 (the "License");
00009  * you may not use this file except in compliance with the License.
00010  * You may obtain a copy of the License at
00011  *
00012  *     http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  * Unless required by applicable law or agreed to in writing, software
00015  * distributed under the License is distributed on an "AS IS" BASIS,
00016  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017  * See the License for the specific language governing permissions and
00018  * limitations under the License.
00019  */
00020 
00021 #ifndef MBED_WATCHDOG_API_H
00022 #define MBED_WATCHDOG_API_H
00023 
00024 #if DEVICE_WATCHDOG
00025 
00026 #include <stdbool.h>
00027 #include <stdint.h>
00028 
00029 /**
00030  * \defgroup hal_watchdog Watchdog HAL API
00031  * Low-level interface to the Independent Watchdog Timer of a target.
00032  *
00033  * This module provides platform independent access to the system watchdog timer
00034  * which is an embedded peripheral that will reset the system in the case of
00035  * system failures or malfunctions.
00036  *
00037  * The watchdog timer initializes a system timer with a time period specified in
00038  * the configuration. This timer counts down and triggers a system reset when it
00039  * wraps. To prevent the system reset the timer must be continually
00040  * kicked/refreshed by calling ::hal_watchdog_kick which will reset the countdown
00041  * to the user specified reset value.
00042  *
00043  * # Defined behavior
00044  * * Sleep and debug modes don't stop the watchdog timer from counting down.
00045  * * The function ::hal_watchdog_init is safe to call repeatedly. The
00046  * function's implementation must not do anything if ::hal_watchdog_init has
00047  * already initialized the hardware watchdog timer.
00048  * * Maximum supported timeout is `UINT32_MAX` milliseconds; minimum timeout
00049  * is 1 millisecond.
00050  * * The uncalibrated watchdog should trigger at or after the timeout value
00051  * multiplied by the frequency accuracy ratio of its oscillator (typical_frequency / max_frequency).
00052  * * The calibrated watchdog should trigger at or after the timeout value.
00053  * * The watchdog should trigger before twice the timeout value.
00054  *
00055  * # Undefined behavior
00056  * * Calling any function other than ::hal_watchdog_init or
00057  * ::hal_watchdog_get_platform_features before you have initialized the watchdog.
00058  *
00059  * # Notes
00060  * * A software reset may not stop the watchdog timer; the behavior is platform specific.
00061  *
00062  * @{
00063  */
00064 
00065 /**
00066  * \defgroup hal_watchdog_tests Watchdog HAL tests
00067  * Greentea tests for the Watchdog HAL.
00068  *
00069  * To run the Watchdog HAL tests use the command:
00070  *
00071  *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-watchdog*
00072  *
00073  */
00074 
00075 /** Watchdog configuration.
00076  */
00077 typedef struct {
00078     /**
00079     * Refresh value for the watchdog in milliseconds. The maximum value of this
00080     * setting is platform dependent, to find the maximum value for the current
00081     * platform call hal_watchdog_get_features() and check the timeout value
00082     * member. The minimum valid value for this setting is 1. Attempting to
00083     * initialize the watchdog with a timeout of 0 ms returns
00084     * WATCHDOG_STATUS_INVALID_ARGUMENT.
00085     */
00086     uint32_t timeout_ms;
00087 } watchdog_config_t;
00088 
00089 /** Watchdog features.
00090  */
00091 typedef struct {
00092     /**
00093      * Maximum timeout value for the watchdog in milliseconds.
00094      */
00095     uint32_t max_timeout;
00096     /**
00097      * You can update the watchdog configuration after the watchdog has started.
00098      */
00099     bool update_config;
00100     /**
00101      * You can stop the watchdog after it starts without a reset.
00102      */
00103     bool disable_watchdog;
00104     /**
00105      * Typical frequency of not calibrated watchdog clock in Hz.
00106      */
00107     uint32_t clock_typical_frequency;
00108     /**
00109      * Maximum frequency of not calibrated watchdog clock in Hz.
00110      */
00111     uint32_t clock_max_frequency;
00112 } watchdog_features_t;
00113 
00114 
00115 /** Status of a watchdog operation.
00116 */
00117 typedef enum {
00118     WATCHDOG_STATUS_OK,                 /**< Operation successful. **/
00119     WATCHDOG_STATUS_NOT_SUPPORTED,      /**< Operation not supported. **/
00120     WATCHDOG_STATUS_INVALID_ARGUMENT    /**< Invalid argument. **/
00121 } watchdog_status_t;
00122 
00123 #ifdef __cplusplus
00124 extern "C" {
00125 #endif
00126 
00127 /** Initialize and start a watchdog timer with the given configuration.
00128  *
00129  * If the watchdog timer is configured and starts successfully, this
00130  * function returns ::WATCHDOG_STATUS_OK.
00131  *
00132  * If the timeout specified is outside the range supported by the platform,
00133  * it returns ::WATCHDOG_STATUS_INVALID_ARGUMENT.
00134  *
00135  * @param[in]  config   Configuration settings for the watchdog timer
00136  *
00137  * @return ::WATCHDOG_STATUS_OK if the watchdog is configured correctly and
00138  *         has started. Otherwise a status indicating the fault.
00139  */
00140 watchdog_status_t hal_watchdog_init(const watchdog_config_t *config);
00141 
00142 /** Refreshes the watchdog timer.
00143  *
00144  * Call this function periodically before the watchdog times out.
00145  * Otherwise, the system resets.
00146  *
00147  * If a watchdog is not running, this function does nothing.
00148  */
00149 void hal_watchdog_kick(void);
00150 
00151 /** Stops the watchdog timer.
00152  *
00153  * Calling this function disables any running watchdog
00154  * timers if the current platform supports them.
00155  *
00156  * @return Returns ::WATCHDOG_STATUS_OK if the watchdog timer was succesfully
00157  *         stopped, or if the timer was never started. Returns
00158  *         ::WATCHDOG_STATUS_NOT_SUPPORTED if the watchdog cannot be disabled on
00159  *         the current platform.
00160  */
00161 watchdog_status_t hal_watchdog_stop(void);
00162 
00163 /** Get the watchdog timer refresh value.
00164  *
00165  * This function returns the configured refresh timeout of the watchdog timer.
00166  *
00167  * @return Reload value for the watchdog timer in milliseconds.
00168  */
00169 uint32_t hal_watchdog_get_reload_value(void);
00170 
00171 /** Get information on the current platforms supported watchdog functionality.
00172  *
00173  * @return watchdog_feature_t indicating supported watchdog features on the
00174  *         current platform
00175  */
00176 watchdog_features_t hal_watchdog_get_platform_features(void);
00177 
00178 /**@}*/
00179 
00180 #ifdef __cplusplus
00181 }
00182 #endif
00183 
00184 #endif // DEVICE_WATCHDOG
00185 
00186 #endif // MBED_WATCHDOG_API_H
00187 
00188 /** @}*/