--- /dev/null
+<!-- 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
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff