Skip to contentSkip to conversation

Documentation: Refactored watchdog old doc

PATCH Superseded Sunny Patel 4 participants 12 messages Apr 9 – Apr 12

Subsystems (2)

v1 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: Refactored watchdog old doc

Revisited old doc of watchdog and did some cleanup. Also added support for new api in doc.

---
 Documentation/watchdog/watchdog-api.rst | 49 +++++++++++++++++++++----
 1 file changed, 41 insertions(+), 8 deletions(-)
Documentation/watchdog/watchdog-api.rst +41 -8
index 78e228c272cf..446f961852ec 100644
@@ -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 tiemout. 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 characted '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
@@ -268,4 +288,17 @@ 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.
\ No newline at end of file
Signature · 1 line
2.43.0
reviewer
#1 lore raw
Quoted 22 lines · Sunny Patel

Revisited old doc of watchdog and did some cleanup. Also added support for new api in doc.

---
 Documentation/watchdog/watchdog-api.rst | 49 +++++++++++++++++++++----
 1 file changed, 41 insertions(+), 8 deletions(-)
Documentation/watchdog/watchdog-api.rst +1 -1
index 78e228c272cf..446f961852ec 100644
@@ -2,7 +2,7 @@
 The Linux Watchdog driver API
 =============================
 
-Last reviewed: 10/05/2007
+Last reviewed: 04/08/2026
 
 
 

Documentation/watchdog/watchdog-api.rst the requested one due to limitation of the hardware:: · line 110

Quoted 7 lines
Documentation/watchdog/watchdog-api.rst +1 -2
@@ -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::
 

These 3 printf() deletions of /was/ are included in my 5-patch series:
https://lore.kernel.org/linux-watchdog/[email protected]/

Quoted 28 lines
Documentation/watchdog/watchdog-api.rst +3 -3
     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
 	================	=======================
 

Documentation/watchdog/watchdog-api.rst The watchdog saw a keepalive ping since it was last queried. · line 237

Quoted 10 lines
Documentation/watchdog/watchdog-api.rst +4 -1
-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 tiemout. USE WDIOC_SETPRETIMEOUT and WDIOC_GETPRETIMEOUT

Use

Quoted 4 lines
Documentation/watchdog/watchdog-api.rst +4 -0
+to set/get the pretimeout.
+
+	================	================================
+	WDIOF_MAGICCLOSE	Supports magic close char

Documentation/watchdog/watchdog-api.rst The watchdog saw a keepalive ping since it was last queried. · line 251

Quoted 10 lines
Documentation/watchdog/watchdog-api.rst +10 -0
+	================	================================
+
+The driver supports the Magic Close feature, The watchdog is only disabled
+if the characted '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
+	================	================================

Documentation/watchdog/watchdog-api.rst:250: ERROR: Malformed table. Text in column margin in table line 2.

================ ================================
WDIOF_ALARMONLY Not a reboot watchdog
================ ================================

Please test your patches.

Quoted 8 lines
Documentation/watchdog/watchdog-api.rst +4 -0
+
+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

Documentation/watchdog/watchdog-api.rst The following options are available: · line 296

Quoted 10 lines
Documentation/watchdog/watchdog-api.rst +6 -1
@@ -268,4 +288,17 @@ 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

, this

Documentation/watchdog/watchdog-api.rst The following options are available: · line 303

Quoted 7 lines
Documentation/watchdog/watchdog-api.rst +7 -0
+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

driver-specific; not all

Documentation/watchdog/watchdog-api.rst The following options are available: · line 304

Quoted 2 lines
Documentation/watchdog/watchdog-api.rst +1 -0
+temperature monitoring.
\ No newline at end of file

warning: ^^^^^^^^^^^^^^^^

Signature · 1 line
~Randy
maintainer
#2 lore raw
In reply to Sunny Patel
Quoted 98 lines · Sunny Patel

Revisited old doc of watchdog and did some cleanup. Also added support for new api in doc.

---
  Documentation/watchdog/watchdog-api.rst | 49 +++++++++++++++++++++----
  1 file changed, 41 insertions(+), 8 deletions(-)
Documentation/watchdog/watchdog-api.rst +32 -8
index 78e228c272cf..446f961852ec 100644
@@ -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 tiemout. 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 characted '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
@@ -268,4 +288,17 @@ 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

Documentation/watchdog/watchdog-api.rst The following options are available: · line 304

Quoted 10 lines
Documentation/watchdog/watchdog-api.rst +9 -0
+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.
\ No newline at end of file

FWIW, I think if we update the document, all functionality not supported by the watchdog core (specifically but not necessarily limited to WDIOS_TEMPPANIC) should be declared/marked deprecated.

Guenter

#3 lore raw

PATCH v2 1/1 Documentation: Refactored watchdog old doc

Good Point. So again revisited the watchdog core api and list out the deprecated one and marked as deprecated in doc and also mentioned it just for legacy driver and not for newer one.

As someof the legacy driver still have reference to old api so just marked as deprecated in doc.

Also checked with other watchdog related api which are deprecated in driver but still present in doc but didn't find any.

---

Revisited old doc of watchdog and did some cleanup. Also added support for new api in doc. Which is WDIOF_MAGICCLOSE and WDIOF_PRETIMEOUT.

Reierate the core api and Mark WDIOC_GETTEMP and WDIO_TEMPPANIC as deprecated.Both are absent from the watchdog core and only present in legacy driver.

---
 Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++----
 1 file changed, 51 insertions(+), 8 deletions(-)
Documentation/watchdog/watchdog-api.rst +51 -8
index 78e228c272cf..e11575db93e6 100644
@@ -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 tiemout. 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 characted '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 if legacy drivers. New Drivers should not
+	implement it.
\ No newline at end of file
Signature · 1 line
2.43.0
maintainer
#4 lore raw
Quoted 5 lines · Sunny Patel

Good Point. So again revisited the watchdog core api and list out the deprecated one and marked as deprecated in doc and also mentioned it just for legacy driver and not for newer one.

Quoted 8 lines

As someof the legacy driver still have reference to old api so just marked as deprecated in doc.

Also checked with other watchdog related api which are deprecated in driver but still present in doc but didn't find any.

---

The above would show up as commit message, there is no change log, and this e-mail was sent as response to v1. And I can see that without even looking at the patch itself.

That makes me wonder what Documentation/process/submitting-patches.rst is useful for. No one seems to bother reading it. We might as well just remove it.

Guenter

maintainer
#5 lore raw
Quoted 15 lines · Guenter Roeck
Quoted 5 lines · Sunny Patel

Good Point. So again revisited the watchdog core api and list out the deprecated one and marked as deprecated in doc and also mentioned it just for legacy driver and not for newer one.

Quoted 8 lines

As someof the legacy driver still have reference to old api so just marked as deprecated in doc.

Also checked with other watchdog related api which are deprecated in driver but still present in doc but didn't find any.

---

Quoted 7 lines

The above would show up as commit message, there is no change log, and this e-mail was sent as response to v1. And I can see that without even looking at the patch itself.

That makes me wonder what Documentation/process/submitting-patches.rst is useful for. No one seems to bother reading it. We might as well just remove it.

It's good to point people at.

I do think it needs a serious rewrite to, among other things, turn it into less of an intimidating tome. On my list of things to do. Now if I could only buy a larger drive to hold that whole list...

jon

maintainer
#6 lore raw
Quoted 25 lines · Jonathan Corbet
Quoted 15 lines · Guenter Roeck
Quoted 5 lines · Sunny Patel

Good Point. So again revisited the watchdog core api and list out the deprecated one and marked as deprecated in doc and also mentioned it just for legacy driver and not for newer one.

Quoted 8 lines

As someof the legacy driver still have reference to old api so just marked as deprecated in doc.

Also checked with other watchdog related api which are deprecated in driver but still present in doc but didn't find any.

---

Quoted 7 lines

The above would show up as commit message, there is no change log, and this e-mail was sent as response to v1. And I can see that without even looking at the patch itself.

That makes me wonder what Documentation/process/submitting-patches.rst is useful for. No one seems to bother reading it. We might as well just remove it.

Quoted 6 lines

It's good to point people at.

I do think it needs a serious rewrite to, among other things, turn it into less of an intimidating tome. On my list of things to do. Now if I could only buy a larger drive to hold that whole list...

Let's have some fun:

1st AI prompt:

You are an experienced Linux kernel developer and an AI prompt expert. Read linux/Documentation/process/submitting-patches.rst and generate an AI prompt file named review.md which can be used by an AI agent to review a patch submission and determine if it follows the guidance in submitting-patches.rst.

2nd AI prompt:

Using @review.md, review the patch in index.html, which targets the repository in the linux/ directory. Provide review output in review.log.

Result is below (raw file as generated by the AI agent, not reformatted).

Guenter

---
Status: NEEDS WORK

Summary:
The patch updates the watchdog API documentation by marking deprecated ioctls and adding descriptions for features like MAGICCLOSE and PRETIMEOUT. While the technical content is useful, the patch requires revisions to the commit message and documentation text to fix typos, grammatical errors, and formatting issues.

Detailed Findings:
1. Commit Message & Description:
- The description starts with conversational filler ("Good Point. So again revisited...") which should be removed.
- The message is not written in the imperative mood (e.g., use "Mark WDIOC_GETTEMP as deprecated" instead of "Revisited... and marked...").
- Typos in the commit message: "someof" (some of), "Reierate" (Reiterate).
- The subject line "Documentation: Refactored watchdog old doc" should use the imperative mood: "Documentation: Refactor watchdog documentation".

2. Technical Content & Style:
- Several typos in the documentation text:
- "reboot tiemout" -> "reboot timeout" (Multiple occurrences).
- "characted 'V'" -> "character 'V'".
- "small number if legacy drivers" -> "small number of legacy drivers".
- Grammatical/Formatting issues:
- Missing space: "WDIOS_DISABLECARD,this" -> "WDIOS_DISABLECARD, this".
- Inconsistent capitalization: "USE WDIOC_SETPRETIMEOUT" should be "Use WDIOC_SETPRETIMEOUT".
- "New Drivers" should be "New drivers".
- The patch results in "No newline at end of file" for Documentation/watchdog/watchdog-api.rst.

3. Canonical Patch Format:
- The patch follows the basic canonical format (Subject, From, Sign-off, separators, changelog, and diffstat are all present).

Actionable Advice:
1. Rewrite the commit message to be professional and in the imperative mood. Remove any conversational references to previous discussions.
2. Perform a spell-check on the documentation changes. Specifically, fix "tiemout", "characted", and "if" (where "of" was intended).
3. Ensure proper spacing after punctuation (e.g., after the comma in the WDIOS_DISABLECARD description).
4. Add a newline at the end of Documentation/watchdog/watchdog-api.rst.
5. Use consistent sentence-case for instructions (e.g., "Use" instead of "USE").

#7 lore raw

PATCH v2 1/1 Documentation: Refactored watchdog old doc

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

---

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(-)
Documentation/watchdog/watchdog-api.rst +51 -8
index 78e228c272cf..3e9021a79671 100644
@@ -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.
Signature · 1 line
2.43.0
reviewer
#8 lore raw
Quoted 20 lines · Sunny Patel

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

---

Quoted 8 lines

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/[email protected]/

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.

Quoted 3 lines
 Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++----
 1 file changed, 51 insertions(+), 8 deletions(-)
Signature · 1 line
~Randy
maintainer
#9 lore raw
Quoted 32 lines · Randy Dunlap
Quoted 20 lines · Sunny Patel

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

---

Quoted 8 lines

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

Quoted 3 lines

However, you failed to fix a malformed table warning that I reported here:
https://lore.kernel.org/linux-doc/[email protected]/

On top of that, it should have been v3, not v2.

Guenter

Quoted 13 lines

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.

Quoted 3 lines
  Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++----
  1 file changed, 51 insertions(+), 8 deletions(-)
maintainer
#10 lore raw
Quoted 33 lines · Guenter Roeck
Quoted 32 lines · Randy Dunlap
Quoted 28 lines · Sunny Patel

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

---

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

Quoted 6 lines
Quoted 3 lines

However, you failed to fix a malformed table warning that I reported here:
https://lore.kernel.org/linux-doc/[email protected]/

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

#11 lore raw

PATCH v3 1/1 Documentation: Refactored watchdog old doc

In reply to Sunny Patel

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

---

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(-)
Documentation/watchdog/watchdog-api.rst +53 -10
index 78e228c272cf..83848d02959d 100644
@@ -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.
Signature · 1 line
2.43.0