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

[Ahmad Fatoum]

On 2/20/26 9:50 AM, Enrico Jörns wrote:
> 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 at pengutronix.de>

Reviewed-by: Ahmad Fatoum <a.fatoum at 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

-- 
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |