packages/devs/watchdog/synth/v2_0/doc/devs-watchdog-synth.html

   1 <!-- Copyright (C) 2002 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.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Synthetic Target Watchdog Device</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "></HEAD
  18 ><BODY
  19 CLASS="REFENTRY"
  20 BGCOLOR="#FFFFFF"
  21 TEXT="#000000"
  22 LINK="#0000FF"
  23 VLINK="#840084"
  24 ALINK="#0000FF"
  25 ><H1
  26 ><A
  27 NAME="DEVS-WATCHDOG-SYNTH">Synthetic Target Watchdog Device</H1
  28 ><DIV
  29 CLASS="REFNAMEDIV"
  30 ><A
  31 NAME="AEN4"
  32 ></A
  33 ><H2
  34 >Name</H2
  35 >Synthetic Target Watchdog Device&nbsp;--&nbsp;Emulate watchdog hardware in the synthetic target</DIV
  36 ><DIV
  37 CLASS="REFSECT1"
  38 ><A
  39 NAME="AEN7"
  40 ></A
  41 ><H2
  42 >Overview</H2
  43 ><P
  44 >Some target hardware comes equipped with a watchdog timer. Application
  45 code can start this timer and after a certain period of time,
  46 typically a second, the watchdog will trigger. Usually this causes the
  47 hardware to reboot. The application can prevent this by regularly
  48 resetting the watchdog. An automatic reboot can be very useful when
  49 deploying hardware in the field: a hardware glitch could cause the
  50 unit to hang; or the software could receive an unexpected sequence of
  51 inputs, never seen in the laboratory, causing the system to lock up.
  52 Often the hardware is still functional, and a reboot sorts out the
  53 problem with only a brief interruption in service.
  54     </P
  55 ><P
  56 >The synthetic target watchdog package emulates watchdog hardware.
  57 During system initialization watchdog device will be instantiated,
  58 and the <TT
  59 CLASS="FILENAME"
  60 >watchdog.tcl</TT
  61 > script will be loaded by the
  62 I/O auxiliary. When the eCos application starts the watchdog device,
  63 the <TT
  64 CLASS="FILENAME"
  65 >watchdog.tcl</TT
  66 > script will start checking the
  67 state of the eCos application at one second intervals. A watchdog
  68 reset call simply involves a message to the I/O auxiliary. If the
  69 <TT
  70 CLASS="FILENAME"
  71 >watchdog.tcl</TT
  72 > script detects that a second has
  73 <A
  74 HREF="devs-watchdog-synth.html#SYNTH-WATCHDOG-WALLCLOCK-ELAPSED"
  75 >elapsed</A
  76 >
  77 without a reset then it will send a <TT
  78 CLASS="LITERAL"
  79 >SIGPWR</TT
  80 > signal
  81 to the eCos application, causing the latter to terminate. If gdb is
  82 being used to run the application, the user will get a chance to
  83 investigate what is happening. This behaviour is different from real
  84 hardware in that there is no automatic reboot, but the synthetic
  85 target is used only for development purposes, not deployment in the
  86 field: if a reboot is desired then this can be achieved very easily
  87 by using gdb commands to run another instance of the application.
  88     </P
  89 ></DIV
  90 ><DIV
  91 CLASS="REFSECT1"
  92 ><A
  93 NAME="DEVS-WATCHDOG-SYNTH-INSTALL"
  94 ></A
  95 ><H2
  96 >Installation</H2
  97 ><P
  98 >Before a synthetic target eCos application can use a watchdog device
  99 it is necessary to build and install host-side support. The relevant
 100 code resides in the <TT
 101 CLASS="FILENAME"
 102 >host</TT
 103 >
 104 subdirectory of the synthetic target watchdog package, and building it
 105 involves the standard <B
 106 CLASS="COMMAND"
 107 >configure</B
 108 >,
 109 <B
 110 CLASS="COMMAND"
 111 >make</B
 112 > and <B
 113 CLASS="COMMAND"
 114 >make install</B
 115 > steps. The
 116 implementation of the watchdog support does not require any
 117 executables, just a Tcl script <TT
 118 CLASS="FILENAME"
 119 >watchdog.tcl</TT
 120 > and
 121 some support files, so the <B
 122 CLASS="COMMAND"
 123 >make</B
 124 > step is a no-op.
 125     </P
 126 ><P
 127 >There are two main ways of building the host-side software. It is
 128 possible to build both the generic host-side software and all
 129 package-specific host-side software, including the watchdog support,
 130 in a single build tree. This involves using the
 131 <B
 132 CLASS="COMMAND"
 133 >configure</B
 134 > script at the toplevel of the eCos
 135 repository. For more information on this, see the
 136 <TT
 137 CLASS="FILENAME"
 138 >README.host</TT
 139 > file at the top of the repository.
 140 Note that if you have an existing build tree which does not include
 141 the synthetic target watchdog support then it will be necessary to
 142 rerun the toplevel configure script: the search for appropriate
 143 packages happens at configure time.
 144     </P
 145 ><P
 146 >The alternative is to build just the host-side for this package.
 147 This requires a separate build directory, building directly in the
 148 source tree is disallowed. The <B
 149 CLASS="COMMAND"
 150 >configure</B
 151 > options
 152 are much the same as for a build from the toplevel, and the
 153 <TT
 154 CLASS="FILENAME"
 155 >README.host</TT
 156 > file can be consulted for more
 157 details. It is essential that the watchdog support be configured with
 158 the same <TT
 159 CLASS="OPTION"
 160 >--prefix</TT
 161 > option as other eCos host-side
 162 software, especially the I/O auxiliary provided by the architectural
 163 synthetic target HAL package, otherwise the I/O auxiliary will be
 164 unable to locate the watchdog support.
 165     </P
 166 ></DIV
 167 ><DIV
 168 CLASS="REFSECT1"
 169 ><A
 170 NAME="SYNTH-WATCHDOG-TARGET-CONFIG"
 171 ></A
 172 ><H2
 173 >Target-side
 174 Configuration</H2
 175 ><P
 176 >The watchdog device depends on the generic watchdog support,
 177 <TT
 178 CLASS="VARNAME"
 179 >CYGPKG_IO_WATCHDOG</TT
 180 >: if the generic support is
 181 absent then the watchdog device will be inactive. Some templates
 182 include this generic package by default, but not all. If the
 183 configuration does not include the generic package then it can be
 184 added using the eCos configuration tools, for example:
 185     </P
 186 ><TABLE
 187 BORDER="5"
 188 BGCOLOR="#E0E0F0"
 189 WIDTH="70%"
 190 ><TR
 191 ><TD
 192 ><PRE
 193 CLASS="SCREEN"
 194 >$ ecosconfig add CYGPKG_IO_WATCHDOG</PRE
 195 ></TD
 196 ></TR
 197 ></TABLE
 198 ><P
 199 >By default the configuration will use the hardware-specific support,
 200 i.e. this package. However the generic watchdog package contains an
 201 alternative implementation using the kernel alarm facility, and that
 202 implementation can be selected if desired. However usually it will be
 203 better to rely on an external watchdog facility as provided by the I/O
 204 auxiliary and the <TT
 205 CLASS="FILENAME"
 206 >watchdog.tcl</TT
 207 > script: if there
 208 are serious problems within the application, for example memory
 209 corruption, then an internal software-only implementation will not be
 210 reliable.
 211     </P
 212 ><P
 213 >The watchdog resolution is currently fixed to one second: if the
 214 device does not receive a reset signal at least once a second then
 215 the watchdog will trigger and the eCos application will be terminated
 216 with a <TT
 217 CLASS="LITERAL"
 218 >SIGPWR</TT
 219 > signal. The current implementation
 220 does not allow this resolution to be changed.
 221     </P
 222 ><P
 223 >On some targets the watchdog device does not perform a hard reset.
 224 Instead the device works more or less via the interrupt subsystem,
 225 allowing application code to install action routines that will be
 226 called when the watchdog triggers. The synthetic target watchdog
 227 support effectively does perform a hard reset, by sending a
 228 <TT
 229 CLASS="LITERAL"
 230 >SIGPWR</TT
 231 > signal to the eCos application, and there is
 232 no support for action routines.
 233     </P
 234 ><P
 235 >The synthetic target watchdog package provides some configuration
 236 options for manipulating the compiler flags used for building the
 237 target-side code. That code is fairly simple, so for nearly all
 238 applications the default flags will suffice.
 239     </P
 240 ><P
 241 >It should be noted that the watchdog device is subject to selective
 242 linking. Unless some code explicitly references the device, for
 243 example by calling the start and reset functions, the watchdog support
 244 will not appear in the final executable. This is desirable because a
 245 watchdog device has no effect until started.
 246     </P
 247 ></DIV
 248 ><DIV
 249 CLASS="REFSECT1"
 250 ><A
 251 NAME="SYNTH-WATCHDOG-WALLCLOCK-ELAPSED"
 252 ></A
 253 ><H2
 254 >Wallclock versus Elapsed Time</H2
 255 ><P
 256 >On real hardware the watchdog device uses wallclock time: if the
 257 device does not receive a reset signal within a set period of time
 258 then the watchdog will trigger. When developing for the synthetic
 259 target this is not always appropriate. There may be other processes
 260 running, using up some or most of the cpu time. For example, the
 261 application may be written such that it will issue a reset after some
 262 calculations which are known to complete within half a second, well
 263 within the one-second resolution of the watchdog device. However if
 264 other Linux processes are running then the synthetic target
 265 application may get timesliced, and half a second of computation may
 266 take several seconds of wallclock time.
 267     </P
 268 ><P
 269 >Another problem with using wallclock time is that it interferes with
 270 debugging: if the application hits a breakpoint then it is unlikely
 271 that the user will manage to restart it in less than a second, and the
 272 watchdog will not get reset in time.
 273     </P
 274 ><P
 275 >To avoid these problems the synthetic target watchdog normally uses
 276 consumed cpu time rather than wallclock time. If the application is
 277 timesliced or if it is halted inside gdb then it does not consume any
 278 cpu time. The application actually has to spend a whole second's worth
 279 of cpu cycles without issuing a reset before the watchdog triggers.
 280     </P
 281 ><P
 282 >However using consumed cpu time is not a perfect solution either. If
 283 the application makes blocking system calls then it is not using cpu
 284 time. Interaction with the I/O auxiliary involves system calls, but
 285 these should take only a short amount of time so their effects can be
 286 ignored. If the application makes direct system calls such as
 287 <TT
 288 CLASS="FUNCTION"
 289 >cyg_hal_sys_read</TT
 290 > then the system behaviour
 291 becomes undefined. In addition by default the idle thread will make
 292 blocking <TT
 293 CLASS="FUNCTION"
 294 >select</TT
 295 > system calls, effectively waiting
 296 until an interrupt occurs. If an application spends much of its time
 297 idle then the watchdog device may take much longer to trigger than
 298 expected. It may be desirable to enable the synthetic target HAL
 299 configuration option <TT
 300 CLASS="VARNAME"
 301 >CYGIMP_HAL_IDLE_THREAD_SPIN</TT
 302 >,
 303 causing the idle thread to spin rather than block, at the cost of
 304 wasted cpu cycles.
 305     </P
 306 ><P
 307 >The default is to use consumed cpu time, but this can be changed in
 308 the target definition file:
 309     </P
 310 ><TABLE
 311 BORDER="5"
 312 BGCOLOR="#E0E0F0"
 313 WIDTH="70%"
 314 ><TR
 315 ><TD
 316 ><PRE
 317 CLASS="PROGRAMLISTING"
 318 >synth_device watchdog {
 319     use wallclock_time
 320     &#8230;
 321 }</PRE
 322 ></TD
 323 ></TR
 324 ></TABLE
 325 ></DIV
 326 ><DIV
 327 CLASS="REFSECT1"
 328 ><A
 329 NAME="SYNTH-WATCHDOG-GUI"
 330 ></A
 331 ><H2
 332 >User Interface</H2
 333 ><P
 334 >When the synthetic target is run in graphical mode the watchdog device
 335 extends the user interface in two ways. The <SPAN
 336 CLASS="GUIMENU"
 337 >Help</SPAN
 338 >
 339 menu is extended with an entry for the watchdog-specific
 340 documentation. There is also a graphical display of the current state
 341 of the watchdog. Initially the watchdog is asleep:
 342     </P
 343 ><DIV
 344 CLASS="INFORMALFIGURE"
 345 ><A
 346 NAME="AEN60"><P
 347 ></P
 348 ><DIV
 349 CLASS="MEDIAOBJECT"
 350 ><P
 351 ><IMG
 352 SRC="asleep.gif"
 353 ALIGN="CENTER"></P
 354 ></DIV
 355 ><P
 356 ></P
 357 ></DIV
 358 ><P
 359 >When application code starts the device the watchdog will begin to
 360 keep an eye on things (or occasionally both eyes).
 361     </P
 362 ><DIV
 363 CLASS="INFORMALFIGURE"
 364 ><A
 365 NAME="AEN65"><P
 366 ></P
 367 ><DIV
 368 CLASS="MEDIAOBJECT"
 369 ><P
 370 ><IMG
 371 SRC="awake.gif"
 372 ALIGN="CENTER"></P
 373 ></DIV
 374 ><P
 375 ></P
 376 ></DIV
 377 ><P
 378 >If the watchdog triggers the display will change again, and optionally
 379 the user can receive an audible alert. The location of the watchdog
 380 display within the I/O auxiliary's window can be controlled via
 381 a <B
 382 CLASS="COMMAND"
 383 >watchdog_pack</B
 384 > entry in the target definition
 385 file. For example the following can be used to put the watchdog
 386 display to the right of the central text window:
 387     </P
 388 ><TABLE
 389 BORDER="5"
 390 BGCOLOR="#E0E0F0"
 391 WIDTH="70%"
 392 ><TR
 393 ><TD
 394 ><PRE
 395 CLASS="PROGRAMLISTING"
 396 >synth_device watchdog {
 397     watchdog_pack -in .main.e -side top
 398     &#8230;
 399 }</PRE
 400 ></TD
 401 ></TR
 402 ></TABLE
 403 ><P
 404 >The user interface section of the generic synthetic target HAL
 405 documentation can be consulted for more information on window packing.
 406     </P
 407 ><P
 408 >By default the watchdog support will not generate an audible alert
 409 when the watchdog triggers, to avoid annoying colleagues. Sound can be
 410 enabled in the target definition file, and two suitable files
 411 <TT
 412 CLASS="FILENAME"
 413 >sound1.au</TT
 414 > and <TT
 415 CLASS="FILENAME"
 416 >sound2.au</TT
 417 > are
 418 supplied as standard:
 419     </P
 420 ><TABLE
 421 BORDER="5"
 422 BGCOLOR="#E0E0F0"
 423 WIDTH="70%"
 424 ><TR
 425 ><TD
 426 ><PRE
 427 CLASS="PROGRAMLISTING"
 428 >synth_device watchdog {
 429     sound sound1.au
 430     &#8230;
 431 }</PRE
 432 ></TD
 433 ></TR
 434 ></TABLE
 435 ><P
 436 >An absolute path can be specified if desired:
 437     </P
 438 ><TABLE
 439 BORDER="5"
 440 BGCOLOR="#E0E0F0"
 441 WIDTH="70%"
 442 ><TR
 443 ><TD
 444 ><PRE
 445 CLASS="PROGRAMLISTING"
 446 >synth_device watchdog {
 447     sound /usr/share/emacs/site-lisp/emacspeak/sounds/default-8k/alarm.au
 448     &#8230;
 449 }</PRE
 450 ></TD
 451 ></TR
 452 ></TABLE
 453 ><P
 454 >Sound facilities are not built into the I/O auxiliary itself, instead
 455 an external program is used. The default player is
 456 <B
 457 CLASS="COMMAND"
 458 >play</B
 459 >, a front-end to the
 460 <SPAN
 461 CLASS="APPLICATION"
 462 >sox</SPAN
 463 > application shipped with some Linux
 464 distributions. If another player should be used then this can be
 465 specified in the target definition file:
 466     </P
 467 ><TABLE
 468 BORDER="5"
 469 BGCOLOR="#E0E0F0"
 470 WIDTH="70%"
 471 ><TR
 472 ><TD
 473 ><PRE
 474 CLASS="PROGRAMLISTING"
 475 >synth_device watchdog {
 476     &#8230;
 477     sound_player my_sound_player</PRE
 478 ></TD
 479 ></TR
 480 ></TABLE
 481 ><P
 482 >The specified program will be run in the background with a single
 483 argument, the sound file.
 484     </P
 485 ></DIV
 486 ><DIV
 487 CLASS="REFSECT1"
 488 ><A
 489 NAME="DEVS-WATCHDOG-SYNTH-ARGS"
 490 ></A
 491 ><H2
 492 >Command Line Arguments</H2
 493 ><P
 494 >The watchdog support does not use any command line arguments. All
 495 configuration is handled through the target definition file.
 496     </P
 497 ></DIV
 498 ><DIV
 499 CLASS="REFSECT1"
 500 ><A
 501 NAME="DEVS-WATCHDOG-SYNTH-HOOKS"
 502 ></A
 503 ><H2
 504 >Hooks</H2
 505 ><P
 506 >The watchdog support does not provide any hooks for use by other
 507 scripts. There is rarely any need for customizing the system's
 508 behaviour when a watchdog triggers because those should be rare
 509 events, even during application development.
 510     </P
 511 ></DIV
 512 ><DIV
 513 CLASS="REFSECT1"
 514 ><A
 515 NAME="DEVS-WATCHDOG-SYNTH-TCL"
 516 ></A
 517 ><H2
 518 >Additional Tcl Procedures</H2
 519 ><P
 520 >The watchdog support does not provide any additional Tcl procedures or
 521 variables for use by other scripts.
 522     </P
 523 ></DIV
 524 ></BODY
 525 ></HTML
 526 >