doc: Add dfu_target_suit to documentation.

Updated all pages related to the dfu_target library by adding
information about SUIT-based dfu_target implementation.

Updated release notes.

Signed-off-by: Arkadiusz Balys <[email protected]>

Author: ArekBalysNordic

doc/nrf/libraries/dfu/dfu_multi_image.rst

@@ -26,17 +26,51 @@ To configure the maximum number of images that the DFU multi-image library is ab
 To enable building the DFU multi-image package that contains commonly used update images, such as the application core firmware, the network core firmware, or MCUboot images, set the ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_BUILD`` Kconfig option.
 The following options control which images are included:
 
-+-------------------------------------------------------------------+---------------------------------------+
-| Kconfig                                                           | Description                           |
-+===================================================================+=======================================+
-|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_APP``           | Include application update.           |
-+-------------------------------------------------------------------+---------------------------------------+
-|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_NET``           | Include network core image update.    |
-+-------------------------------------------------------------------+---------------------------------------+
-|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_MCUBOOT``       | Include MCUboot update.               |
-+-------------------------------------------------------------------+---------------------------------------+
-|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH`` | Include nRF700x WiFi firmware patches.|
-+-------------------------------------------------------------------+---------------------------------------+
++-------------------------------------------------------------------+----------------------------------------+
+| Kconfig                                                           | Description                            |
++===================================================================+========================================+
+|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_APP``           | Include application update.            |
++-------------------------------------------------------------------+----------------------------------------+
+|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_NET``           | Include network core image update.     |
++-------------------------------------------------------------------+----------------------------------------+
+|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_MCUBOOT``       | Include MCUboot update.                |
++-------------------------------------------------------------------+----------------------------------------+
+|               ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH`` | Include nRF700x Wi-Fi firmware patches.|
++-------------------------------------------------------------------+----------------------------------------+
+|               ``SB_CONFIG_SUIT_MULTI_IMAGE_PACKAGE_BUILD``        | Include SUIT envelope and cache images.|
++-------------------------------------------------------------------+----------------------------------------+
+
+.. _lib_dfu_multi_image_suit_multi_image_package:
+
+SUIT multi-image package
+========================
+
+The DFU multi-image library supports building a SUIT multi-image package that includes a SUIT envelope and cache images.
+The SUIT envelope is always included in the package as image 0, while SUIT cache images are included as subsequent images starting from the image 2.
+
+The SUIT multi-image processing requires the SUIT system to support cache processing.
+To enable it, set one of the following Kconfig options to ``y``:
+
+* :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_FULL`
+* :kconfig:option:`SUIT_DFU_CANDIDATE_PROCESSING_PUSH_TO_CACHE`
+
+The build system merges all application images into a single :file:`dfu_cache_partition_1.bin` partition file and places its content into the multi-image image 2.
+This allows all application images to be stored in a single DFU multi-image, as they will be processed by SUIT.
+
+The :kconfig:option:`SB_CONFIG_SUIT_MULTI_IMAGE_PACKAGE_BUILD` Kconfig option enables building the SUIT multi-image package.
+As a result, the multi-image package will contain:
+
+* Image 0:
+   - SUIT envelope that contains manifests only.
+
+* Image 2:
+   - Application core image.
+   - Radio core image, if applicable.
+   - Additional images, if applicable.
+
+You can add more data to be processed by SUIT to the following images starting from image 3.
+This operation will require an additional binary file and the proper :file:`dfu_cache_partition_X` definition in a devicetree configuration file, where ``X`` is the image number minus 1.
+So for the image 3, you would need :file:`dfu_cache_partition_2`.
 
 Dependencies
 ************

doc/nrf/libraries/dfu/dfu_target.rst

@@ -48,6 +48,7 @@ The DFU target library supports the following types of firmware upgrades:
 * MCUboot-style upgrades
 * Modem delta upgrades
 * Full modem firmware upgrades
+* SUIT-style upgrades
 
 MCUboot-style upgrades
 ----------------------
@@ -103,6 +104,69 @@ This DFU target downloads the serialized modem firmware to an external flash mem
 Once the modem firmware has been downloaded, the application should use :ref:`lib_fmfu_fdev` to write the firmware to the modem.
 The DFU target library does not perform the upgrade and calling the :c:func:`dfu_target_schedule_update` function has no effect.
 
+.. _lib_dfu_target_suit_style_update:
+
+SUIT-style upgrades
+-------------------
+
+SUIT-style firmware upgrades can be used for :ref:`ug_nrf54h20_suit_dfu`.
+Depending on the image number and the used SUIT system configuration, this type of DFU writes the data provided to the :c:func:`dfu_target_write` function into the following partitions:
+
+* Image 0: ``dfu_partition``
+* Image 1: ``dfu_cache_partition_0`` - always located just after the ``dfu_partition`` partition.
+* Image 2..n: ``dfu_cache_partition_n`` - located in internal or external memory.
+
+Before calling the :c:func:`dfu_target_init` and :c:func:`dfu_target_write` functions, the application must call the :c:func:`dfu_target_suit_set_buf` function to allocate the buffer used during the firmware update process.
+The buffer size must be at least the size of the largest chunk that will be downloaded at a single time.
+The buffer will be used for processing all images, so there is no need to allocate a new buffer for each image.
+
+You can upgrade your device in several ways depending on your SUIT system configuration:
+
+.. tabs::
+
+   .. tab:: SUIT single image processing
+
+      SUIT minimal processing is used for devices that do not have a cache partition.
+      To enable it, set the :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_MINIMAL` Kconfig option to ``y``.
+
+      In this approach, the SUIT envelope contains the manifests and the firmware image.
+      The SUIT envelope is stored in the ``dfu_partition`` partition.
+      After that, the ``dfu_cache_partition_0`` partition will be created automatically just after the ``dfu_partition`` partition and will contain the firmware.
+
+   .. tab:: SUIT cache processing
+
+      The SUIT cache processing requires one of the following SUIT system configurations set to ``y``:
+
+      * :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_FULL`
+      * :kconfig:option:`SUIT_DFU_CANDIDATE_PROCESSING_PUSH_TO_CACHE`
+
+      With one of these options set, the DFU target SUIT library can process the SUIT envelope and cache images.
+      In this approach, the SUIT envelope contains the manifests only, while the firmware is stored in the cache images.
+
+      You can disable cache processing by setting the :kconfig:option:`DFU_TARGET_SUIT_CACHE_PROCESSING` Kconfig option to ``n``.
+
+      When this approach is used, the SUIT manifests will be stored in the ``dfu_partition`` partition.
+      The firmware will be stored in the ``dfu_cache_partition_1`` partition.
+      This approach can be used for devices that have defined the ``dfu_cache_partition_1`` partition in the internal or external flash memory.
+      The :ref:`lib_dfu_multi_image_suit_multi_image_package` uses this approach for multi-image updates.
+
+      To read more about SUIT cache processing, see the :ref:`ug_nrf54h20_suit_external_memory` guide.
+
+Make sure the application calls the :c:func:`dfu_target_init` function for image 0 first and then downloads the SUIT envelope.
+When the single image data transfer is completed, the application using the DFU target library must call the :c:func:`dfu_target_done` function for each subsequent image.
+After that, the application can call the :c:func:`dfu_target_init` function for another image index.
+
+When all image data transfers are completed, the application using the DFU target library must do the following:
+
+1. Call the :c:func:`dfu_target_schedule_update` function to inform SUIT that the manifests can be processed.
+2. Automatically reboot the device by calling :c:func:`dfu_target_suit_reboot` with a defined delay.
+   You can set the delay before rebooting the device by configuring the :kconfig:option:`CONFIG_DFU_TARGET_SUIT_REBOOT_DELAY` Kconfig option.
+   Alternatively, you can skip this step and reboot the device manually.
+
+.. note::
+   The application must schedule the upgrade of all images at once using the :c:func:`dfu_target_schedule_update` function.
+   During this operation, the manifests stored in the ``dfu_partition`` partition will be processed.
+
 Configuration
 *************
 

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -710,7 +710,10 @@ Debug libraries
 DFU libraries
 -------------
 
-|no_changes_yet_note|
+* :ref:`lib_dfu_target` library:
+
+  * Updated the DFU Target SUIT implementation to the newest version of the SUIT.
+  * Added SUIT cache processing to the DFU Target SUIT library, as described in the :ref:`lib_dfu_target_suit_style_update` section.
 
 Gazell libraries
 ----------------

include/dfu/dfu_target_suit.h

@@ -29,7 +29,8 @@ extern "C" {
 int dfu_target_suit_set_buf(uint8_t *buf, size_t len);
 
 /**
- * @brief Initialize dfu target for specific image, perform steps necessary to receive firmware.
+ * @brief Initialize the DFU target for the specific image and  perform the necessary steps to
+ * receive the firmware.
  *
  * If you call this function, you must call dfu_target_suit_done() to finalize the firmware upgrade
  * before initializing any other images.
@@ -38,7 +39,7 @@ int dfu_target_suit_set_buf(uint8_t *buf, size_t len);
  * @param[in] img_num Image index.
  * @param[in] cb Callback for signaling events(unused).
  *
- * @return 0 If successful
+ * @return 0 If successful.
  * @return -ENODEV errno code if the buffer has not been initialized.
  * @return -ENXIO errno code if the partition dedicated for provided image is not found.
  * @return -ENOMEM errno code if the buffer is not large enough.
@@ -53,7 +54,7 @@ int dfu_target_suit_init(size_t file_size, int img_num, dfu_target_callback_t cb
  *
  * @param[out] offset Returns the offset of the firmware upgrade.
  *
- * @retval 0 if success, otherwise negative value if unable to get the offset
+ * @retval 0 If success. Otherwise, a negative value if unable to get the offset.
  */
 int dfu_target_suit_offset_get(size_t *offset);
 
@@ -63,7 +64,7 @@ int dfu_target_suit_offset_get(size_t *offset);
  * @param[in] buf Pointer to data that should be written.
  * @param[in] len Length of data to write.
  *
- * @return 0 on success
+ * @return 0 If successful.
  * @return -EFAULT errno code if the stream flash has not been initialized for any dfu image.
  * @return other negative errno code if the initialization failed.
  */
@@ -79,7 +80,7 @@ int dfu_target_suit_write(const void *const buf, size_t len);
 int dfu_target_suit_done(bool successful);
 
 /**
- * @brief Schedule an update
+ * @brief Schedule an update.
  *
  * This call processes SUIT envelope and requests images update.
  *
@@ -89,8 +90,9 @@ int dfu_target_suit_done(bool successful);
  * @param[in] img_num Given image pair index or -1 for all
  *		      of image pair indexes.
  *
- * @retval 0 for a successful request or a negative error
- *	   code indicating reason of failure.
+ * @retval 0 Successful request.
+ * @retval negative_errno_code Negative error
+ *	   code indicating the reason of failure.
  **/
 int dfu_target_suit_schedule_update(int img_num);
 
@@ -99,17 +101,19 @@ int dfu_target_suit_schedule_update(int img_num);
  *
  * Cancels any ongoing updates.
  *
- * @retval 0 on success, negative errno otherwise.
+ * @retval negative_errno_code Negative error
+ *	   code indicating the reason of failure.
  */
 int dfu_target_suit_reset(void);
 
 /**
- * @brief Reboot the device, and apply new image.
+ * @brief Reboot the device and apply the new image.
  *
  * The reboot can be delayed by setting the
- * CONFIG_DFU_TARGET_REBOOT_RESET_DELAY_MS kconfig value.
+ * CONFIG_DFU_TARGET_REBOOT_RESET_DELAY_MS Kconfig option value to the desired delay value.
  *
- * @retval 0 on success, negative errno otherwise.
+ * @retval negative_errno_code Negative error
+ *	   code indicating the reason of failure.
  */
 int dfu_target_suit_reboot(void);
 

subsys/dfu/dfu_target/Kconfig

@@ -135,20 +135,20 @@ config DFU_TARGET_SUIT_CACHE_PROCESSING
 	default y
 	depends on SUIT_CACHE_RW
 	help
-	  Enable SUIT cache processing to process images ids bigger than 0.
-	  It allows to store the image in the cache cache partitions and
-	  assign them to be processed by the SUIT.
+	  Enable SUIT cache processing to process images IDs higher than 0.
+	  This allows to store the image in the cache partitions and
+	  assign them to be processed by SUIT.
 
 config DFU_TARGET_SUIT_INITIALIZE_SUIT
-	bool "Initialize SUIT dfu library"
+	bool "Initialize the SUIT DFU library"
 	help
-	  Initialize SUIT library during the system startup.
+	  Initialize the SUIT library during the system startup.
 
 config DFU_TARGET_REBOOT_RESET_DELAY_MS
-	int "Reboot reset delay in milliseconds"
+	int "Set reboot reset delay in milliseconds"
 	default 0
 	help
-	  Set the delay in milliseconds before the device is reset after a reboot
+	  Set the delay in milliseconds for resetting the device after a reboot
 	  function is called.
 
 endif # DFU_TARGET_SUIT

tests/subsys/dfu/dfu_target/suit/src/common.h

@@ -24,11 +24,13 @@
 void reset_fakes(void);
 
 /**
- * @brief Check whether the partition is empty
+ * @brief Check whether the partition is empty.
  *
- * @param address partition address to check
- * @param size partition size
- * @retval true if partition is empty, false otherwise
+ * @param address Partition address to check.
+ * @param size Partition size.
+ *
+ * @retval true If the partition is empty.
+ * @retval false If the partition is not empty.
  */
 bool is_partition_empty(void *address, size_t size);