[PATCH 0/8] Bootchooser Documentation Update

[PATCH 0/8] Bootchooser Documentation Update

[Enrico Jorns]

This is a collection of some documentation updates, fixes and
clarifications for the bootchooser framework.

Enrico Jorns (8):
  doc: bootchooser: fix typos etc.
  doc: bootchooser: explicitly note configuration vs. storage backend
  doc: bootchooser: be more explicit what bootchooser.state_prefix is
    for
  doc: bootchooser: be more explicit about attempts reset on successful
    boot
  doc: bootchooser: note how to actually start the bootchooser
  doc: bootchooser: be more explicit about when the bootchooser
    terminates
  doc: bootchooser: add details about bootchooser.reset_attempts
    handling
  doc: bootchooser: add retry handling to algorithm description

 Documentation/user/bootchooser.rst | 94 +++++++++++++++++++++++-------
 1 file changed, 72 insertions(+), 22 deletions(-)

-- 
2.20.1


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

[PATCH 1/8] doc: bootchooser: fix typos etc.

[Enrico Jorns]

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 05725d8f21..667ab7d736 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -3,7 +3,7 @@
 Barebox Bootchooser
 ===================
 
-In many cases embedded systems are layed out redundantly with multiple
+In many cases embedded systems are laid out redundantly with multiple
 kernels and multiple root file systems. The *bootchooser* framework provides
 the building blocks to model different use cases without the need to start
 from scratch over and over again.
@@ -60,7 +60,7 @@ the boot target won't be booted anymore. To prevent that, the ``remaining_attemp
 counter must be reset to its default. There are different flags in the
 *bootchooser* which control resetting the ``remaining_attempts`` counter,
 controlled by the ``global.bootchooser.reset_attempts`` variable. It holds a
-list of space separated flags. Possible values are:
+list of space-separated flags. Possible values are:
 
 - empty: counters will never be reset
 - ``power-on``: The ``remaining_attempts`` counters of all enabled boot targets are reset
@@ -97,7 +97,7 @@ options not specific to any boot target.
 ``global.bootchooser.reset_attempts``
   Already described in :ref:`Bootchooser Algorithm <bootchooser,algorithm>`
 ``global.bootchooser.reset_priorities``
-  A space separated list of events that cause *bootchooser* to reset the priorities of
+  A space-separated list of events that cause *bootchooser* to reset the priorities of
   all boot targets. Possible values:
 
   * empty: priorities will never be reset
@@ -111,7 +111,7 @@ options not specific to any boot target.
   Variable prefix when *bootchooser* is used with the *state* framework as backend
   for storing run-time data, see below.
 ``global.bootchooser.targets``
-  Space separated list of boot targets that are used. For each entry in the list
+  Space-separated list of boot targets that are used. For each entry in the list
   a corresponding
   set of ``global.bootchooser.<targetname>.<variablename>`` variables must exist.
 ``global.bootchooser.last_chosen``
@@ -125,7 +125,7 @@ Setup Example
 We want to set up a redundant machine with two bootable systems within one shared
 memory, here a NAND type flash memory with a UBI partition. We have a 512 MiB NAND
 type flash, to be used only for the root filesystem. The devicetree doesn't
-define any partition, because we want to run one UBI partition with two volumens
+define any partition, because we want to run one UBI partition with two volumes
 for the redundant root filesystems on this flash memory.
 
 .. code-block:: text
-- 
2.20.1


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

[PATCH 2/8] doc: bootchooser: explicitly note configuration vs. storage backend

[Enrico Jorns]

It is quite confusing for some users sometimes where to set what.

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 667ab7d736..f1251d0c2e 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -11,6 +11,11 @@ from scratch over and over again.
 The *bootchooser* works on abstract boot targets, each with a set of properties
 and implements an algorithm which selects the highest priority target to boot.
 
+To make the *bootchooser* work requires a fixed set of configuration parameters
+and a storage backend for saving status information.
+Currently supported storage backends are either nv variables or the
+barebox *state* framework.
+
 Bootchooser Targets
 -------------------
 
-- 
2.20.1


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

[PATCH 3/8] doc: bootchooser: be more explicit what bootchooser.state_prefix is for

[Enrico Jorns]

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index f1251d0c2e..52aa595c74 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -113,8 +113,9 @@ options not specific to any boot target.
   Otherwise the ``boot`` command will return with an error after the first failed
   boot target.
 ``global.bootchooser.state_prefix``
-  Variable prefix when *bootchooser* is used with the *state* framework as backend
-  for storing run-time data, see below.
+  If set, this makes *bootchooser* use the *state* framework as backend for
+  storing run-time data and defines the name of the state instance to use, see
+  :ref:`below <bootchooser,state_framework>`.
 ``global.bootchooser.targets``
   Space-separated list of boot targets that are used. For each entry in the list
   a corresponding
-- 
2.20.1


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

[PATCH 4/8] doc: bootchooser: be more explicit about attempts reset on successful boot

[Enrico Jorns]

From the current description of how the bootchooser algorithm works it
is not that easy to figure out how to actually use it in a full (redundancy)
boot chain.

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 41 +++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 9 deletions(-)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 52aa595c74..7d7564b552 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -61,9 +61,15 @@ When booting, *bootchooser* starts the boot target with the highest ``priority``
 has a non-zero ``remaining_attempts`` counter. With every start of a boot target the
 ``remaining_attempts`` counter of this boot target is decremented by one. This means
 every boot target's ``remaining_attempts`` counter reaches zero sooner or later and
-the boot target won't be booted anymore. To prevent that, the ``remaining_attempts``
-counter must be reset to its default. There are different flags in the
-*bootchooser* which control resetting the ``remaining_attempts`` counter,
+the boot target won't be booted anymore.
+This behavior assures that one can retry booting a target a limited number of
+times to handle temporary issues (such as power outage) and optionally allows
+booting a fallback in case of a permanent failure.
+To indicate a successful boot, one must explicitly reset the remaining
+attempts counter. See `Marking a Boot as Successful`_.
+
+To prevent ending up in an unbootable system after a number of failed boot
+attempts, there is a also a built-in mechanism to reset the counters to their defaults,
 controlled by the ``global.bootchooser.reset_attempts`` variable. It holds a
 list of space-separated flags. Possible values are:
 
@@ -74,12 +80,29 @@ list of space-separated flags. Possible values are:
 - ``all-zero``: The ``remaining_attempts`` counters of all enabled boot targets are
   reset when none of them has any ``remaining_attempts`` left.
 
-Additionally the ``remaining_attempts`` counter can be reset manually using the
-:ref:`bootchoser command <command_bootchooser>`. This allows for custom conditions
-under which a system is marked as good.
-In case only the booted system itself knows when it is in a good state, the
-barebox-state tool from the dt-utils_ package can be used to reset the
-``remaining_attempts`` counter from the running system.
+Marking a Boot as Successful
+############################
+
+While the bootchooser algorithm handles attempts decrementation, retries and
+selection of the right boot target itself, it cannot decide if the system
+booted successfully on its own.
+
+In case only the booted system itself knows when it is in a good state,
+it can report this to the bootchooser from Linux userspace using the
+*barebox-state* tool from the dt-utils_ package.::
+
+  barebox-state -s bootstate.<target>.remaining_attemps <reset-value>
+
+If instead the bootchooser can detect a failed boot itself using the
+:ref:`reset reason <reset_reason>` (WDG), one can mark the boot successful
+using the barebox :ref:`bootchoser command <command_bootchooser>`::
+
+  bootchooser -s
+
+to mark the last boot successful.
+This will reset the ``remaining_attempts`` counter of the *last chosen* slot to
+its default value (``reset_attempts``).
+
 
 .. _dt-utils: https://git.pengutronix.de/cgit/tools/dt-utils
 
-- 
2.20.1


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

[PATCH 5/8] doc: bootchooser: note how to actually start the bootchooser

[Enrico Jorns]

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 7d7564b552..0c5e56407a 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -16,6 +16,17 @@ and a storage backend for saving status information.
 Currently supported storage backends are either nv variables or the
 barebox *state* framework.
 
+The *Bootchooser* itself is executed as a normal barebox boot target, i.e. one
+can start it via::
+
+  boot bootchooser
+
+or by e.g. setting ``boot.default`` to ``bootchooser``.
+
+.. note:: As ``boot.default`` accepts multiple values, it can also be used to
+  specify a fallback boot target in case the bootchooser fails booting, e.g.
+  ``bootchooser recovery``.
+
 Bootchooser Targets
 -------------------
 
-- 
2.20.1


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

[PATCH 6/8] doc: bootchooser: be more explicit about when the bootchooser terminates

[Enrico Jorns]

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 0c5e56407a..00ce896e37 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -79,6 +79,9 @@ booting a fallback in case of a permanent failure.
 To indicate a successful boot, one must explicitly reset the remaining
 attempts counter. See `Marking a Boot as Successful`_.
 
+The bootchooser algorithm aborts when all enabled targets (priority > 0) have
+no remaining attempts left.
+
 To prevent ending up in an unbootable system after a number of failed boot
 attempts, there is a also a built-in mechanism to reset the counters to their defaults,
 controlled by the ``global.bootchooser.reset_attempts`` variable. It holds a
-- 
2.20.1


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

[PATCH 7/8] doc: bootchooser: add details about bootchooser.reset_attempts handling

[Enrico Jorns]

For understanding and correctly using the algorith it is useful to know
when the values are evaluated.

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 00ce896e37..ad809751dd 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -88,11 +88,13 @@ controlled by the ``global.bootchooser.reset_attempts`` variable. It holds a
 list of space-separated flags. Possible values are:
 
 - empty: counters will never be reset
-- ``power-on``: The ``remaining_attempts`` counters of all enabled boot targets are reset
-  after a ``power-on`` reset (``$global.system.reset="POR"``). This means after a power
-  cycle all boot targets will be tried again for the configured number of retries.
-- ``all-zero``: The ``remaining_attempts`` counters of all enabled boot targets are
-  reset when none of them has any ``remaining_attempts`` left.
+- ``power-on``: When the bootchooser starts and a power-on reset
+  (``$global.system.reset="POR"``) is detected, the ``remaining_attempts``
+  counters of all enabled targets are reset to their defaults.
+  This means after a power cycle all boot targets will be tried again for the configured number of retries.
+- ``all-zero``: When the bootchooser starts and the ``remaining_attempts``
+  counters of all enabled targets are zero, the ``remaining_attempts``
+  counters of all enabled targets are reset to their defaults.
 
 Marking a Boot as Successful
 ############################
-- 
2.20.1


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

[PATCH 8/8] doc: bootchooser: add retry handling to algorithm description

[Enrico Jorns]

Signed-off-by: Enrico Jorns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index ad809751dd..1680ea78ed 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -96,6 +96,11 @@ list of space-separated flags. Possible values are:
   counters of all enabled targets are zero, the ``remaining_attempts``
   counters of all enabled targets are reset to their defaults.
 
+If ``global.bootchooser.retry`` is enabled (set to ``1``), the bootchooser
+algorithm will iterate through all valid boot targets (and decrease their
+counters) until one succeeds or none is left.
+If it is disabled only one attempt will be made for each bootchooser call.
+
 Marking a Boot as Successful
 ############################
 
-- 
2.20.1


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

Re: [PATCH 0/8] Bootchooser Documentation Update

[Sascha Hauer]

On Fri, Feb 15, 2019 at 01:53:40PM +0100, Enrico Jorns wrote:
> This is a collection of some documentation updates, fixes and
> clarifications for the bootchooser framework.
> 
> Enrico Jorns (8):
>   doc: bootchooser: fix typos etc.
>   doc: bootchooser: explicitly note configuration vs. storage backend
>   doc: bootchooser: be more explicit what bootchooser.state_prefix is
>     for
>   doc: bootchooser: be more explicit about attempts reset on successful
>     boot
>   doc: bootchooser: note how to actually start the bootchooser
>   doc: bootchooser: be more explicit about when the bootchooser
>     terminates
>   doc: bootchooser: add details about bootchooser.reset_attempts
>     handling
>   doc: bootchooser: add retry handling to algorithm description
> 
>  Documentation/user/bootchooser.rst | 94 +++++++++++++++++++++++-------
>  1 file changed, 72 insertions(+), 22 deletions(-)

Applied, thanks. I applied it to master to get it out on the website
sooner.

Sascha

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