Commit cc2a2d19 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

docs: watchdog: convert docs to ReST and rename to *.rst

Convert those documents and prepare them to be part of the kernel
API book, as most of the stuff there are related to the
Kernel interfaces.

Still, in the future, it would make sense to split the docs,
as some of the stuff is clearly focused on sysadmin tasks.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - fix tables markups;
  - add some lists markups;
  - mark literal blocks;
  - adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: default avatarGuenter Roeck <linux@roeck-us.net>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 458f69ef
......@@ -5160,7 +5160,7 @@
Default: 3 = cyan.
watchdog timers [HW,WDT] For information on watchdog timers,
see Documentation/watchdog/watchdog-parameters.txt
see Documentation/watchdog/watchdog-parameters.rst
or other driver-specific files in the
Documentation/watchdog/ directory.
......
......@@ -348,7 +348,7 @@ To reduce its OS jitter, do at least one of the following:
2. Boot with "nosoftlockup=0", which will also prevent these kthreads
from being created. Other related watchdog and softlockup boot
parameters may be found in Documentation/admin-guide/kernel-parameters.rst
and Documentation/watchdog/watchdog-parameters.txt.
and Documentation/watchdog/watchdog-parameters.rst.
3. Echo a zero to /proc/sys/kernel/watchdog to disable the
watchdog timer.
4. Echo a large number of /proc/sys/kernel/watchdog_thresh in
......
=========================================================
Converting old watchdog drivers to the watchdog framework
by Wolfram Sang <w.sang@pengutronix.de>
=========================================================
by Wolfram Sang <w.sang@pengutronix.de>
Before the watchdog framework came into the kernel, every driver had to
implement the API on its own. Now, as the framework factored out the common
components, those drivers can be lightened making it a user of the framework.
......@@ -69,16 +71,16 @@ Here is a overview of the functions and probably needed actions:
-ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error
is directly given to the user.
Example conversion:
Example conversion::
-static const struct file_operations s3c2410wdt_fops = {
- .owner = THIS_MODULE,
- .llseek = no_llseek,
- .write = s3c2410wdt_write,
- .unlocked_ioctl = s3c2410wdt_ioctl,
- .open = s3c2410wdt_open,
- .release = s3c2410wdt_release,
-};
-static const struct file_operations s3c2410wdt_fops = {
- .owner = THIS_MODULE,
- .llseek = no_llseek,
- .write = s3c2410wdt_write,
- .unlocked_ioctl = s3c2410wdt_ioctl,
- .open = s3c2410wdt_open,
- .release = s3c2410wdt_release,
-};
Check the functions for device-specific stuff and keep it for later
refactoring. The rest can go.
......@@ -89,24 +91,24 @@ Remove the miscdevice
Since the file_operations are gone now, you can also remove the 'struct
miscdevice'. The framework will create it on watchdog_dev_register() called by
watchdog_register_device().
watchdog_register_device()::
-static struct miscdevice s3c2410wdt_miscdev = {
- .minor = WATCHDOG_MINOR,
- .name = "watchdog",
- .fops = &s3c2410wdt_fops,
-};
-static struct miscdevice s3c2410wdt_miscdev = {
- .minor = WATCHDOG_MINOR,
- .name = "watchdog",
- .fops = &s3c2410wdt_fops,
-};
Remove obsolete includes and defines
------------------------------------
Because of the simplifications, a few defines are probably unused now. Remove
them. Includes can be removed, too. For example:
them. Includes can be removed, too. For example::
- #include <linux/fs.h>
- #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
- #include <linux/uaccess.h> (if no custom IOCTLs are used)
- #include <linux/fs.h>
- #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
- #include <linux/uaccess.h> (if no custom IOCTLs are used)
Add the watchdog operations
......@@ -121,30 +123,30 @@ change the function header. Other changes are most likely not needed, because
here simply happens the direct hardware access. If you have device-specific
code left from the above steps, it should be refactored into these callbacks.
Here is a simple example:
Here is a simple example::
+static struct watchdog_ops s3c2410wdt_ops = {
+ .owner = THIS_MODULE,
+ .start = s3c2410wdt_start,
+ .stop = s3c2410wdt_stop,
+ .ping = s3c2410wdt_keepalive,
+ .set_timeout = s3c2410wdt_set_heartbeat,
+};
+static struct watchdog_ops s3c2410wdt_ops = {
+ .owner = THIS_MODULE,
+ .start = s3c2410wdt_start,
+ .stop = s3c2410wdt_stop,
+ .ping = s3c2410wdt_keepalive,
+ .set_timeout = s3c2410wdt_set_heartbeat,
+};
A typical function-header change looks like:
A typical function-header change looks like::
-static void s3c2410wdt_keepalive(void)
+static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
{
...
+
+ return 0;
}
-static void s3c2410wdt_keepalive(void)
+static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
{
...
+
+ return 0;
}
...
...
- s3c2410wdt_keepalive();
+ s3c2410wdt_keepalive(&s3c2410_wdd);
- s3c2410wdt_keepalive();
+ s3c2410wdt_keepalive(&s3c2410_wdd);
Add the watchdog device
......@@ -159,12 +161,12 @@ static variables. Those have to be converted to use the members in
watchdog_device. Note that the timeout values are unsigned int. Some drivers
use signed int, so this has to be converted, too.
Here is a simple example for a watchdog device:
Here is a simple example for a watchdog device::
+static struct watchdog_device s3c2410_wdd = {
+ .info = &s3c2410_wdt_ident,
+ .ops = &s3c2410wdt_ops,
+};
+static struct watchdog_device s3c2410_wdd = {
+ .info = &s3c2410_wdt_ident,
+ .ops = &s3c2410wdt_ops,
+};
Handle the 'nowayout' feature
......@@ -173,12 +175,12 @@ Handle the 'nowayout' feature
A few drivers use nowayout statically, i.e. there is no module parameter for it
and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be
used. This needs to be converted by initializing the status variable of the
watchdog_device like this:
watchdog_device like this::
.status = WATCHDOG_NOWAYOUT_INIT_STATUS,
Most drivers, however, also allow runtime configuration of nowayout, usually
by adding a module parameter. The conversion for this would be something like:
by adding a module parameter. The conversion for this would be something like::
watchdog_set_nowayout(&s3c2410_wdd, nowayout);
......@@ -191,15 +193,15 @@ Register the watchdog device
Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev).
Make sure the return value gets checked and the error message, if present,
still fits. Also convert the unregister case.
still fits. Also convert the unregister case::
- ret = misc_register(&s3c2410wdt_miscdev);
+ ret = watchdog_register_device(&s3c2410_wdd);
- ret = misc_register(&s3c2410wdt_miscdev);
+ ret = watchdog_register_device(&s3c2410_wdd);
...
...
- misc_deregister(&s3c2410wdt_miscdev);
+ watchdog_unregister_device(&s3c2410_wdd);
- misc_deregister(&s3c2410wdt_miscdev);
+ watchdog_unregister_device(&s3c2410_wdd);
Update the Kconfig-entry
......@@ -207,7 +209,7 @@ Update the Kconfig-entry
The entry for the driver now needs to select WATCHDOG_CORE:
+ select WATCHDOG_CORE
+ select WATCHDOG_CORE
Create a patch and send it to upstream
......@@ -215,4 +217,3 @@ Create a patch and send it to upstream
Make sure you understood Documentation/process/submitting-patches.rst and send your patch to
linux-watchdog@vger.kernel.org. We are looking forward to it :)
===========================
HPE iLO NMI Watchdog Driver
===========================
for iLO based ProLiant Servers
==============================
Last reviewed: 08/20/2018
HPE iLO NMI Watchdog Driver
for iLO based ProLiant Servers
The HPE iLO NMI Watchdog driver is a kernel module that provides basic
watchdog functionality and handler for the iLO "Generate NMI to System"
......@@ -20,23 +25,26 @@ Last reviewed: 08/20/2018
The hpwdt driver also has the following module parameters:
soft_margin - allows the user to set the watchdog timer value.
============ ================================================================
soft_margin allows the user to set the watchdog timer value.
Default value is 30 seconds.
timeout - an alias of soft_margin.
pretimeout - allows the user to set the watchdog pretimeout value.
timeout an alias of soft_margin.
pretimeout allows the user to set the watchdog pretimeout value.
This is the number of seconds before timeout when an
NMI is delivered to the system. Setting the value to
zero disables the pretimeout NMI.
Default value is 9 seconds.
nowayout - basic watchdog parameter that does not allow the timer to
nowayout basic watchdog parameter that does not allow the timer to
be restarted or an impending ASR to be escaped.
Default value is set when compiling the kernel. If it is set
to "Y", then there is no way of disabling the watchdog once
it has been started.
============ ================================================================
NOTE: More information about watchdog drivers in general, including the ioctl
NOTE:
More information about watchdog drivers in general, including the ioctl
interface to /dev/watchdog can be found in
Documentation/watchdog/watchdog-api.txt and Documentation/IPMI.txt.
Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.txt.
Due to limitations in the iLO hardware, the NMI pretimeout if enabled,
can only be set to 9 seconds. Attempts to set pretimeout to other
......@@ -63,4 +71,3 @@ Last reviewed: 08/20/2018
The HPE iLO NMI Watchdog Driver and documentation were originally developed
by Tom Mingarelli.
:orphan:
======================
Linux Watchdog Support
======================
.. toctree::
:maxdepth: 1
hpwdt
mlx-wdt
pcwd-watchdog
watchdog-api
watchdog-kernel-api
watchdog-parameters
watchdog-pm
wdt
convert_drivers_to_kernel_api
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
Mellanox watchdog drivers
for x86 based system switches
=========================
Mellanox watchdog drivers
=========================
for x86 based system switches
=============================
This driver provides watchdog functionality for various Mellanox
Ethernet and Infiniband switch systems.
......@@ -9,16 +13,16 @@ Mellanox watchdog device is implemented in a programmable logic device.
There are 2 types of HW watchdog implementations.
Type 1:
Actual HW timeout can be defined as a power of 2 msec.
e.g. timeout 20 sec will be rounded up to 32768 msec.
The maximum timeout period is 32 sec (32768 msec.),
Get time-left isn't supported
Actual HW timeout can be defined as a power of 2 msec.
e.g. timeout 20 sec will be rounded up to 32768 msec.
The maximum timeout period is 32 sec (32768 msec.),
Get time-left isn't supported
Type 2:
Actual HW timeout is defined in sec. and it's the same as
a user-defined timeout.
Maximum timeout is 255 sec.
Get time-left is supported.
Actual HW timeout is defined in sec. and it's the same as
a user-defined timeout.
Maximum timeout is 255 sec.
Get time-left is supported.
Type 1 HW watchdog implementation exist in old systems and
all new systems have type 2 HW watchdog.
......
===================================
Berkshire Products PC Watchdog Card
===================================
Last reviewed: 10/05/2007
Berkshire Products PC Watchdog Card
Support for ISA Cards Revision A and C
Documentation and Driver by Ken Hollis <kenji@bitgate.com>
Support for ISA Cards Revision A and C
=======================================
Documentation and Driver by Ken Hollis <kenji@bitgate.com>
The PC Watchdog is a card that offers the same type of functionality that
the WDT card does, only it doesn't require an IRQ to run. Furthermore,
......@@ -33,6 +38,7 @@ Last reviewed: 10/05/2007
WDIOC_GETSUPPORT
This returns the support of the card itself. This
returns in structure "PCWDS" which returns:
options = WDIOS_TEMPPANIC
(This card supports temperature)
firmware_version = xxxx
......@@ -63,4 +69,3 @@ Last reviewed: 10/05/2007
-- Ken Hollis
(kenji@bitgate.com)
=============================
The Linux Watchdog driver API
=============================
Last reviewed: 10/05/2007
The Linux Watchdog driver API.
Copyright 2002 Christer Weingel <wingel@nano-system.com>
......@@ -10,7 +13,8 @@ driver which is (c) Copyright 2000 Jakob Oestergaard <jakob@ostenfeld.dk>
This document describes the state of the Linux 2.4.18 kernel.
Introduction:
Introduction
============
A Watchdog Timer (WDT) is a hardware circuit that can reset the
computer system in case of a software fault. You probably knew that
......@@ -30,7 +34,8 @@ drivers implement different, and sometimes incompatible, parts of it.
This file is an attempt to document the existing usage and allow
future driver writers to use it as a reference.
The simplest API:
The simplest API
================
All drivers support the basic mode of operation, where the watchdog
activates as soon as /dev/watchdog is opened and will reboot unless
......@@ -54,7 +59,8 @@ after the timeout has passed. Watchdog devices also usually support
the nowayout module parameter so that this option can be controlled at
runtime.
Magic Close feature:
Magic Close feature
===================
If a driver supports "Magic Close", the driver will not disable the
watchdog unless a specific magic character 'V' has been sent to
......@@ -64,7 +70,8 @@ will assume that the daemon (and userspace in general) died, and will
stop pinging the watchdog without disabling it first. This will then
cause a reboot if the watchdog is not re-opened in sufficient time.
The ioctl API:
The ioctl API
=============
All conforming drivers also support an ioctl API.
......@@ -73,7 +80,7 @@ Pinging the watchdog using an ioctl:
All drivers that have an ioctl interface support at least one ioctl,
KEEPALIVE. This ioctl does exactly the same thing as a write to the
watchdog device, so the main loop in the above program could be
replaced with:
replaced with::
while (1) {
ioctl(fd, WDIOC_KEEPALIVE, 0);
......@@ -82,14 +89,15 @@ replaced with:
the argument to the ioctl is ignored.
Setting and getting the timeout:
Setting and getting the timeout
===============================
For some drivers it is possible to modify the watchdog timeout on the
fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT
flag set in their option field. The argument is an integer
representing the timeout in seconds. The driver returns the real
timeout used in the same variable, and this timeout might differ from
the requested one due to limitation of the hardware.
the requested one due to limitation of the hardware::
int timeout = 45;
ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
......@@ -99,18 +107,19 @@ This example might actually print "The timeout was set to 60 seconds"
if the device has a granularity of minutes for its timeout.
Starting with the Linux 2.4.18 kernel, it is possible to query the
current timeout using the GETTIMEOUT ioctl.
current timeout using the GETTIMEOUT ioctl::
ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
printf("The timeout was is %d seconds\n", timeout);
Pretimeouts:
Pretimeouts
===========
Some watchdog timers can be set to have a trigger go off before the
actual time they will reset the system. This can be done with an NMI,
interrupt, or other mechanism. This allows Linux to record useful
information (like panic information and kernel coredumps) before it
resets.
resets::
pretimeout = 10;
ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);
......@@ -121,89 +130,113 @@ the pretimeout. So, for instance, if you set the timeout to 60 seconds
and the pretimeout to 10 seconds, the pretimeout will go off in 50
seconds. Setting a pretimeout to zero disables it.
There is also a get function for getting the pretimeout:
There is also a get function for getting the pretimeout::
ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
printf("The pretimeout was is %d seconds\n", timeout);
Not all watchdog drivers will support a pretimeout.
Get the number of seconds before reboot:
Get the number of seconds before reboot
=======================================
Some watchdog drivers have the ability to report the remaining time
before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
that returns the number of seconds before reboot.
that returns the number of seconds before reboot::
ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
printf("The timeout was is %d seconds\n", timeleft);
Environmental monitoring:
Environmental monitoring
========================
All watchdog drivers are required return more information about the system,
some do temperature, fan and power level monitoring, some can tell you
the reason for the last reboot of the system. The GETSUPPORT ioctl is
available to ask what the device can do:
available to ask what the device can do::
struct watchdog_info ident;
ioctl(fd, WDIOC_GETSUPPORT, &ident);
the fields returned in the ident struct are:
================ =============================================
identity a string identifying the watchdog driver
firmware_version the firmware version of the card if available
options a flags describing what the device supports
================ =============================================
the options field can have the following bits set, and describes what
kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can
return. [FIXME -- Is this correct?]
================ =========================
WDIOF_OVERHEAT Reset due to CPU overheat
================ =========================
The machine was last rebooted by the watchdog because the thermal limit was
exceeded
exceeded:
============== ==========
WDIOF_FANFAULT Fan failed
============== ==========
A system fan monitored by the watchdog card has failed
============= ================
WDIOF_EXTERN1 External relay 1
============= ================
External monitoring relay/source 1 was triggered. Controllers intended for
real world applications include external monitoring pins that will trigger
a reset.
============= ================
WDIOF_EXTERN2 External relay 2
============= ================
External monitoring relay/source 2 was triggered
================ =====================
WDIOF_POWERUNDER Power bad/power fault
================ =====================
The machine is showing an undervoltage status
=============== =============================
WDIOF_CARDRESET Card previously reset the CPU
=============== =============================
The last reboot was caused by the watchdog card
================ =====================
WDIOF_POWEROVER Power over voltage
================ =====================
The machine is showing an overvoltage status. Note that if one level is
under and one over both bits will be set - this may seem odd but makes
sense.
=================== =====================
WDIOF_KEEPALIVEPING Keep alive ping reply
=================== =====================
The watchdog saw a keepalive ping since it was last queried.
================ =======================
WDIOF_SETTIMEOUT Can set/get the timeout
================ =======================
The watchdog can do pretimeouts.
================ ================================
WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
================ ================================
For those drivers that return any bits set in the option field, the
GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current
status, and the status at the last reboot, respectively.
status, and the status at the last reboot, respectively::
int flags;
ioctl(fd, WDIOC_GETSTATUS, &flags);
......@@ -216,22 +249,23 @@ Note that not all devices support these two calls, and some only
support the GETBOOTSTATUS call.
Some drivers can measure the temperature using the GETTEMP ioctl. The
returned value is the temperature in degrees fahrenheit.
returned value is the temperature in degrees fahrenheit::
int temperature;
ioctl(fd, WDIOC_GETTEMP, &temperature);
Finally the SETOPTIONS ioctl can be used to control some aspects of
the cards operation.
the cards operation::
int options = 0;
ioctl(fd, WDIOC_SETOPTIONS, &options);
The following options are available:
================= ================================
WDIOS_DISABLECARD Turn off the watchdog timer
WDIOS_ENABLECARD Turn on the watchdog timer
WDIOS_TEMPPANIC Kernel panic on temperature trip
================= ================================
[FIXME -- better explanations]
===============================================
The Linux WatchDog Timer Power Management Guide
===============================================
Last reviewed: 17-Dec-2018
Wolfram Sang <wsa+renesas@sang-engineering.com>
......@@ -16,4 +18,5 @@ On resume, a watchdog timer shall be reset to its selected value to give
userspace enough time to resume. [1] [2]
[1] https://patchwork.kernel.org/patch/10252209/
[2] https://patchwork.kernel.org/patch/10711625/
============================================================
WDT Watchdog Timer Interfaces For The Linux Operating System
============================================================
Last Reviewed: 10/05/2007
WDT Watchdog Timer Interfaces For The Linux Operating System
Alan Cox <alan@lxorguk.ukuu.org.uk>
Alan Cox <alan@lxorguk.ukuu.org.uk>
ICS WDT501-P
ICS WDT501-P (no fan tachometer)
ICS WDT500-P
- ICS WDT501-P
- ICS WDT501-P (no fan tachometer)
- ICS WDT500-P
All the interfaces provide /dev/watchdog, which when open must be written
to within a timeout or the machine will reboot. Each write delays the reboot
......@@ -21,19 +24,26 @@ degrees Fahrenheit. Each read returns a single byte giving the temperature.
The third interface logs kernel messages on additional alert events.
The ICS ISA-bus wdt card cannot be safely probed for. Instead you need to
pass IO address and IRQ boot parameters. E.g.:
pass IO address and IRQ boot parameters. E.g.::
wdt.io=0x240 wdt.irq=11
Other "wdt" driver parameters are:
=========== ======================================================
heartbeat Watchdog heartbeat in seconds (default 60)
nowayout Watchdog cannot be stopped once started (kernel
build parameter)
build parameter)
tachometer WDT501-P Fan Tachometer support (0=disable, default=0)
type WDT501-P Card type (500 or 501, default=500)
=========== ======================================================
Features
--------
WDT501P WDT500P
================ ======= =======
WDT501P WDT500P
================ ======= =======
Reboot Timer X X
External Reboot X X
I/O Port Monitor o o
......@@ -42,9 +52,12 @@ Fan Speed X o
Power Under X o
Power Over X o
Overheat X o
================ ======= =======
The external event interfaces on the WDT boards are not currently supported.
Minor numbers are however allocated for it.
Example Watchdog Driver: see samples/watchdog/watchdog-simple.c
Example Watchdog Driver:
see samples/watchdog/watchdog-simple.c
......@@ -7009,7 +7009,7 @@ F: drivers/media/usb/hdpvr/
HEWLETT PACKARD ENTERPRISE ILO NMI WATCHDOG DRIVER
M: Jerry Hoemann <jerry.hoemann@hpe.com>
S: Supported
F: Documentation/watchdog/hpwdt.txt
F: Documentation/watchdog/hpwdt.rst
F: drivers/watchdog/hpwdt.c
HEWLETT-PACKARD SMART ARRAY RAID DRIVER (hpsa)
......
......@@ -18,7 +18,7 @@ menuconfig WATCHDOG
reboot the machine) and a driver for hardware watchdog boards, which
are more robust and can also keep track of the temperature inside
your computer. For details, read
<file:Documentation/watchdog/watchdog-api.txt> in the kernel source.
<file:Documentation/watchdog/watchdog-api.rst> in the kernel source.
The watchdog is usually used together with the watchdog daemon
which is available from
......@@ -1870,7 +1870,7 @@ config BOOKE_WDT
Watchdog driver for PowerPC Book-E chips, such as the Freescale
MPC85xx SOCs and the IBM PowerPC 440.
Please see Documentation/watchdog/watchdog-api.txt for
Please see Documentation/watchdog/watchdog-api.rst for
more information.
config BOOKE_WDT_DEFAULT_TIMEOUT
......@@ -2019,7 +2019,7 @@ config PCWATCHDOG
This card simply watches your kernel to make sure it doesn't freeze,
and if it does, it reboots your computer after a certain amount of
time. This driver is like the WDT501 driver but for different
hardware. Please read <file:Documentation/watchdog/pcwd-watchdog.txt>. The PC
hardware. Please read <file:Documentation/watchdog/pcwd-watchdog.rst>. The PC
watchdog cards can be ordered from <http://www.berkprod.com/>.
To compile this driver as a module, choose M here: the
......
......@@ -36,7 +36,7 @@
* mknod /dev/watchdog c 10 130
*
* For an example userspace keep-alive daemon, see:
* Documentation/watchdog/wdt.txt
* Documentation/watchdog/wdt.rst
*/
#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment