[PATCH v2 2/2] bootstd: rauc: extend and fix doc to reflect real flow

[Martin Schwan]

Reviewed-by: Martin Schwan <m.schwan at phytec.de>

On Thu, 2025-10-02 at 18:24 +0200, Andreas Pretzsch wrote:
> The documentation of bootmeth rauc in some aspects does not reflect
> the
> real program flow. Specifically the reset of boot tries in case of
> "no
> more slots found" is incorrect (it won't change BOOT_ORDER).
> Also the search sequence for boot scripts was mixed and incomplete.
> Fix these points in the documentation.
> 
> Explain the initial setup of any missing BOOT_ORDER and BOOT_x_LEFT
> environment variables, and inform about BOOT_x_LEFT decrementing.
> 
> Signed-off-by: Andreas Pretzsch <apr at cn-eng.de>
> ---
> Changes for v2:
>   - rephrase and fix formatting based on feedback from Martin Schwan
> 
>  doc/develop/bootstd/rauc.rst | 19 +++++++++++++------
>  1 file changed, 13 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/develop/bootstd/rauc.rst
> b/doc/develop/bootstd/rauc.rst
> index b2661d18da4..5afd705dcb1 100644
> --- a/doc/develop/bootstd/rauc.rst
> +++ b/doc/develop/bootstd/rauc.rst
> @@ -21,14 +21,21 @@ with the left one tried first.
>  The default number of boot tries of each slot is set by
>  ``CONFIG_BOOTMETH_RAUC_DEFAULT_TRIES``.
>  
> -In case no valid slot can be found and/or all slots have zero tries
> left, the
> -boot order and slot tries are reset to their default values, if
> -``CONFIG_BOOTMETH_RAUC_RESET_ALL_ZERO_TRIES`` is enabled. This
> prevents a system
> -from locking up in the bootloader and tries booting again after a
> specified
> -number of tries.
> +If ``BOOT_ORDER`` does not exist in environment, it will be created
> and set to
> +``CONFIG_BOOTMETH_RAUC_BOOT_ORDER``.  If any ``BOOT_x_LEFT`` (for
> example
> +``BOOT_A_LEFT`` and/or ``BOOT_B_LEFT``) does not exist in
> environment, it will
> +be created and set to ``CONFIG_BOOTMETH_RAUC_DEFAULT_TRIES``.
> +
> +If ``CONFIG_BOOTMETH_RAUC_RESET_ALL_ZERO_TRIES`` is enabled, and no
> valid slot
> +is found (all slots in ``BOOT_ORDER`` have ``BOOT_x_LEFT`` set to
> 0), *all* slot
> +tries are reset to their default values.  This prevents a system
> from locking up
> +in the bootloader and tries booting again after a specified number
> of tries.
> +
> +If a valid slot is found, its LEFT value in environment is
> decremented by 1.
>  
>  The boot script must be located in each boot partition. The bootmeth
> searches
> -for "boot.scr.uimg" first, then "boot.scr" if not found.
> +for ``boot.scr`` first, then ``boot.scr.uimg`` if not found. It will
> search in
> +all directories of the bootstd list of prefixes (``"/", "/boot"`` by
> default).
>  
>  When the bootflow is booted, the bootmeth sets these environment
> variables:
>