sbin/wdogctl/wdogctl.8

   1 .\"     $NetBSD: wdogctl.8,v 1.18 2008/01/09 14:35:54 xtraeme Exp $
   2 .\"
   3 .\" Copyright (c) 2000 Zembu Labs, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Author: Jason R. Thorpe <thorpej@zembu.com>
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by Zembu Labs, Inc.
  19 .\" 4. Neither the name of Zembu Labs nor the names of its employees may
  20 .\"    be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY ZEMBU LABS, INC. ``AS IS'' AND ANY EXPRESS
  24 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR-
  25 .\" RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DIS-
  26 .\" CLAIMED.  IN NO EVENT SHALL ZEMBU LABS BE LIABLE FOR ANY DIRECT, INDIRECT,
  27 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  28 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  32 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33 .\"
  34 .Dd January 9, 2008
  35 .Dt WDOGCTL 8
  36 .Os
  37 .Sh NAME
  38 .Nm wdogctl
  39 .Nd Watchdog timer control utility
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Nm
  43 .Fl d
  44 .Nm
  45 .Fl e
  46 .Op Fl A
  47 .Op Fl p Ar seconds
  48 .Ar timer
  49 .Nm
  50 .Fl k
  51 .Op Fl A
  52 .Op Fl p Ar seconds
  53 .Ar timer
  54 .Nm
  55 .Fl t
  56 .Nm
  57 .Fl u
  58 .Op Fl A
  59 .Op Fl p Ar seconds
  60 .Ar timer
  61 .Nm
  62 .Fl x
  63 .Op Fl A
  64 .Op Fl p Ar seconds
  65 .Ar timer
  66 .Sh DESCRIPTION
  67 .Nm
  68 is used to manipulate watchdog timers.
  69 Watchdog timers provide a means of ensuring that a system
  70 continues to make progress.
  71 This is accomplished by use of a timer, provided by either hardware or
  72 software; when the timer expires, the watchdog resets the system.
  73 In this case of a hardware watchdog timer, this is accomplished by
  74 asserting the system's hardware reset signal.
  75 In the case of a software watchdog timer,
  76 this is accomplished by calling the kernel's normal reboot path.
  77 In order to prevent the system from rebooting,
  78 something must refresh the timer to prevent it from expiring.
  79 .Pp
  80 The
  81 .Nx
  82 kernel provides three basic modes in which watchdog timers may
  83 operate: kernel tickle mode, user tickle mode, and external tickle mode.
  84 In kernel tickle mode, a timer in the kernel refreshes the watchdog timer.
  85 In user tickle mode,
  86 .Nm
  87 runs in the background and refreshes the watchdog timer.
  88 In kernel tickle mode, progress of the kernel is ensured.
  89 In user tickle mode, the ability for user programs to run within a known
  90 period of time is ensured.
  91 Note that user tickle mode must be used with caution;
  92 on a heavily loaded system, the timer may
  93 expire accidentally, even though user programs may be making
  94 (very slow) progress.
  95 A user-mode timer is disarmed (if possible) when the device is closed,
  96 unless the timer is activated with the
  97 .Fl x
  98 option.
  99 .Pp
 100 External-mode watchdogs are similar to user-mode watchdogs, except
 101 that the tickle must be done explicitly by a separate invocation of
 102 the program with the
 103 .Fl t
 104 option.
 105 .Pp
 106 In the first two modes, an attempt is made to refresh the watchdog timer
 107 in one half the timer's configured period.
 108 That is, if the watchdog timer has a period of 30 seconds, a refresh attempt
 109 is made every 15 seconds.
 110 .Pp
 111 If called without arguments,
 112 .Nm
 113 will list the timers available on the system.
 114 When arming a watchdog timer, the
 115 .Ar timer
 116 argument is the name of the timer to arm.
 117 .Pp
 118 Only one timer may be armed at a time; if an attempt is made
 119 to arm a timer when one is already armed, an error message
 120 will be displayed and no action will be taken.
 121 .Pp
 122 The options are as follows:
 123 .Bl -tag -offset indent -width XpXperiodXX
 124 .It Fl A
 125 When arming a timer, this flag indicates that an audible alarm is
 126 to sound when the watchdog timer expires and resets the system.
 127 If the selected timer does not support an audible alarm, this
 128 option will be silently ignored.
 129 .It Fl d
 130 This flag disarms the currently active timer.
 131 Note that not all watchdog timers can be disabled once armed.
 132 If the selected timer can not be disabled,
 133 an error message will be displayed and the
 134 timer will remain armed.
 135 .It Fl e
 136 Arm
 137 .Ar timer
 138 in external tickle mode.
 139 .It Fl k
 140 Arm
 141 .Ar timer
 142 in kernel tickle mode.
 143 .It Fl p Ar period
 144 When arming a timer, this flag configures the timer period to
 145 .Ar period
 146 seconds.
 147 If the specified period is outside the timer's range,
 148 an error message will be displayed and no action will be taken.
 149 .It Fl t
 150 This flag tickles an external mode timer.
 151 .It Fl u
 152 Arm
 153 .Ar timer
 154 in user tickle mode.
 155 .It Fl x
 156 Arm
 157 .Ar timer
 158 in a modified user tickle mode: closing the device will not disarm
 159 the timer.
 160 .El
 161 .Sh FILES
 162 .Pa /dev/watchdog
 163 -- the system monitor watchdog timer device
 164 .Sh SEE ALSO
 165 .Xr evbarm/iopwdog 4 ,
 166 .Xr i386/elansc 4 ,
 167 .Xr i386/gcscpcib 4 ,
 168 .Xr i386/geodewdog 4 ,
 169 .Xr ichlpcib 4 ,
 170 .Xr ipmi 4 ,
 171 .Xr itesio 4 ,
 172 .Xr pcweasel 4 ,
 173 .Xr swwdog 4
 174 .Sh HISTORY
 175 The
 176 .Nm
 177 command first appeared in
 178 .Nx 1.5.1 .
 179 .Sh AUTHORS
 180 The
 181 .Nm
 182 command and the
 183 .Nx
 184 watchdog timer framework were written by
 185 .An Jason R. Thorpe
 186 .Aq thorpej@zembu.com ,
 187 and contributed by Zembu Labs, Inc.