Commit 74665686 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Wim Van Sebroeck
Browse files

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 avatarGuenter Roeck <linux@roeck-us.net>
Signed-off-by: default avatarWim Van Sebroeck <wim@linux-watchdog.org>
parent c2eac35b

Documentation/admin-guide/kernel-parameters.txt

+1 −1
Original line number Original line Diff line number Diff line
@@ -5162,7 +5162,7 @@ 
			Default: 3 = cyan.

			Default: 3 = cyan.





	watchdog timers	[HW,WDT] For information on watchdog timers,

	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

			or other driver-specific files in the

			Documentation/watchdog/ directory.

			Documentation/watchdog/ directory.

Documentation/kernel-per-CPU-kthreads.txt

+1 −1
Original line number Original line Diff line number Diff line
@@ -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

2.	Boot with "nosoftlockup=0", which will also prevent these kthreads

	from being created.  Other related watchdog and softlockup boot

	from being created.  Other related watchdog and softlockup boot

	parameters may be found in Documentation/admin-guide/kernel-parameters.rst

	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

3.	Echo a zero to /proc/sys/kernel/watchdog to disable the

	watchdog timer.

	watchdog timer.

4.	Echo a large number of /proc/sys/kernel/watchdog_thresh in

4.	Echo a large number of /proc/sys/kernel/watchdog_thresh in

Documentation/watchdog/convert_drivers_to_kernel_api.txt→Documentation/watchdog/convert_drivers_to_kernel_api.rst

+55 −54
Original line number Original line Diff line number Diff line 
=========================================================

Converting old watchdog drivers to the watchdog framework

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

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

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.

components, those drivers can be lightened making it a user of the framework.
@@ -69,7 +71,7 @@ Here is a overview of the functions and probably needed actions: 
  -ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error

  -ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error

  is directly given to the user.

  is directly given to the user.





Example conversion:

Example conversion::





  -static const struct file_operations s3c2410wdt_fops = {

  -static const struct file_operations s3c2410wdt_fops = {

  -       .owner          = THIS_MODULE,

  -       .owner          = THIS_MODULE,
@@ -89,7 +91,7 @@ Remove the miscdevice 




Since the file_operations are gone now, you can also remove the 'struct

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

miscdevice'. The framework will create it on watchdog_dev_register() called by

watchdog_register_device().

watchdog_register_device()::





  -static struct miscdevice s3c2410wdt_miscdev = {

  -static struct miscdevice s3c2410wdt_miscdev = {

  -       .minor          = WATCHDOG_MINOR,

  -       .minor          = WATCHDOG_MINOR,
@@ -102,7 +104,7 @@ Remove obsolete includes and defines 
------------------------------------

------------------------------------





Because of the simplifications, a few defines are probably unused now. Remove

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/fs.h>

  - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)

  - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
@@ -121,7 +123,7 @@ change the function header. Other changes are most likely not needed, because 
here simply happens the direct hardware access. If you have device-specific

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.

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

  +static struct watchdog_ops s3c2410wdt_ops = {

  +       .owner = THIS_MODULE,

  +       .owner = THIS_MODULE,
@@ -131,7 +133,7 @@ Here is a simple example: 
  +       .set_timeout = s3c2410wdt_set_heartbeat,

  +       .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 void s3c2410wdt_keepalive(void)

  +static int s3c2410wdt_keepalive(struct watchdog_device *wdd)

  +static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
@@ -159,7 +161,7 @@ static variables. Those have to be converted to use the members in 
watchdog_device. Note that the timeout values are unsigned int. Some drivers

watchdog_device. Note that the timeout values are unsigned int. Some drivers

use signed int, so this has to be converted, too.

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

  +static struct watchdog_device s3c2410_wdd = {

  +       .info = &s3c2410_wdt_ident,

  +       .info = &s3c2410_wdt_ident,
@@ -173,12 +175,12 @@ Handle the 'nowayout' feature 
A few drivers use nowayout statically, i.e. there is no module parameter for it

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

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

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,

        .status = WATCHDOG_NOWAYOUT_INIT_STATUS,





Most drivers, however, also allow runtime configuration of nowayout, usually

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);

	watchdog_set_nowayout(&s3c2410_wdd, nowayout);
@@ -191,7 +193,7 @@ Register the watchdog device 




Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev).

Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev).

Make sure the return value gets checked and the error message, if present,

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 = misc_register(&s3c2410wdt_miscdev);

  +       ret = watchdog_register_device(&s3c2410_wdd);

  +       ret = watchdog_register_device(&s3c2410_wdd);
@@ -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

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 :)
 
linux-watchdog@vger.kernel.org. We are looking forward to it :)

Documentation/watchdog/hpwdt.txt→Documentation/watchdog/hpwdt.rst

+16 −9
Original line number Original line Diff line number Diff line 
Last reviewed: 08/20/2018

===========================



HPE iLO NMI Watchdog Driver

HPE iLO NMI Watchdog Driver

===========================



for iLO based ProLiant Servers

for iLO based ProLiant Servers

==============================



Last reviewed: 08/20/2018







 The HPE iLO NMI Watchdog driver is a kernel module that provides basic

 The HPE iLO NMI Watchdog driver is a kernel module that provides basic

 watchdog functionality and handler for the iLO "Generate NMI to System"

 watchdog functionality and handler for the iLO "Generate NMI to System"
@@ -20,15 +25,16 @@ Last reviewed: 08/20/2018 




 The hpwdt driver also has the following module parameters:

 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.

               Default value is 30 seconds.

 timeout     - an alias of soft_margin.

 timeout       an alias of soft_margin.

 pretimeout  - allows the user to set the watchdog pretimeout value.

 pretimeout    allows the user to set the watchdog pretimeout value.

               This is the number of seconds before timeout when an

               This is the number of seconds before timeout when an

               NMI is delivered to the system. Setting the value to

               NMI is delivered to the system. Setting the value to

               zero disables the pretimeout NMI.

               zero disables the pretimeout NMI.

               Default value is 9 seconds.

               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.

               be restarted or an impending ASR to be escaped.

               Default value is set when compiling the kernel. If it is set

               Default value is set when compiling the kernel. If it is set

               to "Y", then there is no way of disabling the watchdog once

               to "Y", then there is no way of disabling the watchdog once
@@ -37,10 +43,12 @@ Last reviewed: 08/20/2018 
               before calling panic. (-1) disables the watchdog.  When value

               before calling panic. (-1) disables the watchdog.  When value

               is > 0, the timer is reprogrammed with the greater of

               is > 0, the timer is reprogrammed with the greater of

               value or current timeout value.

               value or current timeout value.

 ============  ================================================================





 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

       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,

 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

 can only be set to 9 seconds.  Attempts to set pretimeout to other
@@ -67,4 +75,3 @@ Last reviewed: 08/20/2018 




 The HPE iLO NMI Watchdog Driver and documentation were originally developed

 The HPE iLO NMI Watchdog Driver and documentation were originally developed

 by Tom Mingarelli.
 
 by Tom Mingarelli.

Documentation/watchdog/index.rst

0 → 100644
+25 −0
Original line number Original line Diff line number Diff line 
: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`

CRA Git | Maintained and supported by SUSTech CRA and CCSE