Synthetic Target Watchdog Device

eCos Reference Manual
Prev

Overview

Some target hardware comes equipped with a watchdog timer. Application -code can start this timer and after a certain period of time, -typically a second, the watchdog will trigger. Usually this causes the -hardware to reboot. The application can prevent this by regularly -resetting the watchdog. An automatic reboot can be very useful when -deploying hardware in the field: a hardware glitch could cause the -unit to hang; or the software could receive an unexpected sequence of -inputs, never seen in the laboratory, causing the system to lock up. -Often the hardware is still functional, and a reboot sorts out the -problem with only a brief interruption in service. -

The synthetic target watchdog package emulates watchdog hardware. -During system initialization watchdog device will be instantiated, -and the watchdog.tcl script will be loaded by the -I/O auxiliary. When the eCos application starts the watchdog device, -the watchdog.tcl script will start checking the -state of the eCos application at one second intervals. A watchdog -reset call simply involves a message to the I/O auxiliary. If the -watchdog.tcl script detects that a second has -elapsed -without a reset then it will send a SIGPWR signal -to the eCos application, causing the latter to terminate. If gdb is -being used to run the application, the user will get a chance to -investigate what is happening. This behaviour is different from real -hardware in that there is no automatic reboot, but the synthetic -target is used only for development purposes, not deployment in the -field: if a reboot is desired then this can be achieved very easily -by using gdb commands to run another instance of the application. -

Installation

Before a synthetic target eCos application can use a watchdog device -it is necessary to build and install host-side support. The relevant -code resides in the host -subdirectory of the synthetic target watchdog package, and building it -involves the standard configure, -make and make install steps. The -implementation of the watchdog support does not require any -executables, just a Tcl script watchdog.tcl and -some support files, so the make step is a no-op. -

There are two main ways of building the host-side software. It is -possible to build both the generic host-side software and all -package-specific host-side software, including the watchdog support, -in a single build tree. This involves using the -configure script at the toplevel of the eCos -repository. For more information on this, see the -README.host file at the top of the repository. -Note that if you have an existing build tree which does not include -the synthetic target watchdog support then it will be necessary to -rerun the toplevel configure script: the search for appropriate -packages happens at configure time. -

The alternative is to build just the host-side for this package. -This requires a separate build directory, building directly in the -source tree is disallowed. The configure options -are much the same as for a build from the toplevel, and the -README.host file can be consulted for more -details. It is essential that the watchdog support be configured with -the same --prefix option as other eCos host-side -software, especially the I/O auxiliary provided by the architectural -synthetic target HAL package, otherwise the I/O auxiliary will be -unable to locate the watchdog support. -

Target-side -Configuration

The watchdog device depends on the generic watchdog support, -CYGPKG_IO_WATCHDOG: if the generic support is -absent then the watchdog device will be inactive. Some templates -include this generic package by default, but not all. If the -configuration does not include the generic package then it can be -added using the eCos configuration tools, for example: -

$ ecosconfig add CYGPKG_IO_WATCHDOG

By default the configuration will use the hardware-specific support, -i.e. this package. However the generic watchdog package contains an -alternative implementation using the kernel alarm facility, and that -implementation can be selected if desired. However usually it will be -better to rely on an external watchdog facility as provided by the I/O -auxiliary and the watchdog.tcl script: if there -are serious problems within the application, for example memory -corruption, then an internal software-only implementation will not be -reliable. -

The watchdog resolution is currently fixed to one second: if the -device does not receive a reset signal at least once a second then -the watchdog will trigger and the eCos application will be terminated -with a SIGPWR signal. The current implementation -does not allow this resolution to be changed. -

On some targets the watchdog device does not perform a hard reset. -Instead the device works more or less via the interrupt subsystem, -allowing application code to install action routines that will be -called when the watchdog triggers. The synthetic target watchdog -support effectively does perform a hard reset, by sending a -SIGPWR signal to the eCos application, and there is -no support for action routines. -

The synthetic target watchdog package provides some configuration -options for manipulating the compiler flags used for building the -target-side code. That code is fairly simple, so for nearly all -applications the default flags will suffice. -

It should be noted that the watchdog device is subject to selective -linking. Unless some code explicitly references the device, for -example by calling the start and reset functions, the watchdog support -will not appear in the final executable. This is desirable because a -watchdog device has no effect until started. -

Wallclock versus Elapsed Time

On real hardware the watchdog device uses wallclock time: if the -device does not receive a reset signal within a set period of time -then the watchdog will trigger. When developing for the synthetic -target this is not always appropriate. There may be other processes -running, using up some or most of the cpu time. For example, the -application may be written such that it will issue a reset after some -calculations which are known to complete within half a second, well -within the one-second resolution of the watchdog device. However if -other Linux processes are running then the synthetic target -application may get timesliced, and half a second of computation may -take several seconds of wallclock time. -

Another problem with using wallclock time is that it interferes with -debugging: if the application hits a breakpoint then it is unlikely -that the user will manage to restart it in less than a second, and the -watchdog will not get reset in time. -

To avoid these problems the synthetic target watchdog normally uses -consumed cpu time rather than wallclock time. If the application is -timesliced or if it is halted inside gdb then it does not consume any -cpu time. The application actually has to spend a whole second's worth -of cpu cycles without issuing a reset before the watchdog triggers. -

However using consumed cpu time is not a perfect solution either. If -the application makes blocking system calls then it is not using cpu -time. Interaction with the I/O auxiliary involves system calls, but -these should take only a short amount of time so their effects can be -ignored. If the application makes direct system calls such as -cyg_hal_sys_read then the system behaviour -becomes undefined. In addition by default the idle thread will make -blocking select system calls, effectively waiting -until an interrupt occurs. If an application spends much of its time -idle then the watchdog device may take much longer to trigger than -expected. It may be desirable to enable the synthetic target HAL -configuration option CYGIMP_HAL_IDLE_THREAD_SPIN, -causing the idle thread to spin rather than block, at the cost of -wasted cpu cycles. -

The default is to use consumed cpu time, but this can be changed in -the target definition file: -

synth_device watchdog {
-    use wallclock_time
-    …
-}

Synthetic Target Watchdog Device

Name

Overview

Installation

Target-side -Configuration

Wallclock versus Elapsed Time

User Interface

Command Line Arguments

Hooks

Additional Tcl Procedures