doc/html/ref/devs-watchdog-synth.html

   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.               -->
   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 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="Synthetic Target Watchdog Device"
  23 HREF="devs-watchdog-synth-ref.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Synthetic Target Watchdog Device"
  26 HREF="devs-watchdog-synth-ref.html"></HEAD
  27 ><BODY
  28 CLASS="REFENTRY"
  29 BGCOLOR="#FFFFFF"
  30 TEXT="#000000"
  31 LINK="#0000FF"
  32 VLINK="#840084"
  33 ALINK="#0000FF"
  34 ><DIV
  35 CLASS="NAVHEADER"
  36 ><TABLE
  37 SUMMARY="Header navigation table"
  38 WIDTH="100%"
  39 BORDER="0"
  40 CELLPADDING="0"
  41 CELLSPACING="0"
  42 ><TR
  43 ><TH
  44 COLSPAN="3"
  45 ALIGN="center"
  46 >eCos Reference Manual</TH
  47 ></TR
  48 ><TR
  49 ><TD
  50 WIDTH="10%"
  51 ALIGN="left"
  52 VALIGN="bottom"
  53 ><A
  54 HREF="devs-watchdog-synth-ref.html"
  55 ACCESSKEY="P"
  56 >Prev</A
  57 ></TD
  58 ><TD
  59 WIDTH="80%"
  60 ALIGN="center"
  61 VALIGN="bottom"
  62 ></TD
  63 ><TD
  64 WIDTH="10%"
  65 ALIGN="right"
  66 VALIGN="bottom"
  67 >&nbsp;</TD
  68 ></TR
  69 ></TABLE
  70 ><HR
  71 ALIGN="LEFT"
  72 WIDTH="100%"></DIV
  73 ><H1
  74 ><A
  75 NAME="DEVS-WATCHDOG-SYNTH">Synthetic Target Watchdog Device</H1
  76 ><DIV
  77 CLASS="REFNAMEDIV"
  78 ><A
  79 NAME="AEN19056"
  80 ></A
  81 ><H2
  82 >Name</H2
  83 >Synthetic Target Watchdog Device&nbsp;--&nbsp;Emulate watchdog hardware in the synthetic target</DIV
  84 ><DIV
  85 CLASS="REFSECT1"
  86 ><A
  87 NAME="AEN19059"
  88 ></A
  89 ><H2
  90 >Overview</H2
  91 ><P
  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.
 102     </P
 103 ><P
 104 >The synthetic target watchdog package emulates watchdog hardware.
 105 During system initialization watchdog device will be instantiated,
 106 and the <TT
 107 CLASS="FILENAME"
 108 >watchdog.tcl</TT
 109 > script will be loaded by the
 110 I/O auxiliary. When the eCos application starts the watchdog device,
 111 the <TT
 112 CLASS="FILENAME"
 113 >watchdog.tcl</TT
 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
 117 <TT
 118 CLASS="FILENAME"
 119 >watchdog.tcl</TT
 120 > script detects that a second has
 121 <A
 122 HREF="devs-watchdog-synth.html#SYNTH-WATCHDOG-WALLCLOCK-ELAPSED"
 123 >elapsed</A
 124 >
 125 without a reset then it will send a <TT
 126 CLASS="LITERAL"
 127 >SIGPWR</TT
 128 > signal
 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.
 136     </P
 137 ></DIV
 138 ><DIV
 139 CLASS="REFSECT1"
 140 ><A
 141 NAME="DEVS-WATCHDOG-SYNTH-INSTALL"
 142 ></A
 143 ><H2
 144 >Installation</H2
 145 ><P
 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
 149 CLASS="FILENAME"
 150 >host</TT
 151 >
 152 subdirectory of the synthetic target watchdog package, and building it
 153 involves the standard <B
 154 CLASS="COMMAND"
 155 >configure</B
 156 >,
 157 <B
 158 CLASS="COMMAND"
 159 >make</B
 160 > and <B
 161 CLASS="COMMAND"
 162 >make install</B
 163 > steps. The
 164 implementation of the watchdog support does not require any
 165 executables, just a Tcl script <TT
 166 CLASS="FILENAME"
 167 >watchdog.tcl</TT
 168 > and
 169 some support files, so the <B
 170 CLASS="COMMAND"
 171 >make</B
 172 > step is a no-op.
 173     </P
 174 ><P
 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
 179 <B
 180 CLASS="COMMAND"
 181 >configure</B
 182 > script at the toplevel of the eCos
 183 repository. For more information on this, see the
 184 <TT
 185 CLASS="FILENAME"
 186 >README.host</TT
 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.
 192     </P
 193 ><P
 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
 197 CLASS="COMMAND"
 198 >configure</B
 199 > options
 200 are much the same as for a build from the toplevel, and the
 201 <TT
 202 CLASS="FILENAME"
 203 >README.host</TT
 204 > file can be consulted for more
 205 details. It is essential that the watchdog support be configured with
 206 the same <TT
 207 CLASS="OPTION"
 208 >--prefix</TT
 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.
 213     </P
 214 ></DIV
 215 ><DIV
 216 CLASS="REFSECT1"
 217 ><A
 218 NAME="SYNTH-WATCHDOG-TARGET-CONFIG"
 219 ></A
 220 ><H2
 221 >Target-side
 222 Configuration</H2
 223 ><P
 224 >The watchdog device depends on the generic watchdog support,
 225 <TT
 226 CLASS="VARNAME"
 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:
 233     </P
 234 ><TABLE
 235 BORDER="5"
 236 BGCOLOR="#E0E0F0"
 237 WIDTH="70%"
 238 ><TR
 239 ><TD
 240 ><PRE
 241 CLASS="SCREEN"
 242 >$ ecosconfig add CYGPKG_IO_WATCHDOG</PRE
 243 ></TD
 244 ></TR
 245 ></TABLE
 246 ><P
 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
 253 CLASS="FILENAME"
 254 >watchdog.tcl</TT
 255 > script: if there
 256 are serious problems within the application, for example memory
 257 corruption, then an internal software-only implementation will not be
 258 reliable.
 259     </P
 260 ><P
 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
 264 with a <TT
 265 CLASS="LITERAL"
 266 >SIGPWR</TT
 267 > signal. The current implementation
 268 does not allow this resolution to be changed.
 269     </P
 270 ><P
 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
 276 <TT
 277 CLASS="LITERAL"
 278 >SIGPWR</TT
 279 > signal to the eCos application, and there is
 280 no support for action routines.
 281     </P
 282 ><P
 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.
 287     </P
 288 ><P
 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.
 294     </P
 295 ></DIV
 296 ><DIV
 297 CLASS="REFSECT1"
 298 ><A
 299 NAME="SYNTH-WATCHDOG-WALLCLOCK-ELAPSED"
 300 ></A
 301 ><H2
 302 >Wallclock versus Elapsed Time</H2
 303 ><P
 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.
 315     </P
 316 ><P
 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.
 321     </P
 322 ><P
 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.
 328     </P
 329 ><P
 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
 335 <TT
 336 CLASS="FUNCTION"
 337 >cyg_hal_sys_read</TT
 338 > then the system behaviour
 339 becomes undefined. In addition by default the idle thread will make
 340 blocking <TT
 341 CLASS="FUNCTION"
 342 >select</TT
 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
 348 CLASS="VARNAME"
 349 >CYGIMP_HAL_IDLE_THREAD_SPIN</TT
 350 >,
 351 causing the idle thread to spin rather than block, at the cost of
 352 wasted cpu cycles.
 353     </P
 354 ><P
 355 >The default is to use consumed cpu time, but this can be changed in
 356 the target definition file:
 357     </P
 358 ><TABLE
 359 BORDER="5"
 360 BGCOLOR="#E0E0F0"
 361 WIDTH="70%"
 362 ><TR
 363 ><TD
 364 ><PRE
 365 CLASS="PROGRAMLISTING"
 366 >synth_device watchdog {
 367     use wallclock_time
 368     &#8230;
 369 }</PRE
 370 ></TD
 371 ></TR
 372 ></TABLE
 373 ></DIV
 374 ><DIV
 375 CLASS="REFSECT1"
 376 ><A
 377 NAME="SYNTH-WATCHDOG-GUI"
 378 ></A
 379 ><H2
 380 >User Interface</H2
 381 ><P
 382 >When the synthetic target is run in graphical mode the watchdog device
 383 extends the user interface in two ways. The <SPAN
 384 CLASS="GUIMENU"
 385 >Help</SPAN
 386 >
 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:
 390     </P
 391 ><DIV
 392 CLASS="INFORMALFIGURE"
 393 ><A
 394 NAME="AEN19112"><P
 395 ></P
 396 ><DIV
 397 CLASS="MEDIAOBJECT"
 398 ><P
 399 ><IMG
 400 SRC="asleep.png"
 401 ALIGN="CENTER"></P
 402 ></DIV
 403 ><P
 404 ></P
 405 ></DIV
 406 ><P
 407 >When application code starts the device the watchdog will begin to
 408 keep an eye on things (or occasionally both eyes).
 409     </P
 410 ><DIV
 411 CLASS="INFORMALFIGURE"
 412 ><A
 413 NAME="AEN19117"><P
 414 ></P
 415 ><DIV
 416 CLASS="MEDIAOBJECT"
 417 ><P
 418 ><IMG
 419 SRC="awake.png"
 420 ALIGN="CENTER"></P
 421 ></DIV
 422 ><P
 423 ></P
 424 ></DIV
 425 ><P
 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
 429 a <B
 430 CLASS="COMMAND"
 431 >watchdog_pack</B
 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:
 435     </P
 436 ><TABLE
 437 BORDER="5"
 438 BGCOLOR="#E0E0F0"
 439 WIDTH="70%"
 440 ><TR
 441 ><TD
 442 ><PRE
 443 CLASS="PROGRAMLISTING"
 444 >synth_device watchdog {
 445     watchdog_pack -in .main.e -side top
 446     &#8230;
 447 }</PRE
 448 ></TD
 449 ></TR
 450 ></TABLE
 451 ><P
 452 >The user interface section of the generic synthetic target HAL
 453 documentation can be consulted for more information on window packing.
 454     </P
 455 ><P
 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
 459 <TT
 460 CLASS="FILENAME"
 461 >sound1.au</TT
 462 > and <TT
 463 CLASS="FILENAME"
 464 >sound2.au</TT
 465 > are
 466 supplied as standard:
 467     </P
 468 ><TABLE
 469 BORDER="5"
 470 BGCOLOR="#E0E0F0"
 471 WIDTH="70%"
 472 ><TR
 473 ><TD
 474 ><PRE
 475 CLASS="PROGRAMLISTING"
 476 >synth_device watchdog {
 477     sound sound1.au
 478     &#8230;
 479 }</PRE
 480 ></TD
 481 ></TR
 482 ></TABLE
 483 ><P
 484 >An absolute path can be specified if desired:
 485     </P
 486 ><TABLE
 487 BORDER="5"
 488 BGCOLOR="#E0E0F0"
 489 WIDTH="70%"
 490 ><TR
 491 ><TD
 492 ><PRE
 493 CLASS="PROGRAMLISTING"
 494 >synth_device watchdog {
 495     sound /usr/share/emacs/site-lisp/emacspeak/sounds/default-8k/alarm.au
 496     &#8230;
 497 }</PRE
 498 ></TD
 499 ></TR
 500 ></TABLE
 501 ><P
 502 >Sound facilities are not built into the I/O auxiliary itself, instead
 503 an external program is used. The default player is
 504 <B
 505 CLASS="COMMAND"
 506 >play</B
 507 >, a front-end to the
 508 <SPAN
 509 CLASS="APPLICATION"
 510 >sox</SPAN
 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:
 514     </P
 515 ><TABLE
 516 BORDER="5"
 517 BGCOLOR="#E0E0F0"
 518 WIDTH="70%"
 519 ><TR
 520 ><TD
 521 ><PRE
 522 CLASS="PROGRAMLISTING"
 523 >synth_device watchdog {
 524     &#8230;
 525     sound_player my_sound_player</PRE
 526 ></TD
 527 ></TR
 528 ></TABLE
 529 ><P
 530 >The specified program will be run in the background with a single
 531 argument, the sound file.
 532     </P
 533 ></DIV
 534 ><DIV
 535 CLASS="REFSECT1"
 536 ><A
 537 NAME="DEVS-WATCHDOG-SYNTH-ARGS"
 538 ></A
 539 ><H2
 540 >Command Line Arguments</H2
 541 ><P
 542 >The watchdog support does not use any command line arguments. All
 543 configuration is handled through the target definition file.
 544     </P
 545 ></DIV
 546 ><DIV
 547 CLASS="REFSECT1"
 548 ><A
 549 NAME="DEVS-WATCHDOG-SYNTH-HOOKS"
 550 ></A
 551 ><H2
 552 >Hooks</H2
 553 ><P
 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.
 558     </P
 559 ></DIV
 560 ><DIV
 561 CLASS="REFSECT1"
 562 ><A
 563 NAME="DEVS-WATCHDOG-SYNTH-TCL"
 564 ></A
 565 ><H2
 566 >Additional Tcl Procedures</H2
 567 ><P
 568 >The watchdog support does not provide any additional Tcl procedures or
 569 variables for use by other scripts.
 570     </P
 571 ></DIV
 572 ><DIV
 573 CLASS="NAVFOOTER"
 574 ><HR
 575 ALIGN="LEFT"
 576 WIDTH="100%"><TABLE
 577 SUMMARY="Footer navigation table"
 578 WIDTH="100%"
 579 BORDER="0"
 580 CELLPADDING="0"
 581 CELLSPACING="0"
 582 ><TR
 583 ><TD
 584 WIDTH="33%"
 585 ALIGN="left"
 586 VALIGN="top"
 587 ><A
 588 HREF="devs-watchdog-synth-ref.html"
 589 ACCESSKEY="P"
 590 >Prev</A
 591 ></TD
 592 ><TD
 593 WIDTH="34%"
 594 ALIGN="center"
 595 VALIGN="top"
 596 ><A
 597 HREF="ecos-ref.html"
 598 ACCESSKEY="H"
 599 >Home</A
 600 ></TD
 601 ><TD
 602 WIDTH="33%"
 603 ALIGN="right"
 604 VALIGN="top"
 605 >&nbsp;</TD
 606 ></TR
 607 ><TR
 608 ><TD
 609 WIDTH="33%"
 610 ALIGN="left"
 611 VALIGN="top"
 612 >Synthetic Target Watchdog Device</TD
 613 ><TD
 614 WIDTH="34%"
 615 ALIGN="center"
 616 VALIGN="top"
 617 ><A
 618 HREF="devs-watchdog-synth-ref.html"
 619 ACCESSKEY="U"
 620 >Up</A
 621 ></TD
 622 ><TD
 623 WIDTH="33%"
 624 ALIGN="right"
 625 VALIGN="top"
 626 >&nbsp;</TD
 627 ></TR
 628 ></TABLE
 629 ></DIV
 630 ></BODY
 631 ></HTML
 632 >