[PATCH v5 1/2] Documentation: add watchdog documentation

[PATCH v5 1/2] Documentation: add watchdog documentation

[Oleksij Rempel]

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 Documentation/user/user-manual.rst |  1 +
 Documentation/user/watchdog.rst    | 85 ++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 Documentation/user/watchdog.rst

diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index f04981c3f0..41fdb8805c 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -34,6 +34,7 @@ Contents:
    state
    random
    debugging
+   watchdog
 
 * :ref:`search`
 * :ref:`genindex`
diff --git a/Documentation/user/watchdog.rst b/Documentation/user/watchdog.rst
new file mode 100644
index 0000000000..7373b81a8d
--- /dev/null
+++ b/Documentation/user/watchdog.rst
@@ -0,0 +1,85 @@
+Watchdog Support
+================
+
+Barebox Watchdog Functionality
+------------------------------
+
+Nevertheless, in some cases we are not able to influence the hardware design
+anymore or while developing one needs to be able to feed the watchdog to
+disable it from within the bootloader. For these scenarios barebox provides the
+watchdog framework with the following functionality and at least
+``CONFIG_WATCHDOG`` should be enabled:
+
+Polling
+~~~~~~~
+
+Watchdog polling/feeding allows to feed the watchdog and keep it running on one
+side and to not reset the system on the other side. It is needed on hardware
+with short-time watchdogs. For example the Atheros ar9331 watchdog has a
+maximal timeout of 7 seconds, so it may reset even on netboot.
+Or it can be used on systems where the watchdog is already running and can't be
+disabled, an example for that is the watchdog of the i.MX2 series.
+This functionally can be seen as a threat, since in error cases barebox will
+continue to feed the watchdog even if that is not desired. So, depending on
+your needs ``CONFIG_WATCHDOG_POLLER`` can be enabled or disabled at compile
+time. Even if barebox was built with watchdog polling support, it is not
+enabled by default. To start polling from command line run:
+
+.. code-block:: console
+
+  wdog0.autoping=1
+
+The poller interval is not configurable, but fixed at 500ms and the watchdog
+timeout is configured by default to the maximum of the supported values by
+hardware. To change the timeout used by the poller, run:
+
+.. code-block:: console
+
+  wdog0.timeout_cur=7
+
+To read the current watchdog's configuration, run:
+
+.. code-block:: console
+
+  devinfo wdog0
+
+The output may look as follows where ``timeout_cur`` and ``timeout_max`` are
+measured in seconds:
+
+.. code-block:: console
+
+  barebox@DPTechnics DPT-Module:/ devinfo wdog0
+  Parameters:
+    autoping: 1 (type: bool)
+    timeout_cur: 7 (type: uint32)
+    timeout_max: 10 (type: uint32)
+
+Use barebox' environment to persist these changes between reboots:
+
+.. code-block:: console
+
+  nv dev.wdog0.autoping=1
+  nv dev.wdog0.timeout_cur=7
+
+Boot Watchdog Timeout
+~~~~~~~~~~~~~~~~~~~~~
+
+With this functionality barebox may start a watchdog or update the timeout of
+an already-running one, just before kicking the boot image. It can be
+configured temporarily via
+
+.. code-block:: console
+
+  global boot.watchdog_timeout=10
+
+or persistently by
+
+.. code-block:: console
+
+  nv boot.watchdog_timeout=10
+
+where the used value again is measured in seconds.
+
+On a system with multiple watchdogs, only the first one (wdog0) is affected by
+the ``boot.watchdog_timeout`` parameter.
+
-- 
2.23.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

[PATCH v5 2/2] doc: watchdog: add note about danger of autoping

[Oleksij Rempel]

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 Documentation/user/watchdog.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/user/watchdog.rst b/Documentation/user/watchdog.rst
index 7373b81a8d..5c671a9f26 100644
--- a/Documentation/user/watchdog.rst
+++ b/Documentation/user/watchdog.rst
@@ -29,6 +29,12 @@ enabled by default. To start polling from command line run:
 
   wdog0.autoping=1
 
+**NOTE** Using this feature might have the effect that the watchdog is
+effectively disabled. In case barebox is stuck in a loop that includes feeding
+the watchdog, then the watchdog will never trigger. Only use this feature
+during development or when a bad watchdog design (Short watchdog timeout
+enabled as boot default) doesn't give you another choice.
+
 The poller interval is not configurable, but fixed at 500ms and the watchdog
 timeout is configured by default to the maximum of the supported values by
 hardware. To change the timeout used by the poller, run:
-- 
2.23.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: [PATCH v5 1/2] Documentation: add watchdog documentation

[Ahmad Fatoum]

On 10/23/19 6:22 PM, Oleksij Rempel wrote:
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> ---
>  Documentation/user/user-manual.rst |  1 +
>  Documentation/user/watchdog.rst    | 85 ++++++++++++++++++++++++++++++
>  2 files changed, 86 insertions(+)
>  create mode 100644 Documentation/user/watchdog.rst
> 
> diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
> index f04981c3f0..41fdb8805c 100644
> --- a/Documentation/user/user-manual.rst
> +++ b/Documentation/user/user-manual.rst
> @@ -34,6 +34,7 @@ Contents:
>     state
>     random
>     debugging
> +   watchdog
>  
>  * :ref:`search`
>  * :ref:`genindex`
> diff --git a/Documentation/user/watchdog.rst b/Documentation/user/watchdog.rst
> new file mode 100644
> index 0000000000..7373b81a8d
> --- /dev/null
> +++ b/Documentation/user/watchdog.rst
> @@ -0,0 +1,85 @@
> +Watchdog Support
> +================
> +
> +Barebox Watchdog Functionality
> +------------------------------
> +
> +Nevertheless, in some cases we are not able to influence the hardware design

The Nevertheless is out of place here. I assume it's a left over from when there
was a prior paragraph,

> +anymore or while developing one needs to be able to feed the watchdog to
> +disable it from within the bootloader. For these scenarios barebox provides the
> +watchdog framework with the following functionality and at least
> +``CONFIG_WATCHDOG`` should be enabled:
> +
> +Polling
> +~~~~~~~
> +
> +Watchdog polling/feeding allows to feed the watchdog and keep it running on one
> +side and to not reset the system on the other side. It is needed on hardware
> +with short-time watchdogs. For example the Atheros ar9331 watchdog has a
> +maximal timeout of 7 seconds, so it may reset even on netboot.
> +Or it can be used on systems where the watchdog is already running and can't be
> +disabled, an example for that is the watchdog of the i.MX2 series.
> +This functionally can be seen as a threat, since in error cases barebox will
> +continue to feed the watchdog even if that is not desired. So, depending on
> +your needs ``CONFIG_WATCHDOG_POLLER`` can be enabled or disabled at compile
> +time. Even if barebox was built with watchdog polling support, it is not
> +enabled by default. To start polling from command line run:
> +
> +.. code-block:: console
> +
> +  wdog0.autoping=1
> +
> +The poller interval is not configurable, but fixed at 500ms and the watchdog
> +timeout is configured by default to the maximum of the supported values by
> +hardware. To change the timeout used by the poller, run:
> +
> +.. code-block:: console
> +
> +  wdog0.timeout_cur=7
> +
> +To read the current watchdog's configuration, run:
> +
> +.. code-block:: console
> +
> +  devinfo wdog0
> +
> +The output may look as follows where ``timeout_cur`` and ``timeout_max`` are
> +measured in seconds:
> +
> +.. code-block:: console
> +
> +  barebox@DPTechnics DPT-Module:/ devinfo wdog0
> +  Parameters:
> +    autoping: 1 (type: bool)
> +    timeout_cur: 7 (type: uint32)
> +    timeout_max: 10 (type: uint32)
> +
> +Use barebox' environment to persist these changes between reboots:
> +
> +.. code-block:: console
> +
> +  nv dev.wdog0.autoping=1
> +  nv dev.wdog0.timeout_cur=7
> +
> +Boot Watchdog Timeout
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +With this functionality barebox may start a watchdog or update the timeout of
> +an already-running one, just before kicking the boot image. It can be
> +configured temporarily via
> +
> +.. code-block:: console
> +
> +  global boot.watchdog_timeout=10
> +
> +or persistently by
> +
> +.. code-block:: console
> +
> +  nv boot.watchdog_timeout=10
> +
> +where the used value again is measured in seconds.
> +
> +On a system with multiple watchdogs, only the first one (wdog0) is affected by
> +the ``boot.watchdog_timeout`` parameter.

This is not correct.
barebox maintains a list of watchdogs ordered by probe order and then searches for
the highest priority watchdog and uses that as default. If there are multiple
watchdogs, it will take the _last_ one in the list.

You could rephrase this as:

On a system with multiple watchdogs, the highest priority watchdog is the one
affected by the ``boot.watchdog_timeout`` parameter. If multipel watchdogs
share the same priority, the order is indeterminate.

> +
> 


-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: [PATCH v5 1/2] Documentation: add watchdog documentation

[Ahmad Fatoum]

On 10/23/19 6:39 PM, Ahmad Fatoum wrote:
> On a system with multiple watchdogs, the highest priority watchdog is the one
> affected by the ``boot.watchdog_timeout`` parameter. If multipel watchdogs
> share the same priority, the order is indeterminate.

Ah, rereading it it's a bit ambiguous. How about:

On a system with multiple watchdogs, the highest priority watchdog is the one
affected by the ``boot.watchdog_timeout`` parameter. If multiple watchdogs
share the same priority, only one will be started.


-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: [PATCH v5 1/2] Documentation: add watchdog documentation

[Ahmad Fatoum]

On 10/23/19 6:45 PM, Ahmad Fatoum wrote:
> On a system with multiple watchdogs, the highest priority watchdog is the one
> affected by the ``boot.watchdog_timeout`` parameter. If multiple watchdogs
> share the same priority, only one will be started.

Oh still not correct, but wait now I got it:

On a system with multiple watchdogs, the watchdog with the highest positive
priority is the one affected by the ``boot.watchdog_timeout`` parameter.
If multiple watchdogs share the same priority, only one will be started.

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox