Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++---- 1 file changed, 51 insertions(+), 8 deletions(-)
Mark WDIOC_GETTEMP and WDIOS_TEMPPANIC as deprecated since
neither is implemented by the watchdog core and both are only
present in a small number of legacy drivers.
Add documentation for previously undocumented status bits
WDIOF_MAGICCLOSE and WDIOF_ALARMONLY in the options field.
Add documentation for WDIOF_PRETIMEOUT and WDIOF_SETTIMEOUT
status bits describing their respective ioctls.
Fix the following issues in existing documentation:
- Remove version-specific reference to Linux 2.4.18 from
the GETTIMEOUT ioctl description
- Fix duplicate "was is" in printf format strings
- Replace [FIXME] placeholder with proper descriptions for
WDIOS_DISABLECARD, WDIOS_ENABLECARD and WDIOS_TEMPPANIC
Signed-off-by: Sunny Patel <nueralspacetech@gmail.com>
---
Changes in v2:
- Fixed typos: "tiemout" -> "timeout", "characted" -> "character"
- Fixed "small number if legacy" -> "of legacy"
- Fixed capitalization: "New Drivers" -> "New drivers", "USE" -> "Use"
- Fixed spacing: "WDIOS_DISABLECARD,this" -> "WDIOS_DISABLECARD, this"
- Fixed double spaces in two places
- Added missing newline at end of file
- Rewrote commit message
Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++----
1 file changed, 51 insertions(+), 8 deletions(-)
diff --git a/Documentation/watchdog/watchdog-api.rst b/Documentation/watchdog/watchdog-api.rst
index 78e228c272cf..3e9021a79671 100644
--- a/Documentation/watchdog/watchdog-api.rst
+++ b/Documentation/watchdog/watchdog-api.rst
@@ -2,7 +2,7 @@
The Linux Watchdog driver API
=============================
-Last reviewed: 10/05/2007
+Last reviewed: 04/08/2026
@@ -106,11 +106,10 @@ the requested one due to limitation of the hardware::
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::
+It is also possible to get the current timeout with the GETTIMEOUT ioctl::
ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
- printf("The timeout was is %d seconds\n", timeout);
+ printf("The timeout is %d seconds\n", timeout);
Pretimeouts
===========
@@ -133,7 +132,7 @@ seconds. Setting a pretimeout to zero disables it.
There is also a get function for getting the pretimeout::
ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
- printf("The pretimeout was is %d seconds\n", timeout);
+ printf("The pretimeout is %d seconds\n", timeout);
Not all watchdog drivers will support a pretimeout.
@@ -145,7 +144,7 @@ before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
that returns the number of seconds before reboot::
ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
- printf("The timeout was is %d seconds\n", timeleft);
+ printf("The timeout is %d seconds\n", timeleft);
Environmental monitoring
========================
@@ -227,12 +226,33 @@ The watchdog saw a keepalive ping since it was last queried.
WDIOF_SETTIMEOUT Can set/get the timeout
================ =======================
-The watchdog can do pretimeouts.
+The watchdog supports timeout set/get via the WDIOC_SETTIMEOUT and
+WDIOC_GETTIMEOUT ioctls.
================ ================================
WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
================ ================================
+The watchdog supports a pretimeout, a warning interrupt that fires before
+the actual reboot timeout. Use WDIOC_SETPRETIMEOUT and WDIOC_GETPRETIMEOUT
+to set/get the pretimeout.
+
+ ================ ================================
+ WDIOF_MAGICCLOSE Supports magic close char
+ ================ ================================
+
+The driver supports the Magic Close feature, The watchdog is only disabled
+if the character 'V' is written to /dev/watchdog before the file descriptor
+is closed. Without this, closing the device disables the watchdog
+unconditionally.
+
+ ================ ================================
+ WDIOF_ALARMONLY Not a reboot watchdog
+ ================ ================================
+
+The watchdog will not reboot the system when it expires. Instead it
+triggers a management or other external alarm. Userspace should not
+rely on a system reboot occurring.
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
@@ -254,6 +274,11 @@ returned value is the temperature in degrees Fahrenheit::
int temperature;
ioctl(fd, WDIOC_GETTEMP, &temperature);
+.. deprecated::
+ ``WDIOC_GETTEMP`` is not implemented by the watchdog core. It is only
+ supported by a small number of legacy drivers. New drivers should not
+ implement it.
+
Finally the SETOPTIONS ioctl can be used to control some aspects of
the cards operation::
@@ -268,4 +293,22 @@ The following options are available:
WDIOS_TEMPPANIC Kernel panic on temperature trip
================= ================================
-[FIXME -- better explanations]
+``WDIOS_DISABLECARD`` stops the watchdog timer. The driver will cease
+pinging the hardware watchdog, allowing a controlled shutdown without
+a forced reboot. This is equivalent to the watchdog being disarmed.
+
+``WDIOS_ENABLECARD`` starts the watchdog timer. If the watchdog was
+previously stopped via ``WDIOS_DISABLECARD``, this will re-enable it. The
+hardware watchdog will begin counting down from the configured timeout.
+
+``WDIOS_TEMPPANIC`` enables temperature-based kernel panic. When set,
+the driver will call ``panic()`` (or ``kernel_power_off()`` on some
+drivers) if the hardware temperature sensor exceeds its threshold,
+rather than only setting the ``WDIOF_OVERHEAT`` status bit. Support
+for this option is driver-specific, not all watchdog drivers implement
+temperature monitoring.
+
+.. deprecated::
+ ``WDIOS_TEMPPANIC`` is not implemented by the watchdog core and is only
+ present in a small number of legacy drivers. New drivers should not
+ implement it.
--
2.43.0On 4/11/26 8:09 AM, Sunny Patel wrote: > Mark WDIOC_GETTEMP and WDIOS_TEMPPANIC as deprecated since > neither is implemented by the watchdog core and both are only > present in a small number of legacy drivers. > > Add documentation for previously undocumented status bits > WDIOF_MAGICCLOSE and WDIOF_ALARMONLY in the options field. > > Add documentation for WDIOF_PRETIMEOUT and WDIOF_SETTIMEOUT > status bits describing their respective ioctls. > > Fix the following issues in existing documentation: > - Remove version-specific reference to Linux 2.4.18 from > the GETTIMEOUT ioctl description > - Fix duplicate "was is" in printf format strings > - Replace [FIXME] placeholder with proper descriptions for > WDIOS_DISABLECARD, WDIOS_ENABLECARD and WDIOS_TEMPPANIC > > Signed-off-by: Sunny Patel <nueralspacetech@gmail.com> > --- > > Changes in v2: > - Fixed typos: "tiemout" -> "timeout", "characted" -> "character" > - Fixed "small number if legacy" -> "of legacy" > - Fixed capitalization: "New Drivers" -> "New drivers", "USE" -> "Use" > - Fixed spacing: "WDIOS_DISABLECARD,this" -> "WDIOS_DISABLECARD, this" > - Fixed double spaces in two places > - Added missing newline at end of file > - Rewrote commit message However, you failed to fix a malformed table warning that I reported here: https://lore.kernel.org/linux-doc/9e3403a0-4ec2-4fbe-a50f-53f939c1d841@infradead.org/ Documentation/watchdog/watchdog-api.rst:250: ERROR: Malformed table. Text in column margin in table line 2. ================ ================================ WDIOF_ALARMONLY Not a reboot watchdog ================ ================================ So I repeat, please test your patches. > > Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++---- > 1 file changed, 51 insertions(+), 8 deletions(-) -- ~Randy
On 4/11/26 10:22, Randy Dunlap wrote: > > > On 4/11/26 8:09 AM, Sunny Patel wrote: >> Mark WDIOC_GETTEMP and WDIOS_TEMPPANIC as deprecated since >> neither is implemented by the watchdog core and both are only >> present in a small number of legacy drivers. >> >> Add documentation for previously undocumented status bits >> WDIOF_MAGICCLOSE and WDIOF_ALARMONLY in the options field. >> >> Add documentation for WDIOF_PRETIMEOUT and WDIOF_SETTIMEOUT >> status bits describing their respective ioctls. >> >> Fix the following issues in existing documentation: >> - Remove version-specific reference to Linux 2.4.18 from >> the GETTIMEOUT ioctl description >> - Fix duplicate "was is" in printf format strings >> - Replace [FIXME] placeholder with proper descriptions for >> WDIOS_DISABLECARD, WDIOS_ENABLECARD and WDIOS_TEMPPANIC >> >> Signed-off-by: Sunny Patel <nueralspacetech@gmail.com> >> --- >> >> Changes in v2: >> - Fixed typos: "tiemout" -> "timeout", "characted" -> "character" >> - Fixed "small number if legacy" -> "of legacy" >> - Fixed capitalization: "New Drivers" -> "New drivers", "USE" -> "Use" >> - Fixed spacing: "WDIOS_DISABLECARD,this" -> "WDIOS_DISABLECARD, this" >> - Fixed double spaces in two places >> - Added missing newline at end of file >> - Rewrote commit message > > However, you failed to fix a malformed table warning that I reported here: > https://lore.kernel.org/linux-doc/9e3403a0-4ec2-4fbe-a50f-53f939c1d841@infradead.org/ > On top of that, it should have been v3, not v2. Guenter > Documentation/watchdog/watchdog-api.rst:250: ERROR: Malformed table. > Text in column margin in table line 2. > > ================ ================================ > WDIOF_ALARMONLY Not a reboot watchdog > ================ ================================ > > > So I repeat, please test your patches. > >> >> Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++---- >> 1 file changed, 51 insertions(+), 8 deletions(-)
On 4/11/26 12:07, Guenter Roeck wrote: > On 4/11/26 10:22, Randy Dunlap wrote: >> >> >> On 4/11/26 8:09 AM, Sunny Patel wrote: >>> Mark WDIOC_GETTEMP and WDIOS_TEMPPANIC as deprecated since >>> neither is implemented by the watchdog core and both are only >>> present in a small number of legacy drivers. >>> >>> Add documentation for previously undocumented status bits >>> WDIOF_MAGICCLOSE and WDIOF_ALARMONLY in the options field. >>> >>> Add documentation for WDIOF_PRETIMEOUT and WDIOF_SETTIMEOUT >>> status bits describing their respective ioctls. >>> >>> Fix the following issues in existing documentation: >>> - Remove version-specific reference to Linux 2.4.18 from >>> the GETTIMEOUT ioctl description >>> - Fix duplicate "was is" in printf format strings >>> - Replace [FIXME] placeholder with proper descriptions for >>> WDIOS_DISABLECARD, WDIOS_ENABLECARD and WDIOS_TEMPPANIC >>> >>> Signed-off-by: Sunny Patel <nueralspacetech@gmail.com> >>> --- >>> >>> Changes in v2: >>> - Fixed typos: "tiemout" -> "timeout", "characted" -> "character" >>> - Fixed "small number if legacy" -> "of legacy" >>> - Fixed capitalization: "New Drivers" -> "New drivers", "USE" -> "Use" >>> - Fixed spacing: "WDIOS_DISABLECARD,this" -> "WDIOS_DISABLECARD, this" >>> - Fixed double spaces in two places >>> - Added missing newline at end of file >>> - Rewrote commit message >> >> However, you failed to fix a malformed table warning that I reported here: >> https://lore.kernel.org/linux-doc/9e3403a0-4ec2-4fbe-a50f-53f939c1d841@infradead.org/ >> > > On top of that, it should have been v3, not v2. > On top of that, again, it was sent as response to the previous patch. There is also some Sashiko feedback: https://sashiko.dev/#/patchset/20260411150922.20536-1-nueralspacetech%40gmail.com Guenter
Mark WDIOC_GETTEMP and WDIOS_TEMPPANIC as deprecated since
neither is implemented by the watchdog core and both are only
present in a small number of legacy drivers.
Add documentation for previously undocumented status bits
WDIOF_MAGICCLOSE and WDIOF_ALARMONLY in the options field.
Add documentation for WDIOF_PRETIMEOUT and WDIOF_SETTIMEOUT
status bits describing their respective ioctls.
Fix the following issues in existing documentation:
- Remove version-specific reference to Linux 2.4.18 from
the GETTIMEOUT ioctl description
- Fix duplicate "was is" in printf format strings
- Replace [FIXME] placeholder with proper descriptions for
WDIOS_DISABLECARD, WDIOS_ENABLECARD and WDIOS_TEMPPANIC
Signed-off-by: Sunny Patel <nueralspacetech@gmail.com>
---
Changes in v3:
- Replaced .. deprecated:: with .. note:: to avoid Sphinx
build warning due to missing version argument
- Fixed WDIOF_MAGICCLOSE description: corrected inverted
behaviour — without 'V', watchdog remains active and
reboots, it does not disable unconditionally
- Fixed comma splice: "Magic Close feature, The" ->
"Magic Close feature. The"
- Fixed WDIOF_ALARMONLY table alignment (malformed table)
- Fixed "driver-specific," -> "driver-specific;" (semicolon)
- Fixed identity row indentation in watchdog_info table
Note: This is sent as v3 and not v4. The previous submission
was v2 and this directly addresses the review comments on it.
The version was not bumped to v4 to keep the revision history
consistent with the actual number of review cycles this patch
has gone through.
Documentation/watchdog/watchdog-api.rst | 63 +++++++++++++++++++++----
1 file changed, 53 insertions(+), 10 deletions(-)
diff --git a/Documentation/watchdog/watchdog-api.rst b/Documentation/watchdog/watchdog-api.rst
index 78e228c272cf..83848d02959d 100644
--- a/Documentation/watchdog/watchdog-api.rst
+++ b/Documentation/watchdog/watchdog-api.rst
@@ -2,7 +2,7 @@
The Linux Watchdog driver API
=============================
-Last reviewed: 10/05/2007
+Last reviewed: 04/08/2026
@@ -42,7 +42,7 @@ activates as soon as /dev/watchdog is opened and will reboot unless
the watchdog is pinged within a certain time, this time is called the
timeout or margin. The simplest way to ping the watchdog is to write
some data to the device. So a very simple watchdog daemon would look
-like this source file: see samples/watchdog/watchdog-simple.c
+like this source file: see samples/watchdog/watchdog-simple.c
A more advanced driver could for example check that a HTTP server is
still responding before doing the write call to ping the watchdog.
@@ -106,11 +106,10 @@ the requested one due to limitation of the hardware::
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::
+It is also possible to get the current timeout with the GETTIMEOUT ioctl::
ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
- printf("The timeout was is %d seconds\n", timeout);
+ printf("The timeout is %d seconds\n", timeout);
Pretimeouts
===========
@@ -133,7 +132,7 @@ seconds. Setting a pretimeout to zero disables it.
There is also a get function for getting the pretimeout::
ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
- printf("The pretimeout was is %d seconds\n", timeout);
+ printf("The pretimeout is %d seconds\n", timeout);
Not all watchdog drivers will support a pretimeout.
@@ -145,12 +144,12 @@ before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
that returns the number of seconds before reboot::
ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
- printf("The timeout was is %d seconds\n", timeleft);
+ printf("The timeout is %d seconds\n", timeleft);
Environmental monitoring
========================
-All watchdog drivers are required return more information about the system,
+All watchdog drivers are required to 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::
@@ -227,12 +226,33 @@ The watchdog saw a keepalive ping since it was last queried.
WDIOF_SETTIMEOUT Can set/get the timeout
================ =======================
-The watchdog can do pretimeouts.
+The watchdog supports timeout set/get via the WDIOC_SETTIMEOUT and
+WDIOC_GETTIMEOUT ioctls.
================ ================================
WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
================ ================================
+The watchdog supports a pretimeout, a warning interrupt that fires before
+the actual reboot timeout. Use WDIOC_SETPRETIMEOUT and WDIOC_GETPRETIMEOUT
+to set/get the pretimeout.
+
+ ================ ================================
+ WDIOF_MAGICCLOSE Supports magic close char
+ ================ ================================
+
+The driver supports the Magic Close feature. The watchdog is only disabled
+if the character 'V' is written to /dev/watchdog before the file descriptor
+is closed. Without writing 'V' before closing, the watchdog remains active
+and will trigger a reboot after the timeout expires.
+
+ ================ ================================
+ WDIOF_ALARMONLY Not a reboot watchdog
+ ================ ================================
+
+The watchdog will not reboot the system when it expires. Instead it
+triggers a management or other external alarm. Userspace should not
+rely on a system reboot occurring.
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
@@ -254,6 +274,11 @@ returned value is the temperature in degrees Fahrenheit::
int temperature;
ioctl(fd, WDIOC_GETTEMP, &temperature);
+.. note::
+ ``WDIOC_GETTEMP`` is not implemented by the watchdog core and is
+ considered deprecated. It is only supported by a small number of
+ legacy drivers. New drivers should not implement it.
+
Finally the SETOPTIONS ioctl can be used to control some aspects of
the cards operation::
@@ -268,4 +293,22 @@ The following options are available:
WDIOS_TEMPPANIC Kernel panic on temperature trip
================= ================================
-[FIXME -- better explanations]
+``WDIOS_DISABLECARD`` stops the watchdog timer. The driver will cease
+pinging the hardware watchdog, allowing a controlled shutdown without
+a forced reboot. This is equivalent to the watchdog being disarmed.
+
+``WDIOS_ENABLECARD`` starts the watchdog timer. If the watchdog was
+previously stopped via ``WDIOS_DISABLECARD``, this will re-enable it. The
+hardware watchdog will begin counting down from the configured timeout.
+
+``WDIOS_TEMPPANIC`` enables temperature-based kernel panic. When set,
+the driver will call ``panic()`` (or ``kernel_power_off()`` on some
+drivers) if the hardware temperature sensor exceeds its threshold,
+rather than only setting the ``WDIOF_OVERHEAT`` status bit. Support
+for this option is driver-specific; not all watchdog drivers implement
+temperature monitoring.
+
+.. note::
+ ``WDIOS_TEMPPANIC`` is not implemented by the watchdog core and is
+ considered deprecated. It is only present in a small number of
+ legacy drivers. New drivers should not implement it.
--
2.43.0
© 2016 - 2026 Red Hat, Inc.