Bootloader Image Format
The bootloader image consists of the same structures as the application image, see Application Image Structures. The only difference is in the Bootloader Description structure.
To get information about the bootloader image, please run the following command:
esptool --chip esp32 image-info ./build/bootloader/bootloader.bin
The resultant output will resemble the following:
esptool v5.0.2
Image size: 26352 bytes
ESP32 Image Header
==================
Image version: 1
Entry point: 0x40080644
Segments: 3
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 0x018e8 0x3fff0030 0x00000018 BYTE_ACCESSIBLE, DRAM, DIRAM_DRAM
1 0x03e58 0x40078000 0x00001908 CACHE_APP
2 0x00f5c 0x40080400 0x00005768 IRAM
ESP32 Image Footer
==================
Checksum: 0x6b (valid)
Validation hash: 09fdc81d436a927b5018e19073a787cd37ffce655f505ad92675edd784419034 (valid)
Bootloader Information
======================
Bootloader version: 1
ESP-IDF: v6.0-dev-1620-g15d7e41a848-dirt
Compile time: Aug 8 2025 16:22:1
Bootloader Description
The DRAM0
segment of the bootloader binary starts with the esp_bootloader_desc_t
structure which carries specific fields describing the bootloader. This structure is located at a fixed offset = sizeof(esp_image_header_t
) + sizeof(esp_image_segment_header_t
).
magic_byte
: the magic byte for the esp_bootloader_desc structure
reserved
: reserved for the future IDF use
secure_version
: the secure version used by the bootloader anti-rollback feature, see CONFIG_BOOTLOADER_ANTI_ROLLBACK_ENABLE.
version
: bootloader version, see CONFIG_BOOTLOADER_PROJECT_VER
idf_ver
: ESP-IDF version. [1]
date
andtime
: compile date and time
reserved2
: reserved for the future IDF use
To get the esp_bootloader_desc_t
structure from the running bootloader, use esp_bootloader_get_description()
.
To get the esp_bootloader_desc_t
structure from a running application, use esp_ota_get_bootloader_description()
.
API Reference
Header File
components/esp_bootloader_format/include/esp_bootloader_desc.h
This header file can be included with:
#include "esp_bootloader_desc.h"
This header file is a part of the API provided by the
esp_bootloader_format
component. To declare that your component depends onesp_bootloader_format
, add the following to your CMakeLists.txt:REQUIRES esp_bootloader_format
or
PRIV_REQUIRES esp_bootloader_format
Functions
-
const esp_bootloader_desc_t *esp_bootloader_get_description(void)
Return esp_bootloader_desc structure.
Intended for use by the bootloader.
- Returns:
Pointer to esp_bootloader_desc structure.
Structures
-
struct esp_bootloader_desc_t
Bootloader description structure.
Public Members
-
uint8_t magic_byte
Magic byte ESP_BOOTLOADER_DESC_MAGIC_BYTE
-
uint8_t reserved[2]
reserved for IDF
-
uint8_t secure_version
The version used by bootloader anti-rollback feature
-
uint32_t version
Bootloader version
-
char idf_ver[32]
Version IDF
-
char date_time[24]
Compile date and time
-
uint8_t reserved2[16]
reserved for IDF
-
uint8_t magic_byte
Macros
-
ESP_BOOTLOADER_DESC_MAGIC_BYTE
The magic byte for the esp_bootloader_desc structure that is in DRAM.