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 H_IMG_MGMT_
#define H_IMG_MGMT_
 
#include <inttypes.h>
#include <zephyr/mgmt/mcumgr/mgmt/mgmt.h>
#include <zephyr/mgmt/mcumgr/smp/smp.h>
#include <bootutil/image.h>
#include <zcbor_common.h>
 
#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 /* H_IMG_MGMT_ */