doc: Added suit and smp doc

Added suit and smp doc.

Signed-off-by: Francesco Domenico Servidio <[email protected]>

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_device_config.rst
    ug_nrf54h20_suit_customize_qsg.rst
    ug_nrf54h20_suit_customize_dfu.rst
+   ug_nrf54h20_suit_smp.rst
    ug_nrf54h20_suit_fetch
    ug_nrf54h20_suit_push
    ug_nrf54h20_suit_external_memory

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

@@ -0,0 +1,224 @@
+.. _ug_nrf54h20_suit_smp:
+
+SUIT and SMP protocol (including SUIT SMP extension)
+####################################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+Adopting SUIT as a firmware update method offers a flexible and extensible update process.
+This document illustrates how the Zephyr management subsystem, via the SMP protocol, can be leveraged to manage SUIT-based images alongside existing MCUBoot images, providing an efficient approach to firmware management.
+
+Slots and Images in Zephyr
+==========================
+
+In the nRF Connect SDK, *slot* and *image* concepts are derived from MCUboot.
+An *image* consists of two slots: a *primary* and a *secondary*.
+The application runs from the primary slot, while updates are uploaded to the secondary slot.
+MCUboot is responsible for swapping these slots during boot.
+
+The slots support a single upgradable application, with equal sizes.
+Zephyr supports up to two images, each represented by an index.
+
+.. note::
+   Image metadata, such as version information, is embedded within the image payload.
+
+Components in SUIT
+==================
+
+SUIT defines a *component* as an updatable logical block, which can be firmware, software, configuration, or data.
+This is similar to how MCUmgr defines an *image*.
+Updates are delivered to the device as a SUIT *envelope,* containing SUIT manifests and, optionally, integrated payloads.
+The relationships between components are maintained through SUIT manifests.
+
+The SUIT envelope serves as the main metadata source for the payload.
+Adding metadata inside the image can lead to synchronization issues, as the lifecycles of the envelope and image may diverge.
+Therefore, manage metadata at the envelope level.
+
+MCUmgr and SUIT - Key Similarities and Differences
+===================================================
+
+The following table summarizes key similarities and differences between MCUmgr and SUIT:
+
++-----------------------------+-------------------------+----------------------------------+
+| Feature                     | MCUmgr                  | SUIT                             |
++=============================+=========================+==================================+
+| Metadata                    | Attached to the images  | Defined by a separate SUIT       |
+|                             |                         | manifest                         |
++-----------------------------+-------------------------+----------------------------------+
+| Image Topology              | Slots (primary,         | Tree structure with manifests    |
+|                             | secondary) organized as | grouped into a hierarchical tree |
+|                             | a list                  |                                  |
++-----------------------------+-------------------------+----------------------------------+
+| Slot/Image Configuration    | Slots defined in        | Slot definitions can be modified |
+|                             | MCUboot; difficult to   | via the SUIT manifest, allowing  |
+|                             | change after deployment | greater flexibility              |
++-----------------------------+-------------------------+----------------------------------+
+| Installation/Boot           | Limited by static       | Fully customizable through SUIT  |
+| Customization               | image metadata          | manifest directives              |
++-----------------------------+-------------------------+----------------------------------+
+
+Versioning Information
+----------------------
+
+MCUmgr and SUIT use different structures for versioning:
+
+- MCUmgr: Uses ``struct image_version`` with fields for ``major``, ``minor``, ``revision``, and ``build_num``.
+- SUIT: Utilizes a manifest sequence number.
+
+State Information
+-----------------
+
+- MCUmgr: Update state is embedded within the image slot metadata.
+- SUIT: Update candidate existence is represented within the SUIT manifest.
+
+Using MCUmgr SMP Protocol with SUIT
+===================================
+
+Get State of Images Request
+---------------------------
+
+This command retrieves images and their states.
+The response is in CBOR format:
+
+.. code-block:: cbor
+
+    {
+      *images*: [
+          {
+            *image*: 0,             // SUIT - always 0, as the system is represented as a *single image*
+            *slot*: 0,              // 0 for primary (installed), 1 for secondary (update candidate)
+            *version*: *v1.0.0*,   // Sequence number from root manifest
+            *hash*: *<digest>*,    // Digest of root manifest
+            *bootable*: true,       // Root manifest is always bootable
+            *pending*: true,        // True if an update candidate is delivered
+            *confirmed*: false,     // Not applicable for SUIT (no rollback)
+            *active*: false,        // Not applicable for SUIT manifests
+            *permanent*: false      // Not applicable for SUIT
+          }
+      ]
+    }
+
+Set State of Image Request
+--------------------------
+
+This command is not applicable to SUIT since it does not support slot swapping or rollback.
+
+Image Upload Request
+--------------------
+
+This command uploads an image to the device.
+Payloads for all SUIT components are delivered integrally.
+The CBOR data format is:
+
+.. code-block:: cbor
+
+    {
+        *image*: 0,             // SUIT - always 0 as a *single image*
+        *len*: <length>,
+        *off*: <offset>,
+        *sha*: *<sha256>*,
+        *data*: <payload>
+    }
+
+Image Erase Request
+-------------------
+
+This command clears the content of the DFU partition when using SUIT.
+
+Feasibility Analysis
+====================
+
+The following table describes the feasibility of using existing tools to work with SUIT:
+
++-----------------------------+--------------------------------------+--------------------------------+
+| Tool                        | Get State of Images Request          | Image Upload                   |
++=============================+======================================+================================+
+| Android Device Manager Tool | Supports version info retrieval;     | Does not support non-MCUboot   |
+|                             | unsupported flags are displayed as   | compatible files.              |
+|                             | false.                               |                                |
++-----------------------------+--------------------------------------+--------------------------------+
+| MCUmgr Command Line Tool    | Works as expected; supports strings  | Accepts files that are not     |
+|                             | for version information.             | MCUboot compatible.            |
++-----------------------------+--------------------------------------+--------------------------------+
+| Zephyr                      | Support for SUIT to be implemented   |                                |
+|                             | in ``zephyr/subsys/mgmt/mcumgr/lib/ |                                |
+|                             | cmd/img_mgmt``.                      |                                |
++-----------------------------+--------------------------------------+--------------------------------+
+
+SUIT SMP Protocol Extension
+===========================
+
+The existing image management approach works well for basic scenarios involving single-step SUIT envelope pushes.
+More advanced scenarios require defining a new SMP management group.
+
+Management Group ID
+-------------------
+
+The new SUIT SMP protocol will use ``MGMT_GROUP_ID_PERUSER + 2`` (i.e., 66), as ``MGMT_GROUP_ID_PERUSER + 1`` is already allocated for Full Modem Firmware Update for nRF9160.
+
+Commands
+--------
+
+Get SUIT Manifests List Request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This command retrieves the roles of the manifests supported by the device.
+
+Command ID: 0
+
+CBOR Data of Successful Response:
+
+.. code-block:: cbor
+
+    {
+        *rc*: 0,
+        *manifests*: [
+            {
+                *role*: <uint>   // Manifest role encoded as domain ID and index
+            }
+        ]
+    }
+
+Get SUIT Manifest State Request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This command provides information about a specific manifest, including configuration and selected attributes.
+
+Command ID: 1
+
+CBOR Data of Successful Response:
+
+.. code-block:: cbor
+
+    {
+        *rc*: 0,
+        *class_id*: *<uuid>*,
+        *vendor_id*: *<uuid>*,
+        *downgrade_prevention_policy*: <uint>,
+        *independent_updateability_policy*: <uint>,
+        *signature_verification_policy*: <uint>,
+        *digest*: *<digest>*,
+        *digest_algorithm*: <int>,
+        *signature_check*: <uint>,
+        *sequence_number*: <uint>,
+        *semantic_version*: [<int>, <int>, <int>, <int>, <int>]
+    }
+
+Additional Commands
+-------------------
+
+- Candidate Envelope Upload Request (Command ID: 2): Uploads a SUIT envelope to the device.
+- Get Missing Image State Request (Command ID: 3): Retrieves information about images that need to be updated.
+- Image Upload Request (Command ID: 4): Used for uploading a requested image.
+- Cache Raw Image Upload Request (Command ID: 5): Uploads an image to a specified cache pool.
+- Cleanup Request (Command ID: 6): Clears the DFU and cache partitions.
+
+Return Codes
+------------
+
+Each command may return specific status codes, including:
+
+- ``MGMT_ERR_ENOTSUP``: Unsupported command.
+- ``MGMT_ERR_EMSGSIZE``: Unable to encode the response due to insufficient RAM buffer size.