Skip to content

Commit

Permalink
doc: update SUIT firmware upgrade with external flash
Browse files Browse the repository at this point in the history 
Updated the SUIT firmware upgrade documentation to reflect the latest
state.

Signed-off-by: Rafał Kuźnia <[email protected]>
  • Loading branch information
@e-rk
e-rk committed Jun 3, 2024
1 parent 0cdcc91 commit cfc49ad
Show file tree
Hide file tree
Showing 3 changed files with 75 additions and 47 deletions.
79 changes: 54 additions & 25 deletions doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,43 +51,43 @@ 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:

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. Power-up the external flash chip on nRF54H20 DK using the `nRF Connect Board Configurator`_ app in `nRF Connect for Desktop`_ .

.. code-block:: devicetree
&mram0 {
partitions {
companion_partition: partition@116000 {
label = "companion-image";
reg = <0x116000 DT_SIZE_K(64)>;
};
};
};
.. note::
This step is needed only on nRF54H20 DK. Skip this step if you are using different hardware.

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 :ref:`suit_flash_companion` 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.
It must follow the ``dfu_cache_partition_<n>`` format.
The number at the end determines the ``CACHE_POOL`` ID, which will be used later in the SUIT manifest.
The number must be between greater than 0 and less than :kconfig:option:`CONFIG_SUIT_CACHE_MAX_CACHES`.
The Secure Domain firmware supports up to 8 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:
...
Expand All @@ -98,21 +98,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
Expand All @@ -121,18 +121,47 @@ 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.

.. code-block:: console
$ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild
$ west flash
The build system will automatically generate :file:`build/suit.zip` archive, which contains the SUIT envelope and candidate images.

#. Build a new version of the application with 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.

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.

#. Tap the :guilabel:`SELECT FILE` button and select the :file:`suit.zip` archive.

#. Tap the :guilabel:`UPLOAD` button.

#. Initiate 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 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.
36 changes: 17 additions & 19 deletions doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_fetch.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,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.
Expand All @@ -38,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.
Expand All @@ -54,14 +54,14 @@ 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
Expand All @@ -80,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:
...
Expand All @@ -101,7 +101,7 @@ To reconfigure the sample to use the fetch model, complete the following steps:

#. Add the ``suit-payload-fetch`` sequence to the application manifest:

.. code-block:: console
.. code-block:: yaml
suit-payload-fetch:
- suit-directive-set-component-index: 2
Expand All @@ -110,13 +110,6 @@ 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 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.

.. code-block:: diff
Expand All @@ -130,8 +123,13 @@ 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.
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://``.

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:
Expand All @@ -142,8 +140,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 candidate image into the envelope.
However, you may still choose to integrate certain payloads.

Creating a custom fetch source
******************************
Expand Down
7 changes: 4 additions & 3 deletions samples/suit/flash_companion/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,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)>;
};
};
Expand All @@ -95,13 +95,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 and flashed automatically by Sysbuild.

Dependencies
************
Expand Down

0 comments on commit cfc49ad

Please sign in to comment.