[4/6] watchdog: Add documentation for millisecond interfaces

Message ID 20200620173351.18752-5-minyard@acm.org
State New
Headers show
Series
  • [1/6] watchdog: Allow a driver to use milliseconds instead of seconds
Related show

Commit Message

Corey Minyard June 20, 2020, 5:33 p.m.
From: Corey Minyard <cminyard@mvista.com>

Document the new interfaces and semantics of how this works.

Signed-off-by: Corey Minyard <cminyard@mvista.com>
---
 Documentation/watchdog/watchdog-api.rst       | 59 +++++++++++++++++++
 .../watchdog/watchdog-kernel-api.rst          | 30 ++++++----
 2 files changed, 78 insertions(+), 11 deletions(-)

Patch

diff --git a/Documentation/watchdog/watchdog-api.rst b/Documentation/watchdog/watchdog-api.rst
index c6c1e9fa9f73..9f9aa1cd7310 100644
--- a/Documentation/watchdog/watchdog-api.rst
+++ b/Documentation/watchdog/watchdog-api.rst
@@ -112,6 +112,39 @@  current timeout using the GETTIMEOUT ioctl::
     ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
     printf("The timeout was is %d seconds\n", timeout);
 
+There is also millisecond-level ioctls for setting timeouts in
+millisecond values.  These will work against a watchdog driver that
+only supports seconds, but values will be truncated up on setting and
+truncated on fetching.  So, for instance:
+
+    int timeout = 44001;
+    ioctl(fd, WDIOC_SETTIMEOUT_MS, &timeout);
+    printf("The timeout was set to %d milliseconds\n", timeout);
+
+If the driver only supports seconds, the timeout will be set to 45
+seconds because it's truncated up.
+
+Fetching does similar conversions.  On a driver that supports
+milliseconds, if the current value is 39603 milliseconds:
+
+    ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
+    printf("The timeout was is %d seconds\n", timeout);
+    ioctl(fd, WDIOC_GETTIMEOUT_MS, &timeout);
+    printf("The timeout was is %d milliseconds\n", timeout);
+
+will print 39 seconds and 39603 milliseconds.
+
+If a driver supports millisecond level precision, it will have the
+WDIOF_MSECTIMER flag set in its option field.  Note that does not mean
+that the driver has millisecond level accuracy.  For instance, a
+device might have a 10Hz clock, giving 100ms accuracy.  The driver
+should set the return timeout for WDIOC_SETTIMEOUT_MS to the actual
+setting of the timeout, so you can verify the value.
+
+It would be nice to have a granularity field, but some devices may not
+be linear.  So a granularity is not a general thing that could be
+done.
+
 Pretimeouts
 ===========
 
@@ -137,6 +170,16 @@  There is also a get function for getting the pretimeout::
 
 Not all watchdog drivers will support a pretimeout.
 
+Like timeouts, pretimeouts also have millisecond-level ioctls:
+
+    pretimeout = 10000;
+    ioctl(fd, WDIOC_SETPRETIMEOUT_MS, &pretimeout);
+    ioctl(fd, WDIOC_GETPRETIMEOUT_NS, &pretimeout);
+    printf("The pretimeout was is %d milliseconds\n", pretimeout);
+
+These work just like the timeouts, see that discussion for how
+conversions are done.
+
 Get the number of seconds before reboot
 =======================================
 
@@ -147,6 +190,14 @@  that returns the number of seconds before reboot::
     ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
     printf("The timeout was is %d seconds\n", timeleft);
 
+There is also a millisecond-level version:
+
+    ioctl(fd, WDIOC_GETTIMELEFT_MS, &timeleft);
+    printf("The timeout was is %d milliseconds\n", timeleft);
+
+If the driver only supports seconds, then the value returns is just
+1000 times the seconds value.
+
 Environmental monitoring
 ========================
 
@@ -223,6 +274,14 @@  sense.
 
 The watchdog saw a keepalive ping since it was last queried.
 
+	===============		========================================
+	WDIOF_MSECTIMER		Driver can use milliseconds for timeouts
+	===============		========================================
+
+The driver can do millisecond-level timeouts.  The seconds-level
+interfaces still work, but setting values in milliseconds can result
+in finer granularity.
+
 	================	=======================
 	WDIOF_SETTIMEOUT	Can set/get the timeout
 	================	=======================
diff --git a/Documentation/watchdog/watchdog-kernel-api.rst b/Documentation/watchdog/watchdog-kernel-api.rst
index 068a55ee0d4a..bee60e6ae274 100644
--- a/Documentation/watchdog/watchdog-kernel-api.rst
+++ b/Documentation/watchdog/watchdog-kernel-api.rst
@@ -80,13 +80,13 @@  It contains following fields:
   additional information about the watchdog timer itself. (Like it's unique name)
 * ops: a pointer to the list of watchdog operations that the watchdog supports.
 * gov: a pointer to the assigned watchdog device pretimeout governor or NULL.
-* timeout: the watchdog timer's timeout value (in seconds).
+* timeout: the watchdog timer's timeout value.
   This is the time after which the system will reboot if user space does
   not send a heartbeat request if WDOG_ACTIVE is set.
-* pretimeout: the watchdog timer's pretimeout value (in seconds).
-* min_timeout: the watchdog timer's minimum timeout value (in seconds).
+* pretimeout: the watchdog timer's pretimeout value.
+* min_timeout: the watchdog timer's minimum timeout value.
   If set, the minimum configurable value for 'timeout'.
-* max_timeout: the watchdog timer's maximum timeout value (in seconds),
+* max_timeout: the watchdog timer's maximum timeout value,
   as seen from userspace. If set, the maximum configurable value for
   'timeout'. Not used if max_hw_heartbeat_ms is non-zero.
 * min_hw_heartbeat_ms: Hardware limit for minimum time between heartbeats,
@@ -96,7 +96,7 @@  It contains following fields:
   If set, the infrastructure will send heartbeats to the watchdog driver
   if 'timeout' is larger than max_hw_heartbeat_ms, unless WDOG_ACTIVE
   is set and userspace failed to send a heartbeat for at least 'timeout'
-  seconds. max_hw_heartbeat_ms must be set if a driver does not implement
+  time. max_hw_heartbeat_ms must be set if a driver does not implement
   the stop function.
 * reboot_nb: notifier block that is registered for reboot notifications, for
   internal use only. If the driver calls watchdog_stop_on_reboot, watchdog core
@@ -117,6 +117,13 @@  It contains following fields:
 * deferred: entry in wtd_deferred_reg_list which is used to
   register early initialized watchdogs.
 
+The time value used to interact with the device can either be in
+seconds or milli-seconds except for min_hw_heartbeat_ms and
+max_hw_heartbeat_ms, which are always in milli-seconds. If the driver
+sets WDIOF_MSECTIMER in the driver info flags, then the time values
+will be in milli-seconds. If it is not set, then the time values will
+be in seconds.
+
 The list of watchdog operations is defined as::
 
   struct watchdog_ops {
@@ -212,12 +219,13 @@  they are supported. These optional routines/operations are:
   also take care of checking if pretimeout is still valid and set up the timer
   accordingly. This can't be done in the core without races, so it is the
   duty of the driver.
-* set_pretimeout: this routine checks and changes the pretimeout value of
-  the watchdog. It is optional because not all watchdogs support pretimeout
-  notification. The timeout value is not an absolute time, but the number of
-  seconds before the actual timeout would happen. It returns 0 on success,
-  -EINVAL for "parameter out of range" and -EIO for "could not write value to
-  the watchdog". A value of 0 disables pretimeout notification.
+* set_pretimeout: this routine checks and changes the pretimeout value
+  of the watchdog. It is optional because not all watchdogs support
+  pretimeout notification. The timeout value is not an absolute time,
+  but the time before the actual timeout would happen. It returns 0 on
+  success, -EINVAL for "parameter out of range" and -EIO for "could
+  not write value to the watchdog". A value of 0 disables pretimeout
+  notification.
 
   (Note: the WDIOF_PRETIMEOUT needs to be set in the options field of the
   watchdog's info structure).