Seeed Grove ++  v0.0.1-2019
Linux C++ Library For Seeed Grove Devices
SG::BeagleBone::Watchdog Class Reference

BeagleBone hardware watchdog. More...

#include <sg_BeagleBone_Watchdog.hpp>

Collaboration diagram for SG::BeagleBone::Watchdog:

Public Member Functions

virtual ~Watchdog (void)
 Destructor. More...
 
 Watchdog (const size_t timeout_in_seconds=60)
 Constructor. More...
 
virtual Watchdogkick (void)
 Kick the watchdog to prevent it from triggering a reboot. More...
 
virtual Watchdogmagic_close (void)
 Attempt to stop kicking the watchdog. More...
 
virtual size_t get_timeout (void)
 Get the watchdog timeout (in seconds). More...
 
virtual Watchdogset_timeout (const size_t timeout_in_seconds=60)
 Set the watchdog timeout (in seconds). More...
 
virtual size_t get_seconds_remaining_before_reboot (void)
 Get the amount of time left before the watchdog triggers a reboot. More...
 
virtual watchdog_info get_info (void)
 Get some simple information from the OMAP watchdog driver. More...
 
virtual int get_status (void)
 Get some status information on the watchdog. More...
 
virtual int get_boot_status (void)
 Get some information on the cause of the last reboot. More...
 
virtual Watchdogstart_simple_thread (const size_t sleep_time_in_seconds=45)
 Calling this will start run_simple_loop() on a secondary thread. More...
 
virtual Watchdogstop_simple_thread (void)
 Stop the secondary watchdog thread started by start_simple_thread(). More...
 
virtual Watchdogrun_simple_loop (const size_t sleep_time_in_seconds)
 Never-ending loop that will periodically call kick() to update the watchdog. More...
 
bool is_valid (void) const
 Determine if the watchdog handle seems to be valid. More...
 

Protected Attributes

std::string path
 Path to the watchdog. Typically will be /dev/watchdog. More...
 
SharedFileDescriptor shared_fd
 File descriptor for the watchdog device. More...
 
std::thread simple_watchdog_thread
 Secondary watchdog thread. Only used when start_simple_thread() has been called. More...
 
std::atomic< bool > watchdog_can_continue
 Secondary watchdog thread. Only used when start_simple_thread() has been called. More...
 

Detailed Description

BeagleBone hardware watchdog.

Once the watchdog on BeagleBone Green (BBG) or BeagleBone Black (BBB) has been activated, it cannot be stopped. The default watchdog timeout is 60 seconds, but it can be changed to a different value with set_timeout().

Creating one of these objects does not automatically activate the watchdog. A call must be made to either kick() or start_simple_thread() to activate it.

See also
https://www.kernel.org/doc/Documentation/watchdog/watchdog-api.txt

Constructor & Destructor Documentation

SG::BeagleBone::Watchdog::~Watchdog ( void  )
virtual

Destructor.

If start_simple_thread() has been called, the destructor will ensure that the secondary thread is stopped when the object goes out of scope.

Note
If the watchdog has been activated, the destruction of the Watchdog object will result in the device rebooting after the timeout period has been reached. The only way to prevent a reboot is to instantiate a new Watchdog object and call start_simple_thread() or resume calling kick().

References shared_fd, and stop_simple_thread().

Here is the call graph for this function:

SG::BeagleBone::Watchdog::Watchdog ( const size_t  timeout_in_seconds = 60)

Constructor.

This does not activate the watchdog. The only way to activate the watchdog is to call start_simple_thread(), or periodically call kick(). Once activated, if the watchdog isn't updated regularly, the BeagleBone will reboot.

There are two ways to use the Watchdog class:

  1. The method kick() can be regularly called.
  2. A secondary thread can be started by start_simple_thread() which will then automatically call kick() until the watchdog object goes out of scope.

First method:

while (true)
{
do_some_quick_work(); // must return in less than 60 seconds
watchdog.kick(); // otherwise the device will reboot
}

Second method:

watchdog.start_simple_thread(); // watchdog is now kicked from a new thread
while (true)
{
do_some_long_work(); // is OK even if it runs for hours or days
}

References is_valid(), set_timeout(), and shared_fd.

Here is the call graph for this function:

Member Function Documentation

int SG::BeagleBone::Watchdog::get_boot_status ( void  )
virtual

Get some information on the cause of the last reboot.

See also
/usr/include/linux/watchdog.h
WDIOC_GETBOOTSTATUS

References is_valid(), and shared_fd.

Referenced by bb_watchdog().

Here is the call graph for this function:

Here is the caller graph for this function:

watchdog_info SG::BeagleBone::Watchdog::get_info ( void  )
virtual

Get some simple information from the OMAP watchdog driver.

The options are a combination of the WDIOF_... flags defined in watchdog.h. For example, 0x8180:

  • 0x8000: WDIOF_KEEPALIVEPING 0x8000 // Keep alive ping reply
  • 0x0100: WDIOF_MAGICCLOSE 0x0100 // Supports magic close char
  • 0x0080: WDIOF_SETTIMEOUT 0x0080 // Set timeout (in seconds)
See also
/usr/include/linux/watchdog.h
WDIOC_GETSUPPORT

References shared_fd.

Referenced by bb_watchdog().

Here is the caller graph for this function:

size_t SG::BeagleBone::Watchdog::get_seconds_remaining_before_reboot ( void  )
virtual

Get the amount of time left before the watchdog triggers a reboot.

See also
WDIOC_GETTIMELEFT

References shared_fd.

Referenced by bb_watchdog().

Here is the caller graph for this function:

int SG::BeagleBone::Watchdog::get_status ( void  )
virtual

Get some status information on the watchdog.

See also
/usr/include/linux/watchdog.h
WDIOC_GETSTATUS

References is_valid(), and shared_fd.

Referenced by bb_watchdog().

Here is the call graph for this function:

Here is the caller graph for this function:

size_t SG::BeagleBone::Watchdog::get_timeout ( void  )
virtual

Get the watchdog timeout (in seconds).

By default, the watchdog timeout is set to 60 seconds. This determines the maximum length of time that can elapse between calls to kick() without triggering a reboot.

See also
set_timeout()
WDIOC_GETTIMEOUT

References is_valid(), and shared_fd.

Referenced by bb_watchdog(), and set_timeout().

Here is the call graph for this function:

Here is the caller graph for this function:

bool SG::BeagleBone::Watchdog::is_valid ( void  ) const
inline

Determine if the watchdog handle seems to be valid.

References shared_fd.

Referenced by get_boot_status(), get_status(), get_timeout(), kick(), magic_close(), set_timeout(), and Watchdog().

Here is the caller graph for this function:

SG::BeagleBone::Watchdog & SG::BeagleBone::Watchdog::kick ( void  )
virtual

Kick the watchdog to prevent it from triggering a reboot.

This needs to be called relatively often to prevent the watchdog from triggering a reboot. For example, if the timeout is set to 60 seconds (the default timeout value) then kick() must be called at intervals of 59 seconds or less to prevent a reboot.

See also
WDIOC_KEEPALIVE

If you periodically call kick() from within your code, then don't start the watchdog's simple thread. Otherwise, the watchdog object's simple thread regularly calling kick() will completely defeat manually calling kick().

References is_valid(), and shared_fd.

Referenced by bb_watchdog(), and run_simple_loop().

Here is the call graph for this function:

Here is the caller graph for this function:

SG::BeagleBone::Watchdog & SG::BeagleBone::Watchdog::magic_close ( void  )
virtual

Attempt to stop kicking the watchdog.

Normally, once the watchdog has been activated, the device will reboot if too much time elapses between calls to kick(). But if the watchdog driver was built without CONFIG_WATCHDOG_NOWAYOUT, then there may be a way to close the watchdog without triggering a reboot.

If the kernel was built with CONFIG_WATCHDOG_NOWAYOUT, you'll find a message similar to this one in dmesg or /var/log/syslog: watchdog watchdog0: nowayout prevents watchdog being stopped!

References is_valid(), and shared_fd.

Here is the call graph for this function:

SG::BeagleBone::Watchdog & SG::BeagleBone::Watchdog::run_simple_loop ( const size_t  sleep_time_in_seconds)
virtual

Never-ending loop that will periodically call kick() to update the watchdog.

This is typically started by calling start_simple_thread(), and wont return until stop_simple_thread() is called.

Parameters
[in]sleep_time_in_secondsDetermines how long to sleep between calls to kick().

This method is usually called on a secondary thread by start_simple_thread(), though it could also be called directly from user code if required.

References kick(), and watchdog_can_continue.

Referenced by start_simple_thread().

Here is the call graph for this function:

Here is the caller graph for this function:

SG::BeagleBone::Watchdog & SG::BeagleBone::Watchdog::set_timeout ( const size_t  timeout_in_seconds = 60)
virtual

Set the watchdog timeout (in seconds).

By default, the watchdog timeout is set to 60 seconds. This determines the length of time that can elapse between calls to kick() without triggering a reboot.

See also
get_timeout()
WDIOC_SETTIMEOUT
Exceptions
std::invalid_argumentif the watchdog timeout cannot be set.

References get_timeout(), is_valid(), shared_fd, and SG::BeagleBone::Detect::to_string().

Referenced by bb_watchdog(), and Watchdog().

Here is the call graph for this function:

Here is the caller graph for this function:

SG::BeagleBone::Watchdog & SG::BeagleBone::Watchdog::start_simple_thread ( const size_t  sleep_time_in_seconds = 45)
virtual

Calling this will start run_simple_loop() on a secondary thread.

Instead of periodically calling kick(), you can have a loop running on a secondary thread to regularly update the watchdog. Because this runs on a secondary thread, it wont detect some kinds of problems such as deadlocks that would be detected by directly calling kick(). But this greatly simplifies the use of watchdog in some applications, and will trigger a reboot if the application that instantiated the Watchdog object aborts, or if the device completely stops responding.

It is safe to call this multiple times.

Parameters
[in]sleep_time_in_secondsDetermines how long the secondary thread will sleep between calls to kick().

If you call start_simple_thread(), then there is no need to manually call kick() within your code.

References run_simple_loop(), simple_watchdog_thread, stop_simple_thread(), and watchdog_can_continue.

Here is the call graph for this function:

SG::BeagleBone::Watchdog & SG::BeagleBone::Watchdog::stop_simple_thread ( void  )
virtual

Stop the secondary watchdog thread started by start_simple_thread().

If the watchdog is active, this will eventually cause a reboot once the timeout period is reached. (Default is 60 seconds.)

It is safe to call this multiple times.

Note
stop_simple_thread() only returns once the secondary watchdog thread has finished running.

References simple_watchdog_thread, and watchdog_can_continue.

Referenced by start_simple_thread(), and ~Watchdog().

Here is the caller graph for this function:

Member Data Documentation

std::string SG::BeagleBone::Watchdog::path
protected

Path to the watchdog. Typically will be /dev/watchdog.

SharedFileDescriptor SG::BeagleBone::Watchdog::shared_fd
protected
std::thread SG::BeagleBone::Watchdog::simple_watchdog_thread
protected

Secondary watchdog thread. Only used when start_simple_thread() has been called.

Referenced by start_simple_thread(), and stop_simple_thread().

std::atomic<bool> SG::BeagleBone::Watchdog::watchdog_can_continue
protected

Secondary watchdog thread. Only used when start_simple_thread() has been called.

Referenced by run_simple_loop(), start_simple_thread(), and stop_simple_thread().


The documentation for this class was generated from the following files: