Zephyr Project API 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
img_mgmt.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018-2021 mcumgr authors
3 * Copyright (c) 2022-2024 Nordic Semiconductor ASA
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8#ifndef H_IMG_MGMT_
9#define H_IMG_MGMT_
10
11#include <inttypes.h>
12#include <bootutil/image.h>
13#include <zcbor_common.h>
14
15#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
18#endif
19
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31#define IMG_MGMT_DATA_SHA_LEN 32 /* SHA256 */
32
38#define IMG_MGMT_STATE_F_PENDING 0x01
40#define IMG_MGMT_STATE_F_CONFIRMED 0x02
42#define IMG_MGMT_STATE_F_ACTIVE 0x04
44#define IMG_MGMT_STATE_F_PERMANENT 0x08
47/* 255.255.65535.4294967295\0 */
48#define IMG_MGMT_VER_MAX_STR_LEN (sizeof("255.255.65535.4294967295"))
49
54#define IMG_MGMT_SWAP_TYPE_NONE 0
55#define IMG_MGMT_SWAP_TYPE_TEST 1
56#define IMG_MGMT_SWAP_TYPE_PERM 2
57#define IMG_MGMT_SWAP_TYPE_REVERT 3
58#define IMG_MGMT_SWAP_TYPE_UNKNOWN 255
65#define IMG_MGMT_ID_STATE 0
66#define IMG_MGMT_ID_UPLOAD 1
67#define IMG_MGMT_ID_FILE 2
68#define IMG_MGMT_ID_CORELIST 3
69#define IMG_MGMT_ID_CORELOAD 4
70#define IMG_MGMT_ID_ERASE 5
71#define IMG_MGMT_ID_SLOT_INFO 6
183
192
193extern int boot_current_slot;
194extern struct img_mgmt_state g_img_mgmt_state;
195
198 uint32_t image; /* 0 by default */
199 size_t off; /* SIZE_MAX if unspecified */
200 size_t size; /* SIZE_MAX if unspecified */
201 struct zcbor_string img_data;
202 struct zcbor_string data_sha;
203 bool upgrade; /* Only allow greater version numbers. */
204};
205
218
222 unsigned long long size;
230 bool erase;
231#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
233 const char *rc_rsn;
234#endif
235};
236
237/*
238 * @brief Read info of an image at the specified slot number
239 *
240 * @param image_slot image slot number
241 * @param ver output buffer for image version
242 * @param hash output buffer for image hash
243 * @param flags output buffer for image flags
244 *
245 * @return 0 on success, non-zero on failure.
246 */
247int img_mgmt_read_info(int image_slot, struct image_version *ver, uint8_t *hash, uint32_t *flags);
248
256int img_mgmt_my_version(struct image_version *ver);
257
266int img_mgmt_ver_str(const struct image_version *ver, char *dst);
267
275int img_mgmt_active_slot(int image);
276
285
298
308
325
338int img_mgmt_state_set_pending(int slot, int permanent);
339
349
360int img_mgmt_vercmp(const struct image_version *a, const struct image_version *b);
361
362#if defined(CONFIG_MCUMGR_GRP_IMG_MUTEX)
363/*
364 * @brief Will reset the image management state back to default (no ongoing upload),
365 * requires that CONFIG_MCUMGR_GRP_IMG_MUTEX be enabled to allow for mutex
366 * locking of the image management state object.
367 */
368void img_mgmt_reset_upload(void);
369#endif
370
371#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
372#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn) ((action)->rc_rsn = (rsn))
373#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) ((action)->rc_rsn)
374int img_mgmt_error_rsp(struct smp_streamer *ctxt, int rc, const char *rsn);
375extern const char *img_mgmt_err_str_app_reject;
376extern const char *img_mgmt_err_str_hdr_malformed;
377extern const char *img_mgmt_err_str_magic_mismatch;
378extern const char *img_mgmt_err_str_no_slot;
379extern const char *img_mgmt_err_str_flash_open_failed;
380extern const char *img_mgmt_err_str_flash_erase_failed;
381extern const char *img_mgmt_err_str_flash_write_failed;
382extern const char *img_mgmt_err_str_downgrade;
383extern const char *img_mgmt_err_str_image_bad_flash_addr;
384extern const char *img_mgmt_err_str_image_too_large;
385extern const char *img_mgmt_err_str_data_overrun;
386#else
387#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn)
388#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) NULL
389#endif
390
395#ifdef __cplusplus
396}
397#endif
398
399#endif /* H_IMG_MGMT_ */
int boot_current_slot
img_mgmt_id_upload_t
IMG_MGMT_ID_UPLOAD statuses.
Definition img_mgmt.h:187
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_ver_str(const struct image_version *ver, char *dst)
Format version string from struct image_version.
int img_mgmt_read_info(int image_slot, struct image_version *ver, uint8_t *hash, uint32_t *flags)
img_mgmt_err_code_t
Command result codes for image management group.
Definition img_mgmt.h:77
int img_mgmt_vercmp(const struct image_version *a, const struct image_version *b)
Compares two image version numbers in a semver-compatible way.
#define IMG_MGMT_DATA_SHA_LEN
Definition img_mgmt.h:31
int img_mgmt_state_set_pending(int slot, int permanent)
Sets the pending flag for the specified image slot.
int img_mgmt_slot_in_use(int slot)
Check if the image slot is in use.
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.
struct img_mgmt_state g_img_mgmt_state
int img_mgmt_my_version(struct image_version *ver)
Get the image version of the currently running application.
int img_mgmt_state_confirm(void)
Confirms the current image state.
@ IMG_MGMT_ID_UPLOAD_STATUS_ONGOING
Definition img_mgmt.h:189
@ IMG_MGMT_ID_UPLOAD_STATUS_COMPLETE
Definition img_mgmt.h:190
@ IMG_MGMT_ID_UPLOAD_STATUS_START
Definition img_mgmt.h:188
@ IMG_MGMT_ERR_NO_FREE_SLOT
There is no free slot to place the image.
Definition img_mgmt.h:106
@ IMG_MGMT_ERR_INVALID_LENGTH
The length parameter was not provided and is required.
Definition img_mgmt.h:142
@ IMG_MGMT_ERR_INVALID_FLASH_ADDRESS
The image load address does not match the address of the flash area.
Definition img_mgmt.h:154
@ IMG_MGMT_ERR_ACTIVE_SLOT_NOT_KNOWN
Current active slot for image cannot be determined.
Definition img_mgmt.h:181
@ IMG_MGMT_ERR_NO_IMAGE
There is no image in the slot.
Definition img_mgmt.h:88
@ IMG_MGMT_ERR_CURRENT_VERSION_IS_NEWER
The currently running application is newer than the version being uploaded.
Definition img_mgmt.h:160
@ IMG_MGMT_ERR_INVALID_IMAGE_VECTOR_TABLE
The image vector table is invalid.
Definition img_mgmt.h:166
@ IMG_MGMT_ERR_INVALID_TLV
The image in the slot has an invalid TLV type and/or length.
Definition img_mgmt.h:94
@ IMG_MGMT_ERR_INVALID_HASH
The hash parameter provided is not valid.
Definition img_mgmt.h:151
@ IMG_MGMT_ERR_INVALID_IMAGE_HEADER_MAGIC
The image header magic value does not match the expected value.
Definition img_mgmt.h:148
@ IMG_MGMT_ERR_NO_TLVS
The image in the slot has no TLVs (tag, length, value).
Definition img_mgmt.h:91
@ IMG_MGMT_ERR_FLASH_CONFIG_QUERY_FAIL
Failed to query flash area configuration.
Definition img_mgmt.h:85
@ IMG_MGMT_ERR_HASH_NOT_FOUND
The image in the slot does not have a hash TLV, which is required.
Definition img_mgmt.h:103
@ IMG_MGMT_ERR_FLASH_AREA_DEVICE_NULL
The device for the flash area is NULL.
Definition img_mgmt.h:133
@ IMG_MGMT_ERR_INVALID_SLOT
The provided slot is not valid.
Definition img_mgmt.h:121
@ IMG_MGMT_ERR_OK
No error, this is implied if there is no ret value in the response.
Definition img_mgmt.h:79
@ IMG_MGMT_ERR_FLASH_OPEN_FAILED
Flash area opening failed.
Definition img_mgmt.h:109
@ IMG_MGMT_ERR_INVALID_PAGE_OFFSET
The offset for a page number is invalid.
Definition img_mgmt.h:136
@ IMG_MGMT_ERR_FLASH_ERASE_FAILED
Flash area erase failed.
Definition img_mgmt.h:118
@ IMG_MGMT_ERR_INVALID_OFFSET
The offset parameter was not provided and is required.
Definition img_mgmt.h:139
@ IMG_MGMT_ERR_UNKNOWN
Unknown error occurred.
Definition img_mgmt.h:82
@ IMG_MGMT_ERR_INVALID_IMAGE_DATA_OVERRUN
The amount of data sent is larger than the provided image size.
Definition img_mgmt.h:172
@ IMG_MGMT_ERR_TLV_INVALID_SIZE
The image in the slot has an invalid TLV size.
Definition img_mgmt.h:100
@ IMG_MGMT_ERR_FLASH_READ_FAILED
Flash area reading failed.
Definition img_mgmt.h:112
@ IMG_MGMT_ERR_FLASH_CONTEXT_NOT_SET
The flash context is not set.
Definition img_mgmt.h:130
@ IMG_MGMT_ERR_IMAGE_SETTING_TEST_TO_ACTIVE_DENIED
Setting test to active slot is not allowed.
Definition img_mgmt.h:178
@ IMG_MGMT_ERR_INVALID_IMAGE_TOO_LARGE
The image it too large to fit.
Definition img_mgmt.h:169
@ IMG_MGMT_ERR_NO_FREE_MEMORY
Insufficient heap memory (malloc failed).
Definition img_mgmt.h:124
@ IMG_MGMT_ERR_TLV_MULTIPLE_HASHES_FOUND
The image in the slot has multiple hash TLVs, which is invalid.
Definition img_mgmt.h:97
@ IMG_MGMT_ERR_INVALID_IMAGE_HEADER
The image length is smaller than the size of an image header.
Definition img_mgmt.h:145
@ IMG_MGMT_ERR_FLASH_WRITE_FAILED
Flash area writing failed.
Definition img_mgmt.h:115
@ IMG_MGMT_ERR_IMAGE_CONFIRMATION_DENIED
Confirmation of image has been denied.
Definition img_mgmt.h:175
@ IMG_MGMT_ERR_VERSION_GET_FAILED
Failed to get version of currently running application.
Definition img_mgmt.h:157
@ IMG_MGMT_ERR_FLASH_CONTEXT_ALREADY_SET
The flash context is already set.
Definition img_mgmt.h:127
@ IMG_MGMT_ERR_IMAGE_ALREADY_PENDING
There is already an image operating pending.
Definition img_mgmt.h:163
SMP - Simple Management Protocol.
flags
Definition parser.h:97
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
Global state for upload in progress.
Definition img_mgmt.h:207
uint8_t data_sha[32]
Definition img_mgmt.h:216
size_t size
Total size of image data.
Definition img_mgmt.h:213
int area_id
Flash area being written; -1 if no upload in progress.
Definition img_mgmt.h:209
uint8_t data_sha_len
Hash of image data; used for resumption of a partial upload.
Definition img_mgmt.h:215
size_t off
Flash offset of next chunk.
Definition img_mgmt.h:211
Describes what to do during processing of an upload request.
Definition img_mgmt.h:220
unsigned long long size
The total size of the image.
Definition img_mgmt.h:222
int area_id
The flash area to write to.
Definition img_mgmt.h:226
bool proceed
Whether to process the request; false if offset is wrong.
Definition img_mgmt.h:228
int write_bytes
The number of image bytes to write to flash.
Definition img_mgmt.h:224
bool erase
Whether to erase the destination flash area.
Definition img_mgmt.h:230
Represents an individual upload request.
Definition img_mgmt.h:197
size_t size
Definition img_mgmt.h:200
bool upgrade
Definition img_mgmt.h:203
uint32_t image
Definition img_mgmt.h:198
struct zcbor_string img_data
Definition img_mgmt.h:201
struct zcbor_string data_sha
Definition img_mgmt.h:202
size_t off
Definition img_mgmt.h:199
Decodes, encodes, and transmits SMP packets.
Definition smp.h:83