URL
https://opencores.org/ocsvn/openrisc/openrisc/trunk
Subversion Repositories openrisc
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [devs-watchdog-synth.html] - Rev 593
Go to most recent revision | Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, Inc. --> <!-- This material may be distributed only subject to the terms --> <!-- and conditions set forth in the Open Publication License, v1.0 --> <!-- or later (the latest version is presently available at --> <!-- http://www.opencontent.org/openpub/). --> <!-- Distribution of the work or derivative of the work in any --> <!-- standard (paper) book form is prohibited unless prior --> <!-- permission is obtained from the copyright holder. --> <HTML ><HEAD ><TITLE >Synthetic Target Watchdog Device</TITLE ><meta name="MSSmartTagsPreventParsing" content="TRUE"> <META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ "><LINK REL="HOME" TITLE="eCos Reference Manual" HREF="ecos-ref.html"><LINK REL="UP" TITLE="Synthetic Target Watchdog Device" HREF="devs-watchdog-synth-ref.html"><LINK REL="PREVIOUS" TITLE="Synthetic Target Watchdog Device" HREF="devs-watchdog-synth-ref.html"></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >eCos Reference Manual</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="devs-watchdog-synth-ref.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" > </TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="DEVS-WATCHDOG-SYNTH">Synthetic Target Watchdog Device</H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN19056" ></A ><H2 >Name</H2 >Synthetic Target Watchdog Device -- Emulate watchdog hardware in the synthetic target</DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN19059" ></A ><H2 >Overview</H2 ><P >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. </P ><P >The synthetic target watchdog package emulates watchdog hardware. During system initialization watchdog device will be instantiated, and the <TT CLASS="FILENAME" >watchdog.tcl</TT > script will be loaded by the I/O auxiliary. When the eCos application starts the watchdog device, the <TT CLASS="FILENAME" >watchdog.tcl</TT > 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 <TT CLASS="FILENAME" >watchdog.tcl</TT > script detects that a second has <A HREF="devs-watchdog-synth.html#SYNTH-WATCHDOG-WALLCLOCK-ELAPSED" >elapsed</A > without a reset then it will send a <TT CLASS="LITERAL" >SIGPWR</TT > 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. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="DEVS-WATCHDOG-SYNTH-INSTALL" ></A ><H2 >Installation</H2 ><P >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 <TT CLASS="FILENAME" >host</TT > subdirectory of the synthetic target watchdog package, and building it involves the standard <B CLASS="COMMAND" >configure</B >, <B CLASS="COMMAND" >make</B > and <B CLASS="COMMAND" >make install</B > steps. The implementation of the watchdog support does not require any executables, just a Tcl script <TT CLASS="FILENAME" >watchdog.tcl</TT > and some support files, so the <B CLASS="COMMAND" >make</B > step is a no-op. </P ><P >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 <B CLASS="COMMAND" >configure</B > script at the toplevel of the eCos repository. For more information on this, see the <TT CLASS="FILENAME" >README.host</TT > 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. </P ><P >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 <B CLASS="COMMAND" >configure</B > options are much the same as for a build from the toplevel, and the <TT CLASS="FILENAME" >README.host</TT > file can be consulted for more details. It is essential that the watchdog support be configured with the same <TT CLASS="OPTION" >--prefix</TT > 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. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-WATCHDOG-TARGET-CONFIG" ></A ><H2 >Target-side Configuration</H2 ><P >The watchdog device depends on the generic watchdog support, <TT CLASS="VARNAME" >CYGPKG_IO_WATCHDOG</TT >: 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: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="SCREEN" >$ ecosconfig add CYGPKG_IO_WATCHDOG</PRE ></TD ></TR ></TABLE ><P >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 <TT CLASS="FILENAME" >watchdog.tcl</TT > script: if there are serious problems within the application, for example memory corruption, then an internal software-only implementation will not be reliable. </P ><P >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 <TT CLASS="LITERAL" >SIGPWR</TT > signal. The current implementation does not allow this resolution to be changed. </P ><P >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 <TT CLASS="LITERAL" >SIGPWR</TT > signal to the eCos application, and there is no support for action routines. </P ><P >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. </P ><P >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. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-WATCHDOG-WALLCLOCK-ELAPSED" ></A ><H2 >Wallclock versus Elapsed Time</H2 ><P >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. </P ><P >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. </P ><P >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. </P ><P >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 <TT CLASS="FUNCTION" >cyg_hal_sys_read</TT > then the system behaviour becomes undefined. In addition by default the idle thread will make blocking <TT CLASS="FUNCTION" >select</TT > 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 <TT CLASS="VARNAME" >CYGIMP_HAL_IDLE_THREAD_SPIN</TT >, causing the idle thread to spin rather than block, at the cost of wasted cpu cycles. </P ><P >The default is to use consumed cpu time, but this can be changed in the target definition file: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >synth_device watchdog { use wallclock_time … }</PRE ></TD ></TR ></TABLE ></DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-WATCHDOG-GUI" ></A ><H2 >User Interface</H2 ><P >When the synthetic target is run in graphical mode the watchdog device extends the user interface in two ways. The <SPAN CLASS="GUIMENU" >Help</SPAN > menu is extended with an entry for the watchdog-specific documentation. There is also a graphical display of the current state of the watchdog. Initially the watchdog is asleep: </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN19112"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="asleep.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >When application code starts the device the watchdog will begin to keep an eye on things (or occasionally both eyes). </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN19117"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="awake.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >If the watchdog triggers the display will change again, and optionally the user can receive an audible alert. The location of the watchdog display within the I/O auxiliary's window can be controlled via a <B CLASS="COMMAND" >watchdog_pack</B > entry in the target definition file. For example the following can be used to put the watchdog display to the right of the central text window: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >synth_device watchdog { watchdog_pack -in .main.e -side top … }</PRE ></TD ></TR ></TABLE ><P >The user interface section of the generic synthetic target HAL documentation can be consulted for more information on window packing. </P ><P >By default the watchdog support will not generate an audible alert when the watchdog triggers, to avoid annoying colleagues. Sound can be enabled in the target definition file, and two suitable files <TT CLASS="FILENAME" >sound1.au</TT > and <TT CLASS="FILENAME" >sound2.au</TT > are supplied as standard: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >synth_device watchdog { sound sound1.au … }</PRE ></TD ></TR ></TABLE ><P >An absolute path can be specified if desired: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >synth_device watchdog { sound /usr/share/emacs/site-lisp/emacspeak/sounds/default-8k/alarm.au … }</PRE ></TD ></TR ></TABLE ><P >Sound facilities are not built into the I/O auxiliary itself, instead an external program is used. The default player is <B CLASS="COMMAND" >play</B >, a front-end to the <SPAN CLASS="APPLICATION" >sox</SPAN > application shipped with some Linux distributions. If another player should be used then this can be specified in the target definition file: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >synth_device watchdog { … sound_player my_sound_player</PRE ></TD ></TR ></TABLE ><P >The specified program will be run in the background with a single argument, the sound file. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="DEVS-WATCHDOG-SYNTH-ARGS" ></A ><H2 >Command Line Arguments</H2 ><P >The watchdog support does not use any command line arguments. All configuration is handled through the target definition file. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="DEVS-WATCHDOG-SYNTH-HOOKS" ></A ><H2 >Hooks</H2 ><P >The watchdog support does not provide any hooks for use by other scripts. There is rarely any need for customizing the system's behaviour when a watchdog triggers because those should be rare events, even during application development. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="DEVS-WATCHDOG-SYNTH-TCL" ></A ><H2 >Additional Tcl Procedures</H2 ><P >The watchdog support does not provide any additional Tcl procedures or variables for use by other scripts. </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="devs-watchdog-synth-ref.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="ecos-ref.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" > </TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Synthetic Target Watchdog Device</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="devs-watchdog-synth-ref.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" > </TD ></TR ></TABLE ></DIV ></BODY ></HTML >
Go to most recent revision | Compare with Previous | Blame | View Log