[PATCH v3 3/4] Documentation: bootchooser: add information about attempts_locked

[Lars Schmidt]

The new variable behaves quite differently from the already existing
method via reset_attempts. So a proper description, including a use case,
is added to the documentation.
Additionally an example how to add it is added to bootstate.dtsi.

Signed-off-by: Lars Schmidt <l.schmidt at pengutronix.de>
---
 Documentation/user/bootchooser.rst | 30 ++++++++++++++++++++++++++++++
 arch/arm/dts/bootstate.dtsi        |  5 +++++
 2 files changed, 35 insertions(+)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 351e1d14e1ead6ba8d329c03c0bc7ed28b523df0..1d7ece6c4b1255b41d359d3303daaf78bacfa17a 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -77,6 +77,23 @@ no remaining attempts left.
 To prevent ending up in an unbootable system after a number of failed boot
 attempts, there is also a built-in mechanism to reset the counters to their defaults,
 controlled by the ``global.bootchooser.reset_attempts`` variable.
+Alternatively, counting down the remaining attempts can be disabled by
+locking bootchooser boot attempts.
+This is done by defining a (32-bit) ``attempts_locked`` variable in the
+bootstate and setting its value to ``1`` (usually from userspace).
+
+In scenarios where the system is rebootet too frequently (after the ``remaining_attempts``
+counter is decremented, but before it got incremented again after a successful boot) and falls
+back to the other boot target, the ``attempts_locked`` variable can be used to avoid this behavior
+Bootchooser is prevented from decrementing the ``remaining_attempts`` counter and falling back
+to the other target. It comes with the trade-off that a slot, that becomes broken
+over time, it won't be detected anymore and will be booted indefinitely.
+
+The variable affects all targets, is optional and its absence is
+interpreted as ``0``, meaning that attempts are decremented normally.
+
+The ``attempts_locked`` value does not influence the decision on which target
+to boot if any, only whether to decrement the attempts when booting.
 
 If ``global.bootchooser.retry`` is enabled (set to ``1``), the bootchooser
 algorithm will iterate through all valid boot targets (and decrease their
@@ -107,6 +124,19 @@ on the :ref:`reset reason <reset_reason>` (i.e. != WDG) using the
 This will reset the ``remaining_attempts`` counter of the *last chosen* slot to
 its default value (``reset_attempts``).
 
+Another option is to use ``attempts_locked``. Normally this should be controlled from
+Linux userspace using the *barebox-state* tool, i.e.::
+
+  barebox-state -s  bootstate.attempts_locked=1
+
+It can also be locked via the :ref:`bootchooser command <command_bootchooser>`::
+
+  bootchooser -l
+
+or unlocked::
+
+  bootchooser -L
+
 
 .. _dt-utils: https://git.pengutronix.de/cgit/tools/dt-utils
 
diff --git a/arch/arm/dts/bootstate.dtsi b/arch/arm/dts/bootstate.dtsi
index aa767d4e3b966244b01702bbc2bdcd5c95ef7009..733441fb2697b283dc784b00b012e11ad671bb15 100644
--- a/arch/arm/dts/bootstate.dtsi
+++ b/arch/arm/dts/bootstate.dtsi
@@ -42,4 +42,9 @@ last_chosen at 10 {
 		reg = <0x10 0x4>;
 		type = "uint32";
 	};
+
+	attempts_locked at 14 {
+		reg = <0x14 0x4>;
+		type = "uint32";
+	};
 };

-- 
2.39.5