App Image Format

[中文]

Application Image Structures

An application image consists of the following:

  1. The esp_image_header_t structure describes the mode of SPI flash and the count of memory segments.

  2. The esp_image_segment_header_t structure describes each segment, its length, and its location in ESP32-C61's memory, followed by the data with a length of data_len. The data offset for each segment in the image is calculated in the following way:

The count of each segment is defined in the segment_count field that is stored in esp_image_header_t. The count cannot be more than ESP_IMAGE_MAX_SEGMENTS.

To get the list of your image segments, please run the following command:

esptool --chip esp32c61 image-info build/app.bin

esptool v5.0.2
Image size: 137312 bytes

ESP32 Image Header
==================
Image version: 1
Entry point: 0x40081214
Segments: 6
Flash size: 2MB
Flash freq: 40m
Flash mode: DIO

ESP32 Extended Image Header
===========================
WP pin: 0xee (disabled)
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
Chip ID: 0 (ESP32)
Minimal chip revision: v0.0, (legacy min_rev = 0)
Maximal chip revision: v3.99

Segments Information
====================
Segment   Length   Load addr   File offs  Memory types
-------  -------  ----------  ----------  ------------
    0  0x0711c  0x3f400020  0x00000018  DROM
    1  0x0241c  0x3ffb0000  0x0000713c  BYTE_ACCESSIBLE, DRAM
    2  0x06ab0  0x40080000  0x00009560  IRAM
    3  0x0b724  0x400d0020  0x00010018  IROM
    4  0x060c0  0x40086ab0  0x0001b744  IRAM
    5  0x00024  0x50000000  0x0002180c  RTC_DATA

ESP32 Image Footer
==================
Checksum: 0x4b (valid)
Validation hash: 8808f05a62fe1a6e1e6830414b95229454b012eb2001511ca434d34e9e63c962 (valid)

Application Information
=======================
Project name: hello_world
App version: qa-test-esp32c61-master-2025070
Compile time: Aug 12 2025 16:36:40
ELF file SHA256: 10972f521b52276e988631d7408de388d639437118e8217c366f2bd93b52e1b6
ESP-IDF: v6.0-dev-1692-g7aad0d47e66-dirt
Minimal eFuse block revision: 0.0
Maximal eFuse block revision: 0.99
MMU page size: 64 KB
Secure version: 0

You can also see the information on segments in the ESP-IDF logs while your application is booting:

I (443) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x13ce0 ( 81120) map
I (489) esp_image: segment 1: paddr=0x00033d08 vaddr=0x3ff80000 size=0x00000 ( 0) load
I (530) esp_image: segment 2: paddr=0x00033d10 vaddr=0x3ff80000 size=0x00000 ( 0) load
I (571) esp_image: segment 3: paddr=0x00033d18 vaddr=0x3ffb0000 size=0x028e0 ( 10464) load
I (612) esp_image: segment 4: paddr=0x00036600 vaddr=0x3ffb28e0 size=0x00000 ( 0) load
I (654) esp_image: segment 5: paddr=0x00036608 vaddr=0x40080000 size=0x00400 ( 1024) load
I (695) esp_image: segment 6: paddr=0x00036a10 vaddr=0x40080400 size=0x09600 ( 38400) load
I (737) esp_image: segment 7: paddr=0x00040018 vaddr=0x400d0018 size=0x62e4c (405068) map
I (847) esp_image: segment 8: paddr=0x000a2e6c vaddr=0x40089a00 size=0x06cec ( 27884) load
I (888) esp_image: segment 9: paddr=0x000a9b60 vaddr=0x400c0000 size=0x00000 ( 0) load
I (929) esp_image: segment 10: paddr=0x000a9b68 vaddr=0x50000000 size=0x00004 ( 4) load
I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load
I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load

For more details on the type of memory segments and their address ranges, see ESP32-C61 Technical Reference Manual > System and Memory > Internal Memory [PDF].

  1. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding.

  2. If the hash_appended field from esp_image_header_t is set then a SHA256 checksum will be appended. The value of the SHA256 hash is calculated on the range from the first byte and up to this field. The length of this field is 32 bytes.

  3. If the option CONFIG_SECURE_SIGNED_APPS_SCHEME is set to ECDSA then the application image will have an additional 68 bytes for an ECDSA signature, which includes:

    • version word (4 bytes)

    • signature data (64 bytes)

  4. If the option CONFIG_SECURE_SIGNED_APPS_SCHEME is set to RSA or ECDSA (V2) then the application image will have an additional signature sector of 4 KB in size. For more details on the format of this signature sector, please refer to Signature Block Format.

Application Description

The DROM segment of the application binary starts with the esp_app_desc_t structure which carries specific fields describing the application:

  • magic_word: the magic word for the esp_app_desc_t structure

  • secure_version: see Anti-rollback

  • version: see App version [1]

  • project_name: filled from PROJECT_NAME [1]

  • time and date: compile time and date

  • idf_ver: version of ESP-IDF [1]

  • app_elf_sha256: contains SHA256 hash for the application ELF file

This structure is useful for identification of images uploaded via Over-the-Air (OTA) updates because it has a fixed offset = sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t). As soon as a device receives the first fragment containing this structure, it has all the information to determine whether the update should be continued with or not.

To obtain the esp_app_desc_t structure for the currently running application, use esp_app_get_description().

To obtain the esp_app_desc_t structure for another OTA partition, use esp_ota_get_partition_description().

Adding a Custom Structure to an Application

Users also have the opportunity to have similar structure with a fixed offset relative to the beginning of the image.

The following pattern can be used to add a custom structure to your image:

const __attribute__((section(".rodata_custom_desc"))) esp_custom_app_desc_t custom_app_desc = { ... }

Offset for custom structure is sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t) + sizeof(esp_app_desc_t).

To guarantee that the custom structure is located in the image even if it is not used, you need to add target_link_libraries(${COMPONENT_TARGET} "-u custom_app_desc") into CMakeLists.txt.

API Reference

Header File

  • components/bootloader_support/include/esp_app_format.h

  • This header file can be included with:

    #include "esp_app_format.h"

  • This header file is a part of the API provided by the bootloader_support component. To declare that your component depends on bootloader_support, add the following to your CMakeLists.txt:

    REQUIRES bootloader_support

    or

    PRIV_REQUIRES bootloader_support

Structures

struct esp_image_header_t

Main header of binary image.

Public Members

uint8_t magic

Magic word ESP_IMAGE_HEADER_MAGIC

uint8_t segment_count

Count of memory segments

uint8_t spi_mode

flash read mode (esp_image_spi_mode_t as uint8_t)

uint8_t spi_speed

flash frequency (esp_image_spi_freq_t as uint8_t)

uint8_t spi_size

flash chip size (esp_image_flash_size_t as uint8_t)

uint32_t entry_addr

Entry address

uint8_t wp_pin

WP pin when SPI pins set via efuse (read by ROM bootloader, the IDF bootloader uses software to configure the WP pin and sets this field to 0xEE=disabled)

uint8_t spi_pin_drv[3]

Drive settings for the SPI flash pins (read by ROM bootloader)

esp_chip_id_t chip_id

Chip identification number

uint8_t min_chip_rev

Minimal chip revision supported by image After the Major and Minor revision eFuses were introduced into the chips, this field is no longer used. But for compatibility reasons, we keep this field and the data in it. Use min_chip_rev_full instead. The software interprets this as a Major version for most of the chips and as a Minor version for the ESP32-C3.

uint16_t min_chip_rev_full

Minimal chip revision supported by image, in format: major * 100 + minor

uint16_t max_chip_rev_full

Maximal chip revision supported by image, in format: major * 100 + minor

uint8_t reserved[4]

Reserved bytes in additional header space, currently unused

uint8_t hash_appended

If 1, a SHA256 digest "simple hash" (of the entire image) is appended after the checksum. Included in image length. This digest is separate to secure boot and only used for detecting corruption. For secure boot signed images, the signature is appended after this (and the simple hash is included in the signed data).

struct esp_image_segment_header_t

Header of binary image segment.

Public Members

uint32_t load_addr

Address of segment

uint32_t data_len

Length of data

Macros

ESP_IMAGE_HEADER_MAGIC

The magic word for the esp_image_header_t structure.

ESP_IMAGE_MAX_SEGMENTS

Max count of segments in the image.

Enumerations

enum esp_chip_id_t

ESP chip ID.

Values:

enumerator ESP_CHIP_ID_ESP32

chip ID: ESP32

enumerator ESP_CHIP_ID_ESP32S2

chip ID: ESP32-S2

enumerator ESP_CHIP_ID_ESP32C3

chip ID: ESP32-C3

enumerator ESP_CHIP_ID_ESP32S3

chip ID: ESP32-S3

enumerator ESP_CHIP_ID_ESP32C2

chip ID: ESP32-C2

enumerator ESP_CHIP_ID_ESP32C6

chip ID: ESP32-C6

enumerator ESP_CHIP_ID_ESP32H2

chip ID: ESP32-H2

enumerator ESP_CHIP_ID_ESP32P4

chip ID: ESP32-P4

enumerator ESP_CHIP_ID_ESP32C5

chip ID: ESP32-C5

enumerator ESP_CHIP_ID_ESP32C61

chip ID: ESP32-C61

enumerator ESP_CHIP_ID_ESP32H21

chip ID: ESP32-H21

enumerator ESP_CHIP_ID_ESP32H4

chip ID: ESP32-H4

enumerator ESP_CHIP_ID_INVALID

Invalid chip ID (we defined it to make sure the esp_chip_id_t is 2 bytes size)

enum esp_image_spi_mode_t

SPI flash mode, used in esp_image_header_t.

Values:

enumerator ESP_IMAGE_SPI_MODE_QIO

SPI mode QIO

enumerator ESP_IMAGE_SPI_MODE_QOUT

SPI mode QOUT

enumerator ESP_IMAGE_SPI_MODE_DIO

SPI mode DIO

enumerator ESP_IMAGE_SPI_MODE_DOUT

SPI mode DOUT

enumerator ESP_IMAGE_SPI_MODE_FAST_READ

SPI mode FAST_READ

enumerator ESP_IMAGE_SPI_MODE_SLOW_READ

SPI mode SLOW_READ

enum esp_image_spi_freq_t

SPI flash clock division factor.

Values:

enumerator ESP_IMAGE_SPI_SPEED_DIV_2

The SPI flash clock frequency is divided by 2 of the clock source

enumerator ESP_IMAGE_SPI_SPEED_DIV_3

The SPI flash clock frequency is divided by 3 of the clock source

enumerator ESP_IMAGE_SPI_SPEED_DIV_4

The SPI flash clock frequency is divided by 4 of the clock source

enumerator ESP_IMAGE_SPI_SPEED_DIV_1

The SPI flash clock frequency equals to the clock source

enum esp_image_flash_size_t

Supported SPI flash sizes.

Values:

enumerator ESP_IMAGE_FLASH_SIZE_1MB

SPI flash size 1 MB

enumerator ESP_IMAGE_FLASH_SIZE_2MB

SPI flash size 2 MB

enumerator ESP_IMAGE_FLASH_SIZE_4MB

SPI flash size 4 MB

enumerator ESP_IMAGE_FLASH_SIZE_8MB

SPI flash size 8 MB

enumerator ESP_IMAGE_FLASH_SIZE_16MB

SPI flash size 16 MB

enumerator ESP_IMAGE_FLASH_SIZE_32MB

SPI flash size 32 MB

enumerator ESP_IMAGE_FLASH_SIZE_64MB

SPI flash size 64 MB

enumerator ESP_IMAGE_FLASH_SIZE_128MB

SPI flash size 128 MB

enumerator ESP_IMAGE_FLASH_SIZE_MAX

SPI flash size MAX

Was this page helpful?