Firmware Image Format
This is technical documentation for the firmware image format used by the ROM bootloader. These are the images created by esptool.py elf2image
.
![](../_images/packetdiag-8483bd17967ef1e47457ec0f7a32f1a0ef11a743.png)
Firmware image format
The firmware file consists of a header, an extended header, a variable number of data segments and a footer. Multi-byte fields are little-endian.
File Header
![](../_images/packetdiag-dd22cd993cca5e989e29b3dac482b5a6141f4ac9.png)
Firmware image header
The image header is 8 bytes long:
Byte |
Description |
---|---|
0 |
Magic number (always |
1 |
Number of segments |
2 |
SPI Flash Mode ( |
3 |
High four bits - Flash size ( Low four bits - Flash frequency ( |
4-7 |
Entry point address |
esptool.py
overrides the 2nd and 3rd (counted from 0) bytes according to the SPI flash info provided through the command line options (see Flash Modes).
These bytes are only overridden if this is a bootloader image (an image written to a correct bootloader offset of 0x1000).
In this case, the appended SHA256 digest, which is a cryptographic hash used to verify the integrity of the image, is also updated to reflect the header changes.
Generating images without SHA256 digest can be achieved by running esptool.py elf2image
with the --dont-append-digest
argument.
Extended File Header
![](../_images/packetdiag-4c3968a7615bbbe93a92420b364c035f106309e4.png)
Extended File Header
Byte |
Description |
---|---|
0 |
WP pin when SPI pins set via eFuse (read by ROM bootloader) |
1-3 |
Drive settings for the SPI flash pins (read by ROM bootloader) |
4-5 |
Chip ID (which ESP device is this image for) |
6 |
Minimal chip revision supported by the image (deprecated, use the following field) |
7-8 |
Minimal chip revision supported by the image (in format: major * 100 + minor) |
9-10 |
Maximal chip revision supported by the image (in format: major * 100 + minor) |
11-14 |
Reserved bytes in additional header space, currently unused |
15 |
Hash appended (If 1, SHA256 digest is appended after the checksum) |
Segment
Byte |
Description |
---|---|
0-3 |
Memory offset |
4-7 |
Segment size |
8…n |
Data |
Analyzing a Binary Image
To analyze a binary image and get a complete summary of its headers and segments, use the image_info command.