1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 #include "esp_flash_partitions.h"
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)
24 /* Support for app/bootloader image parsing
25 Can be compiled as part of app or bootloader code.
28 /* SPI flash mode, used in esp_image_header_t */
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
;
38 /* SPI flash clock frequency */
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
;
46 /* Supported SPI flash sizes */
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
;
56 #define ESP_IMAGE_HEADER_MAGIC 0xE9
58 /* Main header of binary image */
61 uint8_t segment_count
;
62 /* flash read mode (esp_image_spi_mode_t as uint8_t) */
64 /* flash frequency (esp_image_spi_freq_t as uint8_t) */
66 /* flash chip size (esp_image_flash_size_t as uint8_t) */
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) */
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 */
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
;
82 _Static_assert(sizeof(esp_image_header_t
) == 24, "binary image header should be 24 bytes");
84 /* Header of binary image segment */
88 } esp_image_segment_header_t
;
90 #define ESP_IMAGE_MAX_SEGMENTS 16
92 /* Structure to hold on-flash image metadata */
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
;
101 /* Mode selection for esp_image_load() */
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. */
108 } esp_image_load_mode_t
;
111 * @brief Verify and (optionally, in bootloader mode) load an app image.
113 * If encryption is enabled, data will be transparently decrypted.
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.
119 * Image validation checks:
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.
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.
133 esp_err_t
esp_image_load(esp_image_load_mode_t mode
, const esp_partition_pos_t
*part
, esp_image_metadata_t
*data
);
136 * @brief Verify the bootloader image.
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.
141 * @return As per esp_image_load_metadata().
143 esp_err_t
esp_image_verify_bootloader(uint32_t *length
);
147 uint32_t drom_load_addr
;
150 uint32_t irom_load_addr
;
152 } esp_image_flash_mapping_t
;