1.\" $NetBSD: wdogctl.8,v 1.23 2011/03/19 08:41:19 wiz 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 March 18, 2011 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 68is used to manipulate watchdog timers. 69Watchdog timers provide a means of ensuring that a system 70continues to make progress. 71This is accomplished by use of a timer, provided by either hardware or 72software; when the timer expires, the watchdog resets the system. 73In this case of a hardware watchdog timer, this is accomplished by 74asserting the system's hardware reset signal. 75In the case of a software watchdog timer, 76this is accomplished by calling the kernel's normal reboot path. 77In order to prevent the system from rebooting, 78something must refresh the timer to prevent it from expiring. 79.Pp 80The 81.Nx 82kernel provides three basic modes in which watchdog timers may 83operate: kernel tickle mode, user tickle mode, and external tickle mode. 84In kernel tickle mode, a timer in the kernel refreshes the watchdog timer. 85In user tickle mode, 86.Nm 87runs in the background and refreshes the watchdog timer. 88In kernel tickle mode, progress of the kernel is ensured. 89In user tickle mode, the ability for user programs to run within a known 90period of time is ensured. 91Note that user tickle mode must be used with caution; 92on a heavily loaded system, the timer may 93expire accidentally, even though user programs may be making 94(very slow) progress. 95A user-mode timer is disarmed (if possible) when the device is closed, 96unless the timer is activated with the 97.Fl x 98option. 99.Pp 100External-mode watchdogs are similar to user-mode watchdogs, except 101that the tickle must be done explicitly by a separate invocation of 102the program with the 103.Fl t 104option. 105.Pp 106In the first two modes, an attempt is made to refresh the watchdog timer 107in one half the timer's configured period. 108That is, if the watchdog timer has a period of 30 seconds, a refresh attempt 109is made every 15 seconds. 110.Pp 111If called without arguments, 112.Nm 113will list the timers available on the system. 114When arming a watchdog timer, the 115.Ar timer 116argument is the name of the timer to arm. 117.Pp 118Only one timer may be armed at a time; if an attempt is made 119to arm a timer when one is already armed, an error message 120will be displayed and no action will be taken. 121.Pp 122The options are as follows: 123.Bl -tag -offset indent -width XpXperiodXX 124.It Fl A 125When arming a timer, this flag indicates that an audible alarm is 126to sound when the watchdog timer expires and resets the system. 127If the selected timer does not support an audible alarm, this 128option will be silently ignored. 129.It Fl d 130This flag disarms the currently active timer. 131Note that not all watchdog timers can be disabled once armed. 132If the selected timer can not be disabled, 133an error message will be displayed and the 134timer will remain armed. 135.It Fl e 136Arm 137.Ar timer 138in external tickle mode. 139.It Fl k 140Arm 141.Ar timer 142in kernel tickle mode. 143.It Fl p Ar period 144When arming a timer, this flag configures the timer period to 145.Ar period 146seconds. 147If the specified period is outside the timer's range, 148an error message will be displayed and no action will be taken. 149.It Fl t 150This flag tickles an external mode timer. 151.It Fl u 152Arm 153.Ar timer 154in user tickle mode. 155.It Fl x 156Arm 157.Ar timer 158in a modified user tickle mode: closing the device will not disarm 159the timer. 160.El 161.Sh FILES 162.Pa /dev/watchdog 163-- the system monitor watchdog timer device 164.Sh SEE ALSO 165.Xr acpiwdrt 4 , 166.Xr evbarm/iopwdog 4 , 167.Xr i386/elansc 4 , 168.Xr i386/gcscpcib 4 , 169.Xr i386/geodewdog 4 , 170.Xr ipmi 4 , 171.Xr itesio 4 , 172.Xr pcweasel 4 , 173.Xr swwdog 4 , 174.Xr x86/ichlpcib 4 175.Sh HISTORY 176The 177.Nm 178command first appeared in 179.Nx 1.6 . 180.Sh AUTHORS 181The 182.Nm 183command and the 184.Nx 185watchdog timer framework were written by 186.An Jason R. Thorpe 187.Aq thorpej@zembu.com , 188and contributed by Zembu Labs, Inc. 189