[PATCH] doc: bootchooser: use 0 as base for system targets

[PATCH] doc: bootchooser: use 0 as base for system targets

[Michael Tretter]

Most barebox-state configurations in upstream define the bootchooser
targets as system0 and system1. The RAUC bootchooser documentation uses
system0 and system1, too. This is different from the bootchooser
documentation in barebox, which uses system1 and system2 in its
examples.

Change the barebox documentation to be consistent with what most users
will probably find on their respective systems.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
---
 Documentation/user/bootchooser.rst | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index c094dca15a0e415d9076bf210ffdbece05ade62e..9cf8d4c817379e207881aa60334e8552943345d0 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -115,8 +115,8 @@ it can report this to bootchooser from Linux userspace using the
 *barebox-state* tool from the dt-utils_ package.::
 
   barebox-state [-n <state variable set>] -s [<prefix>.]<target>.remaining_attempts=<reset-value>
-  barebox-state -n system_state -s bootstate.system1.remaining_attempts=3
-  barebox-state -s system1.remaining_attempts=3
+  barebox-state -n system_state -s bootstate.system0.remaining_attempts=3
+  barebox-state -s system0.remaining_attempts=3
 
 Alternatively barebox can be configured to mark the last boot successful based
 on the :ref:`reset reason <reset_reason>` (i.e. != WDG) using the
@@ -235,25 +235,25 @@ Either device can be booted with the :ref:`boot <command_boot>` command command,
 and thus can be used by *bootchooser* and we can start to configure the
 *bootchooser* variables.
 
-The following example shows how to initialize two boot targets, ``system1`` and
-``system2``. Both boot from a UBIFS on ``nand0``, the former has a priority of
-21 and boots from the volume ``root_filesystem_1`` whereas the latter has a
-priority of 20 and boots from the volume ``root_filesystem_2``.
+The following example shows how to initialize two boot targets, ``system0`` and
+``system1``. Both boot from a UBIFS on ``nand0``, the former has a priority of
+20 and boots from the volume ``root_filesystem_1`` whereas the latter has a
+priority of 10 and boots from the volume ``root_filesystem_2``.
 
 .. code-block:: sh
 
-  # initialize target 'system1'
-  nv bootchooser.system1.boot=nand0.ubi.root_filesystem_1
-  nv bootchooser.system1.default_attempts=3
-  nv bootchooser.system1.default_priority=21
+  # initialize target 'system0'
+  nv bootchooser.system0.boot=nand0.ubi.root_filesystem_1
+  nv bootchooser.system0.default_attempts=3
+  nv bootchooser.system0.default_priority=20
 
-  # initialize target 'system2'
-  nv bootchooser.system2.boot=nand0.ubi.root_filesystem_2
-  nv bootchooser.system2.default_attempts=3
-  nv bootchooser.system2.default_priority=20
+  # initialize target 'system1'
+  nv bootchooser.system1.boot=nand0.ubi.root_filesystem_2
+  nv bootchooser.system1.default_attempts=3
+  nv bootchooser.system1.default_priority=10
 
   # make targets known
-  nv bootchooser.targets="system1 system2"
+  nv bootchooser.targets="system0 system1"
 
   # retry until one target succeeds
   nv bootchooser.retry=1
@@ -510,7 +510,7 @@ content for the *state* variable set looks like:
 
    system_state {
         [...]
-        system1 {
+        system0 {
              #address-cells = <1>;
              #size-cells = <1>;
              remaining_attempts@0 {
@@ -525,7 +525,7 @@ content for the *state* variable set looks like:
              };
         };
 
-        system2 {
+        system1 {
              #address-cells = <1>;
              #size-cells = <1>;
              remaining_attempts@8 {
@@ -536,7 +536,7 @@ content for the *state* variable set looks like:
              priority@c {
                  reg = <0xc 0x4>;
                  type = "uint32";
-                 default = <21>;
+                 default = <10>;
              };
         };
 
@@ -546,7 +546,7 @@ content for the *state* variable set looks like:
         };
    };
 
-.. important:: While the ``system1/2`` nodes suggest a different namespace inside the
+.. important:: While the ``system0/1`` nodes suggest a different namespace inside the
    *state* variable set, the actual variable's ``reg``-properties and their offset
    part are always relative to the whole *state* variable set and thus must be
    consecutive globally.

---
base-commit: 7e32be40a193007e138c0eb589eb852420655523
change-id: 20250926-bootchooser-doc-f0051dd513f8

Best regards,
-- 
Michael Tretter <m.tretter@pengutronix.de>

Re: [PATCH] doc: bootchooser: use 0 as base for system targets

[Sascha Hauer]

On Fri, 26 Sep 2025 16:07:08 +0200, Michael Tretter wrote:
> Most barebox-state configurations in upstream define the bootchooser
> targets as system0 and system1. The RAUC bootchooser documentation uses
> system0 and system1, too. This is different from the bootchooser
> documentation in barebox, which uses system1 and system2 in its
> examples.
> 
> Change the barebox documentation to be consistent with what most users
> will probably find on their respective systems.
> 
> [...]

Applied, thanks!

[1/1] doc: bootchooser: use 0 as base for system targets
      https://git.pengutronix.de/cgit/barebox/commit/?id=65a86ad2ef88 (link may not be stable)

Best regards,
-- 
Sascha Hauer <s.hauer@pengutronix.de>