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.

The firmware file consists of a header, a variable number of data segments and a footer. Multi-byte fields are little-endian.

File Header

The image header is 8 bytes long:

Byte	Description
0	Magic number (always 0xE9)
1	Number of segments
2	SPI Flash Mode (0 = QIO, 1 = QOUT, 2 = DIO, 3 = DOUT)
3	High four bits - Flash size (0 = 512KB, 1 = 256KB, 2 = 1MB, 3 = 2MB, 4 = 4MB, 5 = 2MB-c1, 6 = 4MB-c1, 8 = 8MB, 9 = 16MB) Low four bits - Flash frequency (0 = 40MHz, 1 = 26MHz, 2 = 20MHz, 0xf = 80MHz)
4-7	Entry point address

esptool.py overrides the 2nd and 3rd (start from 0) bytes according to the SPI flash info provided through command line option, but only if there is no SHA256 digest appended after the image. Therefore, if you would like to change SPI flash info during flashing, i.e. with the esptool.py write_flash command, then generate images without SHA256 digests. This can be achieved by running esptool.py elf2image with the --dont-append-digest argument.

Individual segments come right after this header.

Segment

Byte	Description
0-3	Memory offset
4-7	Segment size
8…n	Data

Footer

The file is padded with zeros until its size is one byte less than a multiple of 16 bytes. A last byte (thus making the file size a multiple of 16) is the checksum of the data of all segments. The checksum is defined as the xor-sum of all bytes and the byte 0xEF.

Analyzing a Binary Image

To analyze a binary image and get a complete summary of its headers and segments, use the image_info command with the --version 2 option.