.\"	$NetBSD: wdogctl.8,v 1.28 2022/09/23 12:35:00 riastradh Exp $
.\"
.\" Copyright (c) 2000 Zembu Labs, Inc.
.\" All rights reserved.
.\"
.\" Author: Jason R. Thorpe <thorpej@zembu.com>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by Zembu Labs, Inc.
.\" 4. Neither the name of Zembu Labs nor the names of its employees may
.\"    be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY ZEMBU LABS, INC. ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR-
.\" RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DIS-
.\" CLAIMED.  IN NO EVENT SHALL ZEMBU LABS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 11, 2020
.Dt WDOGCTL 8
.Os
.Sh NAME
.Nm wdogctl
.Nd Watchdog timer control utility
.Sh SYNOPSIS
.Nm
.Nm
.Fl d
.Nm
.Fl e
.Op Fl A
.Op Fl p Ar seconds
.Ar timer
.Nm
.Fl k
.Op Fl A
.Op Fl p Ar seconds
.Ar timer
.Nm
.Fl t
.Nm
.Fl u
.Op Fl A
.Op Fl p Ar seconds
.Ar timer
.Nm
.Fl x
.Op Fl A
.Op Fl p Ar seconds
.Ar timer
.Sh DESCRIPTION
.Nm
is used to manipulate watchdog timers.
A watchdog timer is a hardware or software timer that resets the system
if it fails to make progress within a prescribed period.
To prevent the system from being reset, something must refresh the
timer to prevent it from expiring.
.Pp
A hardware watchdog timer asserts system's hardware reset signal when
it expires.
A software watchdog timer calls the kernel's s normal reboot path.
.Pp
The
.Nx
kernel provides three modes in which watchdog timers may
operate: kernel tickle mode, user tickle mode, and external tickle mode.
.Bl -tag
.It kernel tickle mode
A timer in the kernel refreshes the watchdog timer.
This ensures kernel threads can make progress within the period of the
watchdog timer.
.It user tickle mode
.Nm
runs in the background and refreshes the watchdog timer.
This ensures user programs can make progress within the period of the
watchdog timer.
.Pp
Note that user tickle mode must be used with caution;
on a heavily loaded system, the timer may
expire accidentally, even though user programs may be making
(very slow) progress.
A user-mode timer is disarmed (if possible) when the device is closed,
unless the timer is activated with the
.Fl x
option.
.It external tickle mode
Similar to user tickle mode, except that the tickle must be done
explicitly by a separate invocation of
.Nm Fl t .
This allows users to determine the activity whose progress the watchdog
timer checks.
.El
.Pp
In kernel and user tickle modes, an attempt is made to refresh the
watchdog timer in one half the timer's configured period.
For example, if the watchdog timer has a period of 30 seconds, a
refresh attempt is made every 15 seconds.
.Pp
If called without arguments,
.Nm
will list the timers available on the system.
When arming a watchdog timer, the
.Ar timer
argument is the name of the timer to arm.
.Pp
Only one timer may be armed at a time; if an attempt is made
to arm a timer when one is already armed, an error message
will be displayed and no action will be taken.
.Pp
The options are as follows:
.Bl -tag -width Fl
.It Fl A
When arming a timer, this flag indicates that an audible alarm is
to sound when the watchdog timer expires and resets the system.
If the selected timer does not support an audible alarm, this
option will be silently ignored.
.It Fl d
This flag disarms the currently active timer.
Note that not all watchdog timers can be disabled once armed.
If the selected timer can not be disabled,
an error message will be displayed and the
timer will remain armed.
.It Fl e
Arm
.Ar timer
in external tickle mode.
.It Fl k
Arm
.Ar timer
in kernel tickle mode.
.It Fl p Ar period
When arming a timer, this flag configures the timer period to
.Ar period
seconds.
If the specified period is outside the timer's range,
an error message will be displayed and no action will be taken.
.It Fl t
This flag tickles an external mode timer.
.It Fl u
Arm
.Ar timer
in user tickle mode.
.It Fl x
Arm
.Ar timer
in a modified user tickle mode: closing the device will not disarm
the timer.
.El
.Sh FILES
.Bl -tag -width ".Pa /dev/watchdog"
.It Pa /dev/watchdog
the system monitor watchdog timer device
.El
.Sh SEE ALSO
.Xr acpiwdrt 4 ,
.Xr evbarm/iopwdog 4 ,
.Xr i386/elansc 4 ,
.Xr i386/gcscpcib 4 ,
.Xr i386/geodewdog 4 ,
.Xr ipmi 4 ,
.Xr itesio 4 ,
.Xr pcweasel 4 ,
.Xr pwdog 4 ,
.Xr swwdog 4 ,
.Xr x86/tco 4
.Sh HISTORY
The
.Nm
command first appeared in
.Nx 1.6 .
.Sh AUTHORS
The
.Nm
command and the
.Nx
watchdog timer framework were written by
.An Jason R. Thorpe
.Aq thorpej@zembu.com ,
and contributed by Zembu Labs, Inc.