diff options
Diffstat (limited to 'ecos/packages/devs/watchdog/synth/current/doc')
| -rw-r--r-- | ecos/packages/devs/watchdog/synth/current/doc/asleep.png | bin | 0 -> 11229 bytes | |||
| -rw-r--r-- | ecos/packages/devs/watchdog/synth/current/doc/awake.png | bin | 0 -> 11438 bytes | |||
| -rw-r--r-- | ecos/packages/devs/watchdog/synth/current/doc/devs-watchdog-synth.html | 526 | ||||
| -rw-r--r-- | ecos/packages/devs/watchdog/synth/current/doc/makefile | 54 | ||||
| -rw-r--r-- | ecos/packages/devs/watchdog/synth/current/doc/synth_watchdog.sgml | 343 |
5 files changed, 923 insertions, 0 deletions
diff --git a/ecos/packages/devs/watchdog/synth/current/doc/asleep.png b/ecos/packages/devs/watchdog/synth/current/doc/asleep.png Binary files differnew file mode 100644 index 0000000..c127379 --- /dev/null +++ b/ecos/packages/devs/watchdog/synth/current/doc/asleep.png diff --git a/ecos/packages/devs/watchdog/synth/current/doc/awake.png b/ecos/packages/devs/watchdog/synth/current/doc/awake.png Binary files differnew file mode 100644 index 0000000..c3504dc --- /dev/null +++ b/ecos/packages/devs/watchdog/synth/current/doc/awake.png diff --git a/ecos/packages/devs/watchdog/synth/current/doc/devs-watchdog-synth.html b/ecos/packages/devs/watchdog/synth/current/doc/devs-watchdog-synth.html new file mode 100644 index 0000000..572f6f4 --- /dev/null +++ b/ecos/packages/devs/watchdog/synth/current/doc/devs-watchdog-synth.html @@ -0,0 +1,526 @@ +<!-- Copyright (C) 2002 Free Software Foundation, 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+ +"></HEAD +><BODY +CLASS="REFENTRY" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><H1 +><A +NAME="DEVS-WATCHDOG-SYNTH">Synthetic Target Watchdog Device</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN4" +></A +><H2 +>Name</H2 +>Synthetic Target Watchdog Device -- Emulate watchdog hardware in the synthetic target</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7" +></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="AEN60"><P +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="asleep.gif" +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="AEN65"><P +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="awake.gif" +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 +></BODY +></HTML +> diff --git a/ecos/packages/devs/watchdog/synth/current/doc/makefile b/ecos/packages/devs/watchdog/synth/current/doc/makefile new file mode 100644 index 0000000..1f195d0 --- /dev/null +++ b/ecos/packages/devs/watchdog/synth/current/doc/makefile @@ -0,0 +1,54 @@ +#============================================================================= +# +# makefile +# +# For building the synthetic target watchdog package documentation +# +#============================================================================= +# ####ECOSGPLCOPYRIGHTBEGIN#### +# ------------------------------------------- +# This file is part of eCos, the Embedded Configurable Operating System. +# Copyright (C) 2002 Free Software Foundation, Inc. +# +# eCos is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free +# Software Foundation; either version 2 or (at your option) any later +# version. +# +# eCos is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received a copy of the GNU General Public License +# along with eCos; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# +# As a special exception, if other files instantiate templates or use +# macros or inline functions from this file, or you compile this file +# and link it with other works to produce a work based on this file, +# this file does not by itself cause the resulting work to be covered by +# the GNU General Public License. However the source code for this file +# must still be made available in accordance with section (3) of the GNU +# General Public License v2. +# +# This exception does not invalidate any other reasons why a work based +# on this file might be covered by the GNU General Public License. +# ------------------------------------------- +# ####ECOSGPLCOPYRIGHTEND#### +#============================================================================= +#####DESCRIPTIONBEGIN#### +# +# Author(s): bartv +# Date: 2002-09-09 +#####DESCRIPTIONEND#### +#============================================================================= + +TOPLEVEL := ../../../../.. +MAIN_SGML := synth_watchdog.sgml +MAIN_HTML := devs-watchdog-synth.html +MAIN_PDF := devs-watchdog-synth.pdf +OTHER_SGML := +PICTURES := + +include $(TOPLEVEL)/pkgconf/rules.doc diff --git a/ecos/packages/devs/watchdog/synth/current/doc/synth_watchdog.sgml b/ecos/packages/devs/watchdog/synth/current/doc/synth_watchdog.sgml new file mode 100644 index 0000000..6085aa4 --- /dev/null +++ b/ecos/packages/devs/watchdog/synth/current/doc/synth_watchdog.sgml @@ -0,0 +1,343 @@ +<!-- DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" --> + +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- synth_watchdog.sgml --> +<!-- --> +<!-- Synthetic target watchdog device --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 2002 Free Software Foundation, 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 obtained from the copyright holder --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- Author(s): bartv --> +<!-- Contact(s): bartv --> +<!-- Date: 2002/09/09 --> +<!-- Version: 0.01 --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<part id="devs-watchdog-synth-ref"> +<!-- reference id="devs-watchdog-synth-ref" --> + <title>Synthetic Target Watchdog Device</title> + +<refentry id="devs-watchdog-synth"> + <refmeta> + <refentrytitle>Synthetic Target Watchdog Device</refentrytitle> + </refmeta> + <refnamediv> + <refname>Synthetic Target Watchdog Device</refname> + <refpurpose>Emulate watchdog hardware in the synthetic target</refpurpose> + </refnamediv> + + <refsect1><title>Overview</title> + <para> +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. + </para> + <para> +The synthetic target watchdog package emulates watchdog hardware. +During system initialization watchdog device will be instantiated, +and the <filename>watchdog.tcl</filename> script will be loaded by the +I/O auxiliary. When the eCos application starts the watchdog device, +the <filename>watchdog.tcl</filename> 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 +<filename>watchdog.tcl</filename> script detects that a second has +<link linkend="synth-watchdog-wallclock-elapsed">elapsed</link> +without a reset then it will send a <literal>SIGPWR</literal> 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. + </para> + </refsect1> + + <refsect1 id="devs-watchdog-synth-install"><title>Installation</title> + <para> +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 <filename class="directory">host</filename> +subdirectory of the synthetic target watchdog package, and building it +involves the standard <command>configure</command>, +<command>make</command> and <command>make install</command> steps. The +implementation of the watchdog support does not require any +executables, just a Tcl script <filename>watchdog.tcl</filename> and +some support files, so the <command>make</command> step is a no-op. + </para> + <para> +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 +<command>configure</command> script at the toplevel of the eCos +repository. For more information on this, see the +<filename>README.host</filename> 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. + </para> + <para> +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 <command>configure</command> options +are much the same as for a build from the toplevel, and the +<filename>README.host</filename> file can be consulted for more +details. It is essential that the watchdog support be configured with +the same <option>--prefix</option> 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. + </para> + </refsect1> + + <refsect1 id="synth-watchdog-target-config"><title>Target-side +Configuration</title> + <para> +The watchdog device depends on the generic watchdog support, +<varname>CYGPKG_IO_WATCHDOG</varname>: 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: + </para> + <screen> +$ ecosconfig add CYGPKG_IO_WATCHDOG +</screen> + <para> +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 <filename>watchdog.tcl</filename> script: if there +are serious problems within the application, for example memory +corruption, then an internal software-only implementation will not be +reliable. + </para> + <para> +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 <literal>SIGPWR</literal> signal. The current implementation +does not allow this resolution to be changed. + </para> + <para> +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 +<literal>SIGPWR</literal> signal to the eCos application, and there is +no support for action routines. + </para> + <para> +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. + </para> + <para> +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. + </para> + </refsect1> + + <refsect1 id="synth-watchdog-wallclock-elapsed"><title>Wallclock versus Elapsed Time</title> + <para> +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. + </para> + <para> +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. + </para> + <para> +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. + </para> + <para> +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 +<function>cyg_hal_sys_read</function> then the system behaviour +becomes undefined. In addition by default the idle thread will make +blocking <function>select</function> 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 <varname>CYGIMP_HAL_IDLE_THREAD_SPIN</varname>, +causing the idle thread to spin rather than block, at the cost of +wasted cpu cycles. + </para> + <para> +The default is to use consumed cpu time, but this can be changed in +the target definition file: + </para> + <programlisting> +synth_device watchdog { + use wallclock_time + … +} +</programlisting> + </refsect1> + + <refsect1 id="synth-watchdog-gui"><title>User Interface</title> + <para> +When the synthetic target is run in graphical mode the watchdog device +extends the user interface in two ways. The <guimenu>Help</guimenu> +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: + </para> + <informalfigure PgWide=1> + <mediaobject> + <imageobject> + <imagedata fileref="asleep.png" Scalefit=1 Align="Center"> + </imageobject> + </mediaobject> + </informalfigure> + <para> +When application code starts the device the watchdog will begin to +keep an eye on things (or occasionally both eyes). + </para> + <informalfigure PgWide=1> + <mediaobject> + <imageobject> + <imagedata fileref="awake.png" Scalefit=1 Align="Center"> + </imageobject> + </mediaobject> + </informalfigure> + <para> +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 <command>watchdog_pack</command> 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: + </para> + <programlisting> +synth_device watchdog { + watchdog_pack -in .main.e -side top + … +} +</programlisting> + <para> +The user interface section of the generic synthetic target HAL +documentation can be consulted for more information on window packing. + </para> + <para> +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 +<filename>sound1.au</filename> and <filename>sound2.au</filename> are +supplied as standard: + </para> + <programlisting> +synth_device watchdog { + sound sound1.au + … +} +</programlisting> + <para> +An absolute path can be specified if desired: + </para> + <programlisting> +synth_device watchdog { + sound /usr/share/emacs/site-lisp/emacspeak/sounds/default-8k/alarm.au + … +} +</programlisting> + <para> +Sound facilities are not built into the I/O auxiliary itself, instead +an external program is used. The default player is +<command>play</command>, a front-end to the +<application>sox</application> application shipped with some Linux +distributions. If another player should be used then this can be +specified in the target definition file: + </para> + <programlisting> +synth_device watchdog { + … + sound_player my_sound_player +</programlisting> + <para> +The specified program will be run in the background with a single +argument, the sound file. + </para> + </refsect1> + + <refsect1 id="devs-watchdog-synth-args"><title>Command Line Arguments</title> + <para> +The watchdog support does not use any command line arguments. All +configuration is handled through the target definition file. + </para> + </refsect1> + + <refsect1 id="devs-watchdog-synth-hooks"><title>Hooks</title> + <para> +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. + </para> + </refsect1> + + <refsect1 id="devs-watchdog-synth-tcl"><title>Additional Tcl Procedures</title> + <para> +The watchdog support does not provide any additional Tcl procedures or +variables for use by other scripts. + </para> + </refsect1> + +</refentry> +</part> +<!-- /reference --> |
