[PATCH 1/2] Documentation: bootchooser: fix grammar and wording for 'attempts_locked'

[PATCH 1/2] Documentation: bootchooser: fix grammar and wording for 'attempts_locked'

[Enrico Jörns]

* 'variable in the bootstate' is undefined -> replace
* fix and rephrase 'use case' sentence
* fix and rephrase 'trade-off' sentence
* Add missing period after 'avoid this behavior'
* Avoid unclear 'to boot if any'
* fix typo, remove excess whitespace

Signed-off-by: Enrico Jörns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 360305e92e..b38bae2c23 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -88,21 +88,23 @@ 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).
+This is done by defining a (32-bit) ``attempts_locked`` run-time variable 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
+In scenarios where the system is rebooted too frequently (after the ``remaining_attempts``
+counter is decremented, but before it got incremented again after a successful boot), it can unintentionally fall
+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.
+to the other target. It comes with the trade-off that a slot that becomes broken
+over time will no longer be detected as such 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.
+The ``attempts_locked`` variable does not influence which boot target is
+selected, only whether its ``remaining_attempts`` counter is decremented when
+booting.
 
 If :ref:`global.bootchooser.retry <magicvar_global_bootchooser_retry>`
 is enabled (set to ``1``), the bootchooser
@@ -134,12 +136,12 @@ 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
+An additional 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
+  barebox-state -s bootstate.attempts_locked=1
 
-It can also be locked via the :ref:`bootchooser command <command_bootchooser>`::
+It can also be locked from barebox via the :ref:`bootchooser command <command_bootchooser>`::
 
   bootchooser -l
 
-- 
2.47.3

[PATCH 2/2] Documentation: bootchooser: move attempts locking to own section

[Enrico Jörns]

Boot attempts locking is useful in specific scenarios, but is specialized
enough that it should not obscure the default bootchooser flow description.

Give only brief hints in the main algorithm section and move the full
description to a distinct section with its own anchor. Sharpen the
wording throughout.

Signed-off-by: Enrico Jörns <ejo@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 58 +++++++++++++++---------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index b38bae2c23..669ebf0a47 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -83,28 +83,8 @@ attempts, there is also a built-in mechanism to reset the counters to their defa
 controlled by the
 :ref:`global.bootchooser.reset_attempts <magicvar_global_bootchooser_reset_attempts>`
 variable.
-
-.. _bootchooser,attempts_lock:
-
-Alternatively, counting down the remaining attempts can be disabled by
-locking bootchooser boot attempts.
-This is done by defining a (32-bit) ``attempts_locked`` run-time variable and
-setting its value to ``1`` (usually from userspace).
-
-In scenarios where the system is rebooted too frequently (after the ``remaining_attempts``
-counter is decremented, but before it got incremented again after a successful boot), it can unintentionally fall
-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 will no longer be detected as such 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`` variable does not influence which boot target is
-selected, only whether its ``remaining_attempts`` counter is decremented when
-booting.
+Alternatively, the remaining attempts counters can be frozen globally by
+enabling :ref:`boot attempts locking <bootchooser,attempts_lock>`.
 
 If :ref:`global.bootchooser.retry <magicvar_global_bootchooser_retry>`
 is enabled (set to ``1``), the bootchooser
@@ -136,18 +116,38 @@ 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``).
 
-An additional option is to use ``attempts_locked``. Normally this should be controlled from
-Linux userspace using the *barebox-state* tool, i.e.::
+An additional option is to use :ref:`boot attempts locking <bootchooser,attempts_lock>`
+to fully disable automatic fallback.
 
-  barebox-state -s bootstate.attempts_locked=1
+.. _bootchooser,attempts_lock:
+
+Boot Attempts Locking
+#####################
+
+In scenarios where the system is rebooted too frequently (after the ``remaining_attempts``
+counter is decremented, but before it is incremented again after a successful boot), it can unintentionally fall
+back to the other boot target.
+This can be avoided by enabling boot attempt locking.
+If enabled, bootchooser is prevented from decrementing the ``remaining_attempts`` counter and falling back
+to the other target. This comes with the trade-off that a slot that becomes broken
+over time will no longer be detected as such and will be booted indefinitely.
+
+Attempts locking can be controlled by an optional (32-bit) ``attempts_locked`` run-time variable.
+Setting its value to ``1`` enables locking for all
+boot targets; setting it to ``0`` disables locking.
 
-It can also be locked from barebox via the :ref:`bootchooser command <command_bootchooser>`::
+The ``attempts_locked`` variable does not influence which boot target is
+selected, only whether the ``remaining_attempts`` counter is decremented on each boot.
 
-  bootchooser -l
+To enable boot attempts locking from Linux userspace using the *barebox-state*
+tool, run::
+
+  barebox-state -s bootstate.attempts_locked=1
 
-or unlocked::
+It can also be controlled from barebox via the :ref:`bootchooser command <command_bootchooser>`::
 
-  bootchooser -L
+  bootchooser -l # lock
+  bootchooser -L # unlock
 
 
 .. _dt-utils: https://git.pengutronix.de/cgit/tools/dt-utils
-- 
2.47.3