|author||Enrico Jorns <email@example.com>||2019-02-15 13:53:44 +0100|
|committer||Sascha Hauer <firstname.lastname@example.org>||2019-02-18 14:26:27 +0100|
doc: bootchooser: be more explicit about attempts reset on successful boot
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 <email@example.com> Signed-off-by: Sascha Hauer <firstname.lastname@example.org>
Diffstat (limited to 'Documentation')
1 files changed, 32 insertions, 9 deletions
diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 52aa595..7d7564b 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