ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Watchdog: Clean up the doxygen comments

pull/10954/head
Filip Jagodzinski 2019-07-03 15:28:37 +02:00
parent 608e4c245f
commit 6f8266c02f
1 changed files with 56 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
drivers/Watchdog.h
View File

@ -30,14 +30,23 @@
namespace mbed { namespace mbed {
/** \addtogroup drivers */ /** \addtogroup drivers */
/** Hardware system timer that will reset the system in the case of system failures or /** A hardware watchdog timer that will reset the system in the case of system
* malfunctions. There is only one instance in the system. * failures or malfunctions. If you fail to refresh the Watchdog periodically,
* it will reset the system after a set period of time.
*
* There is only one instance in the system. 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, the timer must be continually
* kicked/refreshed by calling Watchdog::kick, which will reset the countdown
* to the user specified reset value.
* *
* Example: * Example:
* @code * @code
*
* Watchdog &watchdog = Watchdog::get_instance(); * Watchdog &watchdog = Watchdog::get_instance();
* watchdog.start(); * watchdog.start(500);
* *
* while (true) { * while (true) {
// kick watchdog regularly within provided timeout // kick watchdog regularly within provided timeout
@ -52,8 +61,12 @@ namespace mbed {
class Watchdog : private NonCopyable<Watchdog> { class Watchdog : private NonCopyable<Watchdog> {
public: public:
/** As Watchdog might not stop ever, there is just one instance - we use single instance. /** Get a reference to the single Watchdog instance in the system.
* This ensures we keep Watchdog alive. To operate watchdog, use start/stop methods. *
* There is only one watchdog peripheral and only one Watchdog instance
* to control it.
*
* @return A reference to the single Watchdog instance present in the system.
*/ */
static Watchdog &get_instance() static Watchdog &get_instance()
{ {
@ -64,61 +77,71 @@ public:
return instance; return instance;
} }
/** Start the watchdog timer with the maximum timeout available on a target /** Start the Watchdog timer with the maximum timeout value available for
* the target.
* *
* Timeout is defined as get_max_timeout() * @note The timeout is set to a value returned by Watchdog::get_max_timeout.
* *
* @return status true if the watchdog timer was started * If the Watchdog is already running, this function does nothing.
* successfully. assert if one of the input parameters is out of range for the current platform. *
* false if watchdog timer was not started * @return true, if the Watchdog timer was started successfully,
* false, if Watchdog timer was not started or if the Watchdog
* is already running.
*/ */
bool start(); bool start();
/** Start the watchdog timer /** Start the Watchdog timer.
* *
* @param timeout Watchdog timeout * @note Asset that the timeout param is supported by the target
* (0 < timeout <= Watchdog::get_max_timeout).
* *
* @return status true if the watchdog timer was started * @param timeout Watchdog timeout in milliseconds.
* successfully. assert if one of the input parameters is out of range for the current platform. *
* false if watchdog timer was not started * @return true, if the Watchdog timer was started successfully,
* false, if Watchdog timer was not started or if the Watchdog
* is already running.
*/ */
bool start(uint32_t timeout); bool start(uint32_t timeout);
/** Stops the watchdog timer /** Stop the Watchdog timer.
* *
* Calling this function will attempt to disable any currently running * Calling this function will attempt to disable a running Watchdog
* watchdog timers if supported by the current platform. * peripheral if supported by the platform.
* *
* @return Returns true if the watchdog timer was successfully * @return true, if the Watchdog timer was successfully stopped,
* stopped, Returns false if the watchdog cannot be disabled * false, if the Watchdog cannot be disabled on this platform
* on the current platform or if the timer was never started. * or if the Watchdog has not been started.
*/ */
bool stop(); bool stop();
/** Get the watchdog timer refresh value /** Get the Watchdog timer refresh value.
* *
* This function returns the refresh timeout of the watchdog timer. * This function returns the refresh timeout of the watchdog peripheral.
* *
* @return Reload value for the watchdog timer in milliseconds. * @return Reload value for the Watchdog timer in milliseconds.
*/ */
uint32_t get_timeout() const; uint32_t get_timeout() const;
/** Get the maximum refresh value for the current platform in milliseconds /** Get the maximum Watchdog refresh value for this platform.
* *
* @return Maximum refresh value supported by the watchdog for the current * @return Maximum reload value supported by the Watchdog timer for this
* platform in milliseconds * platform in milliseconds.
*/ */
uint32_t get_max_timeout() const; uint32_t get_max_timeout() const;
/** Check if watchdog is already running /** Check if the Watchdog is already running.
* *
* @return true if watchdog is running, false otherwise * @return true, if the Watchdog is running,
* false, otherwise.
*/ */
bool is_running() const; bool is_running() const;
/** Kick watchdog /** Refresh the Watchdog timer.
* *
* This method is useful to control kicking by application in ticker callback periodically * Call this function periodically before the Watchdog times out.
* Otherwise, the system is reset.
*
* If the Watchdog is not running, this function does nothing.
*/ */
void kick(); void kick();