Zephyr API Documentation  3.6.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-2023 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>
14#include <bootutil/image.h>
15#include <zcbor_common.h>
16
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28#define IMG_MGMT_DATA_SHA_LEN 32 /* SHA256 */
29
33#define IMG_MGMT_STATE_F_PENDING 0x01
34#define IMG_MGMT_STATE_F_CONFIRMED 0x02
35#define IMG_MGMT_STATE_F_ACTIVE 0x04
36#define IMG_MGMT_STATE_F_PERMANENT 0x08
37
38/* 255.255.65535.4294967295\0 */
39#define IMG_MGMT_VER_MAX_STR_LEN (sizeof("255.255.65535.4294967295"))
40
44#define IMG_MGMT_SWAP_TYPE_NONE 0
45#define IMG_MGMT_SWAP_TYPE_TEST 1
46#define IMG_MGMT_SWAP_TYPE_PERM 2
47#define IMG_MGMT_SWAP_TYPE_REVERT 3
48#define IMG_MGMT_SWAP_TYPE_UNKNOWN 255
49
53#define IMG_MGMT_ID_STATE 0
54#define IMG_MGMT_ID_UPLOAD 1
55#define IMG_MGMT_ID_FILE 2
56#define IMG_MGMT_ID_CORELIST 3
57#define IMG_MGMT_ID_CORELOAD 4
58#define IMG_MGMT_ID_ERASE 5
59
66
69
72
75
78
81
84
87
90
93
96
99
102
105
108
111
114
117
120
123
126
129
132
135
138
141
144
147
150
153
156
159
162
165
168};
169
177};
178
179extern int boot_current_slot;
180extern struct img_mgmt_state g_img_mgmt_state;
181
184 uint32_t image; /* 0 by default */
185 size_t off; /* SIZE_MAX if unspecified */
186 size_t size; /* SIZE_MAX if unspecified */
187 struct zcbor_string img_data;
188 struct zcbor_string data_sha;
189 bool upgrade; /* Only allow greater version numbers. */
190};
191
197 size_t off;
199 size_t size;
203};
204
208 unsigned long long size;
216 bool erase;
217#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
219 const char *rc_rsn;
220#endif
221};
222
223/*
224 * @brief Read info of an image at the specified slot number
225 *
226 * @param image_slot image slot number
227 * @param ver output buffer for image version
228 * @param hash output buffer for image hash
229 * @param flags output buffer for image flags
230 *
231 * @return 0 on success, non-zero on failure.
232 */
233int img_mgmt_read_info(int image_slot, struct image_version *ver, uint8_t *hash, uint32_t *flags);
234
242int img_mgmt_my_version(struct image_version *ver);
243
252int img_mgmt_ver_str(const struct image_version *ver, char *dst);
253
261int img_mgmt_active_slot(int image);
262
271
284
294
311
324int img_mgmt_state_set_pending(int slot, int permanent);
325
335
346int img_mgmt_vercmp(const struct image_version *a, const struct image_version *b);
347
348#if IS_ENABLED(CONFIG_MCUMGR_GRP_IMG_MUTEX)
349/*
350 * @brief Will reset the image management state back to default (no ongoing upload),
351 * requires that CONFIG_MCUMGR_GRP_IMG_MUTEX be enabled to allow for mutex
352 * locking of the image management state object.
353 */
354void img_mgmt_reset_upload(void);
355#endif
356
357#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
358#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn) ((action)->rc_rsn = (rsn))
359#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) ((action)->rc_rsn)
360int img_mgmt_error_rsp(struct smp_streamer *ctxt, int rc, const char *rsn);
361extern const char *img_mgmt_err_str_app_reject;
362extern const char *img_mgmt_err_str_hdr_malformed;
363extern const char *img_mgmt_err_str_magic_mismatch;
364extern const char *img_mgmt_err_str_no_slot;
365extern const char *img_mgmt_err_str_flash_open_failed;
366extern const char *img_mgmt_err_str_flash_erase_failed;
367extern const char *img_mgmt_err_str_flash_write_failed;
368extern const char *img_mgmt_err_str_downgrade;
369extern const char *img_mgmt_err_str_image_bad_flash_addr;
370extern const char *img_mgmt_err_str_image_too_large;
371extern const char *img_mgmt_err_str_data_overrun;
372#else
373#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn)
374#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) NULL
375#endif
376
381#ifdef __cplusplus
382}
383#endif
384
385#endif /* H_IMG_MGMT_ */
int boot_current_slot
img_mgmt_id_upload_t
IMG_MGMT_ID_UPLOAD statuses.
Definition: img_mgmt.h:173
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:63
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:28
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:175
@ IMG_MGMT_ID_UPLOAD_STATUS_COMPLETE
Definition: img_mgmt.h:176
@ IMG_MGMT_ID_UPLOAD_STATUS_START
Definition: img_mgmt.h:174
@ IMG_MGMT_ERR_NO_FREE_SLOT
There is no free slot to place the image.
Definition: img_mgmt.h:92
@ IMG_MGMT_ERR_INVALID_LENGTH
The length parameter was not provided and is required.
Definition: img_mgmt.h:128
@ IMG_MGMT_ERR_INVALID_FLASH_ADDRESS
The image load address does not match the address of the flash area.
Definition: img_mgmt.h:140
@ IMG_MGMT_ERR_ACTIVE_SLOT_NOT_KNOWN
Current active slot for image cannot be determined.
Definition: img_mgmt.h:167
@ IMG_MGMT_ERR_NO_IMAGE
There is no image in the slot.
Definition: img_mgmt.h:74
@ IMG_MGMT_ERR_CURRENT_VERSION_IS_NEWER
The currently running application is newer than the version being uploaded.
Definition: img_mgmt.h:146
@ IMG_MGMT_ERR_INVALID_IMAGE_VECTOR_TABLE
The image vector table is invalid.
Definition: img_mgmt.h:152
@ IMG_MGMT_ERR_INVALID_TLV
The image in the slot has an invalid TLV type and/or length.
Definition: img_mgmt.h:80
@ IMG_MGMT_ERR_INVALID_HASH
The hash parameter provided is not valid.
Definition: img_mgmt.h:137
@ IMG_MGMT_ERR_INVALID_IMAGE_HEADER_MAGIC
The image header magic value does not match the expected value.
Definition: img_mgmt.h:134
@ IMG_MGMT_ERR_NO_TLVS
The image in the slot has no TLVs (tag, length, value).
Definition: img_mgmt.h:77
@ IMG_MGMT_ERR_FLASH_CONFIG_QUERY_FAIL
Failed to query flash area configuration.
Definition: img_mgmt.h:71
@ IMG_MGMT_ERR_HASH_NOT_FOUND
The image in the slot does not have a hash TLV, which is required.
Definition: img_mgmt.h:89
@ IMG_MGMT_ERR_FLASH_AREA_DEVICE_NULL
The device for the flash area is NULL.
Definition: img_mgmt.h:119
@ IMG_MGMT_ERR_INVALID_SLOT
The provided slot is not valid.
Definition: img_mgmt.h:107
@ IMG_MGMT_ERR_OK
No error, this is implied if there is no ret value in the response.
Definition: img_mgmt.h:65
@ IMG_MGMT_ERR_FLASH_OPEN_FAILED
Flash area opening failed.
Definition: img_mgmt.h:95
@ IMG_MGMT_ERR_INVALID_PAGE_OFFSET
The offset for a page number is invalid.
Definition: img_mgmt.h:122
@ IMG_MGMT_ERR_FLASH_ERASE_FAILED
Flash area erase failed.
Definition: img_mgmt.h:104
@ IMG_MGMT_ERR_INVALID_OFFSET
The offset parameter was not provided and is required.
Definition: img_mgmt.h:125
@ IMG_MGMT_ERR_UNKNOWN
Unknown error occurred.
Definition: img_mgmt.h:68
@ IMG_MGMT_ERR_INVALID_IMAGE_DATA_OVERRUN
The amount of data sent is larger than the provided image size.
Definition: img_mgmt.h:158
@ IMG_MGMT_ERR_TLV_INVALID_SIZE
The image in the slot has an invalid TLV size.
Definition: img_mgmt.h:86
@ IMG_MGMT_ERR_FLASH_READ_FAILED
Flash area reading failed.
Definition: img_mgmt.h:98
@ IMG_MGMT_ERR_FLASH_CONTEXT_NOT_SET
The flash context is not set.
Definition: img_mgmt.h:116
@ IMG_MGMT_ERR_IMAGE_SETTING_TEST_TO_ACTIVE_DENIED
Setting test to active slot is not allowed.
Definition: img_mgmt.h:164
@ IMG_MGMT_ERR_INVALID_IMAGE_TOO_LARGE
The image it too large to fit.
Definition: img_mgmt.h:155
@ IMG_MGMT_ERR_NO_FREE_MEMORY
Insufficient heap memory (malloc failed).
Definition: img_mgmt.h:110
@ IMG_MGMT_ERR_TLV_MULTIPLE_HASHES_FOUND
The image in the slot has multiple hash TLVs, which is invalid.
Definition: img_mgmt.h:83
@ IMG_MGMT_ERR_INVALID_IMAGE_HEADER
The image length is smaller than the size of an image header.
Definition: img_mgmt.h:131
@ IMG_MGMT_ERR_FLASH_WRITE_FAILED
Flash area writing failed.
Definition: img_mgmt.h:101
@ IMG_MGMT_ERR_IMAGE_CONFIRMATION_DENIED
Confirmation of image has been denied.
Definition: img_mgmt.h:161
@ IMG_MGMT_ERR_VERSION_GET_FAILED
Failed to get version of currently running application.
Definition: img_mgmt.h:143
@ IMG_MGMT_ERR_FLASH_CONTEXT_ALREADY_SET
The flash context is already set.
Definition: img_mgmt.h:113
@ IMG_MGMT_ERR_IMAGE_ALREADY_PENDING
There is already an image operating pending.
Definition: img_mgmt.h:149
SMP - Simple Management Protocol.
flags
Definition: parser.h:96
__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:193
uint8_t data_sha[32]
Definition: img_mgmt.h:202
size_t size
Total size of image data.
Definition: img_mgmt.h:199
int area_id
Flash area being written; -1 if no upload in progress.
Definition: img_mgmt.h:195
uint8_t data_sha_len
Hash of image data; used for resumption of a partial upload.
Definition: img_mgmt.h:201
size_t off
Flash offset of next chunk.
Definition: img_mgmt.h:197
Describes what to do during processing of an upload request.
Definition: img_mgmt.h:206
unsigned long long size
The total size of the image.
Definition: img_mgmt.h:208
int area_id
The flash area to write to.
Definition: img_mgmt.h:212
bool proceed
Whether to process the request; false if offset is wrong.
Definition: img_mgmt.h:214
int write_bytes
The number of image bytes to write to flash.
Definition: img_mgmt.h:210
bool erase
Whether to erase the destination flash area.
Definition: img_mgmt.h:216
Represents an individual upload request.
Definition: img_mgmt.h:183
size_t size
Definition: img_mgmt.h:186
bool upgrade
Definition: img_mgmt.h:189
uint32_t image
Definition: img_mgmt.h:184
struct zcbor_string img_data
Definition: img_mgmt.h:187
struct zcbor_string data_sha
Definition: img_mgmt.h:188
size_t off
Definition: img_mgmt.h:185
Decodes, encodes, and transmits SMP packets.
Definition: smp.h:83