OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [devs-watchdog-synth.html] - Blame information for rev 593

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback
<!-- 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
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.