Zephyr API Documentation 4.0.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>
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#define IMG_MGMT_ID_SLOT_INFO 6
60
170
179
180extern int boot_current_slot;
181extern struct img_mgmt_state g_img_mgmt_state;
182
185 uint32_t image; /* 0 by default */
186 size_t off; /* SIZE_MAX if unspecified */
187 size_t size; /* SIZE_MAX if unspecified */
188 struct zcbor_string img_data;
189 struct zcbor_string data_sha;
190 bool upgrade; /* Only allow greater version numbers. */
191};
192
205
209 unsigned long long size;
217 bool erase;
218#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
220 const char *rc_rsn;
221#endif
222};
223
224/*
225 * @brief Read info of an image at the specified slot number
226 *
227 * @param image_slot image slot number
228 * @param ver output buffer for image version
229 * @param hash output buffer for image hash
230 * @param flags output buffer for image flags
231 *
232 * @return 0 on success, non-zero on failure.
233 */
234int img_mgmt_read_info(int image_slot, struct image_version *ver, uint8_t *hash, uint32_t *flags);
235
243int img_mgmt_my_version(struct image_version *ver);
244
253int img_mgmt_ver_str(const struct image_version *ver, char *dst);
254
262int img_mgmt_active_slot(int image);
263
272
285
295
312
325int img_mgmt_state_set_pending(int slot, int permanent);
326
336
347int img_mgmt_vercmp(const struct image_version *a, const struct image_version *b);
348
349#if defined(CONFIG_MCUMGR_GRP_IMG_MUTEX)
350/*
351 * @brief Will reset the image management state back to default (no ongoing upload),
352 * requires that CONFIG_MCUMGR_GRP_IMG_MUTEX be enabled to allow for mutex
353 * locking of the image management state object.
354 */
355void img_mgmt_reset_upload(void);
356#endif
357
358#ifdef CONFIG_MCUMGR_GRP_IMG_VERBOSE_ERR
359#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn) ((action)->rc_rsn = (rsn))
360#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) ((action)->rc_rsn)
361int img_mgmt_error_rsp(struct smp_streamer *ctxt, int rc, const char *rsn);
362extern const char *img_mgmt_err_str_app_reject;
363extern const char *img_mgmt_err_str_hdr_malformed;
364extern const char *img_mgmt_err_str_magic_mismatch;
365extern const char *img_mgmt_err_str_no_slot;
366extern const char *img_mgmt_err_str_flash_open_failed;
367extern const char *img_mgmt_err_str_flash_erase_failed;
368extern const char *img_mgmt_err_str_flash_write_failed;
369extern const char *img_mgmt_err_str_downgrade;
370extern const char *img_mgmt_err_str_image_bad_flash_addr;
371extern const char *img_mgmt_err_str_image_too_large;
372extern const char *img_mgmt_err_str_data_overrun;
373#else
374#define IMG_MGMT_UPLOAD_ACTION_SET_RC_RSN(action, rsn)
375#define IMG_MGMT_UPLOAD_ACTION_RC_RSN(action) NULL
376#endif
377
382#ifdef __cplusplus
383}
384#endif
385
386#endif /* H_IMG_MGMT_ */
int boot_current_slot
img_mgmt_id_upload_t
IMG_MGMT_ID_UPLOAD statuses.
Definition img_mgmt.h:174
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:64
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:176
@ IMG_MGMT_ID_UPLOAD_STATUS_COMPLETE
Definition img_mgmt.h:177
@ IMG_MGMT_ID_UPLOAD_STATUS_START
Definition img_mgmt.h:175
@ IMG_MGMT_ERR_NO_FREE_SLOT
There is no free slot to place the image.
Definition img_mgmt.h:93
@ IMG_MGMT_ERR_INVALID_LENGTH
The length parameter was not provided and is required.
Definition img_mgmt.h:129
@ IMG_MGMT_ERR_INVALID_FLASH_ADDRESS
The image load address does not match the address of the flash area.
Definition img_mgmt.h:141
@ IMG_MGMT_ERR_ACTIVE_SLOT_NOT_KNOWN
Current active slot for image cannot be determined.
Definition img_mgmt.h:168
@ IMG_MGMT_ERR_NO_IMAGE
There is no image in the slot.
Definition img_mgmt.h:75
@ IMG_MGMT_ERR_CURRENT_VERSION_IS_NEWER
The currently running application is newer than the version being uploaded.
Definition img_mgmt.h:147
@ IMG_MGMT_ERR_INVALID_IMAGE_VECTOR_TABLE
The image vector table is invalid.
Definition img_mgmt.h:153
@ IMG_MGMT_ERR_INVALID_TLV
The image in the slot has an invalid TLV type and/or length.
Definition img_mgmt.h:81
@ IMG_MGMT_ERR_INVALID_HASH
The hash parameter provided is not valid.
Definition img_mgmt.h:138
@ IMG_MGMT_ERR_INVALID_IMAGE_HEADER_MAGIC
The image header magic value does not match the expected value.
Definition img_mgmt.h:135
@ IMG_MGMT_ERR_NO_TLVS
The image in the slot has no TLVs (tag, length, value).
Definition img_mgmt.h:78
@ IMG_MGMT_ERR_FLASH_CONFIG_QUERY_FAIL
Failed to query flash area configuration.
Definition img_mgmt.h:72
@ IMG_MGMT_ERR_HASH_NOT_FOUND
The image in the slot does not have a hash TLV, which is required.
Definition img_mgmt.h:90
@ IMG_MGMT_ERR_FLASH_AREA_DEVICE_NULL
The device for the flash area is NULL.
Definition img_mgmt.h:120
@ IMG_MGMT_ERR_INVALID_SLOT
The provided slot is not valid.
Definition img_mgmt.h:108
@ IMG_MGMT_ERR_OK
No error, this is implied if there is no ret value in the response.
Definition img_mgmt.h:66
@ IMG_MGMT_ERR_FLASH_OPEN_FAILED
Flash area opening failed.
Definition img_mgmt.h:96
@ IMG_MGMT_ERR_INVALID_PAGE_OFFSET
The offset for a page number is invalid.
Definition img_mgmt.h:123
@ IMG_MGMT_ERR_FLASH_ERASE_FAILED
Flash area erase failed.
Definition img_mgmt.h:105
@ IMG_MGMT_ERR_INVALID_OFFSET
The offset parameter was not provided and is required.
Definition img_mgmt.h:126
@ IMG_MGMT_ERR_UNKNOWN
Unknown error occurred.
Definition img_mgmt.h:69
@ IMG_MGMT_ERR_INVALID_IMAGE_DATA_OVERRUN
The amount of data sent is larger than the provided image size.
Definition img_mgmt.h:159
@ IMG_MGMT_ERR_TLV_INVALID_SIZE
The image in the slot has an invalid TLV size.
Definition img_mgmt.h:87
@ IMG_MGMT_ERR_FLASH_READ_FAILED
Flash area reading failed.
Definition img_mgmt.h:99
@ IMG_MGMT_ERR_FLASH_CONTEXT_NOT_SET
The flash context is not set.
Definition img_mgmt.h:117
@ IMG_MGMT_ERR_IMAGE_SETTING_TEST_TO_ACTIVE_DENIED
Setting test to active slot is not allowed.
Definition img_mgmt.h:165
@ IMG_MGMT_ERR_INVALID_IMAGE_TOO_LARGE
The image it too large to fit.
Definition img_mgmt.h:156
@ IMG_MGMT_ERR_NO_FREE_MEMORY
Insufficient heap memory (malloc failed).
Definition img_mgmt.h:111
@ IMG_MGMT_ERR_TLV_MULTIPLE_HASHES_FOUND
The image in the slot has multiple hash TLVs, which is invalid.
Definition img_mgmt.h:84
@ IMG_MGMT_ERR_INVALID_IMAGE_HEADER
The image length is smaller than the size of an image header.
Definition img_mgmt.h:132
@ IMG_MGMT_ERR_FLASH_WRITE_FAILED
Flash area writing failed.
Definition img_mgmt.h:102
@ IMG_MGMT_ERR_IMAGE_CONFIRMATION_DENIED
Confirmation of image has been denied.
Definition img_mgmt.h:162
@ IMG_MGMT_ERR_VERSION_GET_FAILED
Failed to get version of currently running application.
Definition img_mgmt.h:144
@ IMG_MGMT_ERR_FLASH_CONTEXT_ALREADY_SET
The flash context is already set.
Definition img_mgmt.h:114
@ IMG_MGMT_ERR_IMAGE_ALREADY_PENDING
There is already an image operating pending.
Definition img_mgmt.h:150
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:194
uint8_t data_sha[32]
Definition img_mgmt.h:203
size_t size
Total size of image data.
Definition img_mgmt.h:200
int area_id
Flash area being written; -1 if no upload in progress.
Definition img_mgmt.h:196
uint8_t data_sha_len
Hash of image data; used for resumption of a partial upload.
Definition img_mgmt.h:202
size_t off
Flash offset of next chunk.
Definition img_mgmt.h:198
Describes what to do during processing of an upload request.
Definition img_mgmt.h:207
unsigned long long size
The total size of the image.
Definition img_mgmt.h:209
int area_id
The flash area to write to.
Definition img_mgmt.h:213
bool proceed
Whether to process the request; false if offset is wrong.
Definition img_mgmt.h:215
int write_bytes
The number of image bytes to write to flash.
Definition img_mgmt.h:211
bool erase
Whether to erase the destination flash area.
Definition img_mgmt.h:217
Represents an individual upload request.
Definition img_mgmt.h:184
size_t size
Definition img_mgmt.h:187
bool upgrade
Definition img_mgmt.h:190
uint32_t image
Definition img_mgmt.h:185
struct zcbor_string img_data
Definition img_mgmt.h:188
struct zcbor_string data_sha
Definition img_mgmt.h:189
size_t off
Definition img_mgmt.h:186
Decodes, encodes, and transmits SMP packets.
Definition smp.h:83