doc: suit: Push scenario and DFU caches documentation

Added documentation for SUIT DFU cache partitions
and how to use them to push detached payloads for DFU
to the device.

Signed-off-by: Artur Hadasz <artur.hadasz@nordicsemi.no>

doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst

@@ -27,6 +27,7 @@ For a list of available SUIT samples, see the :ref:`suit_samples` page.
    ug_nrf54h20_suit_customize_qsg.rst
    ug_nrf54h20_suit_customize_dfu.rst
    ug_nrf54h20_suit_fetch
+   ug_nrf54h20_suit_push
    ug_nrf54h20_suit_external_memory
    ug_nrf54h20_suit_components.rst
    ug_nrf54h20_suit_hierarchical_manifests.rst

doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_push.rst

@@ -0,0 +1,111 @@
+.. _ug_nrf54h20_suit_push:
+
+How to push SUIT payloads to multiple partitions
+################################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+In the Software Updates for Internet of Things (SUIT), it is possible to push certain payloads separately from the SUIT envelope.
+The envelope can than find them in the device and use them as part of the firmware upgrade process.
+
+In Nordic Semiconductor's implementation, this functionality is provide by a mechanism called the DFU cache partitions.
+
+This guide explains how the DFU cache partitions work, and how to configure the build system and SUIT manifests to use them for pushing detached payloads.
+
+
+Reasons to push images separately from the SUIT envelope
+********************************************************
+
+Pushing images separately from the SUIT envelope can be useful in the following scenarios:
+
+* Pushing part of the image to an external memory chip.
+
+* Pushing parts of the update package to non-adjacent memory areas, separated by other data.
+
+* Reducing the amount of data that needs to be resent in case of communication failure to continue the update.
+
+* Pushing parts of the image through different communication channels.
+
+DFU Cache Partitions
+********************
+
+The payloads pushed to the device must be placed in so called “DFU cache partitions”, numbered 0..n.
+The DFU cache partitions hold data in the format of a CBOR map, in which the keys are URI strings and the values are binary images.
+
+When the Secure Domain processes the manifest and encounters a “fetch” directive it first checks if a given URI is present in its “integrated payloads” section.
+If it is not, it goes through all the DFU cache partitions defined in the device.
+If the given URI is found as a map key, the binary data stored in the value field corresponding to that URI is fetched.
+
+The DFU cache partition 0 is always present in the device.
+It takes all of the space from the dfu_partition which is not occupied by the envelope.
+This partition has a limitation - it can only be used after storing the SUIT envelope.
+
+The DFU cache partitions 1…n are defined in the device tree, by using the dfu_cache_partition_x  node name, where x is the partition number.
+The partitions can be placed both in the internal MRAM as well as in the external flash.
+
+Extracting images
+*********************************************************
+
+The :ref:`nrf54h_suit_sample` sample uses the SMP protocol for uploading new envelopes and is by default configured to use the push model for firmware upgrades.
+To reconfigure the sample to allow for pushing images into DFU cache partitions, complete the following steps:
+
+1. Enable the :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_PUSH_TO_CACHE` Kconfig option.
+   This enables the writing to the DFU cache partitions.
+   Alternatively, you can enable the :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_FULL` option to enable the SUIT envelope processing in the application firmware.
+   This will enable a superset of options enabled by :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_PUSH_TO_CACHE`, but will occupy more memory.
+
+#. If you intend to use any other cache partition then 0, add the DFU cache partition in the appropriate memory area in the device tree overlay:
+
+   .. code-block:: dts
+
+		dfu_cache_partition_N: partition@SIZE {
+			reg = <OFFSET DT_SIZE_K(SIZE)>;
+		};
+
+   Where ``N`` is the partition number, ``OFFSET`` is the offset inside the memory area, and ``SIZE`` is the size of the cache partition.
+
+   For example, you could add the cache partition 1 with the size of 1024 kilobytes in the external flash at an offset of 0 by adding:
+
+   .. code-block:: dts
+
+      &mx25uw63 {
+         status = "okay";
+         partitions {
+            compatible = "fixed-partitions";
+            #address-cells = <1>;
+            #size-cells = <1>;
+
+            dfu_cache_partition_1: partition@0 {
+               reg = <0x0 DT_SIZE_K(1024)>;
+            };
+         };
+      };
+
+#. For each of the images you want to push separately to the device:
+
+   * Enable the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE` option
+   * (Optionally) modify :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE_PARTITION` to select to which partition the image will be pushed (default is 1).
+   * (Optionally) modify the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE_URI` to modify the URI used as key for the given image in the DFU cache.
+
+#. Ensure that the uri used by ``suit-payload-fetch`` sequence to fetch a given image matches the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE_URI`.
+   Note this is done by default if using the provided Nordic manifest templates.
+   <TODO>: do that also for the recovery images.
+   For the application image URI this can be done by (assuming the target name "application" for the image):
+
+   .. code-block:: yaml
+
+      - suit-directive-override-parameters:
+         suit-parameter-uri: '{{ application['config']['CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE_URI'] }}'
+      - suit-directive-fetch:
+        - suit-send-record-failure
+
+#. Ensure that the envelope does integrate the given image inside the envelope integrated payloads section
+   This will be ensured by default if using the provided default SUIT envelope templates.
+
+
+Pushing the images to device
+****************************
+
+For an example how to push an image to a device see the :ref:`SUIT SMP Sample documentation <nrf54h_suit_sample>`.

samples/suit/smp_transfer/README.rst

@@ -107,22 +107,30 @@ See :ref:`app_build_output_files_suit_dfu` for a full table of SUIT-generated ou
 If you want to make modifications to how the DFU is executed in this sample, you can do so by editing the manifest templates, or generating your own custom manifests.
 See the :ref:`ug_nrf54h20_suit_customize_dfu` user guide for instructions and examples.
 
+.. _nrf54h_suit_sample_extflash:
+
 External flash support
 ======================
 
-You can enable the external flash support by setting the following ``FILE_SUFFIX=extflash`` parameter:
+You can build the application with external flash support by running:
 
 .. code-block:: console
 
-   west build -p -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX="extflash"
 
+From the sample directory.
 With this configuration, the sample is configured to use UART as the transport and the external flash is enabled.
+To see which Kconfig options are needed to achieve that, see the ``sample.suit.smp_transfer.cache_push.extflash`` configuration in :file:`samples/suit/sample.yaml`.
 
 To enable both the external flash and the BLE transport, use the following command:
 
 .. code-block:: console
 
-   west build -p -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX="extflash" -DOVERLAY_CONFIG="sysbuild/smp_transfer_bt.conf" -DSB_OVERLAY_CONFIG="sysbuild_bt.conf"
+   west build ./ -b nrf54h20dk/nrf54h20/cpuapp -T  sample.suit.smp_transfer.cache_push.extflash.bt
+
+.. note::
+   This way of building the application with external flash will enable the "push" scenario for updating from external flash.
+   It will also extract the image to a DFU cache partition file.
+   For more information, see :ref:`How to push SUIT payloads to multiple partitions <ug_nrf54h20_suit_push>`
 
 Building and running
 ********************
@@ -313,6 +321,19 @@ After programming the sample to your development kit and updating the sequence n
                197.40 KiB / 244.57 KiB [==============================================================================================================================>------------------------------]  80.71% 20.51 KiB/s 00m02s
                241.16 KiB / 244.57 KiB [=================================================================================================================================================================>--]  98.60% 20.74 KiB/s
                Done
+      #. If you have built the application with :ref:`external flash support <nrf54h_suit_sample_extflash>`, upload the cache partition to the external flash using:
+
+            .. code-block:: console
+
+               mcumgr --conntype serial --connstring "dev=/dev/ttyACM0,baud=115200" image upload -n 2 build/DFU/root.suit
+
+            Note the ``-n 2`` parameter - this means uploading to DFU cache partition 1 (image 0 is the envelope, image 1 is the cache partition 0).
+
+      #. Start the installaltion of the new firmware using:
+
+            .. code-block:: console
+
+               mcumgr --conntype serial --connstring "dev=/dev/ttyACM0,baud=115200" image confirm
 
       #. Read the version and digest of the uploaded root manifest with MCUmgr: