1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >Synthetic Target Watchdog Device</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="Synthetic Target Watchdog Device"
23 HREF="devs-watchdog-synth-ref.html"><LINK
25 TITLE="Synthetic Target Watchdog Device"
26 HREF="devs-watchdog-synth-ref.html"></HEAD
37 SUMMARY="Header navigation table"
46 >eCos Reference Manual</TH
54 HREF="devs-watchdog-synth-ref.html"
75 NAME="DEVS-WATCHDOG-SYNTH">Synthetic Target Watchdog Device</H1
83 >Synthetic Target Watchdog Device -- Emulate watchdog hardware in the synthetic target</DIV
92 >Some target hardware comes equipped with a watchdog timer. Application
93 code can start this timer and after a certain period of time,
94 typically a second, the watchdog will trigger. Usually this causes the
95 hardware to reboot. The application can prevent this by regularly
96 resetting the watchdog. An automatic reboot can be very useful when
97 deploying hardware in the field: a hardware glitch could cause the
98 unit to hang; or the software could receive an unexpected sequence of
99 inputs, never seen in the laboratory, causing the system to lock up.
100 Often the hardware is still functional, and a reboot sorts out the
101 problem with only a brief interruption in service.
104 >The synthetic target watchdog package emulates watchdog hardware.
105 During system initialization watchdog device will be instantiated,
109 > script will be loaded by the
110 I/O auxiliary. When the eCos application starts the watchdog device,
114 > script will start checking the
115 state of the eCos application at one second intervals. A watchdog
116 reset call simply involves a message to the I/O auxiliary. If the
120 > script detects that a second has
122 HREF="devs-watchdog-synth.html#SYNTH-WATCHDOG-WALLCLOCK-ELAPSED"
125 without a reset then it will send a <TT
129 to the eCos application, causing the latter to terminate. If gdb is
130 being used to run the application, the user will get a chance to
131 investigate what is happening. This behaviour is different from real
132 hardware in that there is no automatic reboot, but the synthetic
133 target is used only for development purposes, not deployment in the
134 field: if a reboot is desired then this can be achieved very easily
135 by using gdb commands to run another instance of the application.
141 NAME="DEVS-WATCHDOG-SYNTH-INSTALL"
146 >Before a synthetic target eCos application can use a watchdog device
147 it is necessary to build and install host-side support. The relevant
148 code resides in the <TT
152 subdirectory of the synthetic target watchdog package, and building it
153 involves the standard <B
164 implementation of the watchdog support does not require any
165 executables, just a Tcl script <TT
169 some support files, so the <B
175 >There are two main ways of building the host-side software. It is
176 possible to build both the generic host-side software and all
177 package-specific host-side software, including the watchdog support,
178 in a single build tree. This involves using the
182 > script at the toplevel of the eCos
183 repository. For more information on this, see the
187 > file at the top of the repository.
188 Note that if you have an existing build tree which does not include
189 the synthetic target watchdog support then it will be necessary to
190 rerun the toplevel configure script: the search for appropriate
191 packages happens at configure time.
194 >The alternative is to build just the host-side for this package.
195 This requires a separate build directory, building directly in the
196 source tree is disallowed. The <B
200 are much the same as for a build from the toplevel, and the
204 > file can be consulted for more
205 details. It is essential that the watchdog support be configured with
209 > option as other eCos host-side
210 software, especially the I/O auxiliary provided by the architectural
211 synthetic target HAL package, otherwise the I/O auxiliary will be
212 unable to locate the watchdog support.
218 NAME="SYNTH-WATCHDOG-TARGET-CONFIG"
224 >The watchdog device depends on the generic watchdog support,
227 >CYGPKG_IO_WATCHDOG</TT
228 >: if the generic support is
229 absent then the watchdog device will be inactive. Some templates
230 include this generic package by default, but not all. If the
231 configuration does not include the generic package then it can be
232 added using the eCos configuration tools, for example:
242 >$ ecosconfig add CYGPKG_IO_WATCHDOG</PRE
247 >By default the configuration will use the hardware-specific support,
248 i.e. this package. However the generic watchdog package contains an
249 alternative implementation using the kernel alarm facility, and that
250 implementation can be selected if desired. However usually it will be
251 better to rely on an external watchdog facility as provided by the I/O
252 auxiliary and the <TT
256 are serious problems within the application, for example memory
257 corruption, then an internal software-only implementation will not be
261 >The watchdog resolution is currently fixed to one second: if the
262 device does not receive a reset signal at least once a second then
263 the watchdog will trigger and the eCos application will be terminated
267 > signal. The current implementation
268 does not allow this resolution to be changed.
271 >On some targets the watchdog device does not perform a hard reset.
272 Instead the device works more or less via the interrupt subsystem,
273 allowing application code to install action routines that will be
274 called when the watchdog triggers. The synthetic target watchdog
275 support effectively does perform a hard reset, by sending a
279 > signal to the eCos application, and there is
280 no support for action routines.
283 >The synthetic target watchdog package provides some configuration
284 options for manipulating the compiler flags used for building the
285 target-side code. That code is fairly simple, so for nearly all
286 applications the default flags will suffice.
289 >It should be noted that the watchdog device is subject to selective
290 linking. Unless some code explicitly references the device, for
291 example by calling the start and reset functions, the watchdog support
292 will not appear in the final executable. This is desirable because a
293 watchdog device has no effect until started.
299 NAME="SYNTH-WATCHDOG-WALLCLOCK-ELAPSED"
302 >Wallclock versus Elapsed Time</H2
304 >On real hardware the watchdog device uses wallclock time: if the
305 device does not receive a reset signal within a set period of time
306 then the watchdog will trigger. When developing for the synthetic
307 target this is not always appropriate. There may be other processes
308 running, using up some or most of the cpu time. For example, the
309 application may be written such that it will issue a reset after some
310 calculations which are known to complete within half a second, well
311 within the one-second resolution of the watchdog device. However if
312 other Linux processes are running then the synthetic target
313 application may get timesliced, and half a second of computation may
314 take several seconds of wallclock time.
317 >Another problem with using wallclock time is that it interferes with
318 debugging: if the application hits a breakpoint then it is unlikely
319 that the user will manage to restart it in less than a second, and the
320 watchdog will not get reset in time.
323 >To avoid these problems the synthetic target watchdog normally uses
324 consumed cpu time rather than wallclock time. If the application is
325 timesliced or if it is halted inside gdb then it does not consume any
326 cpu time. The application actually has to spend a whole second's worth
327 of cpu cycles without issuing a reset before the watchdog triggers.
330 >However using consumed cpu time is not a perfect solution either. If
331 the application makes blocking system calls then it is not using cpu
332 time. Interaction with the I/O auxiliary involves system calls, but
333 these should take only a short amount of time so their effects can be
334 ignored. If the application makes direct system calls such as
337 >cyg_hal_sys_read</TT
338 > then the system behaviour
339 becomes undefined. In addition by default the idle thread will make
343 > system calls, effectively waiting
344 until an interrupt occurs. If an application spends much of its time
345 idle then the watchdog device may take much longer to trigger than
346 expected. It may be desirable to enable the synthetic target HAL
347 configuration option <TT
349 >CYGIMP_HAL_IDLE_THREAD_SPIN</TT
351 causing the idle thread to spin rather than block, at the cost of
355 >The default is to use consumed cpu time, but this can be changed in
356 the target definition file:
365 CLASS="PROGRAMLISTING"
366 >synth_device watchdog {
377 NAME="SYNTH-WATCHDOG-GUI"
382 >When the synthetic target is run in graphical mode the watchdog device
383 extends the user interface in two ways. The <SPAN
387 menu is extended with an entry for the watchdog-specific
388 documentation. There is also a graphical display of the current state
389 of the watchdog. Initially the watchdog is asleep:
392 CLASS="INFORMALFIGURE"
407 >When application code starts the device the watchdog will begin to
408 keep an eye on things (or occasionally both eyes).
411 CLASS="INFORMALFIGURE"
426 >If the watchdog triggers the display will change again, and optionally
427 the user can receive an audible alert. The location of the watchdog
428 display within the I/O auxiliary's window can be controlled via
432 > entry in the target definition
433 file. For example the following can be used to put the watchdog
434 display to the right of the central text window:
443 CLASS="PROGRAMLISTING"
444 >synth_device watchdog {
445 watchdog_pack -in .main.e -side top
452 >The user interface section of the generic synthetic target HAL
453 documentation can be consulted for more information on window packing.
456 >By default the watchdog support will not generate an audible alert
457 when the watchdog triggers, to avoid annoying colleagues. Sound can be
458 enabled in the target definition file, and two suitable files
466 supplied as standard:
475 CLASS="PROGRAMLISTING"
476 >synth_device watchdog {
484 >An absolute path can be specified if desired:
493 CLASS="PROGRAMLISTING"
494 >synth_device watchdog {
495 sound /usr/share/emacs/site-lisp/emacspeak/sounds/default-8k/alarm.au
502 >Sound facilities are not built into the I/O auxiliary itself, instead
503 an external program is used. The default player is
507 >, a front-end to the
511 > application shipped with some Linux
512 distributions. If another player should be used then this can be
513 specified in the target definition file:
522 CLASS="PROGRAMLISTING"
523 >synth_device watchdog {
525 sound_player my_sound_player</PRE
530 >The specified program will be run in the background with a single
531 argument, the sound file.
537 NAME="DEVS-WATCHDOG-SYNTH-ARGS"
540 >Command Line Arguments</H2
542 >The watchdog support does not use any command line arguments. All
543 configuration is handled through the target definition file.
549 NAME="DEVS-WATCHDOG-SYNTH-HOOKS"
554 >The watchdog support does not provide any hooks for use by other
555 scripts. There is rarely any need for customizing the system's
556 behaviour when a watchdog triggers because those should be rare
557 events, even during application development.
563 NAME="DEVS-WATCHDOG-SYNTH-TCL"
566 >Additional Tcl Procedures</H2
568 >The watchdog support does not provide any additional Tcl procedures or
569 variables for use by other scripts.
577 SUMMARY="Footer navigation table"
588 HREF="devs-watchdog-synth-ref.html"
612 >Synthetic Target Watchdog Device</TD
618 HREF="devs-watchdog-synth-ref.html"