Skip to contentSkip to conversation

Bootchooser Documentation Update

PATCH Applied Enrico Jorns 2 participants 10 messages Feb 15, 2019 – Feb 18, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

cover Bootchooser Documentation Update

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(-)
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#1 lore raw

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

---
 Documentation/user/bootchooser.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/user/bootchooser.rst +5 -5
index 05725d8f21..667ab7d736 100644
@@ -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
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#2 lore raw

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

In reply to Enrico Jorns

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

---
 Documentation/user/bootchooser.rst | 5 +++++
 1 file changed, 5 insertions(+)
Documentation/user/bootchooser.rst +5 -0
index 667ab7d736..f1251d0c2e 100644
@@ -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
 -------------------
 
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#3 lore raw

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

In reply to Enrico Jorns
---
 Documentation/user/bootchooser.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/user/bootchooser.rst +3 -2
index f1251d0c2e..52aa595c74 100644
@@ -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
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#4 lore raw

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

In reply to 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.

---
 Documentation/user/bootchooser.rst | 41 +++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 9 deletions(-)
Documentation/user/bootchooser.rst +32 -9
index 52aa595c74..7d7564b552 100644
@@ -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
 
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#5 lore raw

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

In reply to Enrico Jorns
---
 Documentation/user/bootchooser.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)
Documentation/user/bootchooser.rst +11 -0
index 7d7564b552..0c5e56407a 100644
@@ -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
 -------------------
 
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#6 lore raw

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

In reply to Enrico Jorns
---
 Documentation/user/bootchooser.rst | 3 +++
 1 file changed, 3 insertions(+)
Documentation/user/bootchooser.rst +3 -0
index 0c5e56407a..00ce896e37 100644
@@ -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
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#7 lore raw

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

In reply to Enrico Jorns

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

---
 Documentation/user/bootchooser.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/user/bootchooser.rst +7 -5
index 00ce896e37..ad809751dd 100644
@@ -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
 ############################
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#8 lore raw

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

In reply to Enrico Jorns
---
 Documentation/user/bootchooser.rst | 5 +++++
 1 file changed, 5 insertions(+)
Documentation/user/bootchooser.rst +5 -0
index ad809751dd..1680ea78ed 100644
@@ -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
 ############################
 
Signature · 7 lines
2.20.1


_______________________________________________
barebox mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
Applied
#9 lore raw
In reply to Enrico Jorns
Quoted 17 lines · 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

Quoted 2 lines
 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

Signature · 9 lines
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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox