Watchdog.h

00001 /*
00002  * Copyright (c) 2018 Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef MBED_WATCHDOG_H
00019 #define MBED_WATCHDOG_H
00020 
00021 #ifdef DEVICE_WATCHDOG
00022 
00023 #include "platform/mbed_error.h"
00024 #include "platform/mbed_assert.h"
00025 #include "platform/mbed_critical.h"
00026 #include "hal/watchdog_api.h"
00027 #include "platform/NonCopyable.h"
00028 #include <cstdio>
00029 
00030 namespace mbed {
00031 /**
00032  * \defgroup drivers_Watchdog Watchdog class
00033  * \ingroup drivers-public-api
00034  * @{
00035  */
00036 
00037 /** A hardware watchdog timer that resets the system in the case of system
00038  * failures or malfunctions. If you fail to refresh the Watchdog timer periodically,
00039  * it resets the system after a set period of time.
00040  *
00041  * There is only one instance of the Watchdog class in the system, which directly maps to the hardware.
00042  * Use Watchdog::get_instance to obtain a reference.
00043  *
00044  * Watchdog::start initializes a system timer with a time period specified in
00045  * @a timeout param. This timer counts down and triggers a system reset
00046  * when it wraps. To prevent the system reset, you must periodically kick or refresh
00047  * the timer by calling Watchdog::kick, which resets the countdown
00048  * to the initial value.
00049  *
00050  * Example:
00051  * @code
00052  * Watchdog &watchdog = Watchdog::get_instance();
00053  * watchdog.start(500);
00054  *
00055  * while (true) {
00056       // kick watchdog regularly within provided timeout
00057       watchdog.kick();
00058       // Application code
00059  * }
00060  * @endcode
00061  *
00062  * @note Synchronization level: Interrupt safe
00063  */
00064 class Watchdog : private NonCopyable<Watchdog>  {
00065 public:
00066 
00067     /** Get a reference to the single Watchdog instance in the system.
00068      *
00069      * @return A reference to the single Watchdog instance present in the system.
00070      */
00071     static Watchdog &get_instance()
00072     {
00073         // Use this implementation of singleton (Meyer's) rather than the one that allocates
00074         // the instance on the heap because it ensures destruction at program end (preventing warnings
00075         // from memory checking tools, such as valgrind).
00076         static Watchdog instance;
00077         return instance;
00078     }
00079 
00080     /** Start the Watchdog timer with the maximum timeout value available for
00081      * the target.
00082      *
00083      * @note The timeout is set to a value returned by Watchdog::get_max_timeout.
00084      *
00085      * If the Watchdog timer is already running, this function does nothing.
00086      *
00087      * @return true if the Watchdog timer was started successfully;
00088      *         false if the Watchdog timer was not started or if the Watchdog
00089      *         timer is already running.
00090      */
00091     bool start();
00092 
00093     /** Start the Watchdog timer.
00094      *
00095      * @note Asset that the timeout param is supported by the target
00096      * (0 < timeout <= Watchdog::get_max_timeout).
00097      *
00098      * @param timeout Watchdog timeout in milliseconds.
00099      *
00100      * @return true if the Watchdog timer was started successfully;
00101      *         false if Watchdog timer was not started or if the Watchdog
00102      *         timer is already running.
00103      */
00104     bool start(uint32_t timeout);
00105 
00106     /** Stop the Watchdog timer.
00107      *
00108      * Calling this function disables a running Watchdog
00109      * peripheral if the platform supports it.
00110      *
00111      * @return true if the Watchdog timer was successfully stopped;
00112      *         false if the Watchdog timer cannot be disabled on this platform
00113      *         or if the Watchdog timer has not been started.
00114      */
00115     bool stop();
00116 
00117     /** Get the Watchdog timer refresh value.
00118      *
00119      * This function returns the refresh timeout of the watchdog peripheral.
00120      *
00121      * @return Reload value for the Watchdog timer in milliseconds.
00122      */
00123     uint32_t get_timeout() const;
00124 
00125     /** Get the maximum Watchdog refresh value for this platform.
00126      *
00127      * @return Maximum reload value supported by the Watchdog timer for this
00128      *         platform in milliseconds.
00129      */
00130     uint32_t get_max_timeout() const;
00131 
00132     /** Check if the Watchdog timer is already running.
00133      *
00134      * @return true if the Watchdog timer is running and
00135      *         false otherwise.
00136      */
00137     bool is_running() const;
00138 
00139     /** Refresh the Watchdog timer.
00140      *
00141      * Call this function periodically before the Watchdog times out.
00142      * Otherwise, the system resets.
00143      *
00144      * If the Watchdog timer is not running, this function does nothing.
00145      */
00146     void kick();
00147 
00148 private:
00149     Watchdog();
00150     ~Watchdog();
00151 
00152     bool _running;
00153 };
00154 
00155 /** @}*/
00156 
00157 } // namespace mbed
00158 
00159 #endif // DEVICE_WATCHDOG
00160 #endif // MBED_WATCHDOG_H