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 #pragma once
  15
  16 #include <stdbool.h>
  17 #include <esp_err.h>
  18 #include "esp_flash_partitions.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     /* flash read mode (esp_image_spi_mode_t as uint8_t) */
  63     uint8_t spi_mode;
  64     /* flash frequency (esp_image_spi_freq_t as uint8_t) */
  65     uint8_t spi_speed: 4;
  66     /* flash chip size (esp_image_flash_size_t as uint8_t) */
  67     uint8_t spi_size: 4;
  68     uint32_t entry_addr;
  69     /* WP pin when SPI pins set via efuse (read by ROM bootloader, the IDF bootloader uses software to configure the WP
  70      * pin and sets this field to 0xEE=disabled) */
  71     uint8_t wp_pin;
  72     /* Drive settings for the SPI flash pins (read by ROM bootloader) */
  73     uint8_t spi_pin_drv[3];
  74     /* Reserved bytes in ESP32 additional header space, currently unused */
  75     uint8_t reserved[11];
  76     /* If 1, a SHA256 digest "simple hash" (of the entire image) is appended after the checksum. Included in image length. This digest
  77      * is separate to secure boot and only used for detecting corruption. For secure boot signed images, the signature
  78      * is appended after this (and the simple hash is included in the signed data). */
  79     uint8_t hash_appended;
  80 } __attribute__((packed))  esp_image_header_t;
  81
  82 _Static_assert(sizeof(esp_image_header_t) == 24, "binary image header should be 24 bytes");
  83
  84 /* Header of binary image segment */
  85 typedef struct {
  86     uint32_t load_addr;
  87     uint32_t data_len;
  88 } esp_image_segment_header_t;
  89
  90 #define ESP_IMAGE_MAX_SEGMENTS 16
  91
  92 /* Structure to hold on-flash image metadata */
  93 typedef struct {
  94   uint32_t start_addr;   /* Start address of image */
  95   esp_image_header_t image; /* Header for entire image */
  96   esp_image_segment_header_t segments[ESP_IMAGE_MAX_SEGMENTS]; /* Per-segment header data */
  97   uint32_t segment_data[ESP_IMAGE_MAX_SEGMENTS]; /* Data offsets for each segment */
  98   uint32_t image_len; /* Length of image on flash, in bytes */
  99 } esp_image_metadata_t;
 100
 101 /* Mode selection for esp_image_load() */
 102 typedef enum {
 103     ESP_IMAGE_VERIFY,        /* Verify image contents, load metadata. Print errorsors. */
 104     ESP_IMAGE_VERIFY_SILENT, /* Verify image contents, load metadata. Don't print errors. */
 105 #ifdef BOOTLOADER_BUILD
 106     ESP_IMAGE_LOAD,          /* Verify image contents, load to memory. Print errors. */
 107 #endif
 108 } esp_image_load_mode_t;
 109
 110 /**
 111  * @brief Verify and (optionally, in bootloader mode) load an app image.
 112  *
 113  * If encryption is enabled, data will be transparently decrypted.
 114  *
 115  * @param mode Mode of operation (verify, silent verify, or load).
 116  * @param part Partition to load the app from.
 117  * @param[inout] data Pointer to the image metadata structure which is be filled in by this function. 'start_addr' member should be set (to the start address of the image.) Other fields will all be initialised by this function.
 118  *
 119  * Image validation checks:
 120  * - Magic byte.
 121  * - Partition smaller than 16MB.
 122  * - All segments & image fit in partition.
 123  * - 8 bit image checksum is valid.
 124  * - SHA-256 of image is valid (if image has this appended).
 125  * - (Signature) if signature verification is enabled.
 126  *
 127  * @return
 128  * - ESP_OK if verify or load was successful
 129  * - ESP_ERR_IMAGE_FLASH_FAIL if a SPI flash error occurs
 130  * - ESP_ERR_IMAGE_INVALID if the image appears invalid.
 131  * - ESP_ERR_INVALID_ARG if the partition or data pointers are invalid.
 132  */
 133 esp_err_t esp_image_load(esp_image_load_mode_t mode, const esp_partition_pos_t *part, esp_image_metadata_t *data);
 134
 135 /**
 136  * @brief Verify the bootloader image.
 137  *
 138  * @param[out] If result is ESP_OK and this pointer is non-NULL, it
 139  * will be set to the length of the bootloader image.
 140  *
 141  * @return As per esp_image_load_metadata().
 142  */
 143 esp_err_t esp_image_verify_bootloader(uint32_t *length);
 144
 145 typedef struct {
 146     uint32_t drom_addr;
 147     uint32_t drom_load_addr;
 148     uint32_t drom_size;
 149     uint32_t irom_addr;
 150     uint32_t irom_load_addr;
 151     uint32_t irom_size;
 152 } esp_image_flash_mapping_t;