Diff: drivers/Watchdog.h

Revision:

0:5b88d5760320

Child:

1:9db0e321a9f4

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/drivers/Watchdog.h	Tue Dec 17 23:23:45 2019 +0000
@@ -0,0 +1,155 @@
+/*
+ * Copyright (c) 2018 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef MBED_WATCHDOG_H
+#define MBED_WATCHDOG_H
+
+#ifdef DEVICE_WATCHDOG
+
+#include "platform/mbed_error.h"
+#include "platform/mbed_assert.h"
+#include "platform/mbed_critical.h"
+#include "hal/watchdog_api.h"
+#include "platform/NonCopyable.h"
+#include <cstdio>
+
+namespace mbed {
+
+/** \addtogroup drivers */
+/** A hardware watchdog timer that resets the system in the case of system
+ * failures or malfunctions. If you fail to refresh the Watchdog timer periodically,
+ * it resets the system after a set period of time.
+ *
+ * There is only one instance of the Watchdog class in the system, which directly maps to the hardware.
+ * Use Watchdog::get_instance to obtain a reference.
+ *
+ * Watchdog::start initializes a system timer with a time period specified in
+ * @a timeout param. This timer counts down and triggers a system reset
+ * when it wraps. To prevent the system reset, you must periodically kick or refresh
+ * the timer by calling Watchdog::kick, which resets the countdown
+ * to the initial value.
+ *
+ * Example:
+ * @code
+ * Watchdog &watchdog = Watchdog::get_instance();
+ * watchdog.start(500);
+ *
+ * while (true) {
+      // kick watchdog regularly within provided timeout
+      watchdog.kick();
+      // Application code
+ * }
+ * @endcode
+ *
+ * @note Synchronization level: Interrupt safe
+ * @ingroup drivers
+ */
+class Watchdog : private NonCopyable<Watchdog>  {
+public:
+
+    /** Get a reference to the single Watchdog instance in the system.
+     *
+     * @return A reference to the single Watchdog instance present in the system.
+     */
+    static Watchdog &get_instance()
+    {
+        // Use this implementation of singleton (Meyer's) rather than the one that allocates
+        // the instance on the heap because it ensures destruction at program end (preventing warnings
+        // from memory checking tools, such as valgrind).
+        static Watchdog instance;
+        return instance;
+    }
+
+    /** Start the Watchdog timer with the maximum timeout value available for
+     * the target.
+     *
+     * @note The timeout is set to a value returned by Watchdog::get_max_timeout.
+     *
+     * If the Watchdog timer is already running, this function does nothing.
+     *
+     * @return true if the Watchdog timer was started successfully;
+     *         false if the Watchdog timer was not started or if the Watchdog
+     *         timer is already running.
+     */
+    bool start();
+
+    /** Start the Watchdog timer.
+     *
+     * @note Asset that the timeout param is supported by the target
+     * (0 < timeout <= Watchdog::get_max_timeout).
+     *
+     * @param timeout Watchdog timeout in milliseconds.
+     *
+     * @return true if the Watchdog timer was started successfully;
+     *         false if Watchdog timer was not started or if the Watchdog
+     *         timer is already running.
+     */
+    bool start(uint32_t timeout);
+
+    /** Stop the Watchdog timer.
+     *
+     * Calling this function disables a running Watchdog
+     * peripheral if the platform supports it.
+     *
+     * @return true if the Watchdog timer was successfully stopped;
+     *         false if the Watchdog timer cannot be disabled on this platform
+     *         or if the Watchdog timer has not been started.
+     */
+    bool stop();
+
+    /** Get the Watchdog timer refresh value.
+     *
+     * This function returns the refresh timeout of the watchdog peripheral.
+     *
+     * @return Reload value for the Watchdog timer in milliseconds.
+     */
+    uint32_t get_timeout() const;
+
+    /** Get the maximum Watchdog refresh value for this platform.
+     *
+     * @return Maximum reload value supported by the Watchdog timer for this
+     *         platform in milliseconds.
+     */
+    uint32_t get_max_timeout() const;
+
+    /** Check if the Watchdog timer is already running.
+     *
+     * @return true if the Watchdog timer is running and
+     *         false otherwise.
+     */
+    bool is_running() const;
+
+    /** Refresh the Watchdog timer.
+     *
+     * Call this function periodically before the Watchdog times out.
+     * Otherwise, the system resets.
+     *
+     * If the Watchdog timer is not running, this function does nothing.
+     */
+    void kick();
+
+private:
+    Watchdog();
+    ~Watchdog();
+
+    bool _running;
+};
+
+} // namespace mbed
+
+#endif // DEVICE_WATCHDOG
+#endif // MBED_WATCHDOG_H