diff --git a/doc/nrf/device_guides/nrf54h.rst b/doc/nrf/device_guides/nrf54h.rst index f28e0e7f72c9..23c78aa84dcd 100644 --- a/doc/nrf/device_guides/nrf54h.rst +++ b/doc/nrf/device_guides/nrf54h.rst @@ -28,5 +28,6 @@ Zephyr and the |NCS| provide support and contain board definitions for developin working_with_nrf/nrf54h/ug_nrf54h20_gs working_with_nrf/nrf54h/ug_nrf54h20_architecture working_with_nrf/nrf54h/ug_nrf54h20_configuration + working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu working_with_nrf/nrf54h/ug_nrf54h20_debugging working_with_nrf/nrf54h/ug_nrf54h20_custom_pcb diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_default_manifest_topology.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_default_manifest_topology.png index ffe7f73da250..44d979f9782d 100644 Binary files a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_default_manifest_topology.png and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_default_manifest_topology.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_compare_other_dfu.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_compare_other_dfu.rst index ae32254c9a9e..d8955bb26be1 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_compare_other_dfu.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_compare_other_dfu.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_compare_other_dfu: DFU and bootloader comparison @@ -10,9 +8,9 @@ It provides a more flexible and tailored DFU experience compared to the MCUboot See the diagram and comparison table below for further comparison. .. figure:: images/nrf54h20_suit_mcuboot_comparison.png - :alt: MCUboot and SUIT architecture comparison + :alt: MCUboot and SUIT, and nRF Secure Immutable Bootloader architecture comparison - MCUboot and SUIT architecture comparison + MCUboot, SUIT, and |NSIB| architecture comparison +--------------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ | Characteristic | MCUboot | SUIT | nRF Secure Immutable Bootloader | diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_components.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_components.rst index e4443c37fb27..80cddd0edbe5 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_components.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_components.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_components: SUIT components diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst index 1a3c1dbdc6d2..6686eb8bd674 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_customize_dfu: How to customize the SUIT DFU process @@ -9,7 +7,7 @@ How to customize the SUIT DFU process :local: :depth: 2 -Nordic Semiconductor provides a Software Update Internet of Things (SUIT) sample (```nrf54h_suit_sample``) which uses predefined configurations in the build system. +Nordic Semiconductor provides a Software Update Internet of Things (SUIT) sample (:ref:`ug_nrf54h20_suit_intro`) which uses predefined configurations in the build system. The specified Kconfig options in the sample can be used to customize the DFU process and integrate the DFU solution with external build systems. This guide provides a comprehensive set of instructions for modifying values in the :ref:`SUIT manifest `. @@ -22,7 +20,7 @@ It consists of two main concepts: the SUIT envelope and the SUIT manifest. * The SUIT envelope acts as a secure container for transporting firmware updates, encapsulating the firmware binary and its manifest. * The SUIT manifest is a structured file with metadata essential for the update process, including firmware version, size, and hash for integrity verification. -During the first build of the ``nrf54h_suit_sample``, default manifest templates are provided. +During the first build of the :ref:`nrf54h_suit_sample`, default manifest templates are provided. These templates form the basis for generating SUIT envelopes and manifests tailored to specific application requirements. Customization of these templates is crucial for specific use cases and security requirements. @@ -67,16 +65,16 @@ These templates, suitable for standard development needs, are automatically plac Customizing UUIDs in the manifest templates enhances security and is recommended for specific use cases. For information about adding custom UUID values, refer to the :ref:`ug_suit_using_manifest_gen` section. -After the first build of the ``nrf54h_suit_sample``, three additional files are created in the :file:`nrf/samples/suit/smp_transfer` directory (or two levels above the build directory when using the ``west -d`` parameter): +After the first build of the :ref:`nrf54h_suit_sample`, three additional files are created in the :file:`nrf/samples/suit/smp_transfer` directory (or two levels above the build directory when using the ``west -d`` parameter): * Root manifest - :file:`root_hierarchical_envelope.yaml.jinja2` -* Application Domain manifest - :file:`app_envelope.yaml.jinja2` -* Radio Domain manifest - :file:`rad_envelope.yaml.jinja2` +* Application domain manifest - :file:`app_envelope.yaml.jinja2` +* Radio domain manifest - :file:`rad_envelope.yaml.jinja2` The destination directory for these :file:`jinja2` file templates can be changed by setting the :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION` Kconfig option. .. note:: - The Radio Domain manifest template is available only for the Bluetooth® Low Energy version of the ``nrf54h_suit_sample``, not the UART version. + The radio domain manifest template is available only for the Bluetooth® Low Energy version of the :ref:`nrf54h_suit_sample`, not the UART version. .. _ug_suit_change_manifest_location: @@ -140,9 +138,9 @@ The following files should be used to create DFU envelope: * Root envelope - :file:`root.yaml.jinja2` -* Application Domain - :file:`app.yaml.jinja2` +* Application domain - :file:`app.yaml.jinja2` -* Radio Domain - :file:`radio.yaml.jinja2` +* Radio domain - :file:`radio.yaml.jinja2` .. figure:: images/nrf54h20_suit_example_update_process.png :alt: Example update process @@ -197,7 +195,7 @@ The component values are filled out automatically by the build system during the Variables in the provided templates, like memory ranges and paths to binaries, are filled out by the build system. However, values like ``class-identifier`` and ``vendor-identifier`` should be customized manually. -An example of a YAML representation for a basic installation and invoke-process of the Application firmware could look like the following: +An example of a YAML representation for a basic installation and invoke-process of the application firmware could look like the following: .. code-block:: @@ -247,7 +245,7 @@ An example of a YAML representation for a basic installation and invoke-process '#app': ``/path/to/application_fw.bin`` .. note:: - Default values of OEM-controlled manifests (related to the Application and Radio Domains) are hardcoded in the SDFW, but you can overwrite these values and this is strongly recommended. + Default values of OEM-controlled manifests (related to the application and radio domains) are hardcoded in the SDFW, but you can overwrite these values and this is strongly recommended. The ``class-identifier`` and ``vendor-identifier`` values in the manifest templates, like :file:`app_envelope_yam.jinja2`, can be modified to suit specific requirements. For example, changing these values from `nordicsemi.com` to a custom vendor or class identifier enhances the specificity and security of the DFU process. @@ -308,7 +306,7 @@ The manifest templates have access to the following: Some of these values are stored in the Python dictionaries that are named after the target name. (Therefore, Python is used within the ``.jinja2`` files to fill in the necessary values in the manifest(s).) -For example, for the ``nrf54h_suit_sample`` there will be two variables available: ``app`` and ``hci_rpmsg_subimage``. +For example, for the :ref:`nrf54h_suit_sample` there will be two variables available: ``app`` and ``hci_rpmsg_subimage``. Each variable is a Python dictionary type (``dict``) containing the following keys: * ``name`` - name of the target @@ -375,7 +373,7 @@ For more information, see the file available in the sample and `Jinja ` (conditions and directives) as well as the concept of :ref:`components `. To use the SUIT DFU in a product you need to customize it. -You can learn about this in the :ref:`ug_nrf54h20_suit_customize_dfu` page, which involves using the ``nrf54h_suit_sample`` sample. +You can learn about this in the :ref:`ug_nrf54h20_suit_customize_dfu` page, which involves using the :ref:`nrf54h_suit_sample` sample. + +For a list of available SUIT samples, see the :ref:`suit_samples` page. .. toctree:: :maxdepth: 2 :caption: Subpages: - ug_nrf54h20_suit_customize_qsg.rst - ug_nrf54h20_suit_customize_dfu.rst ug_nrf54h20_suit_intro.rst ug_nrf54h20_suit_manifest_overview.rst + ug_nrf54h20_suit_customize_qsg.rst + ug_nrf54h20_suit_customize_dfu.rst + ug_nrf54h20_suit_fetch + ug_nrf54h20_suit_external_memory ug_nrf54h20_suit_components.rst ug_nrf54h20_suit_hierarchical_manifests.rst - ug_nrf54h20_suit_why.rst ug_nrf54h20_suit_compare_other_dfu.rst diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst index 465c6a8e65c2..72bd0c39f53a 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_external_memory: Firmware upgrade with external memory @@ -9,8 +7,9 @@ Firmware upgrade with external memory :local: :depth: 2 -Storing firmware upgrade data in external memory poses a unique challenge on nRF54H20 DK, because the secure domain is unable to access the external memory by itself. -The application domain is used as a proxy for the secure domain to access the external memory. +The Secure Domain firmware is unable to access the external memory by itself. +However, the application domain can implement an IPC service, which allows the Secure Domain firmware to access the external memory with application domain serving as a proxy. +This guide explains how to prepare the application domain firmware and the SUIT envelope to perform SUIT firmware upgrade with external memory. .. note:: The prerequisite to this guide is the :ref:`ug_nrf54h20_suit_fetch` user guide, as this guide assumes that the application uses the fetch model to obtain the candidate images. @@ -18,10 +17,10 @@ The application domain is used as a proxy for the secure domain to access the ex The following terms are used in this guide: -* External memory (extmem) service - IPC service allowing the secure domain to use the application domain as a proxy when accessing external memory. +* External memory (extmem) service - IPC service allowing the Secure Domain to use the application domain as a proxy when accessing external memory. * Companion image - Application domain firmware implementing the extmem service and external memory driver. - The IPC service allows the secure domain to access the external memory. + The IPC service allows the Secure Domain to access the external memory. Overview of external memory in SUIT firmware updates **************************************************** @@ -29,66 +28,65 @@ Overview of external memory in SUIT firmware updates To use external memory with SUIT, the fetch model-based firmware upgrade is required. The SUIT envelope must always be stored in the non-volatile memory in the MCU. The SUIT manifests stored in the envelope contain instructions that the device must perform to fetch other required payloads. -To store payloads in the external memory, a DFU cache partition must be defined in the external memory's devicetree node. +To store payloads in the external memory, a Device Dirmware Update (DFU) cache partition must be defined in the external memory's devicetree node. In the SUIT manifest, you can define a component representing the cache partition in the external memory. Within the ``suit-payload-fetch`` sequence, you can then store any fetched payload into any ``CACHE_POOL`` component. -When the secure domain processes the ``suit-install`` sequence, issuing ``suit-directive-fetch`` on any non-integrated payload will instruct the secure domain firmware to search for a given URI in all cache partitions in the system. -However, when such a cache partition is located in the external memory, the secure domain is unable to access the data. +When the Secure Domain processes the ``suit-install`` sequence, issuing ``suit-directive-fetch`` on any non-integrated payload will instruct the Secure Domain firmware to search for a given URI in all cache partitions in the system. +However, when such a cache partition is located in the external memory, the Secure Domain is unable to access the data. Before any ``suit-directive-fetch`` directive is issued that accesses a payload stored on the external memory, a companion image that implements an external memory device driver must be booted. The companion image consists of two main parts: * Device driver adequate for the external memory device -* IPC service exposed towards the secure domain +* IPC service exposed towards the Secure Domain -When the companion image is booted and a directive that accesses the data on the external memory is issued, such as the ``suit-directive-fetch`` and ``suit-directive-copy`` directives, the secure domain firmware uses the IPC service provided by the companion image to access the contents of the external memory. +When the companion image is booted and a directive that accesses the data on the external memory is issued, such as the ``suit-directive-fetch`` and ``suit-directive-copy`` directives, the Secure Domain firmware uses the IPC service provided by the companion image to access the contents of the external memory. Beyond the booting of the companion image, the update process does not differ from regular fetch model-based update. Enabling external flash support in SUIT DFU ******************************************* -The :file:`nrf/samples/suit/smp_transfer` sample contains a premade configuration enabling the external memory in SUIT DFU. -To enable the external memory, you must apply the :file:`nrf/samples/suit/smp_transfer/overlay-extmem.conf` and :file:`nrf/samples/suit/smp_transfer/ext_flash_nrf54h20dk.overlay` overlays to the sample build or complete the following steps: +The :ref:`nrf54h_suit_sample` sample contains a premade configuration enabling the external memory in SUIT DFU. +To enable the external memory, you must add the ``-DFILE_SUFFIX="extflash"`` argument to the build, or complete the following steps: -1. Create a partition named ``companion_partition`` in the executable memory region that is accessible to the application domain by editing the devicetree (DTS) file: +1. Turn on the external flash chip on the nRF54H20 DK using the `nRF Connect Board Configurator`_ app within `nRF Connect for Desktop`_ . - .. code-block:: devicetree + .. note:: + This step is needed only on nRF54H20 DK. Skip this step if you are using different hardware. - &mram0 { - partitions { - companion_partition: partition@116000 { - label = "companion-image"; - reg = <0x116000 DT_SIZE_K(64)>; - }; - }; - }; - - The ``companion_partition`` is the region where the companion image will be executed. - Adjust the addresses accordingly to your application. +#. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Sysbuild Kconfig option, which enables the build of the reference companion image. + See the :ref:`suit_flash_companion` user guide for instructions on how to configure the companion image using Sysbuild. #. Define a new DFU cache partition in the external memory in the DTS file: .. code-block:: devicetree - mx66um1g: mx66um1g45g@0 { + &mx25uw63 { ... + status = "okay"; partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + dfu_cache_partition_1: partition@0 { - reg = <0x0 DT_SIZE_K(512)>; + reg = <0x0 DT_SIZE_K(1024)>; }; }; }; - Note the name of the partition. + Note that the name of the partition must follow the following formate: ``dfu_cache_partition_``. The number at the end determines the ``CACHE_POOL`` ID, which will be used later in the SUIT manifest. + This number must be between greater than 0 and less than the value of :kconfig:option:`CONFIG_SUIT_CACHE_MAX_CACHES`. + The Secure Domain firmware supports up to eight DFU cache partitions. #. Modify the application manifest file :file:`app_envelope.yaml.jinja2` by completing the following: a. Modify the ``CACHE_POOL`` identifier in the SUIT manifest: - .. code-block:: console + .. code-block:: yaml suit-components: ... @@ -99,21 +97,21 @@ To enable the external memory, you must apply the :file:`nrf/samples/suit/smp_tr #. Append the ``MEM`` type component that represents the companion image in the same SUIT manifest file: - .. code-block:: console + .. code-block:: yaml suit-components: ... - - MEM - - {{ flash_companion_subimage['dt'].label2node['cpu'].unit_addr }} - - {{ get_absolute_address(flash_companion_subimage['dt'].chosen_nodes['zephyr,code-partition']) }} - - {{ flash_companion_subimage['dt'].chosen_nodes['zephyr,code-partition'].regs[0].size }} + - {{ flash_companion['dt'].label2node['cpu'].unit_addr }} + - {{ get_absolute_address(flash_companion['dt'].chosen_nodes['zephyr,code-partition']) }} + - {{ flash_companion['dt'].chosen_nodes['zephyr,code-partition'].regs[0].size }} In this example, the component index is ``3``. In the following steps, the companion image component is selected with ``suit-directive-set-component-index: 3``. #. Modify the ``suit-install`` sequence to boot the companion image before accessing the candidate images, which are stored in the external memory: - .. code-block:: console + .. code-block:: yaml suit-install: - suit-directive-set-component-index: 3 @@ -122,18 +120,46 @@ To enable the external memory, you must apply the :file:`nrf/samples/suit/smp_tr The companion image can be optionally upgraded and have its integrity checked. -#. Enable the :kconfig:option:`CONFIG_SUIT_EXTERNAL_MEMORY_SUPPORT` Kconfig option, which enables the build of the reference companion image to be used as a child image of the application firmware. - It also enables other additional options that are required for the external memory DFU to work. +#. Build and flash the application by completing the following: + + .. code-block:: console + + $ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild + $ west flash + + The build system will automatically generate a :file:`build/suit.zip` archive, which contains the SUIT envelope and candidate images. + +#. Build a new version of the application with the incremented :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM` value. + +#. Download the new :file:`suit.zip` archive to your mobile device. + +#. Use the `nRF Connect Device Manager`_ mobile app to update your device with the new firmware by completing the following: + + a. Ensure that you can access the :file:`suit.zip` archive from your phone or tablet. + + #. In the mobile app, scan and select the device to update. + + #. Switch to the :guilabel:`Image` tab. + + #. Press the :guilabel:`SELECT FILE` button and select the :file:`suit.zip` archive. + + #. Press the :guilabel:`START` button. + This initiates the DFU process of transferring the image to the device. + + The Device Manager mobile application will unpack the file and upload the SUIT envelope to the device. + The firmware images will be uploaded separately by the mobile application to the device, if the device requests it. + + #. Wait for the DFU to finish and then verify that the application works properly. Create custom companion images ****************************** -Nordic Semiconductor provides a reference companion image in the :file:`samples/suit/flash_companion` file, which can serve as a base for developing a customized companion image. +Nordic Semiconductor provides a reference companion image in the :file:`samples/suit/flash_companion` directory, which can serve as a base for developing a customized companion image. Limitations *********** -* The secure domain and companion image candidates must always be stored in MRAM. +* The Secure Domain, System Controller and companion image update candidates must always be stored in the MRAM. Trying to store those candidates in external memory will result in failure during the installation process. * The companion image needs a dedicated area in the executable region of the MRAM that is assigned to the application domain. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_fetch.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_fetch.rst index ed3c80028f41..aeca1ae9a7b8 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_fetch.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_fetch.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_fetch: How to fetch payloads @@ -13,7 +11,7 @@ In the Software Updates for Internet of Things (SUIT), it is possible for a devi 1. The push model - where all necessary candidate images are integrated into the SUIT envelope, and uploaded to a device as a single unit. -#. The fetch model - where the envelope contains 0 or not all necessary candidate images, and is performed by the application firmware. +#. The fetch model - where the envelope contains 0 or not all necessary candidate images. The manifest contains logic that instructs the device to fetch other required candidate images through a user-defined mechanism during the envelope processing. This guide explains how to reconfigure an application that uses the push model to a fetch model-based upgrade. @@ -40,7 +38,7 @@ The fetch model has greater flexibility compared to the push model in the follow For example, fetching up-to-date firmware can be completely skipped, which saves battery life and transfer costs. * Custom fetch source can be implemented. - Nordic Semiconductor provides a reference fetch source implementation which uses the SMP protocol over serial or Bluetooth® LE. + Nordic Semiconductor provides a reference fetch source implementation which uses the SMP protocol over serial or Bluetooth® LE. You have the option to implement any fetching mechanism needed for the application, such as fetching from an HTTP resource. * Candidate images can be stored in a different memory partition than the envelope itself. @@ -50,20 +48,20 @@ The fetch model has greater flexibility compared to the push model in the follow Migrating from push-based to fetch-based firmware upgrade ********************************************************* -The ``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. +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 use the fetch model, complete the following steps: 1. Enable the following three Kconfig options: * :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_FULL` - This enables SUIT envelope processing in the application firmware. - The application firmware will execute the ``suit-payload-fetch`` sequence, if is already in the root manifest. + The application firmware will execute the ``suit-payload-fetch`` sequence, if it is defined in the root manifest. * :kconfig:option:`CONFIG_MGMT_SUITFU_GRP_SUIT_CAND_ENV_UPLOAD` and :kconfig:option:`CONFIG_MGMT_SUITFU_GRP_SUIT_IMAGE_FETCH`. These options enable Nordic Semiconductor's reference implementation of the SMP-based fetch source. In this implementation, the SMP server (the device being updated) uses the SMP client (a computer or a mobile phone) as a proxy to fetch the required candidate images. -#. Add the ``suit-payload-fetch`` sequence to the root manifest :file:`root_hierarchical_envelope.yaml.jinja2`: +#. Add the ``suit-payload-fetch`` sequence to the root manifest :file:`root_with_binary_nordic_top.yaml.jinja2`: - .. code-block:: console + .. code-block:: yaml suit-payload-fetch: - suit-directive-set-component-index: 0 @@ -82,13 +80,13 @@ To reconfigure the sample to use the fetch model, complete the following steps: - suit-send-sysinfo-success - suit-send-sysinfo-failure - This instructs the SUIT processor to execute the ``suit-payload-fetch`` in the application manifest, which will be added in the next step. + This instructs the SUIT processor to execute the ``suit-payload-fetch`` sequence in the application manifest, which will be added in the next step. #. Modify the application manifest :file:`app_envelope.yaml.jinja2` by completing the following: a. Append the ``CACHE_POOL`` component: - .. code-block:: console + .. code-block:: yaml suit-components: ... @@ -112,12 +110,10 @@ To reconfigure the sample to use the fetch model, complete the following steps: - suit-directive-fetch: - suit-send-record-failure - #. Modify the ``suit-install`` sequence to use an identical URI, (as in the ``suit-payload-fetch``), instead of the integrated one: + The SUIT procedure attempts to use all fetch sources registered with :c:func:`suit_dfu_fetch_source_register` until one of them fetches the payload. + If no sources are able to fetch the payload, the update process ends with an error. - The SUIT procedure attempts to use all fetch sources registered with :c:func:`suit_dfu_fetch_source_register` until one of them fetches the payload. - If no sources are able to fetch the payload, the update process ends with an error. - - The reference SMP fetch source implementation only recognizes URIs that start with ``file://``. + The reference SMP fetch source implementation only recognizes URIs that start with ``file://``. #. Modify the ``suit-install`` sequence to use an identical URI, as in the ``suit-payload-fetch``, instead of the integrated one. @@ -132,9 +128,8 @@ To reconfigure the sample to use the fetch model, complete the following steps: - suit-directive-fetch: - suit-send-record-failure - When the secure domain firmware processes the ``suit-install`` sequence, this sequence of directives instructs the secure domain to search for a payload with a given URI in all cache partitions. - If no such payload is found, the update process ends with an error. - + When the secure domain firmware processes the ``suit-install`` sequence, this sequence of directives instructs the secure domain to search for a payload with a given URI in all cache partitions. + If no such payload is found, the update process ends with an error. #. Remove the application binary from the integrated payloads: @@ -144,8 +139,8 @@ To reconfigure the sample to use the fetch model, complete the following steps: - '#{{ app['name'] }}': {{ app['binary'] }} + suit-integrated-payloads: {} - In the fetch model-based firmware upgrade, it is not necessary to integrate the payload into the envelope. - However, you may still choose to integrate certain payloads. + In the fetch model-based firmware upgrade, it is not necessary to integrate the payload into the envelope. + However, you may still choose to integrate certain payloads. Creating a custom fetch source ****************************** diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_hierarchical_manifests.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_hierarchical_manifests.rst index ea941c7bb933..05c3e799a841 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_hierarchical_manifests.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_hierarchical_manifests.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_hierarchical_manifests: Hierarchical manifests @@ -19,7 +17,7 @@ Additionally, splitting the system into more than one part (each described by a * Assigning different signing authorities per system parts, (a single part is represented by a single SUIT manifest). * Assigning different access rights to certain memory locations on the device. - (Due to security reasons, the manifest representing the Radio Domain is not be able to install, alter, read-out images or memory locations assigned to the Application Domain.) + (Due to security reasons, the manifest representing the radio domain is not be able to install, alter, read-out images or memory locations assigned to the application domain.) * Possibility to assign different downgrade prevention or signing verification policies per single domain. @@ -43,7 +41,7 @@ The following image shows the default manifest topology for the nRF54H20 SoC: Default manifest topology for the nRF54H20 SoC -Manifest located in the lowest positions of the hierarchy (such as the Application Local, Radio Local, System Controller, SDFW, and SDFW_Recovery manifests) contain a specific updatable image for a specific core/domain of the device. +Manifest located in the lowest positions of the hierarchy (such as the application local, radio local, System Controller, SDFW, and SDFW_Recovery manifests) contain a specific updatable image for a specific core/domain of the device. The Nordic Top manifest coordinates update and invocation logic for its dependencies (System Controller and SDFW). The root manifest bundles all other manifests together and coordinates the entire DFU process. @@ -55,7 +53,7 @@ An example of how this would be implemented includes: * A root manifest that coordinates update and invocation processes on its dependency manifests. It does not belong to any domain or control any local domain resources. - * A dependency manifest for each of the domains, such as the Application and Radio Domains. + * A dependency manifest for each of the domains, such as the application and radio domains. * Nordic Semiconductor controlled manifests - for the SecDom, including the System Controller. They will be released by Nordic Semiconductor and can be incorporated into the firmware update package prepared by the OEM. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_intro.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_intro.rst index ca2ee4af4078..8504878ef289 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_intro.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_intro.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_intro: Introduction to SUIT @@ -10,7 +8,7 @@ Introduction to SUIT :depth: 2 This documentives an overview of SUIT and its characteristics. -See the ``nrf54h_suit_sample`` if you want to try using the SUIT procedure on the nRF54H20 SoC. +See the :ref:`nrf54h_suit_sample` if you want to try using the SUIT procedure on the nRF54H20 SoC. .. _ug_suit_overview: @@ -30,13 +28,13 @@ When it starts execution, it continues the SoC boot sequence according to the ma The local domain CPU firmware images are validated and started by the Secure Domain as instructed by the manifest. Once the invocation process is complete, the SDFW is still active and may serve specific requests from specified domains. -Therefore, unlike in MCUboot, the Application Core and other cores may use the SDFW services. +Therefore, unlike in MCUboot, the application core and other cores may use the SDFW services. (See the :ref:`ug_nrf54h20_suit_compare_other_dfu` page for more details and further comparison of SUIT with other DFU and bootloader procedures.) The bootloader SDFW image provided by Nordic Semiconductor is offered in binary form. Along with this, you can compose a final image with your own application image that is signed by your own keys. .. figure:: images/nrf54h20_suit_example_update_workflow.png - :alt: Example of the anticipated workflow for an Application Domain update using SUIT + :alt: Example of the anticipated workflow for an application domain update using SUIT .. _ug_suit_dfu_suit_concepts: diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_manifest_overview.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_manifest_overview.rst index 5ff14bcb44e2..feff87bdca23 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_manifest_overview.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_manifest_overview.rst @@ -1,5 +1,3 @@ -:orphan: - .. _ug_nrf54h20_suit_manifest_overview: SUIT manifest overview @@ -17,14 +15,14 @@ This includes the following: * A root manifest that contains the main execution instructions for the DFU within the different Domains. -* Two local manifests, one for the Application Domain, another for the Radio Domain. +* Two local manifests, one for the application domain, another for the radio domain. * Manifests for the SecDom, which are controlled by Nordic Semiconductor and cannot be modified. - This includes a Nordic "Top" manifest, one specifically for the SecDom firmware (SDFW), and the System Controller. + This includes a Nordic "Top" manifest, one specifically for the Secure Domain firmware (SDFW), and the System Controller. You can read more about manifest topology in the :ref:`ug_nrf54h20_suit_hierarchical_manifests` page. -Manifest templates are provided by Nordic Semiconductor, and automatically generated when you build the ``nrf54h_suit_sample`` sample. +Manifest templates are provided by Nordic Semiconductor, and automatically generated when you build the :ref:`nrf54h_suit_sample` sample. These templates work out-of-the-box for development and testing purposes. This document describes the contents of a SUIT manifest. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_why.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_why.rst deleted file mode 100644 index ab5426bfeb7b..000000000000 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_why.rst +++ /dev/null @@ -1,59 +0,0 @@ -:orphan: - -.. _ug_nrf54h20_suit_why: - -Why SUIT was selected as a bootloader and DFU procedure -####################################################### - -.. contents:: - :local: - :depth: 2 - -The nRF54H Series contains multiple CPU cores and images as opposed to other products by Nordic Semiconductor, such as the nRF52 Series. -Multiple CPU cores add more possibilities for development and complexity for operations such as performing a DFU. -This requires a DFU procedure that can address the needs of a single device containing multiple cores and multiple images. - -Therefore, the SUIT procedure was selected due to its features: - -* Script-based systems that allow you to customize the instructions for installation and invocation - -* Dependency management between multiple executable images - -* Support for multiple signing authorities that will be required for each dependency - -* Customization for the allocation of upgradeable elements - -.. note:: - - The term "invocation" is used in this document to mean "booting procedure". - -Script-based systems -******************** - -SUIT features a script-based system. -This contains high-level instructions collected into *command sequences*. -SUIT's command sequences allow you to express certain sequences for installation and invocation in an imperative way. -This offers flexibility in cases where, for example, you want to minimize the size of a download within the DFU lifecycle to increase flash efficiency. - -This allows for extensive management of dependencies between components, meaning you can execute different logic on different groups of components. -For example, the location of a slot or component does not have to be static and can be changed within the manifest. - -The script-based system also allows you to direct the manifest to download only the necessary, specified data. -You can do this, for example, by checking what is already in the device receiving the DFU or by checking the version number of the existing firmware. -This saves on both transfer cost and memory on the device. - -SUIT topology -************* - -SUIT features a topology which allows for dependency management between multiple executable images. -Additionally, the SUIT topology allows you to provide multiple signing authorities that will be required for each dependency. - -For information on the SUIT topology used by Nordic Semiconductor's implementation of SUIT, see the :ref:`ug_nrf54h20_suit_hierarchical_manifests` page. - -Allocation of components -************************ - -SUIT itself does not decide the component allocation, rather it can be defined in the manifest. -This is because their location is flexible and there are some options available to change the location of a specific image within the manifest. - -See the :ref:`ug_nrf54h20_suit_compare_other_dfu` page for further information on why SUIT was selected for DFU procedures for the nRF54H Series of SoC. diff --git a/samples/suit/flash_companion/README.rst b/samples/suit/flash_companion/README.rst index 260d566eaed2..65acb36341b0 100644 --- a/samples/suit/flash_companion/README.rst +++ b/samples/suit/flash_companion/README.rst @@ -1,5 +1,3 @@ -:orphan: - .. _suit_flash_companion: SUIT flash companion @@ -78,7 +76,7 @@ Perform the following steps in the main application directory: reg = <0xa6000 DT_SIZE_K(448)>; }; companion_partition: partition@116000 { - reg = <0x116000 DT_SIZE_K(64)>; + reg = <0x116000 DT_SIZE_K(36)>; }; }; @@ -95,13 +93,14 @@ Perform the following steps in the main application directory: status = "okay"; }; -#. Build the main application: +#. Build and flash the main application: .. code-block:: console $ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild + $ west flash -The flash companion sample will be built automatically by Sysbuild. +The flash companion sample will be built flashed automatically by Sysbuild. Dependencies ************ diff --git a/samples/suit/recovery/README.rst b/samples/suit/recovery/README.rst index 304249abc3fc..c078fa0ae2d8 100644 --- a/samples/suit/recovery/README.rst +++ b/samples/suit/recovery/README.rst @@ -1,5 +1,3 @@ -:orphan: - .. _suit_recovery: SUIT recovery application