DFU target

The DFU target library provides an API that supports different types of firmware upgrades against a single interface.

Overview 

The DFU target library collects sequentially the image data received from a transport protocol. It then saves the data using buffered writes, resulting in fewer write operations and faster response times seen by the application. The library also takes away, from the application, the responsibility of calculating the data-chunk write offset.

Common application flow 

Each of the supported upgrade types follow the common DFU flow.

Initialize the specific DFU target by calling the dfu_target_init() function.

Internally, it uses the image type and image number to decide which target to initialize.
Ask the offset of already downloaded blocks by calling the dfu_target_offset_get() function.

This step is optional, but it allows the application to skip the blocks that are already downloaded. All targets do not necessarily support it.
Write a block of DFU image into the target by calling the dfu_target_write() function.

Repeat until all blocks have been downloaded.
When all downloads have completed, call the dfu_target_done() function to tell the DFU library that the process has completed.
When the application is ready to install the image, call the dfu_target_schedule_update() function to mark it as ready for update.

Some targets perform the installation automatically on next boot.

To cancel an ongoing operation, call the dfu_target_reset() function. This clears up any images that have already been downloaded or even marked to be updated. This is different than aborting a download by calling the dfu_target_done() function, in which case the same download can be resumed later by initializing the same target.

Supported upgrade types 

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

You can use MCUboot-style firmware upgrades for updates to the application and to the upgradable bootloader. This type of DFU writes the data given to the dfu_target_write() function into the secondary slot specified by MCUboot’s flash memory partitions. Depending on the type of upgrade, it has the following behavior:

For application updates, the new image replaces the existing application.
For bootloader updates, the new firmware is placed in the non-active partition (slot 0 or slot 1, see Second-stage upgradable bootloader).

The MCUboot target type supports multiple image pairs, like the application core image pair and the network core image pair, to support multi-image updates where the device contains two or more executable images at once.

Note

When updating the bootloader, ensure that the provided bootloader firmware is linked against the correct partition. This is handled automatically by the FOTA download library.

When the image data transfer is completed, the application using the DFU target library must do the following:

Call the dfu_target_done() function to finish the image data collection.
Call the dfu_target_schedule_update() function to mark the firmware as ready to be booted. On the next reboot, the device will run with the new firmware.

After that, the application can call the dfu_target_init() function for another image pair index.

Note

The application can schedule the upgrade of all the image pairs at once using the dfu_target_schedule_update() function.

Modem delta upgrades

This type of firmware upgrade is used for delta upgrades to the modem firmware (see: Delta firmware updates). The modem stores the data in the memory location reserved for firmware patches. If there is already a firmware patch stored in the modem, the library requests the modem to delete the old firmware patch to make space for the new patch.

When the transfer has completed, the application must call the dfu_target_done() function to release modem resources and then call dfu_target_schedule_update() to request the modem to apply the patch. On the next reboot, the modem tries to apply the patch.

If an existing image needs to be removed, even if it is marked to be updated, the application may call the dfu_target_reset() function, which erases the DFU area and prepares it for next download.

Full modem upgrades

Note

An external flash memory with minimum 4 MB is required for this type of upgrade.

This type of firmware upgrade supports updating the modem firmware using the serialized firmware bundled in the zip file of the modem firmware release. The serialized firmware file uses the .cbor extension.

This DFU target downloads the serialized modem firmware to an external flash memory. Once the modem firmware has been downloaded, the application should use Full modem firmware update from flash device to write the firmware to the modem. The DFU target library does not perform the upgrade and calling the dfu_target_schedule_update() function has no effect.

SUIT-style upgrades

SUIT-style firmware upgrades can be used for Device Firmware Update using SUIT. Depending on the image number and the used SUIT system configuration, this type of DFU writes the data provided to the 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 dfu_target_init() and dfu_target_write() functions, the application must call the 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:

SUIT minimal processing is used for devices that do not have a cache partition. To enable it, set the 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.

The SUIT cache processing requires one of the following SUIT system configurations set to y:

CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_FULL
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 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 SUIT multi-image package uses this approach for multi-image updates.

To read more about SUIT cache processing, see the Firmware upgrade with external memory guide.

Make sure the application calls the 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 dfu_target_done() function for each subsequent image. After that, the application can call the 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:

Call the dfu_target_schedule_update() function to inform SUIT that the manifests can be processed.
Automatically reboot the device by calling dfu_target_suit_reboot() with a defined delay. You can set the delay before rebooting the device by configuring the 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 dfu_target_schedule_update() function. During this operation, the manifests stored in the dfu_partition partition will be processed.

Configuration 

Configuring the library requires making edits to your component and using Kconfig options.

Enabling the library 

Every supported DFU target must implement the set of functions defined in the subsys/dfu/src/dfu_target.c file.

When initializing the DFU target library, you must provide information about the type of firmware upgrade. To do this automatically, send the first fragment of the firmware to the dfu_target_img_type() function. This function can identify all supported firmware upgrade types. The result of this call can then be given as input to the dfu_target_init() function.

Note

After starting a DFU procedure for a given target, you cannot initialize a new DFU procedure with a different firmware file for the same target until the pending DFU procedure has completed successfully or the device has been restarted.

Disabling support for specific DFU targets 

You can disable support for specific DFU targets using the following options:

Maintaining writing progress after reboot 

You can let the application maintain the writing progress in case the device reboots. Enable the following options:

The MCUboot target will then use the Settings subsystem in Zephyr to store the current progress used by the dfu_target_write() function across power failures and device resets.

Using a dedicated partition for full modem upgrades 

External flash partitions require the chosen node nordic,pm-ext-flash to be set to the external flash device in devicetree, see Partition Manager for details. When nordic,pm-ext-flash is set, the Partition Manager will add the partition fmfu_storage to the external flash region.

API documentation 

Header file: include/dfu/dfu_target.h

Source files: subsys/dfu/dfu_target/src/

DFU Target