Device Firmware Upgrade

Overview

The Device Firmware Upgrade subsystem provides the necessary frameworks to upgrade the image of a Zephyr-based application at run time. It currently consists of two different modules:

subsys/dfu/boot/: Interface code to bootloaders
subsys/dfu/img_util/: Image management code

The DFU subsystem deals with image management, but not with the transport or management protocols themselves required to send the image to the target device. For information on these protocols and frameworks please refer to the Device Management section.

Flash Image

The flash image API as part of the Device Firmware Upgrade (DFU) subsystem provides an abstraction on top of Flash Stream to simplify writing firmware image chunks to flash.

API Reference

group flash_img_api

Abstraction layer to write firmware images to flash.

Functions

int flash_img_init_id(struct flash_img_context *ctx, uint8_t area_id)

Initialize context needed for writing the image to the flash.

Parameters:

ctx – context to be initialized
area_id – flash area id of partition where the image should be written

Returns:

0 on success, negative errno code on fail

int flash_img_init(struct flash_img_context *ctx)

Initialize context needed for writing the image to the flash.

Parameters:

ctx – context to be initialized

Returns:

0 on success, negative errno code on fail

size_t flash_img_bytes_written(struct flash_img_context *ctx)

Read number of bytes of the image written to the flash.

Parameters:

ctx – context

Returns:

Number of bytes written to the image flash.

int flash_img_buffered_write(struct flash_img_context *ctx, const uint8_t *data, size_t len, bool flush)

Process input buffers to be written to the image slot 1.

flash memory in single blocks. Will store remainder between calls.

A final call to this function with flush set to true will write out the remaining block buffer to flash. Since flash is written to in blocks, the contents of flash from the last byte written up to the next multiple of CONFIG_IMG_BLOCK_BUF_SIZE is padded with 0xff.

Parameters:

ctx – context
data – data to write
len – Number of bytes to write
flush – when true this forces any buffered data to be written to flash

Returns:

0 on success, negative errno code on fail

int flash_img_check(struct flash_img_context *ctx, const struct flash_img_check *fic, uint8_t area_id)

Verify flash memory length bytes integrity from a flash area.

The start point is indicated by an offset value.

The function is enabled via CONFIG_IMG_ENABLE_IMAGE_CHECK Kconfig options.

Parameters:

ctx – [in] context.
fic – [in] flash img check data.
area_id – [in] flash area id of partition where the image should be verified.

Returns:

0 on success, negative errno code on fail

struct flash_img_context: #include <flash_img.h>

struct flash_img_check

#include <flash_img.h>

Structure for verify flash region integrity.

Match vector length is fixed and depends on size from hash algorithm used to verify flash integrity. The current available algorithm is SHA-256.

Public Members

size_t clen: Match vector data.

MCUBoot API

The MCUboot API is provided to get version information and boot status of application images. It allows to select application image and boot type for the next boot.

API Reference

group mcuboot_api

MCUboot public API for MCUboot control of image boot process.

Defines

BOOT_SWAP_TYPE_NONE: Attempt to boot the contents of slot 0.

BOOT_SWAP_TYPE_TEST

Swap to slot 1.

Absent a confirm command, revert back on next boot.

BOOT_SWAP_TYPE_PERM: Swap to slot 1, and permanently switch to booting its contents.

BOOT_SWAP_TYPE_REVERT

Swap back to alternate slot.

A confirm changes this state to NONE.

BOOT_SWAP_TYPE_FAIL: Swap failed because image to be run is not valid.

BOOT_IMG_VER_STRLEN_MAX

BOOT_UPGRADE_TEST: Boot upgrade request modes.

BOOT_UPGRADE_PERMANENT

Functions

int boot_read_bank_header(uint8_t area_id, struct mcuboot_img_header *header, size_t header_size)

Read the MCUboot image header information from an image bank.

This attempts to parse the image header, From the start of the area_id image.

Parameters:

area_id – flash_area ID of image bank which stores the image.
header – On success, the returned header information is available in this structure.
header_size – Size of the header structure passed by the caller. If this is not large enough to contain all of the necessary information, an error is returned.

Returns:

Zero on success, a negative value on error.

bool boot_is_img_confirmed(void)

Check if the currently running image is confirmed as OK.

MCUboot can perform “test” upgrades. When these occur, a new firmware image is installed and booted, but the old version will be reverted at the next reset unless the new image explicitly marks itself OK.

This routine can be used to check if the currently running image has been marked as OK.

Bootloaders

MCUboot

Zephyr is directly compatible with the open source, cross-RTOS MCUboot boot loader. It interfaces with MCUboot and is aware of the image format required by it, so that Device Firmware Upgrade is available when MCUboot is the boot loader used with Zephyr. The source code itself is hosted in the MCUboot GitHub Project page.

In order to use MCUboot with Zephyr you need to take the following into account:

You will need to define the flash partitions required by MCUboot; see Flash map for details.
You will have to specify your flash partition as the chosen code partition

/ {
   chosen {
      zephyr,code-partition = &slot0_partition;
   };
};

Your application’s .conf file needs to enable the CONFIG_BOOTLOADER_MCUBOOT Kconfig option in order for Zephyr to be built in an MCUboot-compatible manner
You need to build and flash MCUboot itself on your device
You might need to take precautions to avoid mass erasing the flash and also to flash the Zephyr application image at the correct offset (right after the bootloader)

More detailed information regarding the use of MCUboot with Zephyr can be found in the MCUboot with Zephyr documentation page on the MCUboot website.