1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #pragma once 15 16 #include <stdbool.h> 17 #include <esp_err.h> 18 #include "esp_flash_partitions.h" 19 #include "esp_app_format.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #define ESP_ERR_IMAGE_BASE 0x2000 26 #define ESP_ERR_IMAGE_FLASH_FAIL (ESP_ERR_IMAGE_BASE + 1) 27 #define ESP_ERR_IMAGE_INVALID (ESP_ERR_IMAGE_BASE + 2) 28 29 /* Support for app/bootloader image parsing 30 Can be compiled as part of app or bootloader code. 31 */ 32 33 #define ESP_IMAGE_HASH_LEN 32 /* Length of the appended SHA-256 digest */ 34 35 /* Structure to hold on-flash image metadata */ 36 typedef struct { 37 uint32_t start_addr; /* Start address of image */ 38 esp_image_header_t image; /* Header for entire image */ 39 esp_image_segment_header_t segments[ESP_IMAGE_MAX_SEGMENTS]; /* Per-segment header data */ 40 uint32_t segment_data[ESP_IMAGE_MAX_SEGMENTS]; /* Data offsets for each segment */ 41 uint32_t image_len; /* Length of image on flash, in bytes */ 42 uint8_t image_digest[32]; /* appended SHA-256 digest */ 43 } esp_image_metadata_t; 44 45 typedef enum { 46 ESP_IMAGE_VERIFY, /* Verify image contents, not load to memory, load metadata. Print errors. */ 47 ESP_IMAGE_VERIFY_SILENT, /* Verify image contents, not load to memory, load metadata. Don't print errors. */ 48 #ifdef BOOTLOADER_BUILD 49 ESP_IMAGE_LOAD, /* Verify image contents, load to memory, load metadata. Print errors. */ 50 ESP_IMAGE_LOAD_NO_VALIDATE, /* Not verify image contents, load to memory, load metadata. Print errors. */ 51 #endif 52 } esp_image_load_mode_t; 53 54 typedef struct { 55 esp_partition_pos_t partition; /*!< Partition of application which worked before goes to the deep sleep. */ 56 uint16_t reboot_counter; /*!< Reboot counter. Reset only when power is off. */ 57 uint16_t reserve; /*!< Reserve */ 58 #ifdef CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC 59 uint8_t custom[CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE]; /*!< Reserve for custom propose */ 60 #endif 61 uint32_t crc; /*!< Check sum crc32 */ 62 } rtc_retain_mem_t; 63 64 #ifdef CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC 65 _Static_assert(CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE % 4 == 0, "CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE must be a multiple of 4 bytes"); 66 #endif 67 68 #if defined(CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP) || defined(CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC) 69 _Static_assert(CONFIG_BOOTLOADER_RESERVE_RTC_SIZE % 4 == 0, "CONFIG_BOOTLOADER_RESERVE_RTC_SIZE must be a multiple of 4 bytes"); 70 #endif 71 72 #ifdef CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC 73 #define ESP_BOOTLOADER_RESERVE_RTC (CONFIG_BOOTLOADER_RESERVE_RTC_SIZE + CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE) 74 #elif defined(CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP) 75 #define ESP_BOOTLOADER_RESERVE_RTC (CONFIG_BOOTLOADER_RESERVE_RTC_SIZE) 76 #endif 77 78 #if defined(CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP) || defined(CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC) 79 _Static_assert(sizeof(rtc_retain_mem_t) <= ESP_BOOTLOADER_RESERVE_RTC, "Reserved RTC area must exceed size of rtc_retain_mem_t"); 80 #endif 81 82 /** 83 * @brief Verify an app image. 84 * 85 * If encryption is enabled, data will be transparently decrypted. 86 * 87 * @param mode Mode of operation (verify, silent verify, or load). 88 * @param part Partition to load the app from. 89 * @param[inout] data Pointer to the image metadata structure which is be filled in by this function. 90 * 'start_addr' member should be set (to the start address of the image.) 91 * Other fields will all be initialised by this function. 92 * 93 * Image validation checks: 94 * - Magic byte. 95 * - Partition smaller than 16MB. 96 * - All segments & image fit in partition. 97 * - 8 bit image checksum is valid. 98 * - SHA-256 of image is valid (if image has this appended). 99 * - (Signature) if signature verification is enabled. 100 * 101 * @return 102 * - ESP_OK if verify or load was successful 103 * - ESP_ERR_IMAGE_FLASH_FAIL if a SPI flash error occurs 104 * - ESP_ERR_IMAGE_INVALID if the image appears invalid. 105 * - ESP_ERR_INVALID_ARG if the partition or data pointers are invalid. 106 */ 107 esp_err_t esp_image_verify(esp_image_load_mode_t mode, const esp_partition_pos_t *part, esp_image_metadata_t *data); 108 109 /** 110 * @brief Get metadata of app 111 * 112 * If encryption is enabled, data will be transparently decrypted. 113 * 114 * @param part Partition to load the app from. 115 * @param[out] metadata Pointer to the image metadata structure which is be filled in by this function. 116 * Fields will all be initialised by this function. 117 * 118 * @return 119 * - ESP_OK if filling of metadata was successful 120 */ 121 esp_err_t esp_image_get_metadata(const esp_partition_pos_t *part, esp_image_metadata_t *metadata); 122 123 /** 124 * @brief Verify and load an app image (available only in space of bootloader). 125 * 126 * If encryption is enabled, data will be transparently decrypted. 127 * 128 * @param part Partition to load the app from. 129 * @param[inout] data Pointer to the image metadata structure which is be filled in by this function. 130 * 'start_addr' member should be set (to the start address of the image.) 131 * Other fields will all be initialised by this function. 132 * 133 * Image validation checks: 134 * - Magic byte. 135 * - Partition smaller than 16MB. 136 * - All segments & image fit in partition. 137 * - 8 bit image checksum is valid. 138 * - SHA-256 of image is valid (if image has this appended). 139 * - (Signature) if signature verification is enabled. 140 * 141 * @return 142 * - ESP_OK if verify or load was successful 143 * - ESP_ERR_IMAGE_FLASH_FAIL if a SPI flash error occurs 144 * - ESP_ERR_IMAGE_INVALID if the image appears invalid. 145 * - ESP_ERR_INVALID_ARG if the partition or data pointers are invalid. 146 */ 147 esp_err_t bootloader_load_image(const esp_partition_pos_t *part, esp_image_metadata_t *data); 148 149 /** 150 * @brief Load an app image without verification (available only in space of bootloader). 151 * 152 * If encryption is enabled, data will be transparently decrypted. 153 * 154 * @param part Partition to load the app from. 155 * @param[inout] data Pointer to the image metadata structure which is be filled in by this function. 156 * 'start_addr' member should be set (to the start address of the image.) 157 * Other fields will all be initialised by this function. 158 * 159 * @return 160 * - ESP_OK if verify or load was successful 161 * - ESP_ERR_IMAGE_FLASH_FAIL if a SPI flash error occurs 162 * - ESP_ERR_IMAGE_INVALID if the image appears invalid. 163 * - ESP_ERR_INVALID_ARG if the partition or data pointers are invalid. 164 */ 165 esp_err_t bootloader_load_image_no_verify(const esp_partition_pos_t *part, esp_image_metadata_t *data); 166 167 /** 168 * @brief Verify the bootloader image. 169 * 170 * @param[out] If result is ESP_OK and this pointer is non-NULL, it 171 * will be set to the length of the bootloader image. 172 * 173 * @return As per esp_image_load_metadata(). 174 */ 175 esp_err_t esp_image_verify_bootloader(uint32_t *length); 176 177 /** 178 * @brief Verify the bootloader image. 179 * 180 * @param[out] Metadata for the image. Only valid if result is ESP_OK. 181 * 182 * @return As per esp_image_load_metadata(). 183 */ 184 esp_err_t esp_image_verify_bootloader_data(esp_image_metadata_t *data); 185 186 /** 187 * @brief Get the flash size of the image 188 * 189 * @param app_flash_size The value configured in the image header 190 * @return Actual size, in bytes. 191 */ 192 int esp_image_get_flash_size(esp_image_flash_size_t app_flash_size); 193 194 195 typedef struct { 196 uint32_t drom_addr; 197 uint32_t drom_load_addr; 198 uint32_t drom_size; 199 uint32_t irom_addr; 200 uint32_t irom_load_addr; 201 uint32_t irom_size; 202 } esp_image_flash_mapping_t; 203 204 #ifdef __cplusplus 205 } 206 #endif 207
