MCUboot public API for MCUboot control of image boot process. More...

Data Structures
struct	mcuboot_img_sem_ver
	MCUboot image header representation for image version. More...

struct	mcuboot_img_header_v1
	Model for the MCUboot image header as of version 1. More...

struct	mcuboot_img_header
	Model for the MCUBoot image header. More...

Macros
#define	BOOT_SWAP_TYPE_NONE 1
	Attempt to boot the contents of slot 0.

#define	BOOT_SWAP_TYPE_TEST 2
	Swap to slot 1.

#define	BOOT_SWAP_TYPE_PERM 3
	Swap to slot 1, and permanently switch to booting its contents.

#define	BOOT_SWAP_TYPE_REVERT 4
	Swap back to alternate slot.

#define	BOOT_SWAP_TYPE_FAIL 5
	Swap failed because image to be run is not valid.

#define	BOOT_IMG_VER_STRLEN_MAX 25 /* 255.255.65535.4294967295\0 */

#define	BOOT_UPGRADE_TEST 0
	Boot upgrade request modes.

#define	BOOT_UPGRADE_PERMANENT 1

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.

bool	boot_is_img_confirmed (void)
	Check if the currently running image is confirmed as OK.

int	boot_write_img_confirmed (void)
	Marks the currently running image as confirmed.

int	boot_write_img_confirmed_multi (int image_index)
	Marks the image with the given index in the primary slot as confirmed.

int	mcuboot_swap_type (void)
	Determines the action, if any, that mcuboot will take on the next reboot.

int	mcuboot_swap_type_multi (int image_index)
	Determines the action, if any, that mcuboot will take on the next reboot.

int	boot_request_upgrade (int permanent)
	Marks the image in slot 1 as pending.

int	boot_request_upgrade_multi (int image_index, int permanent)
	Marks the image with the given index in the secondary slot as pending.

int	boot_erase_img_bank (uint8_t area_id)
	Erase the image Bank.

ssize_t	boot_get_area_trailer_status_offset (uint8_t area_id)
	Get the offset of the status in the image bank.

ssize_t	boot_get_trailer_status_offset (size_t area_size)
	Get the offset of the status from an image bank size.

Detailed Description

MCUboot public API for MCUboot control of image boot process.

Macro Definition Documentation

◆ BOOT_IMG_VER_STRLEN_MAX

#define BOOT_IMG_VER_STRLEN_MAX 25 /* 255.255.65535.4294967295\0 */

#include <zephyr/dfu/mcuboot.h>

◆ BOOT_SWAP_TYPE_FAIL

#define BOOT_SWAP_TYPE_FAIL 5

#include <zephyr/dfu/mcuboot.h>

Swap failed because image to be run is not valid.

◆ BOOT_SWAP_TYPE_NONE

#define BOOT_SWAP_TYPE_NONE 1

#include <zephyr/dfu/mcuboot.h>

Attempt to boot the contents of slot 0.

◆ BOOT_SWAP_TYPE_PERM

#define BOOT_SWAP_TYPE_PERM 3

#include <zephyr/dfu/mcuboot.h>

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

◆ BOOT_SWAP_TYPE_REVERT

#define BOOT_SWAP_TYPE_REVERT 4

#include <zephyr/dfu/mcuboot.h>

Swap back to alternate slot.

A confirm changes this state to NONE.

◆ BOOT_SWAP_TYPE_TEST

#define BOOT_SWAP_TYPE_TEST 2

#include <zephyr/dfu/mcuboot.h>

Swap to slot 1.

Absent a confirm command, revert back on next boot.

◆ BOOT_UPGRADE_PERMANENT

#define BOOT_UPGRADE_PERMANENT 1

#include <zephyr/dfu/mcuboot.h>

◆ BOOT_UPGRADE_TEST

#define BOOT_UPGRADE_TEST 0

#include <zephyr/dfu/mcuboot.h>

Boot upgrade request modes.

Function Documentation

◆ boot_erase_img_bank()

int boot_erase_img_bank ( uint8_t area_id )

#include <zephyr/dfu/mcuboot.h>

Erase the image Bank.

Parameters

area_id flash_area ID of image bank to be erased.

Returns: 0 on success, negative errno code on fail.

◆ boot_get_area_trailer_status_offset()

ssize_t boot_get_area_trailer_status_offset ( uint8_t area_id )

#include <zephyr/dfu/mcuboot.h>

Get the offset of the status in the image bank.

Parameters

area_id flash_area ID of image bank to get the status offset

Returns: a positive offset on success, negative errno code on fail

◆ boot_get_trailer_status_offset()

ssize_t boot_get_trailer_status_offset ( size_t area_size )

#include <zephyr/dfu/mcuboot.h>

Get the offset of the status from an image bank size.

Parameters

area_size size of image bank

Returns: offset of the status. When negative the status will not fit the given size

◆ boot_is_img_confirmed()

bool boot_is_img_confirmed ( void )

#include <zephyr/dfu/mcuboot.h>

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.

Returns: True if the image is confirmed as OK, false otherwise.

See also: boot_write_img_confirmed()

◆ boot_read_bank_header()

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

#include <zephyr/dfu/mcuboot.h>

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.

◆ boot_request_upgrade()

int boot_request_upgrade ( int permanent )

#include <zephyr/dfu/mcuboot.h>

Marks the image in slot 1 as pending.

On the next reboot, the system will perform a boot of the slot 1 image.

Parameters

permanent Whether the image should be used permanently or only tested once: BOOT_UPGRADE_TEST=run image once, then confirm or revert. BOOT_UPGRADE_PERMANENT=run image forever.

Returns: 0 on success, negative errno code on fail.

◆ boot_request_upgrade_multi()

int boot_request_upgrade_multi	(	int	image_index,
		int	permanent
	)

#include <zephyr/dfu/mcuboot.h>

Marks the image with the given index in the secondary slot as pending.

On the next reboot, the system will perform a boot of the secondary slot image.

Parameters

image_index	Image pair index.
permanent	Whether the image should be used permanently or only tested once: BOOT_UPGRADE_TEST=run image once, then confirm or revert. BOOT_UPGRADE_PERMANENT=run image forever.

Returns: 0 on success, negative errno code on fail.

◆ boot_write_img_confirmed()

int boot_write_img_confirmed ( void )

#include <zephyr/dfu/mcuboot.h>

Marks the currently running image as confirmed.

This routine attempts to mark the currently running firmware image as OK, which will install it permanently, preventing MCUboot from reverting it for an older image at the next reset.

This routine is safe to call if the current image has already been confirmed. It will return a successful result in this case.

Returns: 0 on success, negative errno code on fail.

◆ boot_write_img_confirmed_multi()

int boot_write_img_confirmed_multi ( int image_index )

#include <zephyr/dfu/mcuboot.h>

Marks the image with the given index in the primary slot as confirmed.

This routine attempts to mark the firmware image in the primary slot as OK, which will install it permanently, preventing MCUboot from reverting it for an older image at the next reset.

This routine is safe to call if the current image has already been confirmed. It will return a successful result in this case.

Parameters

image_index Image pair index.

Returns: 0 on success, negative errno code on fail.

◆ mcuboot_swap_type()

int mcuboot_swap_type ( void )

#include <zephyr/dfu/mcuboot.h>

Determines the action, if any, that mcuboot will take on the next reboot.

Returns: a BOOT_SWAP_TYPE_[...] constant on success, negative errno code on fail.

◆ mcuboot_swap_type_multi()

int mcuboot_swap_type_multi ( int image_index )

#include <zephyr/dfu/mcuboot.h>

Determines the action, if any, that mcuboot will take on the next reboot.

Parameters

image_index Image pair index.

Returns: a BOOT_SWAP_TYPE_[...] constant on success, negative errno code on fail.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BOOT_IMG_VER_STRLEN_MAX

◆ BOOT_SWAP_TYPE_FAIL

◆ BOOT_SWAP_TYPE_NONE

◆ BOOT_SWAP_TYPE_PERM

◆ BOOT_SWAP_TYPE_REVERT

◆ BOOT_SWAP_TYPE_TEST

◆ BOOT_UPGRADE_PERMANENT

◆ BOOT_UPGRADE_TEST

Function Documentation

◆ boot_erase_img_bank()

◆ boot_get_area_trailer_status_offset()

◆ boot_get_trailer_status_offset()

◆ boot_is_img_confirmed()

◆ boot_read_bank_header()

◆ boot_request_upgrade()

◆ boot_request_upgrade_multi()

◆ boot_write_img_confirmed()

◆ boot_write_img_confirmed_multi()

◆ mcuboot_swap_type()

◆ mcuboot_swap_type_multi()