WIP

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

@@ -237,20 +237,123 @@ To turn an application into a recovery application, the following steps have to
 
 #. When building the main application, set ``SB_CONFIG_SUIT_RECOVERY_APPLICATION_CUSTOM`` (or the Kconfig option name if a different one was chosen) to ``y``.
 
-Entering recovery via button press
-**********************************
+.. _ug_nrf54h20_suit_recovery_enter_recovery_request:
+
+Entering recovery via are a request from the local domains
+**********************************************************
 
-It is possible to enable a feature that allows the device to enter recovery mode by pressing a button.
+It is possible to to enter recovery mode via a request sent from the local domains.
 This can be used for several purposes, such as:
 
 * Recovering the device if the main firmware crashes and no JLink connection is available.
 * Using the recovery application as a "foreground update" application, allowing to save some space in the main application.
 * Debugging the recovery application.
 
-When this feature is enabled, the device will enter recovery mode if the button is pressed during boot.
+:ref:`<ug_nrf54h20_suit_recovery_enter_via_button>` uses such requests.
+The code for this feature is located in the :file:`nrf/subsys/suit/app_tools/recovery_button` directory.
+It can be used as a reference design.
+
+To request entering the recovery mode, the ``suit_foreground_dfu_required()`` function must be called.
+
+To exit recovery mode, the ``suit_boot_flags_reset()`` must be called from the recovery application.
+However - if the main application firmware is corrupted, the device will regardlessly enter recovery mode again on the next boot.
+
+"Enter recovery check" by running recovery firmware (companion image) before the main application
+=================================================================================================
+
+In some cases the device might need to check if the it should enter recovery mode before running the main application.
+For example, the developer might want to enter recovery mode if a button is pressed during boot.
+
+This can be done by running the recovery application as a companion image before the main application in the invoke path.
+A different companion might be used for this purpose, but the recovery application is the most common choice.
+It allows reusing the recovery firmware for multiple purposes, simplifying the system.
+
+The recovery (companion) application can check if the device should enter recovery mode and set the recovery flag using ``suit_foreground_dfu_required()`` if needed.
+It is important to only do this if the device is currently in the SUIT_BOOT_MODE_INVOKE boot mode - the current boot mode can be checked using ``suit_boot_mode_read``.
+If the device should remain in normal boot mode (the condidion is not met) or the device already is in recovery mode, the firmware should call ``suit_invoke_confirm(0)``.
+This will allow for further proccessing of the SUIT manifest by the Secure Domain Frimware and booting the main application.
+
+To enable this feature, the following steps must be performed.
+This is assuming that the companion image is orchestrated by the APP_LOCAL_3 SUIT manifest - which will be true by default when using the recovery firmware as the companion.
+
+1. Add the appropriate checking code the recovery (companion) application in in its startup code.
+   The following code snippet can be used:
+
+   ..code-block:: c
+
+      static int should_enter_recovery_check(void)
+      {
+         suit_boot_mode_t mode = SUIT_BOOT_MODE_INVOKE_RECOVERY;
+         suit_ssf_err_t err = SUIT_PLAT_SUCCESS;
+         int ret = 0;
+
+         err = suit_boot_mode_read(&mode);
+
+         if (err != SUIT_PLAT_SUCCESS) {
+            suit_invoke_confirm(-EPIPE);
+            return -EPIPE;
+         }
+
+         if (mode == SUIT_BOOT_MODE_INVOKE) {
+            if (/* add the condition here */) {
+               err = suit_foreground_dfu_required();
+            }
+         }
+
+         if (err != SUIT_PLAT_SUCCESS) {
+            ret = -EPIPE;
+         }
+
+         (void)suit_invoke_confirm(ret);
+
+         return ret;
+      }
+
+      SYS_INIT(should_enter_recovery_check, APPLICATION, CONFIG_APPLICATION_INIT_PRIORITY);
+
+   The code should be placed in the recovery (companion) application's source code.
+   To do this, create a module with this code and attach it to the Nordic provided recovery application or create a custom recovery application/companion image.
+
+2. If using the default SUIT manifests and running the recovery image as the companion image, no modifications to the manifest templates are needed.
+   Instead, set the :kconfig:option:`CONFIG_SUIT_INVOKE_APP_LOCAL_3_BEFORE_MAIN_APP` option in the recovery image.
+   This can be done by adding ``-Drecovery_CONFIG_SUIT_INVOKE_APP_LOCAL_3_BEFORE_MAIN_APP=y`` to the build command when building the recovery application.
+
+   However, otherwise, the manifest templates have to be modified as follows:
+
+a. In the APP_LOCAL_3 manifest template, add the following code before the ``suit-directive-invoke`` directive on the companion image:
+
+   .. code-block:: yaml
+
+      - suit-directive-override-parameters:
+          suit-parameter-invoke-args:
+            suit-synchronous-invoke: True
+            suit-timeout: 1000
+
+b. In the root manifest template add the ``INSTLD_MFST`` component for the local manifest orchestrating the comapanion image.
+   Make sure it is invoked before the main application images.
+   If the modified template is based on the root manifest template from |NCS|, it will in most cases be enough to add it as the first manifst in the component list.
+   The following code snippet is responsible for this in the default root manifest template:
+
+   .. code-block:: yaml
+
+      {{- component_list.append( app_recovery_local_component_index ) or ""}}
+      - - INSTLD_MFST
+        - RFC4122_UUID:
+            namespace: {{ mpi_app_recovery_local_vendor_name }}
+            name: {{ mpi_app_recovery_local_class_name }}
+
+
+.. _ug_nrf54h20_suit_recovery_enter_via_button:
+
+Entering recovery via button press
+==================================
+
+A common use case for entering recovery mode is to allow the device to enter recovery mode by pressing a button.
+In NCS this use case is provided as a simple plug-and-play solution.
+When it is enabled, the device will enter recovery mode if the button is pressed during boot.
 
 .. note::
-   To exit the recovery mode, a device firmware update must be performed.
+   If no modifications or additional modules are added to the recovery application the only way to exit the recovery mode is performing a device firmware upgrade.
 
 There are two variants of this feature:
 
@@ -260,19 +363,17 @@ There are two variants of this feature:
 The first variant is recommended as it allows to perform the check independently of the main application.
 
 Recovery button checked in the recovery application
-===================================================
+---------------------------------------------------
 
-In this variant the recovery application is run as a companion image before the main application when the device boots.
+In this variant,the recovery application is run as a companion image before the main application as part of the normal invoke path.
 It checks if the device already is in recovery mode.
 If it is, the recovery application proceeds with its normal operation allowing to recover firmware.
 
 If the device is not in recovery mode, the recovery application checks if the specified button is pressed.
 If the button is pressed, the recovery application sets the recovery flag and reboots the device.
 Otherwise it sends a confirmation message to the Secure Domain Firmware, which then halts the recovery application and proceeds with booting the main application.
 
-To enable the feature in this variant perform the following steps:
-
-1. Add the following code to :file:`sysbuild/recovery.overlay` in the main application directory:
+To enable the feature add the following code to :file:`sysbuild/recovery.overlay` in the main application directory:
 
    .. code-block:: dts
 
@@ -284,9 +385,6 @@ To enable the feature in this variant perform the following steps:
 
    Replace ``button0`` with the appropriate button node.
 
-2. Enable :kconfig:option:`CONFIG_SUIT_RECOVERY_BUTTON` in the *recovery application* configuration.
-
-   When building from the command line, this can be done by adding ``-Drecovery_CONFIG_SUIT_RECOVERY_BUTTON=y`` to the build command.
 
 .. note::
    In this option running the recovery application as a companion image is orchestrated by the root SUIT manifest.
@@ -296,14 +394,12 @@ To enable the feature in this variant perform the following steps:
 
 
 Recovery button checked in the main application
-===============================================
+-----------------------------------------------
 
 In this variant a check if the specified button is pressed is performed at an early stage when inside the main application firmware.
 If the button is pressed, the recovery flag is set and the device reboots.
 
-To enable the feature in this variant perform the following steps:
-
-1. Add the following overlay to the main application's configuration:
+To enable the feature in this variant add the following overlay to the main application's configuration:
 
    .. code-block:: dts
 
@@ -314,7 +410,3 @@ To enable the feature in this variant perform the following steps:
       };
 
    Replace ``button0`` with the appropriate button node.
-
-2. Enable :kconfig:option:`CONFIG_SUIT_RECOVERY_BUTTON` in the main application configuration.
-
-   When building from the command line, this can be done by adding ``-DCONFIG_SUIT_RECOVERY_BUTTON=y`` to the build command.