MCUmgr Image Management API. More...

Modules
	Image Management Callbacks
	MCUmgr Image Management Callbacks API.

	Image Management Client
	MCUmgr Image management client API.

Data Structures
struct	img_mgmt_upload_req
	Represents an individual upload request. More...

struct	img_mgmt_state
	Global state for upload in progress. More...

struct	img_mgmt_upload_action
	Describes what to do during processing of an upload request. More...

Macros
#define	IMG_MGMT_DATA_SHA_LEN 32 /* SHA256 */

#define	IMG_MGMT_VER_MAX_STR_LEN (sizeof("255.255.65535.4294967295"))

#define	IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn)

#define	IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) NULL

Enumerations
enum	img_mgmt_err_code_t { IMG_MGMT_ERR_OK = 0 , IMG_MGMT_ERR_UNKNOWN , IMG_MGMT_ERR_FLASH_CONFIG_QUERY_FAIL , IMG_MGMT_ERR_NO_IMAGE , IMG_MGMT_ERR_NO_TLVS , IMG_MGMT_ERR_INVALID_TLV , IMG_MGMT_ERR_TLV_MULTIPLE_HASHES_FOUND , IMG_MGMT_ERR_TLV_INVALID_SIZE , IMG_MGMT_ERR_HASH_NOT_FOUND , IMG_MGMT_ERR_NO_FREE_SLOT , IMG_MGMT_ERR_FLASH_OPEN_FAILED , IMG_MGMT_ERR_FLASH_READ_FAILED , IMG_MGMT_ERR_FLASH_WRITE_FAILED , IMG_MGMT_ERR_FLASH_ERASE_FAILED , IMG_MGMT_ERR_INVALID_SLOT , IMG_MGMT_ERR_NO_FREE_MEMORY , IMG_MGMT_ERR_FLASH_CONTEXT_ALREADY_SET , IMG_MGMT_ERR_FLASH_CONTEXT_NOT_SET , IMG_MGMT_ERR_FLASH_AREA_DEVICE_NULL , IMG_MGMT_ERR_INVALID_PAGE_OFFSET , IMG_MGMT_ERR_INVALID_OFFSET , IMG_MGMT_ERR_INVALID_LENGTH , IMG_MGMT_ERR_INVALID_IMAGE_HEADER , IMG_MGMT_ERR_INVALID_IMAGE_HEADER_MAGIC , IMG_MGMT_ERR_INVALID_HASH , IMG_MGMT_ERR_INVALID_FLASH_ADDRESS , IMG_MGMT_ERR_VERSION_GET_FAILED , IMG_MGMT_ERR_CURRENT_VERSION_IS_NEWER , IMG_MGMT_ERR_IMAGE_ALREADY_PENDING , IMG_MGMT_ERR_INVALID_IMAGE_VECTOR_TABLE , IMG_MGMT_ERR_INVALID_IMAGE_TOO_LARGE , IMG_MGMT_ERR_INVALID_IMAGE_DATA_OVERRUN , IMG_MGMT_ERR_IMAGE_CONFIRMATION_DENIED , IMG_MGMT_ERR_IMAGE_SETTING_TEST_TO_ACTIVE_DENIED , IMG_MGMT_ERR_ACTIVE_SLOT_NOT_KNOWN }
	Command result codes for image management group. More...

enum	img_mgmt_id_upload_t { IMG_MGMT_ID_UPLOAD_STATUS_START = 0 , IMG_MGMT_ID_UPLOAD_STATUS_ONGOING , IMG_MGMT_ID_UPLOAD_STATUS_COMPLETE }
	IMG_MGMT_ID_UPLOAD statuses. More...

Functions
int	img_mgmt_read_info (int image_slot, struct image_version ver, uint8_t hash, uint32_t *flags)

int	img_mgmt_my_version (struct image_version *ver)
	Get the image version of the currently running application.

int	img_mgmt_ver_str (const struct image_version ver, char dst)
	Format version string from struct image_version.

int	img_mgmt_active_slot (int image)
	Get active, running application slot number for an image.

int	img_mgmt_active_image (void)
	Get active image number.

int	img_mgmt_slot_in_use (int slot)
	Check if the image slot is in use.

int	img_mgmt_state_any_pending (void)
	Check if any slot is in MCUboot pending state.

uint8_t	img_mgmt_state_flags (int query_slot)
	Returns state flags set to slot.

int	img_mgmt_state_set_pending (int slot, int permanent)
	Sets the pending flag for the specified image slot.

int	img_mgmt_state_confirm (void)
	Confirms the current image state.

int	img_mgmt_vercmp (const struct image_version a, const struct image_version b)
	Compares two image version numbers in a semver-compatible way.

Variables
int	boot_current_slot

struct img_mgmt_state	g_img_mgmt_state

Image state flags
#define	IMG_MGMT_STATE_F_PENDING 0x01
	Image is set for next swap.

#define	IMG_MGMT_STATE_F_CONFIRMED 0x02
	Image has been confirmed.

#define	IMG_MGMT_STATE_F_ACTIVE 0x04
	Image is currently active.

#define	IMG_MGMT_STATE_F_PERMANENT 0x08
	Image is to stay in primary slot after the next boot.

Swap Types for image management state machine
#define	IMG_MGMT_SWAP_TYPE_NONE 0
	No swap.

#define	IMG_MGMT_SWAP_TYPE_TEST 1
	Test swap.

#define	IMG_MGMT_SWAP_TYPE_PERM 2
	Permanent swap.

#define	IMG_MGMT_SWAP_TYPE_REVERT 3
	Revert swap.

#define	IMG_MGMT_SWAP_TYPE_UNKNOWN 255
	Unknown swap.

Command IDs for image management group.
#define	IMG_MGMT_ID_STATE 0
	State of images.

#define	IMG_MGMT_ID_UPLOAD 1
	Image upload.

#define	IMG_MGMT_ID_FILE 2
	File.

#define	IMG_MGMT_ID_CORELIST 3
	Corelist.

#define	IMG_MGMT_ID_CORELOAD 4
	Coreload.

#define	IMG_MGMT_ID_ERASE 5
	Image erase.

#define	IMG_MGMT_ID_SLOT_INFO 6
	Slot info.

Detailed Description

MCUmgr Image Management API.

Macro Definition Documentation

◆ IMG_MGMT_DATA_SHA_LEN

#define IMG_MGMT_DATA_SHA_LEN 32 /* SHA256 */

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

◆ IMG_MGMT_ID_CORELIST

#define IMG_MGMT_ID_CORELIST 3

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Corelist.

◆ IMG_MGMT_ID_CORELOAD

#define IMG_MGMT_ID_CORELOAD 4

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Coreload.

◆ IMG_MGMT_ID_ERASE

#define IMG_MGMT_ID_ERASE 5

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Image erase.

◆ IMG_MGMT_ID_FILE

#define IMG_MGMT_ID_FILE 2

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

File.

◆ IMG_MGMT_ID_SLOT_INFO

#define IMG_MGMT_ID_SLOT_INFO 6

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Slot info.

◆ IMG_MGMT_ID_STATE

#define IMG_MGMT_ID_STATE 0

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

State of images.

◆ IMG_MGMT_ID_UPLOAD

#define IMG_MGMT_ID_UPLOAD 1

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Image upload.

◆ IMG_MGMT_STATE_F_ACTIVE

#define IMG_MGMT_STATE_F_ACTIVE 0x04

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Image is currently active.

◆ IMG_MGMT_STATE_F_CONFIRMED

#define IMG_MGMT_STATE_F_CONFIRMED 0x02

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Image has been confirmed.

◆ IMG_MGMT_STATE_F_PENDING

#define IMG_MGMT_STATE_F_PENDING 0x01

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Image is set for next swap.

◆ IMG_MGMT_STATE_F_PERMANENT

#define IMG_MGMT_STATE_F_PERMANENT 0x08

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Image is to stay in primary slot after the next boot.

◆ IMG_MGMT_SWAP_TYPE_NONE

#define IMG_MGMT_SWAP_TYPE_NONE 0

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

No swap.

◆ IMG_MGMT_SWAP_TYPE_PERM

#define IMG_MGMT_SWAP_TYPE_PERM 2

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Permanent swap.

◆ IMG_MGMT_SWAP_TYPE_REVERT

#define IMG_MGMT_SWAP_TYPE_REVERT 3

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Revert swap.

◆ IMG_MGMT_SWAP_TYPE_TEST

#define IMG_MGMT_SWAP_TYPE_TEST 1

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Test swap.

◆ IMG_MGMT_SWAP_TYPE_UNKNOWN

#define IMG_MGMT_SWAP_TYPE_UNKNOWN 255

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Unknown swap.

◆ IMG_MGMT_UPLOAD_ACTION_RC_RSN

#define IMG_MGMT_UPLOAD_ACTION_RC_RSN ( action ) NULL

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

◆ IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN

#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN	(	action,
		rsn
	)

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

◆ IMG_MGMT_VER_MAX_STR_LEN

#define IMG_MGMT_VER_MAX_STR_LEN (sizeof("255.255.65535.4294967295"))

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Enumeration Type Documentation

◆ img_mgmt_err_code_t

enum img_mgmt_err_code_t

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Command result codes for image management group.

Enumerator
IMG_MGMT_ERR_OK	No error, this is implied if there is no ret value in the response.
IMG_MGMT_ERR_UNKNOWN	Unknown error occurred.
IMG_MGMT_ERR_FLASH_CONFIG_QUERY_FAIL	Failed to query flash area configuration.
IMG_MGMT_ERR_NO_IMAGE	There is no image in the slot.
IMG_MGMT_ERR_NO_TLVS	The image in the slot has no TLVs (tag, length, value).
IMG_MGMT_ERR_INVALID_TLV	The image in the slot has an invalid TLV type and/or length.
IMG_MGMT_ERR_TLV_MULTIPLE_HASHES_FOUND	The image in the slot has multiple hash TLVs, which is invalid.
IMG_MGMT_ERR_TLV_INVALID_SIZE	The image in the slot has an invalid TLV size.
IMG_MGMT_ERR_HASH_NOT_FOUND	The image in the slot does not have a hash TLV, which is required.
IMG_MGMT_ERR_NO_FREE_SLOT	There is no free slot to place the image.
IMG_MGMT_ERR_FLASH_OPEN_FAILED	Flash area opening failed.
IMG_MGMT_ERR_FLASH_READ_FAILED	Flash area reading failed.
IMG_MGMT_ERR_FLASH_WRITE_FAILED	Flash area writing failed.
IMG_MGMT_ERR_FLASH_ERASE_FAILED	Flash area erase failed.
IMG_MGMT_ERR_INVALID_SLOT	The provided slot is not valid.
IMG_MGMT_ERR_NO_FREE_MEMORY	Insufficient heap memory (malloc failed).
IMG_MGMT_ERR_FLASH_CONTEXT_ALREADY_SET	The flash context is already set.
IMG_MGMT_ERR_FLASH_CONTEXT_NOT_SET	The flash context is not set.
IMG_MGMT_ERR_FLASH_AREA_DEVICE_NULL	The device for the flash area is NULL.
IMG_MGMT_ERR_INVALID_PAGE_OFFSET	The offset for a page number is invalid.
IMG_MGMT_ERR_INVALID_OFFSET	The offset parameter was not provided and is required.
IMG_MGMT_ERR_INVALID_LENGTH	The length parameter was not provided and is required.
IMG_MGMT_ERR_INVALID_IMAGE_HEADER	The image length is smaller than the size of an image header.
IMG_MGMT_ERR_INVALID_IMAGE_HEADER_MAGIC	The image header magic value does not match the expected value.
IMG_MGMT_ERR_INVALID_HASH	The hash parameter provided is not valid.
IMG_MGMT_ERR_INVALID_FLASH_ADDRESS	The image load address does not match the address of the flash area.
IMG_MGMT_ERR_VERSION_GET_FAILED	Failed to get version of currently running application.
IMG_MGMT_ERR_CURRENT_VERSION_IS_NEWER	The currently running application is newer than the version being uploaded.
IMG_MGMT_ERR_IMAGE_ALREADY_PENDING	There is already an image operating pending.
IMG_MGMT_ERR_INVALID_IMAGE_VECTOR_TABLE	The image vector table is invalid.
IMG_MGMT_ERR_INVALID_IMAGE_TOO_LARGE	The image it too large to fit.
IMG_MGMT_ERR_INVALID_IMAGE_DATA_OVERRUN	The amount of data sent is larger than the provided image size.
IMG_MGMT_ERR_IMAGE_CONFIRMATION_DENIED	Confirmation of image has been denied.
IMG_MGMT_ERR_IMAGE_SETTING_TEST_TO_ACTIVE_DENIED	Setting test to active slot is not allowed.
IMG_MGMT_ERR_ACTIVE_SLOT_NOT_KNOWN	Current active slot for image cannot be determined.

◆ img_mgmt_id_upload_t

enum img_mgmt_id_upload_t

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

IMG_MGMT_ID_UPLOAD statuses.

Enumerator
IMG_MGMT_ID_UPLOAD_STATUS_START
IMG_MGMT_ID_UPLOAD_STATUS_ONGOING
IMG_MGMT_ID_UPLOAD_STATUS_COMPLETE

Function Documentation

◆ img_mgmt_active_image()

int img_mgmt_active_image ( void )

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Get active image number.

Gets 0 based number for running application.

Returns: Non-negative image number.

◆ img_mgmt_active_slot()

int img_mgmt_active_slot ( int image )

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Get active, running application slot number for an image.

Parameters

image image number to get active slot for.

Returns: Non-negative slot number

◆ img_mgmt_my_version()

int img_mgmt_my_version ( struct image_version * ver )

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Get the image version of the currently running application.

Parameters

ver	output buffer for an image version information object.

Returns: 0 on success, non-zero on failure.

◆ img_mgmt_read_info()

int img_mgmt_read_info	(	int	image_slot,
		struct image_version *	ver,
		uint8_t *	hash,
		uint32_t *	flags
	)

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

◆ img_mgmt_slot_in_use()

int img_mgmt_slot_in_use ( int slot )

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Check if the image slot is in use.

The check is based on MCUboot flags, not image contents. This means that slot with image in it, but no bootable flags set, is considered empty. Active slot is always in use.

Parameters

slot	slot number

Returns: 0 if slot is not used, non-0 otherwise.

◆ img_mgmt_state_any_pending()

int img_mgmt_state_any_pending ( void )

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Check if any slot is in MCUboot pending state.

Function returns 1 if slot 0 or slot 1 is in MCUboot pending state, which means that it has been either marked for test or confirmed.

Returns: 1 if there's pending DFU otherwise 0.

◆ img_mgmt_state_confirm()

int img_mgmt_state_confirm ( void )

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Confirms the current image state.

Prevents a fallback from occurring on the next reboot if the active image is currently being tested.

Returns: 0 on success, non-zero on failure

◆ img_mgmt_state_flags()

uint8_t img_mgmt_state_flags ( int query_slot )

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Returns state flags set to slot.

Flags are translated from MCUboot image state flags. Returned value is zero if no flags are set or a combination of: IMG_MGMT_STATE_F_PENDING IMG_MGMT_STATE_F_CONFIRMED IMG_MGMT_STATE_F_ACTIVE IMG_MGMT_STATE_F_PERMANENT

Parameters

query_slot slot number

Returns: return the state flags.

◆ img_mgmt_state_set_pending()

int img_mgmt_state_set_pending	(	int	slot,
		int	permanent
	)

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Sets the pending flag for the specified image slot.

Sets specified image slot to be used as active slot during next boot, either for test or permanently. Non-permanent image will be reverted unless image confirms itself during next boot.

Parameters

slot	slot number
permanent	permanent or test only

Returns: 0 on success, non-zero on failure

◆ img_mgmt_ver_str()

int img_mgmt_ver_str	(	const struct image_version *	ver,
		char *	dst
	)

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Format version string from struct image_version.

Parameters

ver	pointer to image_version object
dst	output buffer for image version string

Returns: Non-negative on success, negative value on error.

◆ img_mgmt_vercmp()

int img_mgmt_vercmp	(	const struct image_version *	a,
		const struct image_version *	b
	)

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Compares two image version numbers in a semver-compatible way.

Parameters

a	The first version to compare
b	The second version to compare

Returns: -1 if a < b; 0 if a = b; 1 if a > b

Variable Documentation

◆ boot_current_slot

int boot_current_slot

extern

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

◆ g_img_mgmt_state

struct img_mgmt_state g_img_mgmt_state

extern

#include <include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>

Modules

Data Structures

Macros

Enumerations

Functions

Variables

Image state flags

Swap Types for image management state machine

Command IDs for image management group.

Detailed Description

Macro Definition Documentation

◆ IMG_MGMT_DATA_SHA_LEN

◆ IMG_MGMT_ID_CORELIST

◆ IMG_MGMT_ID_CORELOAD

◆ IMG_MGMT_ID_ERASE

◆ IMG_MGMT_ID_FILE

◆ IMG_MGMT_ID_SLOT_INFO

◆ IMG_MGMT_ID_STATE

◆ IMG_MGMT_ID_UPLOAD

◆ IMG_MGMT_STATE_F_ACTIVE

◆ IMG_MGMT_STATE_F_CONFIRMED

◆ IMG_MGMT_STATE_F_PENDING

◆ IMG_MGMT_STATE_F_PERMANENT

◆ IMG_MGMT_SWAP_TYPE_NONE

◆ IMG_MGMT_SWAP_TYPE_PERM

◆ IMG_MGMT_SWAP_TYPE_REVERT

◆ IMG_MGMT_SWAP_TYPE_TEST

◆ IMG_MGMT_SWAP_TYPE_UNKNOWN

◆ IMG_MGMT_UPLOAD_ACTION_RC_RSN

◆ IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN

◆ IMG_MGMT_VER_MAX_STR_LEN

Enumeration Type Documentation

◆ img_mgmt_err_code_t

◆ img_mgmt_id_upload_t

Function Documentation

◆ img_mgmt_active_image()

◆ img_mgmt_active_slot()

◆ img_mgmt_my_version()

◆ img_mgmt_read_info()

◆ img_mgmt_slot_in_use()

◆ img_mgmt_state_any_pending()

◆ img_mgmt_state_confirm()

◆ img_mgmt_state_flags()

◆ img_mgmt_state_set_pending()

◆ img_mgmt_ver_str()

◆ img_mgmt_vercmp()

Variable Documentation

◆ boot_current_slot

◆ g_img_mgmt_state