Re: [PATCH] Documentation: Refactored watchdog old doc

[Randy Dunlap]

On 4/9/26 10:53 AM, Sunny Patel wrote:
> Revisited old doc of watchdog and did some cleanup.
> Also added support for new api in doc.
> 
> Signed-off-by: Sunny Patel <nueralspacetech@xxxxxxxxx>
> ---
>  Documentation/watchdog/watchdog-api.rst | 49 +++++++++++++++++++++----
>  1 file changed, 41 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/watchdog/watchdog-api.rst b/Documentation/watchdog/watchdog-api.rst
> index 78e228c272cf..446f961852ec 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::
>  

These 3 printf() deletions of /was/ are included in my 5-patch series:
https://lore.kernel.org/linux-watchdog/20260228010402.2389343-1-rdunlap@xxxxxxxxxxxxx/


>      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

                              Use

> +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
> +	================	================================

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.

> +
> +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

                                               , this

> +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

> +temperature monitoring.
> \ No newline at end of file

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

-- 
~Randy