Bootchooser Documentation Update
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
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
@@ -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
PATCH 2/8 doc: bootchooser: explicitly note configuration vs. storage backend
In reply to Enrico JornsIt 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
@@ -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
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
@@ -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
PATCH 4/8 doc: bootchooser: be more explicit about attempts reset on successful boot
In reply to Enrico JornsFrom 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
@@ -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
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
@@ -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
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
@@ -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
PATCH 7/8 doc: bootchooser: add details about bootchooser.reset_attempts handling
In reply to Enrico JornsFor 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
@@ -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
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
@@ -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
Sascha Hauer
AppliedQuoted 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