img_mgmt.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018-2021 mcumgr authors
 * Copyright (c) 2022-2024 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_MGMT_MCUMGR_GRP_IMG_MGMT_IMG_MGMT_H_
#define ZEPHYR_INCLUDE_MGMT_MCUMGR_GRP_IMG_MGMT_IMG_MGMT_H_

 
#include <inttypes.h>
#include <bootutil/image.h>
#include <zcbor_common.h>
 
#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
#include <zephyr/mgmt/mcumgr/mgmt/mgmt.h>
#include <zephyr/mgmt/mcumgr/smp/smp.h>
#endif

 
#ifdef __cplusplus
extern "C" {
#endif
 
#define IMG_MGMT_DATA_SHA_LEN   32 /* SHA256 */

#define IMG_MGMT_STATE_F_PENDING        0x01
#define IMG_MGMT_STATE_F_CONFIRMED      0x02
#define IMG_MGMT_STATE_F_ACTIVE         0x04
#define IMG_MGMT_STATE_F_PERMANENT      0x08
 
/* 255.255.65535.4294967295\0 */
#define IMG_MGMT_VER_MAX_STR_LEN        (sizeof("255.255.65535.4294967295"))

#define IMG_MGMT_SWAP_TYPE_NONE    0   
#define IMG_MGMT_SWAP_TYPE_TEST    1   
#define IMG_MGMT_SWAP_TYPE_PERM    2   
#define IMG_MGMT_SWAP_TYPE_REVERT  3   
#define IMG_MGMT_SWAP_TYPE_UNKNOWN 255 

#define IMG_MGMT_ID_STATE     0 
#define IMG_MGMT_ID_UPLOAD    1 
#define IMG_MGMT_ID_FILE      2 
#define IMG_MGMT_ID_CORELIST  3 
#define IMG_MGMT_ID_CORELOAD  4 
#define IMG_MGMT_ID_ERASE     5 
#define IMG_MGMT_ID_SLOT_INFO 6 

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,
};

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,
};
 
extern int boot_current_slot;
extern struct img_mgmt_state g_img_mgmt_state;

struct img_mgmt_upload_req {
        uint32_t image; /* 0 by default */
        size_t off;     /* SIZE_MAX if unspecified */
        size_t size;    /* SIZE_MAX if unspecified */
        struct zcbor_string img_data;
        struct zcbor_string data_sha;
        bool upgrade;                   /* Only allow greater version numbers. */
};

struct img_mgmt_state {
        int area_id;
        size_t off;
        size_t size;
        uint8_t data_sha_len;
        uint8_t data_sha[IMG_MGMT_DATA_SHA_LEN];
};

struct img_mgmt_upload_action {
        unsigned long long size;
        int write_bytes;
        int area_id;
        bool proceed;
        bool erase;
#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
        const char *rc_rsn;
#endif
};
 
/*
 * @brief Read info of an image at the specified slot number
 *
 * @param image_slot    image slot number
 * @param ver           output buffer for image version
 * @param hash          output buffer for image hash
 * @param flags         output buffer for image flags
 *
 * @return 0 on success, non-zero on failure.
 */
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);

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

int img_mgmt_active_slot(int image);

int img_mgmt_active_image(void);

int img_mgmt_slot_in_use(int slot);

int img_mgmt_state_any_pending(void);

uint8_t img_mgmt_state_flags(int query_slot);

int img_mgmt_state_set_pending(int slot, int permanent);

int img_mgmt_state_confirm(void);

int img_mgmt_vercmp(const struct image_version *a, const struct image_version *b);
 
#if defined(CONFIG_MCUMGR_GRP_IMG_MUTEX)
/*
 * @brief       Will reset the image management state back to default (no ongoing upload),
 *              requires that CONFIG_MCUMGR_GRP_IMG_MUTEX be enabled to allow for mutex
 *              locking of the image management state object.
 */
void img_mgmt_reset_upload(void);
#endif
 
#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn) ((action)->rc_rsn = (rsn))
#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) ((action)->rc_rsn)
int img_mgmt_error_rsp(struct smp_streamer *ctxt, int rc, const char *rsn);
extern const char *img_mgmt_err_str_app_reject;
extern const char *img_mgmt_err_str_hdr_malformed;
extern const char *img_mgmt_err_str_magic_mismatch;
extern const char *img_mgmt_err_str_no_slot;
extern const char *img_mgmt_err_str_flash_open_failed;
extern const char *img_mgmt_err_str_flash_erase_failed;
extern const char *img_mgmt_err_str_flash_write_failed;
extern const char *img_mgmt_err_str_downgrade;
extern const char *img_mgmt_err_str_image_bad_flash_addr;
extern const char *img_mgmt_err_str_image_too_large;
extern const char *img_mgmt_err_str_data_overrun;
#else
#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn)
#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) NULL
#endif

 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_MGMT_MCUMGR_GRP_IMG_MGMT_IMG_MGMT_H_ */