Merge pull request rauc#1903 from ejoerns/revise-mark

Fix, update and rewrite parts of the 'mark' documentation

Author: jluebbe

docs/reference.rst

@@ -2443,15 +2443,27 @@ Bootloader Interaction
 RAUC comes with a generic interface for interacting with the bootloader.
 It handles *all* slots that have a ``bootname`` property set.
 
-It provides two base functions:
+.. note:: The terminology between the 'mark' methods and the low-level 'boot'
+   methods slightly differs.
 
-1) Setting state 'good' or 'bad', reflected by API routine ``r_boot_set_state()``
-   and command line tool option ``rauc status mark <good/bad>``
-2) Marking a slot 'primary', reflected by API routine ``r_boot_set_primary()``
-   and command line tool option ``rauc status mark-active``
+It provides three base operations:
+
+1) Setting state 'bad' (non-bootable), triggered by the API method ``r_mark_bad()``.
+
+   The bootloader backend API call for this is
+   ``r_boot_set_state(…, FALSE, …)``.
+2) Setting state 'good' (bootable), reflected by the API method ``r_mark_good()``.
+
+   The bootloader backend API call for this is
+   ``r_boot_set_state(…, TRUE, …)``.
+3) Marking a slot 'active' (primary boot target), reflected by API routine
+   ``r_mark_active()``.
+
+   The bootloader backend API call for this is
+   ``r_boot_set_primary()``.
 
 The default flow of how they will be called during the installation of a new
-bundle (on Slot 'A') looks as follows:
+bundle looks as follows:
 
 .. image:: images/bootloader-interaction_install.svg
   :width: 400
@@ -2491,16 +2503,16 @@ A normal reboot of the system will look as follows:
 Some bootloaders do not require explicitly setting state 'good' as they are able
 to differentiate between a POR and a watchdog reset, for example.
 
-.. note: Despite the naming might suggest it, marking a slot bad and good are
+.. note:: Despite the naming might suggest it, marking a slot bad and good are
   not reversible operations, meaning you have no guarantee that a slot first
   set to 'bad' and then set to 'good' again will be in the same state as
   before.
   Actually reactivating it will only work by marking it primary (active).
 
-What the high-level functions described above actually do mainly depends on the underlying
-bootloader used and the capabilities it provides.
-Below is a short description about behavior of each bootloader interface
-currently implemented:
+The exact behavior of each operation depends on the underlying bootloader and
+its capabilities.
+The following sections describe how each supported bootloader backend
+implements the above-mentioned operations.
 
 U-Boot
 ~~~~~~

docs/using.rst

@@ -139,42 +139,43 @@ points to the correct directory.
 That way, installed artifacts can be found by following
 ``/run/rauc/artifacts/<repository-name>/<artifact-name>``.
 
-React to a Successfully Booted System/Failed Boot
--------------------------------------------------
+Marking a Boot as Successful or Failed
+--------------------------------------
 
-Normally, the full system update chain is not complete before being sure that
-the newly installed system runs without any errors.
-As the definition and detection of a `successful` operation is really
-system-dependent, RAUC provides commands to preserve a slot as being the
-preferred one to boot or to discard a slot from being bootable.
+A system update is only considered complete once the newly installed system has
+been confirmed to be running correctly.
+Since the definition and detection of a successful boot is system-dependent,
+RAUC provides explicit commands and a :ref:`D-Bus Method
+<gdbus-method-de-pengutronix-rauc-Installer.Mark>` to mark the booted slot
+group as either good (confirmed working) or bad (non-working).
 
 .. code-block:: console
 
   # rauc status mark-good
 
-After verifying that the currently booted system is fully operational, one
-wants to signal this information to the underlying bootloader implementation
-which then, for example, resets a boot attempt counter.
+Once the currently booted system is verified as fully operational, run this
+command to signal success to the bootloader.
+Depending on the bootloader backend, this typically resets a boot attempt
+counter and confirms the current slot as the active one.
+
 
 .. code-block:: console
 
   # rauc status mark-bad
 
-If the current boot failed in some way, this command can be used to communicate
-that to the underlying bootloader implementation.
-In most cases this will disable the currently booted slot or at least switch to
-a different one.
+If the current boot has failed, run this command to signal failure to the
+bootloader.
+Depending on the bootloader backend, this will either disable the currently
+booted slot or switch to a different one.
 
-Although not very useful in the field, both commands recognize an optional
-argument to explicitly identify the slot to act on:
+To maintain consistency with ``rauc status mark-active``, both commands accept
+an optional slot argument:
 
 .. code-block:: console
 
   # rauc status mark-{good,bad} [booted | other | <SLOT_NAME>]
 
-This is to maintain consistency with respect to ``rauc status mark-active``
-where that argument is definitively wanted, see :ref:`here
-<optional-slot-identifier-argument>`.
+In practice this is rarely needed.
 
 .. _mark-active: