granicus.if.org Git - esp-idf/blob - components/bootloader_support/include/esp_image_format.h

   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 #ifndef __ESP32_IMAGE_FORMAT_H
  15 #define __ESP32_IMAGE_FORMAT_H
  16
  17 #include <stdbool.h>
  18 #include <esp_err.h>
  19
  20 #define ESP_ERR_IMAGE_BASE       0x2000
  21 #define ESP_ERR_IMAGE_FLASH_FAIL (ESP_ERR_IMAGE_BASE + 1)
  22 #define ESP_ERR_IMAGE_INVALID    (ESP_ERR_IMAGE_BASE + 2)
  23
  24 /* Support for app/bootloader image parsing
  25    Can be compiled as part of app or bootloader code.
  26 */
  27
  28 /* SPI flash mode, used in esp_image_header_t */
  29 typedef enum {
  30     ESP_IMAGE_SPI_MODE_QIO,
  31     ESP_IMAGE_SPI_MODE_QOUT,
  32     ESP_IMAGE_SPI_MODE_DIO,
  33     ESP_IMAGE_SPI_MODE_DOUT,
  34     ESP_IMAGE_SPI_MODE_FAST_READ,
  35     ESP_IMAGE_SPI_MODE_SLOW_READ
  36 } esp_image_spi_mode_t;
  37
  38 /* SPI flash clock frequency */
  39 enum {
  40     ESP_IMAGE_SPI_SPEED_40M,
  41     ESP_IMAGE_SPI_SPEED_26M,
  42     ESP_IMAGE_SPI_SPEED_20M,
  43     ESP_IMAGE_SPI_SPEED_80M = 0xF
  44 } esp_image_spi_freq_t;
  45
  46 /* Supported SPI flash sizes */
  47 typedef enum {
  48     ESP_IMAGE_FLASH_SIZE_1MB = 0,
  49     ESP_IMAGE_FLASH_SIZE_2MB,
  50     ESP_IMAGE_FLASH_SIZE_4MB,
  51     ESP_IMAGE_FLASH_SIZE_8MB,
  52     ESP_IMAGE_FLASH_SIZE_16MB,
  53     ESP_IMAGE_FLASH_SIZE_MAX
  54 } esp_image_flash_size_t;
  55
  56 #define ESP_IMAGE_HEADER_MAGIC 0xE9
  57
  58 /* Main header of binary image */
  59 typedef struct {
  60     uint8_t magic;
  61     uint8_t segment_count;
  62     uint8_t spi_mode;      /* flash read mode (esp_image_spi_mode_t as uint8_t) */
  63     uint8_t spi_speed: 4;  /* flash frequency (esp_image_spi_freq_t as uint8_t) */
  64     uint8_t spi_size: 4;   /* flash chip size (esp_image_flash_size_t as uint8_t) */
  65     uint32_t entry_addr;
  66     uint8_t encrypt_flag;    /* encrypt flag */
  67     uint8_t extra_header[15]; /* ESP32 additional header, unused by second bootloader */
  68 }  esp_image_header_t;
  69
  70 /* Header of binary image segment */
  71 typedef struct {
  72     uint32_t load_addr;
  73     uint32_t data_len;
  74 } esp_image_segment_header_t;
  75
  76
  77 /**
  78  * @brief Read an ESP image header from flash.
  79  *
  80  * If encryption is enabled, data will be transparently decrypted.
  81  *
  82  * @param src_addr Address in flash to load image header. Must be 4 byte aligned.
  83  * @param log_errors Log error output if image header appears invalid.
  84  * @param[out] image_header Pointer to an esp_image_header_t struture to be filled with data. If the function fails, contents are undefined.
  85  *
  86  * @return ESP_OK if image header was loaded, ESP_ERR_IMAGE_FLASH_FAIL
  87  * if a SPI flash error occurs, ESP_ERR_IMAGE_INVALID if the image header
  88  * appears invalid.
  89  */
  90 esp_err_t esp_image_load_header(uint32_t src_addr, bool log_errors, esp_image_header_t *image_header);
  91
  92 /**
  93  * @brief Read the segment header and data offset of a segment in the image.
  94  *
  95  * If encryption is enabled, data will be transparently decrypted.
  96  *
  97  * @param index Index of the segment to load information for.
  98  * @param src_addr Base address in flash of the image.
  99  * @param[in] image_header Pointer to the flash image header, already loaded by @ref esp_image_load_header().
 100  * @param log_errors Log errors reading the segment header.
 101  * @param[out] segment_header Pointer to a segment header structure to be filled with data. If the function fails, contents are undefined.
 102  * @param[out] segment_data_offset Pointer to the data offset of the segment.
 103  *
 104  * @return ESP_OK if segment_header & segment_data_offset were loaded successfully, ESP_ERR_IMAGE_FLASH_FAIL if a SPI flash error occurs, ESP_ERR_IMAGE_INVALID if the image header appears invalid, ESP_ERR_INVALID_ARG if the index is invalid.
 105  */
 106 esp_err_t esp_image_load_segment_header(uint8_t index, uint32_t src_addr, const esp_image_header_t *image_header, bool log_errors, esp_image_segment_header_t *segment_header, uint32_t *segment_data_offset);
 107
 108
 109 /**
 110  * @brief Non-cryptographically validate app image integrity. On success, length of image is provided to caller.
 111  *
 112  * If the image has a secure boot signature appended, the signature is not checked and this length is not included in the
 113  * output value.
 114  *
 115  * Image validation checks:
 116  * - Magic byte
 117  * - No single segment longer than 16MB
 118  * - Total image no longer than 16MB
 119  * - 8 bit image checksum is valid
 120  *
 121  * If flash encryption is enabled, the image will be tranpsarently decrypted.
 122  *
 123  * @param src_addr Offset of the start of the image in flash. Must be 4 byte aligned.
 124  * @param allow_decrypt If true and flash encryption is enabled, the image will be transparently decrypted.
 125  * @param log_errors Log errors verifying the image.
 126  * @param[out] length Length of the image, set to a value if the image is valid. Can be null.
 127  *
 128  * @return ESP_OK if image is valid, ESP_FAIL or ESP_ERR_IMAGE_INVALID on errors.
 129  *
 130  */
 131 esp_err_t esp_image_basic_verify(uint32_t src_addr, bool log_errors, uint32_t *length);
 132
 133
 134 typedef struct {
 135     uint32_t drom_addr;
 136     uint32_t drom_load_addr;
 137     uint32_t drom_size;
 138     uint32_t irom_addr;
 139     uint32_t irom_load_addr;
 140     uint32_t irom_size;
 141 } esp_image_flash_mapping_t;
 142
 143 #endif