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

[Martin Schwan]

Hi Andreas,

two small nit-picks below...

On Thu, 2025-10-02 at 01:22 +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>
> ---
>  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..668d2a138a3 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``
> (``BOOT_A_LEFT``,
> +``BOOT_B_LEFT``) does not exist in environment, it will be created

Use "e.g." here, as the slots may be named differently and this is just
an example:

  (e.g. ``BOOT_A_LEFT``, ``BOOT_B_LEFT``)

> 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*

Use inline literal formatting here:

  (all slots in ``BOOT_ORDER`` have ``BOOT_x_LEFT`` set to 0)

Regards,
Martin

> 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:
>