Loading...
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | /*
* Copyright (c) 2017 Nordic Semiconductor ASA
* Copyright (c) 2016 Linaro Limited
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_DFU_MCUBOOT_H_
#define ZEPHYR_INCLUDE_DFU_MCUBOOT_H_
#include <stdbool.h>
#include <stddef.h>
#include <zephyr/types.h>
#ifdef __cplusplus
extern "C" {
#endif
#ifdef BOOT_SWAP_TYPE_NONE
#if BOOT_SWAP_TYPE_NONE != 1 /*ensure the same definition in MCUboot */
#error "definition incompatible"
#endif
#else
/** Attempt to boot the contents of slot 0. */
#define BOOT_SWAP_TYPE_NONE 1
#endif
#ifdef BOOT_SWAP_TYPE_TEST
#if BOOT_SWAP_TYPE_TEST != 2 /*ensure the same definition in MCUboot */
#error "definition incompatible"
#endif
#else
/** Swap to slot 1. Absent a confirm command, revert back on next boot. */
#define BOOT_SWAP_TYPE_TEST 2
#endif
#ifdef BOOT_SWAP_TYPE_PERM
#if BOOT_SWAP_TYPE_PERM != 3 /*ensure the same definition in MCUboot */
#error "definition incompatible"
#endif
#else
/** Swap to slot 1, and permanently switch to booting its contents. */
#define BOOT_SWAP_TYPE_PERM 3
#endif
#ifdef BOOT_SWAP_TYPE_REVERT
#if BOOT_SWAP_TYPE_REVERT != 4 /*ensure the same definition in MCUboot */
#error "definition incompatible"
#endif
#else
/** Swap back to alternate slot. A confirm changes this state to NONE. */
#define BOOT_SWAP_TYPE_REVERT 4
#endif
#ifdef BOOT_SWAP_TYPE_FAIL
#if BOOT_SWAP_TYPE_FAIL != 5 /*ensure the same definition in MCUboot */
#error "definition incompatible"
#endif
#else
/** Swap failed because image to be run is not valid */
#define BOOT_SWAP_TYPE_FAIL 5
#endif
#define BOOT_IMG_VER_STRLEN_MAX 25 /* 255.255.65535.4294967295\0 */
/* Trailer: */
#define BOOT_MAX_ALIGN 8
#ifndef BOOT_MAGIC_SZ
#define BOOT_MAGIC_SZ 16
#endif
#define BOOT_TRAILER_IMG_STATUS_OFFS(bank_area) ((bank_area)->fa_size -\
BOOT_MAGIC_SZ -\
BOOT_MAX_ALIGN * 2)
/**
* @brief MCUboot image header representation for image version
*
* The header for an MCUboot firmware image contains an embedded
* version number, in semantic versioning format. This structure
* represents the information it contains.
*/
struct mcuboot_img_sem_ver {
uint8_t major;
uint8_t minor;
uint16_t revision;
uint32_t build_num;
};
/**
* @brief Model for the MCUboot image header as of version 1
*
* This represents the data present in the image header, in version 1
* of the header format.
*
* Some information present in the header but not currently relevant
* to applications is omitted.
*/
struct mcuboot_img_header_v1 {
/** The size of the image, in bytes. */
uint32_t image_size;
/** The image version. */
struct mcuboot_img_sem_ver sem_ver;
};
/**
* @brief Model for the MCUBoot image header
*
* This contains the decoded image header, along with the major
* version of MCUboot that the header was built for.
*
* (The MCUboot project guarantees that incompatible changes to the
* image header will result in major version changes to the bootloader
* itself, and will be detectable in the persistent representation of
* the header.)
*/
struct mcuboot_img_header {
/**
* The version of MCUboot the header is built for.
*
* The value 1 corresponds to MCUboot versions 1.x.y.
*/
uint32_t mcuboot_version;
/**
* The header information. It is only valid to access fields
* in the union member corresponding to the mcuboot_version
* field above.
*/
union {
/** Header information for MCUboot version 1. */
struct mcuboot_img_header_v1 v1;
} h;
};
/**
* @brief Read the MCUboot image header information from an image bank.
*
* This attempts to parse the image header,
* From the start of the @a area_id image.
*
* @param area_id flash_area ID of image bank which stores the image.
* @param header On success, the returned header information is available
* in this structure.
* @param header_size Size of the header structure passed by the caller.
* If this is not large enough to contain all of the
* necessary information, an error is returned.
* @return Zero on success, a negative value on error.
*/
int boot_read_bank_header(uint8_t area_id,
struct mcuboot_img_header *header,
size_t header_size);
/**
* @brief Check if the currently running image is confirmed as OK.
*
* MCUboot can perform "test" upgrades. When these occur, a new
* firmware image is installed and booted, but the old version will be
* reverted at the next reset unless the new image explicitly marks
* itself OK.
*
* This routine can be used to check if the currently running image
* has been marked as OK.
*
* @return True if the image is confirmed as OK, false otherwise.
* @see boot_write_img_confirmed()
*/
bool boot_is_img_confirmed(void);
/**
* @brief Marks the currently running image as confirmed.
*
* This routine attempts to mark the currently running firmware image
* as OK, which will install it permanently, preventing MCUboot from
* reverting it for an older image at the next reset.
*
* This routine is safe to call if the current image has already been
* confirmed. It will return a successful result in this case.
*
* @return 0 on success, negative errno code on fail.
*/
int boot_write_img_confirmed(void);
/**
* @brief Determines the action, if any, that mcuboot will take on the next
* reboot.
* @return a BOOT_SWAP_TYPE_[...] constant on success, negative errno code on
* fail.
*/
int mcuboot_swap_type(void);
/** Boot upgrade request modes */
#define BOOT_UPGRADE_TEST 0
#define BOOT_UPGRADE_PERMANENT 1
/**
* @brief Marks the image in slot 1 as pending. On the next reboot, the system
* will perform a boot of the slot 1 image.
*
* @param permanent Whether the image should be used permanently or
* only tested once:
* BOOT_UPGRADE_TEST=run image once, then confirm or revert.
* BOOT_UPGRADE_PERMANENT=run image forever.
* @return 0 on success, negative errno code on fail.
*/
int boot_request_upgrade(int permanent);
/**
* @brief Erase the image Bank.
*
* @param area_id flash_area ID of image bank to be erased.
* @return 0 on success, negative errno code on fail.
*/
int boot_erase_img_bank(uint8_t area_id);
#ifdef __cplusplus
}
#endif
#endif /* ZEPHYR_INCLUDE_DFU_MCUBOOT_H_ */
|