Software Updates for Internet of Things (SUIT)

The Software Updates for Internet of Things (SUIT) Device Firmware Upgrade (DFU) library provides functionality to a local domain for for orchestrating the update based on the SUIT manifest.

Overview

The SUIT is the DFU and secure boot method for nRF54H Series of System-on-Chip. For a conceptual overview of the SUIT procedures, manifests, and components, read the Device Firmware Update using SUIT page.

The SUIT DFU library provides APIs to start and prepare the device before the update procedure begins. The preparation for the DFU can be described as a sequence within a SUIT manifest (suit-payload-fetch). To interpret and execute this sequence, a SUIT processor must be instantiated in the local domain’s firmware. This library provides a simplified API that manages the SUIT processor state, executes the fetching sequence from the SUIT manifest, and passes the update candidate information to the Secure Domain.

The application requires the following steps to perform the Device Firmware Update:

  1. Call suit_dfu_initialize() to initialize the SUIT DFU module before any other SUIT functionality is used. This function must be called only once, after the device drivers are ready.

  2. If the design of the DFU system used by this device allows for the fetch of additional data in the suit-payload-fetch sequence, register fetch sources using suit_dfu_fetch_source_register().

  3. Store the SUIT candidate envelope in the non-volatile memory area defined as dfu_partition in the devicetree.

  4. After the SUIT candidate envelope is stored, call suit_dfu_candidate_envelope_stored().

  5. Call suit_dfu_candidate_preprocess(). Any fetch source registered in step number 2 can be used by this function to fetch additional data.

  6. Call suit_dfu_update_start(). This will start the firmware update by resetting the device and passing control over the update to the Secure Domain.

In addition to this library, a compatibility layer for the DFU target is available. The compatibility layer is limited to updates that contain a single update binary and does not allow the local domain to process SUIT manifests. To use other upgrade schemes, the SUIT DFU API must be used.

Dependencies

This module uses the following nRF Connect SDK libraries and drivers:

This module also uses the following Zephyr drivers:

API documentation

Header file: include/dfu/suit_dfu.h
Source files: subsys/suit
group suit

Functions

int suit_dfu_initialize(void)

Initialize the SUIT DFU before it can be used.

Returns:

0 on success, non-zero value otherwise.

int suit_dfu_cleanup(void)

Purge all the SUIT DFU partitions and perform cleanup.

Call this if the update needs to be interrupted after suit_dfu_candidate_envelope_stored is called. This will purge the dfu_partition as well as all DFU cache partitions. To start the update again, the SUIT envelope must be downloaded again and SUIT DFU be reinitialized with suit_dfu_candidate_envelope_stored.

Returns:

0 on success, non-zero value otherwise.

int suit_dfu_candidate_envelope_stored(void)

Inform the SUIT module that the candidate envelope upload has ended.

After this stage no modifications to the candidate are allowed (unless the API user performs cleanup with suit_dfu_cleanup and restarts the update process).

Note

Modifications to DFU cache partitions are still allowed.

Returns:

0 on success, non-zero value otherwise.

int suit_dfu_candidate_preprocess(void)

Process all the information stored in the envelope, but do not start the update yet.

This function runs the SUIT processor on the envelope. If any fetch sources were registered using suit_dfu_fetch_source_register they might be used by the SUIT processor to pull any missing images. Also, cache partitions might be modified.

Returns:

0 on success, non-zero value otherwise.

int suit_dfu_update_start(void)

Start the update.

This will trigger a reset and pass the control to the Secure Domain in order to perform firmware update based on the installed envelope and other data stored in the SUIT DFU cache as a result of earlier operations.

Returns:

0 on success, non-zero value otherwise.