1.. _image-format:
2
3Firmware Image Format
4=====================
5
6This is technical documentation for the firmware image format used by the ROM bootloader. These are the images created by ``esptool.py elf2image``.
7
8.. only:: esp8266
9
10    The firmware file consists of a header, a variable number of data segments and a footer. Multi-byte fields are little-endian.
11
12.. only:: not esp8266
13
14    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.
15
16File Header
17-----------
18
19The image header is 8 bytes long:
20
21.. only:: esp8266
22
23    +--------+--------------------------------------------------------------------------------------------------+
24    | Byte   | Description                                                                                      |
25    +========+==================================================================================================+
26    | 0      | Magic number (always ``0xE9``)                                                                   |
27    +--------+--------------------------------------------------------------------------------------------------+
28    | 1      | Number of segments                                                                               |
29    +--------+--------------------------------------------------------------------------------------------------+
30    | 2      | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT)                            |
31    +--------+--------------------------------------------------------------------------------------------------+
32    | 3      | High four bits - Flash size (``0`` = 512KB, ``1`` = 256KB, ``2`` = 1MB, ``3`` = 2MB, ``4`` = 4MB,|
33    |        | ``5`` = 2MB-c1, ``6`` = 4MB-c1, ``8`` = 8MB, ``9`` = 16MB)                                       |
34    |        |                                                                                                  |
35    |        | Low four bits - Flash frequency (``0`` = 40MHz, ``1`` = 26MHz, ``2`` = 20MHz, ``0xf`` = 80MHz)   |
36    +--------+--------------------------------------------------------------------------------------------------+
37    | 4-7    | Entry point address                                                                              |
38    +--------+--------------------------------------------------------------------------------------------------+
39
40.. only:: not esp8266
41
42    +--------+--------------------------------------------------------------------------------------------------+
43    | Byte   | Description                                                                                      |
44    +========+==================================================================================================+
45    | 0      | Magic number (always ``0xE9``)                                                                   |
46    +--------+--------------------------------------------------------------------------------------------------+
47    | 1      | Number of segments                                                                               |
48    +--------+--------------------------------------------------------------------------------------------------+
49    | 2      | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT)                            |
50    +--------+--------------------------------------------------------------------------------------------------+
51    | 3      | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB)   |
52    |        |                                                                                                  |
53    |        | Low four bits - Flash frequency (``0`` = 40MHz, ``1`` = 26MHz, ``2`` = 20MHz, ``0xf`` = 80MHz)   |
54    +--------+--------------------------------------------------------------------------------------------------+
55    | 4-7    | Entry point address                                                                              |
56    +--------+--------------------------------------------------------------------------------------------------+
57
58.. only:: esp32c2 or esp32h2
59
60    .. fail_when_new_target_added::
61
62        TODO: Update flash frequency lists to be esp32c2 or esp32h2 specific
63
64``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.
65
66.. only:: esp8266
67
68    Individual segments come right after this header.
69
70.. only:: not esp8266
71
72    Extended File Header
73    --------------------
74
75    The 16-byte long extended header comes right after the image header, individual segments come right after it:
76
77    +--------+---------------------------------------------------------------------------------------------------------+
78    | Byte   | Description                                                                                             |
79    +========+=========================================================================================================+
80    | 0      | WP pin when SPI pins set via efuse (read by ROM bootloader)                                             |
81    +--------+---------------------------------------------------------------------------------------------------------+
82    | 1-3    | Drive settings for the SPI flash pins (read by ROM bootloader)                                          |
83    +--------+---------------------------------------------------------------------------------------------------------+
84    | 4-5    | Chip ID (which ESP device is this image for)                                                            |
85    +--------+---------------------------------------------------------------------------------------------------------+
86    | 6      | Minimal chip revision supported by the image (deprecated, use the following field)                      |
87    +--------+---------------------------------------------------------------------------------------------------------+
88    | 7-8    | Minimal chip revision supported by the image (in format: major * 100 + minor)                           |
89    +--------+---------------------------------------------------------------------------------------------------------+
90    | 9-10   | Maximal chip revision supported by the image (in format: major * 100 + minor)                           |
91    +--------+---------------------------------------------------------------------------------------------------------+
92    | 11-14  | Reserved bytes in additional header space, currently unused                                             |
93    +--------+---------------------------------------------------------------------------------------------------------+
94    | 15     | Hash appended (If 1, SHA256 digest is appended after the checksum)                                      |
95    +--------+---------------------------------------------------------------------------------------------------------+
96
97Segment
98-------
99
100+---------+-----------------+
101| Byte    | Description     |
102+=========+=================+
103| 0-3     | Memory offset   |
104+---------+-----------------+
105| 4-7     | Segment size    |
106+---------+-----------------+
107| 8...n   | Data            |
108+---------+-----------------+
109
110Footer
111------
112
113The 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``.
114
115.. only:: not esp8266
116
117    If ``hash appended`` in the extended file header is ``0x01``, a SHA256 digest “simple hash” (of the entire image) is appended after the checksum. This digest is separate to secure boot and only used for detecting corruption. The SPI flash info cannot be changed during flashing if hash is appended after the image.
118
119    If secure boot is enabled, a signature is also appended (and the simple hash is included in the signed data). This image signature is `Secure Boot V1 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v1.html#image-signing-algorithm>`_ and `Secure Boot V2 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v2.html#signature-block-format>`_ specific.
120
121
122Analyzing a Binary Image
123------------------------
124
125To analyze a binary image and get a complete summary of its headers and segments, use the :ref:`image_info <image-info>` command with the ``--version 2`` option.
126