# Technical Documentation: espressif/esptool > ℹ️ **Provenance:** Hybrid Fusion: `espressif/esptool` (README + 10 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/espressif/esptool) · Recency: Active (< 180 days) ## 1. Project Overview & Quickstart (espressif/esptool) # esptool A Python-based, open-source, platform-independent serial utility for flashing, provisioning, and interacting with Espressif SoCs. [](https://github.com/espressif/esptool/actions/workflows/test_esptool.yml) [](https://github.com/espressif/esptool/actions/workflows/build_esptool.yml) [](https://results.pre-commit.ci/latest/github/espressif/esptool/master) ## Documentation Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -h`. ## Flasher Stub esptool uploads a small [flasher stub](https://docs.espressif.com/projects/esptool/en/latest/esptool/flasher-stub.html) program to the chip to improve flashing performance and work around ROM bootloader limitations. The stub is developed in the [esp-flasher-stub](https://github.com/espressif/esp-flasher-stub) repository. Prebuilt binaries are bundled with esptool releases. ## Contribute If you're interested in contributing to esptool, please check the [contributions guide](https://docs.espressif.com/projects/esptool/en/latest/contributing.html). ## About esptool was initially created by Fredrik Ahlberg (@[themadinventor](https://github.com/themadinventor/)), and later maintained by Angus Gratton (@[projectgus](https://github.com/projectgus/)). It is now supported by Espressif Systems. It has also received improvements from many members of the community. ## License This document and the attached source code are released as Free Software under GNU General Public License Version 2 or later. See the accompanying [LICENSE file](https://github.com/espressif/esptool/blob/master/LICENSE) for a copy. ## 2. In-Tree Documentation Chapters (espressif/esptool) ## File: README.md # esptool A Python-based, open-source, platform-independent serial utility for flashing, provisioning, and interacting with Espressif SoCs. [](https://github.com/espressif/esptool/actions/workflows/test_esptool.yml) [](https://github.com/espressif/esptool/actions/workflows/build_esptool.yml) [](https://results.pre-commit.ci/latest/github/espressif/esptool/master) ## Documentation Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -h`. ## Flasher Stub esptool uploads a small [flasher stub](https://docs.espressif.com/projects/esptool/en/latest/esptool/flasher-stub.html) program to the chip to improve flashing performance and work around ROM bootloader limitations. The stub is developed in the [esp-flasher-stub](https://github.com/espressif/esp-flasher-stub) repository. Prebuilt binaries are bundled with esptool releases. ## Contribute If you're interested in contributing to esptool, please check the [contributions guide](https://docs.espressif.com/projects/esptool/en/latest/contributing.html). ## About esptool was initially created by Fredrik Ahlberg (@[themadinventor](https://github.com/themadinventor/)), and later maintained by Angus Gratton (@[projectgus](https://github.com/projectgus/)). It is now supported by Espressif Systems. It has also received improvements from many members of the community. ## License This document and the attached source code are released as Free Software under GNU General Public License Version 2 or later. See the accompanying [LICENSE file](https://github.com/espressif/esptool/blob/master/LICENSE) for a copy. --- ## File: docs/en/advanced-topics/boot-mode-selection.rst {IDF_TARGET_STRAP_BOOT_GPIO:default="GPIO9", esp8266="GPIO0", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32p4="GPIO35", esp32c5="GPIO28", esp32h21="GPIO14", esp32h4="GPIO14", esp32s31="GPIO61"} {IDF_TARGET_STRAP_BOOT_2_GPIO:default="GPIO8", esp32="GPIO2", esp32s2="GPIO46", esp32s3="GPIO46", esp32p4="GPIO36", esp32c5="GPIO27", esp32h21="GPIO13", esp32h4="GPIO13", esp32s31="GPIO60"} {IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000", esp32c5="0x2000", esp32s31="0x2000"} .. _boot-mode: Boot Mode Selection =================== This guide explains how to select the boot mode correctly and describes the boot log messages of {IDF_TARGET_NAME}. .. only:: esp8266 On many development boards with built-in USB/Serial, this is done for you and ``esptool`` can automatically reset the board into bootloader mode. For other configurations, you will need to follow these steps: Required Pins ------------- The following ESP8266 pins must be in a known state for either normal (flash boot) or serial bootloader operation. Most development boards or modules make necessary connections already, internally: +--------+--------------------------------------------------------------------------------------------------------------------+ | GPIO | State | +========+====================================================================================================================+ | 15 | Pulled Low/GND (directly connected to GND, or external pull-down resistor) | +--------+--------------------------------------------------------------------------------------------------------------------+ | 2 | Pull-up resistor High/VCC, or No Connection (pin has internal weak pullup, external pullup resistor is optional) | +--------+--------------------------------------------------------------------------------------------------------------------+ If these pins are set differently to shown, nothing on the ESP8266 will work as expected. See `ESP8266 Pin List document `__ to see what boot modes are enabled for different pin combinations. When the ESP8266 goes into serial bootloader mode, the Boot ROM switches GPIO2 to an output and the UART TX signal is also output to this pin. For this reason GPIO2 should not be directly connected to VCC. Similarly, make sure GPIO2 is not connected to another peripheral where this may cause an issue when in download mode. Select Bootloader Mode ---------------------- The ESP8266 will enter the serial bootloader when GPIO0 is held low on reset. Otherwise it will run the program in flash. +---------------+----------------------------------------+ | GPIO0 Input | Mode | +===============+========================================+ | Low/GND | ROM serial bootloader for esptool | +---------------+----------------------------------------+ | High/VCC | Normal execution mode | +---------------+----------------------------------------+ Many configurations use a "Flash" button that pulls GPIO0 low when pressed. .. only:: not esp8266 .. warning:: The {IDF_TARGET_NAME} has a 45k ohm internal pull-up/pull-down resistor at {IDF_TARGET_STRAP_BOOT_GPIO} (and other pins). If you want to connect a switch button to enter the boot mode, this has to be a strong pull-down. For example a 10k resistor to GND. Information about {IDF_TARGET_NAME} strapping pins can also be found in the `{IDF_TARGET_NAME} Datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__, section "Strapping Pins". On many development boards with built-in USB/Serial, ``esptool`` can automatically reset the board into bootloader mode. For other configurations or custom hardware, you will need to check the orientation of some "strapping pins" to get the correct boot mode: Select Bootloader Mode ---------------------- {IDF_TARGET_STRAP_BOOT_GPIO} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The {IDF_TARGET_NAME} will enter the serial bootloader when {IDF_TARGET_STRAP_BOOT_GPIO} is held low on reset. Otherwise it will run the program in flash. .. list-table:: :widths: 10 25 :header-rows: 1 * - {IDF_TARGET_STRAP_BOOT_GPIO} Input - Mode * - Low/GND - ROM serial bootloader for esptool * - High/VCC - Normal execution mode {IDF_TARGET_STRAP_BOOT_GPIO} has an internal pullup resistor, so if it is left unconnected then it will pull high. Many boards use a button marked "Flash" (or "BOOT" on some Espressif development boards) that pulls {IDF_TARGET_STRAP_BOOT_GPIO} low when pressed. {IDF_TARGET_STRAP_BOOT_2_GPIO} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. only:: esp32 or esp32s2 or esp32s3 {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be either left unconnected/floating, or driven Low, in order to enter the serial bootloader. .. only:: esp32c3 or esp32c2 or esp32h2 or esp32c6 or esp32p4 or esp32c5 or esp32c61 or esp32h21 or esp32h4 or esp32s31 {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be driven High, in order to enter the serial bootloader reliably. The strapping combination of {IDF_TARGET_STRAP_BOOT_2_GPIO} = 0 and {IDF_TARGET_STRAP_BOOT_GPIO} = 0 is invalid and will trigger unexpected behavior. In normal boot mode ({IDF_TARGET_STRAP_BOOT_GPIO} high), {IDF_TARGET_STRAP_BOOT_2_GPIO} is ignored. Other Pins ^^^^^^^^^^ .. only:: not esp32 As well as the above mentioned pins, other ones influence the serial bootloader, please consult the `{IDF_TARGET_NAME} Datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__, section "Strapping Pins". .. only:: esp32 As well as {IDF_TARGET_STRAP_BOOT_GPIO} and {IDF_TARGET_STRAP_BOOT_2_GPIO}, the following pins influence the serial bootloader mode: +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | GPIO | Meaning | +=============+============================================================================================================================================================================================================================================================================================+ | 12 (MTDI) | If driven High, flash voltage (VDD_SDIO) is 1.8V not default 3.3V. Has internal pull-down, so unconnected = Low = 3.3V. May prevent flashing and/or booting if 3.3V flash is used and this pin is pulled high, causing the flash to brownout. See the datasheet for more details. | +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 15 (MTDO) | If driven Low, silences boot messages printed by the ROM bootloader. Has an internal pull-up, so unconnected = High = normal output. | +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ For more information, consult the `{IDF_TARGET_NAME} Datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__, section "Strapping Pins". .. _automatic-bootloader: Automatic Bootloader -------------------- ``esptool`` resets {IDF_TARGET_NAME} automatically by asserting ``DTR`` and ``RTS`` control lines of the USB to serial converter chip, i.e., FTDI, CP210x, or CH340x. The ``DTR`` and ``RTS`` control lines are in turn connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` (``CHIP_PU``) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of ``DTR`` and ``RTS`` will boot the {IDF_TARGET_NAME} into Firmware Download mode. .. note:: When developing ``esptool``, keep in mind ``DTR`` and ``RTS`` are active low signals, i.e., ``True`` = pin @ 0V, ``False`` = pin @ VCC. As an example of auto-reset curcuitry implementation, check the `schematic `_ of the ESP32 DevKitC development board: - The **Micro USB 5V & USB-UART** section shows the ``DTR`` and ``RTS`` control lines of the USB to serial converter chip connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` pins of the ESP module. - Some OS and/or drivers may activate ``RTS`` and or ``DTR`` automatically when opening the serial port (true only for some serial terminal programs, not ``esptool``), pulling them low together and holding the ESP in reset. If ``RTS`` is wired directly to ``EN`` then RTS/CTS "hardware flow control" needs to be disabled in the serial program to avoid this. An additional circuitry is implemented in order to avoid this problem - if both ``RTS`` and ``DTR`` are asserted together, this doesn't reset the chip. The schematic shows this specific circuit with two transistors and its truth table. - If this circuitry is implemented (all Espressif boards have it), adding a capacitor between the ``EN`` pin and ``GND`` (in the 1uF-10uF range) is necessary for the reset circuitry to work reliably. This is shown in the **ESP32 Module** section of the schematic. - The **Switch Button** section shows buttons needed for :ref:`manually switching to bootloader `. Make the following connections for ``esptool`` to automatically enter the bootloader of an {IDF_TARGET_NAME} chip: .. list-table:: :header-rows: 1 * - ESP Pin - Serial Pin * - EN - RTS * - {IDF_TARGET_STRAP_BOOT_GPIO} - DTR In Linux serial ports by default will assert RTS when nothing is attached to them. This can hold the {IDF_TARGET_NAME} in a reset loop which may cause some serial adapters to subsequently reset loop. This functionality can be disabled by disabling ``HUPCL`` (ie ``sudo stty -F /dev/ttyUSB0 -hupcl``). (Some third party {IDF_TARGET_NAME} development boards use an automatic reset circuit for ``EN`` & ``{IDF_TARGET_STRAP_BOOT_GPIO}`` pins, but don't add a capacitor on the ``EN`` pin. This results in unreliable automatic reset, especially on Windows. Adding a 1uF (or higher) value capacitor between ``EN`` pin and ``GND`` may make automatic reset more reliable.) In general, you should have no problems with the official Espressif development boards. However, ``esptool`` is not able to reset your hardware automatically in the following cases: - Your hardware does not have the ``DTR`` and ``RTS`` lines connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` (``CHIP_PU``) - The ``DTR`` and ``RTS`` lines are configured differently - There are no such serial control lines at all .. _manual-bootloader: Manual Bootloader ----------------- Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset). - For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset a development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_BOOT_GPIO}``) and press the **EN** button (``EN`` (``CHIP_PU``)). - For other types of hardware, try pulling ``{IDF_TARGET_STRAP_BOOT_GPIO}`` down. .. note:: If esptool is able to reset the chip but for some reason the chip is not entering into bootloader mode then hold down the Boot button (or pull down ``{IDF_TARGET_STRAP_BOOT_GPIO}``) while you start esptool and keep it down during reset. .. only:: esp8266 .. _boot-log-esp8266: Boot Log -------- The ESP8266 boot rom writes a log to the UART when booting. The timing is a little bit unusual: ``74880 baud`` (see :ref:`serial-port-settings`). :: ets Jan 8 2014,rst cause 1, boot mode:(3,7) load 0x40100000, len 24236, room 16 tail 12 chksum 0xb7 ho 0 tail 12 room 4 load 0x3ffe8000, len 3008, room 12 tail 4 chksum 0x2c load 0x3ffe8bc0, len 4816, room 4 tail 12 chksum 0x46 csum 0x46 Explanation ^^^^^^^^^^^ **rst_cause:** +---------------+----------------------------------------+ | Value | Meaning | +===============+========================================+ | 1 | power-on | +---------------+----------------------------------------+ | 2 | external-reset | +---------------+----------------------------------------+ | 4 | hardware watchdog-reset | +---------------+----------------------------------------+ **The first parameter of boot_mode:** +-------------------------+----------------------------------------------+ | Value | Meaning | +=========================+==============================================+ | 1 (eg. boot mode:(1,x)) | UART download mode (download FW into Flash) | +-------------------------+----------------------------------------------+ | 2 (eg. boot mode:(3,x)) | Boot from flash mode | +-------------------------+----------------------------------------------+ **chksum:** If value of "chksum" == value of "csum", it means flash has been read correctly during booting. The rest of boot messages are used internally by Espressif. .. only:: not esp8266 Boot Log -------- Boot Mode Message ^^^^^^^^^^^^^^^^^ After reset, the second line printed by the {IDF_TARGET_NAME} ROM (at 115200bps) is a reset & boot mode message: :: ets Jun 8 2016 00:22:57 rst:0x1 (POWERON_RESET),boot:0x3 (DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)) ``rst:0xNN (REASON)`` is an enumerated value (and description) of the reason for the reset. A mapping between the hex value and each reason can be found in the `ESP-IDF source under RESET_REASON enum `__. The value can be read in {IDF_TARGET_NAME} code via the `get_reset_reason() ROM function `__. ``boot:0xNN (DESCRIPTION)`` is the hex value of the strapping pins, as represented in the `GPIO_STRAP register `__. The individual bit values are as follows: .. only:: esp32 - ``0x01`` - GPIO5 - ``0x02`` - MTDO (GPIO15) - ``0x04`` - GPIO4 - ``0x08`` - GPIO2 - ``0x10`` - GPIO0 - ``0x20`` - MTDI (GPIO12) .. only:: not esp32 - ``0x04`` - {IDF_TARGET_STRAP_BOOT_2_GPIO} - ``0x08`` - {IDF_TARGET_STRAP_BOOT_GPIO} If the pin was high on reset, the bit value will be set. If it was low on reset, the bit will be cleared. A number of boot mode strings can be shown depending on which bits are set: - ``DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)`` or ``DOWNLOAD(USB/UART0)`` - {IDF_TARGET_NAME} is in download flashing mode (suitable for esptool) - ``SPI_FAST_FLASH_BOOT`` - This is the normal SPI flash boot mode. - Other modes (including ``SPI_FLASH_BOOT``, ``SDIO_REI_FEO_V1_BOOT``, ``ATE_BOOT``) may be shown here. This indicates an unsupported boot mode has been selected. Consult the strapping pins shown above (in most cases, one of these modes is selected if {IDF_TARGET_STRAP_BOOT_2_GPIO} has been pulled high when {IDF_TARGET_STRAP_BOOT_GPIO} is low). .. only:: esp32 .. note:: ``GPIO_STRAP`` register includes GPIO 4 but this pin is not used by any supported boot mode and be set either high or low for all supported boot modes. Later Boot Messages ^^^^^^^^^^^^^^^^^^^ Later output from the ROM bootloader depends on the strapping pins and the boot mode. Some common output includes: Early Flash Read Error """""""""""""""""""""" .. only:: esp8266 :: flash read err, 0 .. only:: not esp8266 :: Invalid header This fatal error indicates that the bootloader tried to read the software bootloader header at address {IDF_TARGET_BOOTLOADER_OFFSET} but failed to read valid data. Possible reasons for this include: .. list:: - There isn't actually a bootloader at offset {IDF_TARGET_BOOTLOADER_OFFSET} (maybe the bootloader was flashed to the wrong offset by mistake, or the flash has been erased and no bootloader has been flashed yet.) - Physical problem with the connection to the flash chip, or flash chip power. - Flash encryption is enabled but the bootloader is plaintext. Alternatively, flash encryption is disabled but the bootloader is encrypted ciphertext. :esp32: - Boot mode accidentally set to ``HSPI_FLASH_BOOT``, which uses different SPI flash pins. Check {IDF_TARGET_STRAP_BOOT_2_GPIO} (see above). :esp32: - VDDSDIO has been enabled at 1.8V (due to MTDI/GPIO12, see above), but this flash chip requires 3.3V so it's browning out. Software Bootloader Header Info """"""""""""""""""""""""""""""" .. only:: esp32 :: configsip: 0, SPIWP:0x00 clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 mode:DIO, clock div:1 .. only:: not esp32 :: SPIWP:0xee mode:DIO, clock div:1 This is normal boot output based on a combination of eFuse values and information read from the bootloader header at flash offset {IDF_TARGET_BOOTLOADER_OFFSET}: .. list:: :esp32: - ``configsip: N`` indicates SPI flash config: :esp32: - 0 for default SPI flash :esp32: - 1 if booting from the HSPI bus (due to eFuse configuration) :esp32: - Any other value indicates that SPI flash pins have been remapped via eFuse (the value is the value read from eFuse, consult :ref:`espefuse docs ` to get an easier to read representation of these pin mappings). - ``SPIWP:0xNN`` indicates a custom ``WP`` pin value, which is stored in the bootloader header. This pin value is only used if SPI flash pins have been remapped via eFuse (as shown in the ``configsip`` value). All custom pin values but WP are encoded in the configsip byte loaded from eFuse, and WP is supplied in the bootloader header. :esp32: - ``clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00`` Custom GPIO drive strength values for SPI flash pins. These are read from the bootloader header in flash. Not currently supported. - ``mode: AAA, clock div: N``. SPI flash access mode. Read from the bootloader header, correspond to the ``--flash-mode`` and ``--flash-freq`` arguments supplied to ``esptool write-flash`` or ``esptool elf2image``. - ``mode`` can be DIO, DOUT, QIO, or QOUT. *QIO and QOUT are not supported here*, to boot in a Quad I/O mode the ROM bootloader should load the software bootloader in a Dual I/O mode and then the ESP-IDF software bootloader enables Quad I/O based on the detected flash chip mode. - ``clock div: N`` is the SPI flash clock frequency divider. This is an integer clock divider value from an 80MHz APB clock, based on the supplied ``--flash-freq`` argument (ie 80MHz=1, 40MHz=2, etc). The ROM bootloader actually loads the software bootloader at a lower frequency than the ``--flash-freq`` value. The initial APB clock frequency is equal to the crystal frequency, so with a 40MHz crystal the SPI clock used to load the software bootloader will be half the configured value (40MHz/2=20MHz). When the software bootloader starts it sets the APB clock to 80MHz causing the SPI clock frequency to match the value set when flashing. Software Bootloader Load Segments """"""""""""""""""""""""""""""""" :: load:0x3fff0008,len:8 load:0x3fff0010,len:3680 load:0x40078000,len:8364 load:0x40080000,len:252 entry 0x40080034 These entries are printed as the ROM bootloader loads each segment in the software bootloader image. The load address and length of each segment is printed. You can compare these values to the software bootloader image by running ``esptool --chip {IDF_TARGET_PATH_NAME} image-info /path/to/bootloader.bin`` to dump image info including a summary of each segment. Corresponding details will also be found in the bootloader ELF file headers. If there is a problem with the SPI flash chip addressing mode, the values printed by the bootloader here may be corrupted. The final line shows the entry point address of the software bootloader, where the ROM bootloader will call as it hands over control. --- ## File: docs/en/advanced-topics/firmware-image-format.rst {IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48", esp32h21="48", esp32h4="48"} {IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24", esp32h21="24", esp32h4="24"} {IDF_TARGET_FLASH_FREQ_1:default="26", esp32c2="20", esp32h2="16", esp32h21="16", esp32h4="16"} {IDF_TARGET_FLASH_FREQ_2:default="20", esp32c2="15", esp32h2="12", esp32h21="12", esp32h4="12"} {IDF_TARGET_FLASH_SIZE_ENC_EXTRA:default="", esp32s2=", ``5`` = 32MB, ``6`` = 64MB, ``7`` = 128MB", esp32s3=", ``5`` = 32MB, ``6`` = 64MB, ``7`` = 128MB", esp32p4=", ``5`` = 32MB, ``6`` = 64MB", esp32c5=", ``5`` = 32MB", esp32c61=", ``5`` = 32MB", esp32h4=", ``5`` = 32MB", esp32s31=", ``5`` = 32MB, ``6`` = 64MB, ``7`` = 128MB"} {IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000", esp32c5="0x2000", esp32s31="0x2000"} .. _image-format: Firmware Image Format ===================== This is technical documentation for the firmware image format used by the ROM bootloader. These are the images created by ``esptool elf2image``. .. only:: esp8266 .. packetdiag:: diag/firmware_image_format_esp8266.diag :caption: Firmware image format :align: center The firmware file consists of a header, a variable number of data segments and a footer. Multi-byte fields are little-endian. .. only:: not esp8266 .. packetdiag:: diag/firmware_image_format.diag :caption: Firmware image format :align: center 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 ----------- .. packetdiag:: diag/firmware_image_header_format.diag :caption: Firmware image header :align: center The image header is 8 bytes long: .. only:: esp8266 +--------+--------------------------------------------------------------------------------------------------+ | 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 | +--------+--------------------------------------------------------------------------------------------------+ .. only:: not esp8266 .. list-table:: :header-rows: 1 :widths: 15 85 * - 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`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB{IDF_TARGET_FLASH_SIZE_ENC_EXTRA}) .. only:: not (esp32c5 or esp32c61 or esp32c6 or esp32s31) Low four bits - Flash frequency (``0`` = {IDF_TARGET_FLASH_FREQ_0}MHz, ``1`` = {IDF_TARGET_FLASH_FREQ_1}MHz, ``2`` = {IDF_TARGET_FLASH_FREQ_2}MHz, ``0xf`` = {IDF_TARGET_FLASH_FREQ_F}MHz) .. only:: esp32c5 or esp32c61 or esp32s31 Low four bits - Flash frequency (``0xf`` = {IDF_TARGET_FLASH_FREQ_F}MHz, ``0`` = {IDF_TARGET_FLASH_FREQ_0}MHz, ``2`` = {IDF_TARGET_FLASH_FREQ_2}MHz) .. only:: esp32c6 Low four bits - Flash frequency (``0`` = 80MHz or 40MHz, ``2`` = 20MHz) * - 4-7 - Entry point address .. only:: esp32c6 .. note:: Flash frequency with value ``0`` can mean either 80MHz or 40MHz based on MSPI clock source mode. ``esptool`` overrides the 2nd and 3rd (counted from 0) bytes according to the SPI flash info provided through the command line options (see :ref:`flash-modes`). These bytes are only overridden if this is a bootloader image (an image written to a correct bootloader offset of {IDF_TARGET_BOOTLOADER_OFFSET}). 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 elf2image`` with the ``--dont-append-digest`` argument. .. only:: esp8266 Individual segments come right after this header. .. only:: not esp8266 Extended File Header -------------------- .. packetdiag:: diag/firmware_image_ext_header_format.diag :caption: Extended File Header :align: center +--------+---------------------------------------------------------------------------------------------------------+ | 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 | +---------+-----------------+ 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``. .. only:: not esp8266 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. 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 `_ and `Secure Boot V2 `_ specific. Analyzing a Binary Image ------------------------ To analyze a binary image and get a complete summary of its headers and segments, use the :ref:`image-info ` command. --- ## File: docs/en/advanced-topics/index.rst Advanced Topics =============== This sections contains advanced topics and technical documentation useful if you're developing ``esptool`` or hacking system internals: .. toctree:: :maxdepth: 1 Firmware Image Format Serial Protocol SPI Flash Modes Boot Mode Selection --- ## File: docs/en/advanced-topics/serial-protocol.rst {IDF_TARGET_SECURITY_INFO:default="32 bits ``flags``, 1 byte ``flash_crypt_cnt``, 7x1 byte ``key_purposes``, 32-bit word ``chip_id``, 32-bit word ``eco_version``", esp32s2="32 bits ``flags``, 1 byte ``flash_crypt_cnt``, 7x1 byte ``key_purposes`` "} .. _serial-protocol: Serial Protocol =============== This is technical documentation for the serial protocol used by the UART bootloader in the {IDF_TARGET_NAME} ROM and the esptool :ref:`stub loader ` program. The UART bootloader runs on chip reset if certain strapping pins are set. See :ref:`entering-the-bootloader` for details of this process. By default, esptool uploads a stub "software loader" to the IRAM of the chip. The stub loader then replaces the ROM loader for all future interactions. This standardizes much of the behavior. Pass ``--no-stub`` to esptool in order to disable the stub loader. See :ref:`stub` for more information. .. note:: There are differences in the serial protocol between ESP chips! To switch to documentation for a different chip, choose the desired target from the dropdown menu in the upper left corner. Packet Description ------------------ The host computer sends a SLIP encoded command request to the ESP chip. The ESP chip responds to the request with a SLIP encoded response packet, including status information and any data as a payload. .. _low-level-protocol: Low Level Protocol ^^^^^^^^^^^^^^^^^^ The bootloader protocol uses `SLIP `_ packet framing for data transmissions in both directions. Each SLIP packet begins and ends with ``0xC0``. Within the packet, all occurrences of ``0xC0`` and ``0xDB`` are replaced with ``0xDB 0xDC`` and ``0xDB 0xDD``, respectively. The replacing is to be done **after** the checksum and lengths are calculated, so the packet length may be longer than the ``size`` field below. Command Packet ^^^^^^^^^^^^^^ Each command is a SLIP packet initiated by the host and results in a response packet. Inside the packet, the packet consists of a header and a variable-length body. All multi-byte fields are little-endian. .. packetdiag:: diag/command_packet_format.diag :caption: Command packet format :align: center +--------+-------------+--------------------------------------------------------------------------------------------------------------------+ | Byte | Name | Comment | +========+=============+====================================================================================================================+ | 0 | Direction | Always ``0x00`` for requests | +--------+-------------+--------------------------------------------------------------------------------------------------------------------+ | 1 | Command | Command identifier (see `Commands`_). | +--------+-------------+--------------------------------------------------------------------------------------------------------------------+ | 2-3 | Size | Length of Data field, in bytes. | +--------+-------------+--------------------------------------------------------------------------------------------------------------------+ | 4-7 | Checksum | Simple checksum of part of the data field (only used for some commands, see `Checksum`_). | +--------+-------------+--------------------------------------------------------------------------------------------------------------------+ | 8..n | Data | Variable length data payload (0-65535 bytes, as indicated by Size parameter). Usage depends on specific command. | +--------+-------------+--------------------------------------------------------------------------------------------------------------------+ Response Packet ^^^^^^^^^^^^^^^ Each received command will result in a response SLIP packet sent from the ESP chip to the host. Contents of the response packet is: .. packetdiag:: diag/response_packet_format.diag :caption: Command packet format :align: center +--------+-------------+--------------------------------------------------------------------------------------------------------------+ | Byte | Name | Comment | +========+=============+==============================================================================================================+ | 0 | Direction | Always ``0x01`` for responses | +--------+-------------+--------------------------------------------------------------------------------------------------------------+ | 1 | Command | Same value as Command identifier in the request packet that triggered the response | +--------+-------------+--------------------------------------------------------------------------------------------------------------+ | 2-3 | Size | Size of data field. At least the length of the `Status Bytes`_ (2 or 4 bytes, see below). | +--------+-------------+--------------------------------------------------------------------------------------------------------------+ | 4-7 | Value | Response value used by READ_REG command (see below). Zero otherwise. | +--------+-------------+--------------------------------------------------------------------------------------------------------------+ | 8..n | Data | Variable length data payload. Length indicated by "Size" field. | +--------+-------------+--------------------------------------------------------------------------------------------------------------+ Status Bytes """""""""""" The final bytes of the Data payload indicate command status: .. only:: esp8266 For stub loader and ESP8266 ROM loader the final two bytes indicate status (most commands return at least a two byte Data payload): .. only:: not esp8266 For stub loader the final two bytes indicate status (most commands return at least a two byte Data payload): +----------+----------+-----------------------------------------------------+ | Byte | Name | Comment | +==========+==========+=====================================================+ | Size-2 | Status | Status flag, success (``0``) or failure (``1``) | +----------+----------+-----------------------------------------------------+ | Size-1 | Error | If Status is 1, this indicates the type of error. | +----------+----------+-----------------------------------------------------+ .. only:: not esp8266 For {IDF_TARGET_NAME} ROM (only, not the stub loader) the final four bytes are used, but only the first two bytes contain status information: +----------+------------+---------------------------------------------------+ | Byte | Name | Comment | +==========+============+===================================================+ | Size-4 | Status | Status flag, success (``0``) or failure (``1``) | +----------+------------+---------------------------------------------------+ | Size-3 | Error | If Status 1, this indicates the type of error. | +----------+------------+---------------------------------------------------+ | Size-2 | Reserved | | +----------+------------+---------------------------------------------------+ | Size-1 | Reserved | | +----------+------------+---------------------------------------------------+ ROM Loader Errors """"""""""""""""" The ROM loader sends the following error values +----------+---------------------------------------------------------------------------+ | Value | Meaning | +==========+===========================================================================+ | ``0x00`` | "Undefined errors" | +----------+---------------------------------------------------------------------------+ | ``0x01`` | "The input parameter is invalid" | +----------+---------------------------------------------------------------------------+ | ``0x02`` | "Failed to malloc memory from system" | +----------+---------------------------------------------------------------------------+ | ``0x03`` | "Failed to send out message" | +----------+---------------------------------------------------------------------------+ | ``0x04`` | "Failed to receive message" | +----------+---------------------------------------------------------------------------+ | ``0x05`` | "The format of the received message is invalid" | +----------+---------------------------------------------------------------------------+ | ``0x06`` | "Message is ok, but the running result is wrong" | +----------+---------------------------------------------------------------------------+ | ``0x07`` | "Checksum error" | +----------+---------------------------------------------------------------------------+ | ``0x08`` | "Flash write error" - after writing a block of data to flash, | | | the ROM loader reads the value back and the 8-bit CRC is compared | | | to the data read from flash. If they don't match, this error is returned. | +----------+---------------------------------------------------------------------------+ | ``0x09`` | "Flash read error" - SPI read failed | +----------+---------------------------------------------------------------------------+ | ``0x0a`` | "Flash read length error" - SPI read request length is wrong | +----------+---------------------------------------------------------------------------+ | ``0x0b`` | "Deflate failed error" (compressed uploads only) | +----------+---------------------------------------------------------------------------+ | ``0x0c`` | "Deflate Adler32 error" | +----------+---------------------------------------------------------------------------+ | ``0x0d`` | "Deflate parameter error" | +----------+---------------------------------------------------------------------------+ | ``0x0e`` | "Invalid RAM binary size" | +----------+---------------------------------------------------------------------------+ | ``0x0f`` | "Invalid RAM binary address" | +----------+---------------------------------------------------------------------------+ | ``0x64`` | "Invalid parameter" | +----------+---------------------------------------------------------------------------+ | ``0x65`` | "Invalid format" | +----------+---------------------------------------------------------------------------+ | ``0x66`` | "Description too long" | +----------+---------------------------------------------------------------------------+ | ``0x67`` | "Bad encoding description" | +----------+---------------------------------------------------------------------------+ | ``0x69`` | "Insufficient storage" | +----------+---------------------------------------------------------------------------+ Stub Loader Status & Error """""""""""""""""""""""""" If the stub loader is used: - The status response is always 2 bytes regardless of chip type. - Stub loader error codes are entirely different to the ROM loader codes. They all take the form ``0xC*``, or ``0xFF`` for "unimplemented command". (`Full list here `_). After sending a command, the host should continue to read response packets until one is received where the Command field matches the request's Command field, or a timeout is exceeded. Commands ^^^^^^^^ Supported by Stub Loader and ROM Loader """"""""""""""""""""""""""""""""""""""" .. only:: esp8266 +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | Byte | Name | Description | Input Data | Output Data | +============+================+=======================================================+====================================================================================================================================+================================================+ | ``0x02`` | FLASH_BEGIN | `Begin Flash Download <#writing-data>`__ | Four 32-bit words: size to erase, number of data packets, data size in one packet, flash offset. | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x03`` | FLASH_DATA | `Flash Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x04`` | FLASH_END | `Finish Flash Download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x05`` | MEM_BEGIN | `Begin RAM Download Start <#writing-data>`__ | Total size, number of data packets, data size in one packet, memory offset | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x06`` | MEM_END | `Finish RAM Download <#writing-data>`__ | Two 32-bit words: execute flag, entry point address | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x07`` | MEM_DATA | `RAM Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x08`` | SYNC | `Sync Frame <#initial-synchronisation>`__ | 36 bytes: ``0x07 0x07 0x12 0x20``, followed by 32 x ``0x55`` | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x09`` | WRITE_REG | `Write 32-bit memory address <#32-bit-readwrite>`__ | Four 32-bit words: address, value, mask and delay (in microseconds) | | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ | ``0x0a`` | READ_REG | `Read 32-bit memory address <#32-bit-readwrite>`__ | Address as 32-bit word | Read data as 32-bit word in ``value`` field. | +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ .. only:: esp32 +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | Byte | Name | Description | Input Data | Output Data | +============+======================+================================================================+================================================================================================================================================================================================================================================+===================================================================================================================================+ | ``0x02`` | FLASH_BEGIN | `Begin Flash Download <#writing-data>`__ | Four 32-bit words: size to erase, number of data packets, data size in one packet, flash offset. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x03`` | FLASH_DATA | `Flash Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x04`` | FLASH_END | `Finish Flash Download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x05`` | MEM_BEGIN | `Begin RAM Download Start <#writing-data>`__ | Total size, number of data packets, data size in one packet, memory offset | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x06`` | MEM_END | `Finish RAM Download <#writing-data>`__ | Two 32-bit words: execute flag, entry point address | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x07`` | MEM_DATA | `RAM Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x08`` | SYNC | `Sync Frame <#initial-synchronisation>`__ | 36 bytes: ``0x07 0x07 0x12 0x20``, followed by 32 x ``0x55`` | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x09`` | WRITE_REG | `Write 32-bit memory address <#32-bit-readwrite>`__ | Four 32-bit words: address, value, mask and delay (in microseconds) | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0a`` | READ_REG | `Read 32-bit memory address <#32-bit-readwrite>`__ | Address as 32-bit word | Read data as 32-bit word in ``value`` field. | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0b`` | SPI_SET_PARAMS | `Configure SPI flash <#spi-set-parameters>`__ | Six 32-bit words: id, total size in bytes, block size, sector size, page size, status mask. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0d`` | SPI_ATTACH | `Attach SPI flash <#spi-attach-command>`__ | 32-bit word: Zero for normal SPI flash. A second 32-bit word (should be ``0``) is passed to ROM loader only. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0f`` | CHANGE_BAUDRATE | `Change Baud rate <#initial-synchronisation>`__ | Two 32-bit words: new baud rate, ``0`` if we are talking to the ROM loader or the current/old baud rate if we are talking to the stub loader. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x10`` | FLASH_DEFL_BEGIN | `Begin compressed flash download <#writing-data>`__ | Four 32-bit words: uncompressed size, number of data packets, data packet size, flash offset. With stub loader the uncompressed size is exact byte count to be written, whereas on ROM bootloader it is rounded up to flash erase block size. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x11`` | FLASH_DEFL_DATA | `Compressed flash download data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | Error code ``0xC1`` on checksum error. | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x12`` | FLASH_DEFL_END | `End compressed flash download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x13`` | SPI_FLASH_MD5 | `Calculate MD5 of flash region <#verifying-uploaded-data>`__ | Four 32-bit words: address, size, ``0``, ``0`` | Body contains 16 raw bytes of MD5 followed by 2 status bytes (stub loader) or 32 hex-coded ASCII (ROM loader) of calculated MD5 | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ .. only:: not esp8266 and not esp32 +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | Byte | Name | Description | Input Data | Output Data | +============+======================+================================================================+================================================================================================================================================================================================================================================+===================================================================================================================================+ | ``0x02`` | FLASH_BEGIN | `Begin Flash Download <#writing-data>`__ | Four 32-bit words: size to erase, number of data packets, data size in one packet, flash offset. A fifth 32-bit word passed to ROM loader only: ``1`` to begin encrypted flash, ``0`` to not. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x03`` | FLASH_DATA | `Flash Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x04`` | FLASH_END | `Finish Flash Download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x05`` | MEM_BEGIN | `Begin RAM Download Start <#writing-data>`__ | Total size, number of data packets, data size in one packet, memory offset | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x06`` | MEM_END | `Finish RAM Download <#writing-data>`__ | Two 32-bit words: execute flag, entry point address | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x07`` | MEM_DATA | `RAM Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x08`` | SYNC | `Sync Frame <#initial-synchronisation>`__ | 36 bytes: ``0x07 0x07 0x12 0x20``, followed by 32 x ``0x55`` | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x09`` | WRITE_REG | `Write 32-bit memory address <#32-bit-readwrite>`__ | Four 32-bit words: address, value, mask and delay (in microseconds) | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0a`` | READ_REG | `Read 32-bit memory address <#32-bit-readwrite>`__ | Address as 32-bit word | Read data as 32-bit word in ``value`` field. | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0b`` | SPI_SET_PARAMS | `Configure SPI flash <#spi-set-parameters>`__ | Six 32-bit words: id, total size in bytes, block size, sector size, page size, status mask. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0d`` | SPI_ATTACH | `Attach SPI flash <#spi-attach-command>`__ | 32-bit word: Zero for normal SPI flash. A second 32-bit word (should be ``0``) is passed to ROM loader only. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x0f`` | CHANGE_BAUDRATE | `Change Baud rate <#initial-synchronisation>`__ | Two 32-bit words: new baud rate, ``0`` if we are talking to the ROM loader or the current/old baud rate if we are talking to the stub loader. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x10`` | FLASH_DEFL_BEGIN | `Begin compressed flash download <#writing-data>`__ | Four 32-bit words: uncompressed size, number of data packets, data packet size, flash offset. With stub loader the uncompressed size is exact byte count to be written, whereas on ROM bootloader it is rounded up to flash erase block size. | | | | | | A fifth 32-bit word passed to ROM loader only: ``1`` to begin encrypted flash, ``0`` to not. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x11`` | FLASH_DEFL_DATA | `Compressed flash download data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | Error code ``0xC1`` on checksum error. | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x12`` | FLASH_DEFL_END | `End compressed flash download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader. | | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x13`` | SPI_FLASH_MD5 | `Calculate MD5 of flash region <#verifying-uploaded-data>`__ | Four 32-bit words: address, size, ``0``, ``0`` | Body contains 16 raw bytes of MD5 followed by 2 status bytes (stub loader) or 32 hex-coded ASCII (ROM loader) of calculated MD5 | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | ``0x14`` | GET_SECURITY_INFO | Read chip security info | | {IDF_TARGET_SECURITY_INFO} | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ Supported by Stub Loader Only """"""""""""""""""""""""""""" ROM loaders will not recognize these commands. +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ | Byte | Name | Description | Input | Output | +============+===================+===================================+=========================================================================================================================+==========+ | ``0xd0`` | ERASE_FLASH | Erase entire flash chip | | | +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ | ``0xd1`` | ERASE_REGION | Erase flash region | Two 32-bit words: flash offset to erase, erase size in bytes. Both must be multiples of flash sector size. | | +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ | ``0xd2`` | READ_FLASH | `Read flash <#reading-flash>`__ | Four 32-bit words: flash offset, read length, flash sector size, read packet size, maximum number of un-acked packets | | +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ | ``0xd3`` | RUN_USER_CODE | Exits loader and runs user code | | | +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ .. only:: not esp8266 and not esp32 .. _supported-in-sdm: Supported in Secure Download Mode """"""""""""""""""""""""""""""""" Secure Download Mode is a restricted version of the ROM Loader available on Espressif chips. It only allows a limited set of commands: * synchronisation (``SYNC``) * attaching SPI flash (``SPI_ATTACH``) * updating SPI config (``SPI_SET_PARAMS``) * changing baud rate (``CHANGE_BAUDRATE``) * basic flash write (``FLASH_BEGIN``, ``FLASH_DATA``, ``FLASH_END``) * reading a summary of currently enabled security features (``GET_SECURITY_INFO``) Any other command (e.g., reading or writing memory, arbitrary code execution through loading to RAM, ...) will result in an error. You can read more about Secure Download Mode in the `ESP-IDF Security Overview `__ or read about its :ref:`limitations here `. Checksum ^^^^^^^^ The checksum field is ignored (can be zero) for all commands except for MEM_DATA, FLASH_DATA, and FLASH_DEFL_DATA. Each of the ``_DATA`` command packets (like ``FLASH_DEFL_DATA``, ``MEM_DATA``) has the same "data payload" format: +---------+--------------------------+----------------------------------------------------------------+ | Bytes | Name | Format | +=========+==========================+================================================================+ | 0-3 | "Data to write" length | Little endian 32-bit word. | +---------+--------------------------+----------------------------------------------------------------+ | 4-7 | Sequence number | Little endian 32-bit word. The sequence numbers are 0 based. | +---------+--------------------------+----------------------------------------------------------------+ | 8-15 | 0 | Two words of all zeroes, unused. | +---------+--------------------------+----------------------------------------------------------------+ | 16- | "Data to write" | Length given at beginning of payload. | +---------+--------------------------+----------------------------------------------------------------+ The checksum is only applied to this final "data to write" section, not the first 16 bytes of data. To calculate checksum, start with seed value 0xEF and XOR each individual byte in the "data to write". The 8-bit result is stored in the checksum field of the packet header (as a little endian 32-bit value). .. note:: Because this checksum is not adequate to ensure valid data, the SPI_FLASH_MD5 command was added to validate flash contents after flashing. It is recommended that this command is always used. See `Verifying Uploaded Data`_, below. Functional Description ---------------------- .. blockdiag:: diag/download_procedure_chart.diag :caption: Download procedure flow chart :align: center .. note:: This flow chart is used to illustrate the download procedure (writing to flash), other commands have different flows. Initialization ^^^^^^^^^^^^^^ .. list:: :esp8266: * The ESP chip is reset into UART bootloader mode. The host starts by sending SYNC commands. These commands have a large data payload which is also used by the ESP chip to detect the configured baud rate. The ESP8266 will initialise at 74800bps with a 26MHz crystal and 115200bps with a 40MHz crystal. However the sync packets can be sent at any baud rate, and the UART peripheral will detect this. :not esp8266: * The ESP chip is reset into UART bootloader mode. The host starts by sending SYNC commands. These commands have a large data payload which is also used by the ESP chip to detect the configured baud rate. {IDF_TARGET_NAME} always initialises at 115200bps. However the sync packets can be sent at any baud rate, and the UART peripheral will detect this. * The host should wait until it sees a valid response to a SYNC command, indicating the ESP chip is correctly communicating. * Chip type detection then uses various methods to identify chip type, subtype, revision, etc. See below. * Esptool then (by default) uses the "RAM Download" sequence to upload :ref:`stub loader ` code to IRAM of the chip. The MEM_END command contains the entry-point address to run the stub loader. The stub loader then sends a custom SLIP packet of the sequence OHAI (``0xC0 0x4F 0x48 0x41 0x49 0xC0``), indicating that it is now running. This is the only unsolicited packet ever sent by the ESP. If the ``--no-stub`` argument is supplied to esptool, this entire step is skipped. :not esp8266: * For commands which need to use the flash, the {IDF_TARGET_NAME} ROM an stub loader requires the SPI_ATTACH and SPI_SET_PARAMS commands. See `SPI Configuration Commands`_. :esp8266: * For stub loader, the host can send a CHANGE_BAUD command to set the baud rate to an explicit value. Compared to auto-detecting during the SYNC pulse, this can be more reliable for setting very high baud rate. Esptool tries to sync at (maximum) 115200bps and then sends this command to go to a higher baud rate, if requested. :not esp8266: * For stub loader and/or {IDF_TARGET_NAME} ROM loader, the host can send a CHANGE_BAUD command to set the baud rate to an explicit value. Compared to auto-detecting during the SYNC pulse, this can be more reliable for setting very high baud rate. Esptool tries to sync at (maximum) 115200bps and then sends this command to go to a higher baud rate, if requested. Initialization - Chip Type Detection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ {IDF_TARGET_NAME} Chip Detection """""""""""""""""""""""""""""""" .. only:: esp8266 or esp32 {IDF_TARGET_NAME} does not support **GET_SECURITY_INFO (0x14)** command and its **chip-id** value. So, chip is detected by using **READ_REG** and his magic value. .. only:: esp32s2 {IDF_TARGET_NAME} supports the **GET_SECURITY_INFO (0x14)** command, but the output lacks the **chip-id**. Therefore, esptool uses the **magic register** as a fallback for this chip as well. If reading the register also fails, it indicates the chip is in **secure download** mode. .. only:: not esp8266 and not esp32 and not esp32s2 {IDF_TARGET_NAME} is detected by using **GET_SECURITY_INFO (0x14)** command and its **chip-id** value. Overview of Detection for All Chips """"""""""""""""""""""""""""""""""" .. blockdiag:: diag/chip_type_detection_chart.diag :caption: All chips detection flow chart :align: center On older devices that do not support the **GET_SECURITY_INFO (0x14)** command (which provides the **chip-id**), esptool falls back to reading a **magic register** to determine the chip type. The main exception is the **ESP32-S2**: although it supports the **GET_SECURITY_INFO (0x14)** command, the output lacks the **chip-id**. Therefore, esptool uses the **magic register** as a fallback for this chip as well. If reading the register also fails, it indicates the chip is in **secure download** mode. For details see: `esptool chip detection code `__ Writing Data ^^^^^^^^^^^^ (Includes RAM Download, Flash Download, Compressed Flash Download.) .. list:: * RAM Download (MEM_BEGIN, MEM_DATA, MEM_END) loads data into the ESP chip memory space and (optionally) executes it. * Flash Download (FLASH_BEGIN, FLASH_DATA) flashes data into the ESP SPI flash. :esp8266: * Compressed Flash Download is the same, only the data is compressed using the gzip Deflate algorithm to reduce serial overhead. Not supported on ESP8266 ROM loader. :not esp8266: * Compressed Flash Download is the same, only the data is compressed using the gzip Deflate algorithm to reduce serial overhead. All three of these sequences follow a similar pattern: * A _BEGIN command (FLASH_BEGIN, etc) is sent which contains basic parameters for the flash erase size, start address to write to, etc. The uploader also needs to specify how many "blocks" of data (ie individual data packets) will be sent, and how big each packet is. * One or more _DATA commands (FLASH_DATA, etc) is sent where the data payload contains the actual data to write to flash/RAM. In the case of Compressed Flash Downloads, the data is compressed using the gzip deflate algorithm. The number of _DATA commands is specified in the _BEGIN command, as is the size of each _DATA payload. The last data block should be padded to the block size with 0xFF bytes. * An _END command (FLASH_END, etc) is sent to exit the bootloader and optionally reset the chip (or jump to an address in RAM, in the case of MEM_END). Not necessary to send after flashing if you wish to continue sending other or different commands. It's not necessary to send flash erase commands before sending commands to write to flash, etc. The ROM loaders erase the to-be-written region in response to the FLASH_BEGIN command. The stub loader does just-in-time erasing as it writes data, to maximize overall flashing performance (each block of data is read into RAM via serial while the previous block is simultaneously being written to flash, and 4KB and 64KB erases are done as needed before writing to flash). The block size chosen should be small enough to fit into RAM of the device. Esptool uses 16KB which gives good performance when used with the stub loader. .. only:: esp8266 Erase Size Bug """""""""""""" On ESP8266 ROM loader only (not stub loader), there is a bug in the interpretation of the FLASH_BEGIN "erase size" parameter. Consult the ``ESP8266ROM.get_erase_size()`` function in esptool for the algorithm which works around this bug and provides the correct erase size parameter to send to the ESP8266. This workaround is not needed if the ESP8266 is running the stub loader. Verifying Uploaded Data """"""""""""""""""""""" .. only:: esp8266 The 8-bit checksum used in the upload protocol is not sufficient to ensure valid flash contents after upload. The uploader should send the SPI_FLASH_MD5 command (not supported on ESP8266 ROM loader) or use another method to verify flash contents. .. only:: not esp8266 The 8-bit checksum used in the upload protocol is not sufficient to ensure valid flash contents after upload. The uploader should send the SPI_FLASH_MD5 command or use another method to verify flash contents. The SPI_FLASH_MD5 command passes the start address in flash and the size of data to calculate. The MD5 value is returned in the response payload, before the status bytes. .. only:: not esp8266 Note that the {IDF_TARGET_NAME} ROM loader returns the md5sum as 32 hex encoded ASCII bytes, whereas the stub loader returns the md5sum as 16 raw data bytes of MD5 followed by 2 status bytes. SPI Configuration Commands ^^^^^^^^^^^^^^^^^^^^^^^^^^ SPI Attach Command """""""""""""""""" The SPI_ATTACH command enables the SPI flash interface. It takes a 32-bit data payload which is used to determine which SPI peripheral and pins should be used to connect to SPI flash. .. only:: esp8266 On the ESP8266 stub loader sending this command before interacting with SPI flash is optional. On ESP8266 ROM loader this command is not supported (SPI flash is enabled when the FLASH_BEGIN command is sent). +------------------+----------------------------------------------------------------------------------------------------------------------------------+ | Value | Meaning | +==================+==================================================================================================================================+ | 0 | Default SPI flash interface | +------------------+----------------------------------------------------------------------------------------------------------------------------------+ | 1 | HSPI interface | +------------------+----------------------------------------------------------------------------------------------------------------------------------+ .. only:: not esp8266 On the {IDF_TARGET_NAME} stub loader sending this command before interacting with SPI flash is optional. On {IDF_TARGET_NAME} ROM loader, it is required to send this command before interacting with SPI flash. +------------------+----------------------------------------------------------------------------------------------------------------------------------+ | Value | Meaning | +==================+==================================================================================================================================+ | 0 | Default SPI flash interface | +------------------+----------------------------------------------------------------------------------------------------------------------------------+ | 1 | HSPI interface | +------------------+----------------------------------------------------------------------------------------------------------------------------------+ | (other values) | Pin numbers as 6-bit values, packed into a 30-bit value. Order (from MSB): HD pin, Q pin, D pin, CS pin, CLK pin. | +------------------+----------------------------------------------------------------------------------------------------------------------------------+ The "Default SPI flash interface" uses pins configured via the ``SPI_PAD_CONFIG_xxx`` eFuses (if unset, these eFuses are all zero and the default SPI flash pins given in the datasheet are used.) When writing the values of each pin as 6-bit numbers packed into the data word, each 6-bit value uses the following representation: .. only:: esp32 * Pin numbers 0 through 30 are represented as themselves. * Pin numbers 32 & 33 are represented as values 30 & 31. * It is not possible to represent pins 30 & 31 or pins higher than 33. This is the same 6-bit representation used by the ``SPI_PAD_CONFIG_xxx`` eFuses. On {IDF_TARGET_NAME} ROM loader only, there is an additional 4 bytes in the data payload of this command. These bytes should all be set to zero. SPI Set Parameters """""""""""""""""" The SPI_SET_PARAMS command sets some parameters of the attached SPI flash chip (sizes, etc). .. only:: esp8266 This command is not supported by the ESP8266 ROM loader. All the values which are passed except total size are hardcoded, and most are not used when writing to flash. See `flash_set_parameters function `__ in esptool for the values which it sends. 32-Bit Read/Write ^^^^^^^^^^^^^^^^^ The 32-bit read/write commands (READ_REG, WRITE_REG) allow word-oriented reading and writing of memory and register data. These commands can be used to manipulate peripherals in arbitrary ways. For example, the esptool "flash id" functionality is implemented by manipulating the SPI peripheral registers to send a JEDEC flash ID command to the flash chip and read the response. Reading Flash ^^^^^^^^^^^^^ The stub loader implements a READ_FLASH command. This command behaves differently to other commands, including the ROM loader's READ_FLASH command: * The host sends the READ_FLASH command and the data payload contains the offset, read size, size of each individual packet of data, and the maximum number of "un-acknowledged" data packets which can be in flight at one time. * The stub loader will send a standard response packet, with no additional data payload. * Now the stub loader will start sending SLIP packets with raw data (of the size requested in the command). There is no metadata included with these SLIP packets. * After each SLIP packet is received, the host should send back a 4 byte raw SLIP acknowledgement packet with the total number of bytes which have been received. There is no header or other metadata included with these SLIP packets. * The stub loader may send up to a maximum number (specified by the host in the READ_FLASH commands) of data packets before waiting for the first acknowledgement packet. No more than this "max in flight" limit can be un-acknowledged at any one time. * After all data packets are acknowledged received, the stub loader sends a 16 byte MD5 digest of all the data which was read from flash. This is also sent as a raw SLIP packet, with no metadata. After the read flash process is complete, the stub loader goes back to normal command/response operation. The ROM loader read flash command is more normal but also much slower to read data. .. _tracing-communications: Tracing Esptool Serial Communications ------------------------------------- esptool has a ``--trace`` option which can be supplied in the first group of arguments (before the command). This will dump all traffic sent and received via the serial port to the console. Here is a sample extract, showing a READ_REG command and response: :: TRACE +0.000 --- Cmd READ_REG (0x0a) | data_len 4 | wait_response 1 | timeout 3.000 | data 00100040 --- TRACE +0.000 Write 14 bytes: c0000a04000000000000100040c0 TRACE +0.046 Read 1 bytes: c0 TRACE +0.000 Read 11 bytes: 010a0200090000000000c0 TRACE +0.000 Received full packet: 010a0200090000000000 The +X.XXX value is the time delta (in seconds) since the last trace line. Values are printed in hexadecimal. If more than 16 bytes is printed at one time, a split display is used with hexadecimal bytes on the left and ASCII on the right. Non-printable characters are represented as ``.`` in ASCII: Note that multiple protocol layers are represented in the logs. The "Write X bytes" lines show exactly which bytes are being sent "over the wire", including SLIP framing. Similarly the "Read X bytes" lines show what bytes are being read over the wire, including any SLIP framing. Once a full SLIP packet is read, the same bytes - as a SLIP payload with any escaping removed - appear in the "Received full packet" log lines. Here is a second example showing part of the initial synchronization sequence (lots of 0x55 bytes which are ``U`` in ASCII): :: TRACE +0.000 Write 46 bytes: c000082400000000 0007071220555555 | ...$........ UUU 5555555555555555 5555555555555555 | UUUUUUUUUUUUUUUU 5555555555555555 5555555555c0 | UUUUUUUUUUUUU. TRACE +0.012 Read 1 bytes: c0 TRACE +0.000 Read 63 bytes: 0108040007071220 00000000c0c00108 | ....... ........ 0400070712200000 0000c0c001080400 | ..... .......... 0707122000000000 c0c0010804000707 | ... ............ 122000000000c0c0 01080400070712 | . ............. TRACE +0.000 Received full packet: 010804000707122000000000 TRACE +0.000 Received full packet: 010804000707122000000000 .. important:: If you don't plan to use the esptool stub loader, pass ``--no-stub --trace`` to see interactions with the chip's built-in ROM loader only. Otherwise, the trace will show the full binary upload of the loader. In addition to this trace feature, most operating systems have "system call trace" or "port trace" features which can be used to dump serial interactions. --- ## File: docs/en/advanced-topics/spi-flash-modes.rst .. _spi-flash-modes: SPI Flash Modes =============== The ESP chips support four different SPI flash access modes: DIO, DOUT, QIO & QOUT. These can be set via the ``--flash-mode`` option of ``esptool write-flash``. These options control how many I/O pins are used for communication with the attached SPI flash chip, and which SPI commands are used. ESP chips use these commands when reading or executing code and data from the SPI flash chip. Data is read and then cached internally to the chip. Summary ------- In order of performance: +------------+---------------+----------------------------------+-----------------------------------+ | Option | Mode Name | Pins Used | Speed (ESP device) | +============+===============+==================================+===================================+ | ``qio`` | Quad I/O | 4 pins used for address & data | Fastest. | +------------+---------------+----------------------------------+-----------------------------------+ | ``qout`` | Quad Output | 4 pins used for data. | Approx 15% slower than ``qio``. | +------------+---------------+----------------------------------+-----------------------------------+ | ``dio`` | Dual I/O | 2 pins used for address & data | Approx 45% slower than ``qio``. | +------------+---------------+----------------------------------+-----------------------------------+ | ``dout`` | Dual Output | 2 pins used for data. | Approx 50% slower than ``qio``. | +------------+---------------+----------------------------------+-----------------------------------+ In general, choose the fastest option for ``--flash-mode`` that works with your device. Not all devices support all modes. See FAQ below for details. Mode Descriptions ----------------- Normal SPI ^^^^^^^^^^ A traditional "single" SPI (Serial Peripheral Interface) bus uses 4 pins for communication: * Clock (CLK) * Master Out Slave In (MOSI) * Master In Slave Out (MISO) * Chip Select (CS) `Wikipedia has a fairly complete description `__. All of these signals are unidirectional. In single SPI mode, data is sent from the device to the host using the MISO pin and from the host to the device using the MOSI pin. The maximum data rate for normal SPI is the clock rate in bits - so a 40MHz clock = 40Mbits/sec = 5Mbytes/sec. Dual SPI ^^^^^^^^ To improve performance, SPI flash manufacturers introduced "Dual SPI". In Dual SPI modes, the MOSI & MISO pins are both used to read or write data simultaneously with two bits per clock cycle. This doubles the data rate for some commands, compared to single SPI. In ``dout`` mode, the host uses the "Dual Output Fast Read" (3BH) command to read data. Each read command and the read address is sent from the host to the flash chip via normal SPI, but then the host reads the data via both the MOSI & MISO pins simultaneously with two bits per clock. This doubles the data transfer rate compared to single SPI which only uses MISO to read data. In ``dio`` mode, the host uses the "Dual I/O Fast Read" (BBH) command to read data. Each read command is sent from the host to the flash chip via normal SPI, but then the address is sent to the flash chip via both the MOSI & MISO pins with two bits per clock. After this, the host reads the data bits with two bits per clock in the same way as "Dual Output Fast Read". For ESP chips, 32 bytes is read per command and ``dio`` mode is approximately 5% faster than ``dout``. Consult the datasheet for your particular SPI flash chip to determine if it supports either or both of these commands. Quad SPI ^^^^^^^^ To further improve the performance of SPI flash data transfers, SPI flash manufacturers introduced "Quad SPI" mode. This mode added two additional pins (otherwise used for flash chip ``WP`` and ``HOLD`` signals) for data transfers. This allows double the data rate of dual SPI. Not all flash chips support Quad SPI modes, and not all ESP chips have these pins wired up to the SPI flash chip. Some flash chips require special commands to enable quad modes (see below). In ``qout`` mode, the host uses the "Quad Output Fast Read" (6BH) command to read data. This command is the same as "Dual Output Fast Read", only data is read on 4 pins instead of 2 with 4 bits per clock cycle. This makes the data transfer exactly twice as fast as "Dual Output Fast Read". In ``qio`` mode, the host uses the "Quad I/O Fast Read" (EBH) command to read data. This command is the same as "Dual I/O Fast Read", only both address & data are transferred on 4 pins instead of 2 with 4 bits per clock cycle. This makes both the address & data transfer exactly twice as fast as "Dual I/O Fast Read". .. only:: esp32s3 Octal SPI ^^^^^^^^^ Some ESP chips additionally support Octal SPI mode. This mode uses 8 pins for communication with the SPI flash chip, and allows for even faster data transfers than Quad SPI. This mode added four additional pins (SPIIO4~7) compared to Quad SPI for data transfers. The 1st and 2nd bootloaders don't support ``opi`` mode. Because of that esptool doesn't use ``opi`` and ``dout`` is used instead. The bootloader retrieves the information from eFuse and effectively replaces the mode. .. note:: Use the ``esptool flash-id`` command to check if your ESP is using Quad or Octal SPI mode. It prints information based on the eFuse settings. Frequently Asked Questions -------------------------- Why don't qio & qout modes work with my Espressif chip/module? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It is usually one of the following reasons: * The WP and HOLD pins of the SPI flash chip are not wired to the correct GPIOs of the Espressif chip. These pins must be connected correctly for quad modes to work, and not all boards/modules connect them at all. * The SPI flash chip does not support quad modes. Look up the flash chip datasheet to see which modes it supports. You can identify the flash chip visually, or by using the :ref:`esptool flash-id ` command. * Quad mode is not enabled correctly for this chip model. SPI flash is not a standard, so every manufacturer implements their chip differently. Most flash chips require certain commands to be sent in order to enable Quad SPI modes, and these commands vary. For Espressif chips, this often means that the chip first boots in a Dual SPI mode and then software detects the chip type and tries to enable Quad SPI mode. If the particular chip model is not supported by the software then it won't be able to enter quad mode. Why does qout/dout mode work but qio/dio mode doesn't work? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some SPI flash chip models only support the "Dual Output Fast Read" and/or "Quad Output Fast Read" commands, not their Dual I/O & Quad I/O equivalents. Will my code run half as fast in Dual SPI mode compared to Quad SPI? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ No. Espressif chips execute code directly from flash, however because reading from flash is slow the data is cached transparently in RAM. Flash read commands are only sent went a cache miss occurs. However, refilling the cache with a Dual SPI read is approximately half as fast as its Quad SPI equivalent. If you can't use the Quad SPI modes, make sure you are configuring the fastest SPI Flash clock rate that works reliably on your board/module. An 80MHz SPI clock in Dual I/O mode is faster than a 40MHz SPI clock in Quad I/O mode. How is flash mode communicated to the Espressif chip? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The bootloader .bin file, flashed to the SPI flash, contains a header which has flash speed, flash mode, and some other metadata. The initial host mode is determined by ROM code when it reads this header after reset. Passing the ``--flash-mode`` argument to esptool will update this header when the file is being written to flash. This only determines the mode which is used for the initial boot from reset. Software may then configure the flash mode differently as part of the boot process. For example, on ESP32 if ESP-IDF is configured for qio/qout mode then the IDF software bootloader is actually flashed with a dio/dout mode. When ROM code boots this bootloader from flash, the bootloader software checks the flash chip model and enables the correct Quad SPI mode for the rest of the boot process. This is because of the multiple different ways to enable Quad SPI on different chip models. --- ## File: docs/en/espefuse/inc/summary_ESP32.rst .. code-block:: none > espefuse -p PORT summary Connecting........__ Detecting chip type... ESP32 === Run "summary" command === EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) ---------------------------------------------------------------------------------------- Calibration fuses: ADC_VREF (BLOCK0): True ADC reference voltage = 1121 R/W (0b00011) Config fuses: WR_DIS (BLOCK0): Efuse write disable mask = 0 R/W (0x0000) RD_DIS (BLOCK0): Disable reading from BlOCK1-3 = 0 R/W (0x0) DISABLE_APP_CPU (BLOCK0): Disables APP CPU = False R/W (0b0) DISABLE_BT (BLOCK0): Disables Bluetooth = False R/W (0b0) DIS_CACHE (BLOCK0): Disables cache = False R/W (0b0) CHIP_CPU_FREQ_LOW (BLOCK0): If set alongside EFUSE_RD_CHIP_CPU_FREQ_RATED; the = False R/W (0b0) ESP32's max CPU frequency is rated for 160MHz. 24 0MHz otherwise CHIP_CPU_FREQ_RATED (BLOCK0): If set; the ESP32's maximum CPU frequency has been = True R/W (0b1) rated BLK3_PART_RESERVE (BLOCK0): BLOCK3 partially served for ADC calibration data = False R/W (0b0) CLK8M_FREQ (BLOCK0): 8MHz clock freq override = 51 R/W (0x33) VOL_LEVEL_HP_INV (BLOCK0): This field stores the voltage level for CPU to run = 0 R/W (0b00) at 240 MHz; or for flash/PSRAM to run at 80 MHz.0 x0: level 7; 0x1: level 6; 0x2: level 5; 0x3: leve l 4. (RO) CODING_SCHEME (BLOCK0): Efuse variable block length scheme = NONE (BLK1-3 len=256 bits) R/W (0b00) CONSOLE_DEBUG_DISABLE (BLOCK0): Disable ROM BASIC interpreter fallback = True R/W (0b1) DISABLE_SDIO_HOST (BLOCK0): = False R/W (0b0) DISABLE_DL_CACHE (BLOCK0): Disable flash cache in UART bootloader = False R/W (0b0) Flash fuses: FLASH_CRYPT_CNT (BLOCK0): Flash encryption is enabled if this field has an o = 0 R/W (0b0000000) dd number of bits set FLASH_CRYPT_CONFIG (BLOCK0): Flash encryption config (key tweak bits) = 0 R/W (0x0) Identity fuses: CHIP_PACKAGE_4BIT (BLOCK0): Chip package identifier #4bit = False R/W (0b0) CHIP_PACKAGE (BLOCK0): Chip package identifier = 1 R/W (0b001) CHIP_VER_REV1 (BLOCK0): bit is set to 1 for rev1 silicon = True R/W (0b1) CHIP_VER_REV2 (BLOCK0): = True R/W (0b1) WAFER_VERSION_MINOR (BLOCK0): = 0 R/W (0b00) WAFER_VERSION_MAJOR (BLOCK0): calc WAFER VERSION MAJOR from CHIP_VER_REV1 and CH = 3 R/W (0b011) IP_VER_REV2 and apb_ctl_date (read only) PKG_VERSION (BLOCK0): calc Chip package = CHIP_PACKAGE_4BIT << 3 + CHIP_ = 1 R/W (0x1) PACKAGE (read only) Jtag fuses: JTAG_DISABLE (BLOCK0): Disable JTAG = False R/W (0b0) Mac fuses: MAC (BLOCK0): MAC address = 94:b9:7e:5a:6e:58 (CRC 0xe2 OK) R/W MAC_CRC (BLOCK0): CRC8 for MAC address = 226 R/W (0xe2) MAC_VERSION (BLOCK3): Version of the MAC field = 0 R/W (0x00) Security fuses: UART_DOWNLOAD_DIS (BLOCK0): Disable UART download mode. Valid for ESP32 V3 and = False R/W (0b0) newer; only ABS_DONE_0 (BLOCK0): Secure boot V1 is enabled for bootloader image = False R/W (0b0) ABS_DONE_1 (BLOCK0): Secure boot V2 is enabled for bootloader image = False R/W (0b0) DISABLE_DL_ENCRYPT (BLOCK0): Disable flash encryption in UART bootloader = False R/W (0b0) DISABLE_DL_DECRYPT (BLOCK0): Disable flash decryption in UART bootloader = False R/W (0b0) KEY_STATUS (BLOCK0): Usage of efuse block 3 (reserved) = False R/W (0b0) SECURE_VERSION (BLOCK3): Secure version for anti-rollback = 0 R/W (0x00000000) BLOCK1 (BLOCK1): Flash encryption key = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK2 (BLOCK2): Security boot key = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK3 (BLOCK3): Variable Block 3 = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W Spi Pad fuses: SPI_PAD_CONFIG_HD (BLOCK0): read for SPI_pad_config_hd = 0 R/W (0b00000) SPI_PAD_CONFIG_CLK (BLOCK0): Override SD_CLK pad (GPIO6/SPICLK) = 0 R/W (0b00000) SPI_PAD_CONFIG_Q (BLOCK0): Override SD_DATA_0 pad (GPIO7/SPIQ) = 0 R/W (0b00000) SPI_PAD_CONFIG_D (BLOCK0): Override SD_DATA_1 pad (GPIO8/SPID) = 0 R/W (0b00000) SPI_PAD_CONFIG_CS0 (BLOCK0): Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0b00000) Vdd fuses: XPD_SDIO_REG (BLOCK0): read for XPD_SDIO_REG = False R/W (0b0) XPD_SDIO_TIEH (BLOCK0): If XPD_SDIO_FORCE & XPD_SDIO_REG = 1.8V R/W (0b0) XPD_SDIO_FORCE (BLOCK0): Ignore MTDI pin (GPIO12) for VDD_SDIO on reset = False R/W (0b0) Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V, Low/NC for 3.3V) --- ## File: docs/en/espefuse/inc/summary_ESP32-C2.rst .. code-block:: none > espefuse -p PORT summary Connecting................... Detecting chip type... ESP32-C2 === Run "summary" command === EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) ---------------------------------------------------------------------------------------- Config fuses: WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00) RD_DIS (BLOCK0) Disable reading from BlOCK3 = 0 R/W (0b00) UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00) DIS_DIRECT_BOOT (BLOCK0) This bit set means disable direct_boot mode = False R/W (0b0) Flash fuses: FORCE_SEND_RESUME (BLOCK0) Set this bit to force ROM code to send a resume co = False R/W (0b0) mmand during SPI boot FLASH_TPUW (BLOCK0) Configures flash waiting time after power-up; in u = 0 R/W (0x0) nit of ms. If the value is less than 15; the waiti ng time is the configurable value. Otherwise; the waiting time is twice the configurable value Identity fuses: DISABLE_WAFER_VERSION_MAJOR (BLOCK0) Disables check of wafer version major = False R/W (0b0) DISABLE_BLK_VERSION_MAJOR (BLOCK0) Disables check of blk version major = False R/W (0b0) WAFER_VERSION_MINOR (BLOCK2) WAFER_VERSION_MINOR = 0 R/W (0x0) WAFER_VERSION_MAJOR (BLOCK2) WAFER_VERSION_MAJOR = 1 R/W (0b01) PKG_VERSION (BLOCK2) EFUSE_PKG_VERSION = 1 R/W (0b001) BLK_VERSION_MINOR (BLOCK2) Minor version of BLOCK2 = No calib R/W (0b000) BLK_VERSION_MAJOR (BLOCK2) Major version of BLOCK2 = 0 R/W (0b00) Jtag fuses: DIS_PAD_JTAG (BLOCK0) Set this bit to disable pad jtag = False R/W (0b0) Mac fuses: CUSTOM_MAC_USED (BLOCK0) True if MAC_CUSTOM is burned = False R/W (0b0) CUSTOM_MAC (BLOCK1) Custom MAC address = 00:00:00:00:00:00 (OK) R/W MAC (BLOCK2) MAC address = 10:97:bd:f0:e5:28 (OK) R/W Security fuses: DIS_DOWNLOAD_ICACHE (BLOCK0) The bit be set to disable icache in download mode = False R/W (0b0) DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) The bit be set to disable manual encryption = False R/W (0b0) SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) and disables otherwise XTS_KEY_LENGTH_256 (BLOCK0) Flash encryption key length = 128 bits key R/W (0b0) DIS_DOWNLOAD_MODE (BLOCK0) Set this bit to disable download mode (boot_mode[3 = False R/W (0b0) :0] = 0; 1; 2; 4; 5; 6; 7) ENABLE_SECURITY_DOWNLOAD (BLOCK0) Set this bit to enable secure UART download mode = False R/W (0b0) SECURE_BOOT_EN (BLOCK0) The bit be set to enable secure boot = False R/W (0b0) SECURE_VERSION (BLOCK0) Secure version for anti-rollback = 0 R/W (0x0) BLOCK_KEY0 (BLOCK3) BLOCK_KEY0 - 256-bits. 256-bit key of Flash Encryp = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W tion BLOCK_KEY0_LOW_128 (BLOCK3) BLOCK_KEY0 - lower 128-bits. 128-bit key of Flash = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W Encryption BLOCK_KEY0_HI_128 (BLOCK3) BLOCK_KEY0 - higher 128-bits. 128-bits key of Secu = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W re Boot Wdt fuses: WDT_DELAY_SEL (BLOCK0) RTC watchdog timeout threshold; in unit of slow cl = 40000 R/W (0b00) ock cycle --- ## File: docs/en/espefuse/inc/summary_ESP32-C3.rst .. code-block:: none > espefuse -p PORT summary Connecting.... Detecting chip type... ESP32-C3 === Run "summary" command === EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) ---------------------------------------------------------------------------------------- Calibration fuses: K_RTC_LDO (BLOCK1) BLOCK1 K_RTC_LDO = -36 R/W (0b1001001) K_DIG_LDO (BLOCK1) BLOCK1 K_DIG_LDO = -64 R/W (0b1010000) V_RTC_DBIAS20 (BLOCK1) BLOCK1 voltage of rtc dbias20 = -40 R/W (0x8a) V_DIG_DBIAS20 (BLOCK1) BLOCK1 voltage of digital dbias20 = -76 R/W (0x93) DIG_DBIAS_HVT (BLOCK1) BLOCK1 digital dbias when hvt = -28 R/W (0b10111) THRES_HVT (BLOCK1) BLOCK1 pvt threshold when hvt = 2000 R/W (0b0111110100) TEMP_CALIB (BLOCK2) Temperature calibration data = -7.2 R/W (0b101001000) OCODE (BLOCK2) ADC OCode = 78 R/W (0x4e) ADC1_INIT_CODE_ATTEN0 (BLOCK2) ADC1 init code at atten0 = 1560 R/W (0b0110000110) ADC1_INIT_CODE_ATTEN1 (BLOCK2) ADC1 init code at atten1 = -108 R/W (0b1000011011) ADC1_INIT_CODE_ATTEN2 (BLOCK2) ADC1 init code at atten2 = -232 R/W (0b1000111010) ADC1_INIT_CODE_ATTEN3 (BLOCK2) ADC1 init code at atten3 = -696 R/W (0b1010101110) ADC1_CAL_VOL_ATTEN0 (BLOCK2) ADC1 calibration voltage at atten0 = -212 R/W (0b1000110101) ADC1_CAL_VOL_ATTEN1 (BLOCK2) ADC1 calibration voltage at atten1 = 52 R/W (0b0000001101) ADC1_CAL_VOL_ATTEN2 (BLOCK2) ADC1 calibration voltage at atten2 = -152 R/W (0b1000100110) ADC1_CAL_VOL_ATTEN3 (BLOCK2) ADC1 calibration voltage at atten3 = -284 R/W (0b1001000111) Config fuses: WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000) RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) DIS_ICACHE (BLOCK0) Set this bit to disable Icache = False R/W (0b0) DIS_TWAI (BLOCK0) Set this bit to disable CAN function = False R/W (0b0) DIS_DIRECT_BOOT (BLOCK0) Disable direct boot mode = False R/W (0b0) UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00) ERR_RST_ENABLE (BLOCK0) Use BLOCK0 to check error record registers = with check R/W (0b1) BLOCK_USR_DATA (BLOCK3) User data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W Flash fuses: FLASH_TPUW (BLOCK0) Configures flash waiting time after power-up; in u = 0 R/W (0x0) nit of ms. If the value is less than 15; the waiti ng time is the configurable value; Otherwise; the waiting time is twice the configurable value FORCE_SEND_RESUME (BLOCK0) Set this bit to force ROM code to send a resume co = False R/W (0b0) mmand during SPI boot Identity fuses: DISABLE_WAFER_VERSION_MAJOR (BLOCK0) Disables check of wafer version major = False R/W (0b0) DISABLE_BLK_VERSION_MAJOR (BLOCK0) Disables check of blk version major = False R/W (0b0) WAFER_VERSION_MINOR_LO (BLOCK1) WAFER_VERSION_MINOR least significant bits = 3 R/W (0b011) PKG_VERSION (BLOCK1) Package version = 0 R/W (0b000) BLK_VERSION_MINOR (BLOCK1) BLK_VERSION_MINOR = 2 R/W (0b010) WAFER_VERSION_MINOR_HI (BLOCK1) WAFER_VERSION_MINOR most significant bit = False R/W (0b0) WAFER_VERSION_MAJOR (BLOCK1) WAFER_VERSION_MAJOR = 0 R/W (0b00) OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID = 25 60 04 96 c3 fd 41 6f be ed 2c 51 1d e3 7e 21 R/W BLK_VERSION_MAJOR (BLOCK2) BLK_VERSION_MAJOR of BLOCK2 = With calibration R/W (0b01) WAFER_VERSION_MINOR (BLOCK0) calc WAFER VERSION MINOR = WAFER_VERSION_MINOR_HI = 3 R/W (0x3) << 3 + WAFER_VERSION_MINOR_LO (read only) Jtag fuses: SOFT_DIS_JTAG (BLOCK0) Set these bits to disable JTAG in the soft way (od = 0 R/W (0b000) d number 1 means disable ). JTAG can be enabled in HMAC module DIS_PAD_JTAG (BLOCK0) Set this bit to disable JTAG in the hard way. JTAG = False R/W (0b0) is disabled permanently Mac fuses: MAC (BLOCK1) MAC address = 58:cf:79:0f:96:8c (OK) R/W CUSTOM_MAC (BLOCK3) Custom MAC address = 00:00:00:00:00:00 (OK) R/W Security fuses: DIS_DOWNLOAD_ICACHE (BLOCK0) Set this bit to disable Icache in download mode (b = False R/W (0b0) oot_mode[3:0] is 0; 1; 2; 3; 6; 7) DIS_FORCE_DOWNLOAD (BLOCK0) Set this bit to disable the function that forces c = False R/W (0b0) hip into download mode DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Set this bit to disable flash encryption when in d = False R/W (0b0) ownload boot modes SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) and disables otherwise SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) KEY_PURPOSE_0 (BLOCK0) Purpose of Key0 = USER R/W (0x0) KEY_PURPOSE_1 (BLOCK0) Purpose of Key1 = USER R/W (0x0) KEY_PURPOSE_2 (BLOCK0) Purpose of Key2 = USER R/W (0x0) KEY_PURPOSE_3 (BLOCK0) Purpose of Key3 = USER R/W (0x0) KEY_PURPOSE_4 (BLOCK0) Purpose of Key4 = USER R/W (0x0) KEY_PURPOSE_5 (BLOCK0) Purpose of Key5 = USER R/W (0x0) SECURE_BOOT_EN (BLOCK0) Set this bit to enable secure boot = False R/W (0b0) SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Set this bit to enable revoking aggressive secure = False R/W (0b0) boot DIS_DOWNLOAD_MODE (BLOCK0) Set this bit to disable download mode (boot_mode[3 = False R/W (0b0) :0] = 0; 1; 2; 3; 6; 7) ENABLE_SECURITY_DOWNLOAD (BLOCK0) Set this bit to enable secure UART download mode = False R/W (0b0) SECURE_VERSION (BLOCK0) Secure version (used by ESP-IDF anti-rollback feat = 0 R/W (0x0000) ure) BLOCK_KEY0 (BLOCK4) Purpose: USER Key0 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY1 (BLOCK5) Purpose: USER Key1 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY2 (BLOCK6) Purpose: USER Key2 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY3 (BLOCK7) Purpose: USER Key3 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY4 (BLOCK8) Purpose: USER Key4 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY5 (BLOCK9) Purpose: USER Key5 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W Spi Pad fuses: SPI_PAD_CONFIG_CLK (BLOCK1) SPI PAD CLK = 0 R/W (0b000000) SPI_PAD_CONFIG_Q (BLOCK1) SPI PAD Q(D1) = 0 R/W (0b000000) SPI_PAD_CONFIG_D (BLOCK1) SPI PAD D(D0) = 0 R/W (0b000000) SPI_PAD_CONFIG_CS (BLOCK1) SPI PAD CS = 0 R/W (0b000000) SPI_PAD_CONFIG_HD (BLOCK1) SPI PAD HD(D3) = 0 R/W (0b000000) SPI_PAD_CONFIG_WP (BLOCK1) SPI PAD WP(D2) = 0 R/W (0b000000) SPI_PAD_CONFIG_DQS (BLOCK1) SPI PAD DQS = 0 R/W (0b000000) SPI_PAD_CONFIG_D4 (BLOCK1) SPI PAD D4 = 0 R/W (0b000000) SPI_PAD_CONFIG_D5 (BLOCK1) SPI PAD D5 = 0 R/W (0b000000) SPI_PAD_CONFIG_D6 (BLOCK1) SPI PAD D6 = 0 R/W (0b000000) SPI_PAD_CONFIG_D7 (BLOCK1) SPI PAD D7 = 0 R/W (0b000000) Usb fuses: DIS_USB_JTAG (BLOCK0) Set this bit to disable function of usb switch to = False R/W (0b0) jtag in module of usb device DIS_USB_SERIAL_JTAG (BLOCK0) USB-Serial-JTAG = Enable R/W (0b0) USB_EXCHG_PINS (BLOCK0) Set this bit to exchange USB D+ and D- pins = False R/W (0b0) DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) USB printing = Enable R/W (0b0) DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Disable UART download mode through USB-Serial-JTAG = False R/W (0b0) Vdd fuses: VDD_SPI_AS_GPIO (BLOCK0) Set this bit to vdd spi pin function as gpio = False R/W (0b0) Wdt fuses: WDT_DELAY_SEL (BLOCK0) RTC watchdog timeout threshold; in unit of slow cl = 40000 R/W (0b00) ock cycle --- ## File: docs/en/espefuse/inc/summary_ESP32-C5.rst .. code-block:: none > espefuse -p PORT summary Connecting.... Detecting chip type... ESP32-C5 === Run "summary" command === EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) ---------------------------------------------------------------------------------------- Config fuses: WR_DIS (BLOCK0) Disable programming of individual eFuses = 4608 R/W (0x00001200) RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) DIS_ICACHE (BLOCK0) Represents whether icache is disabled or enabled.\ = False R/W (0b0) \ 1: disabled\\ 0: enabled\\ DIS_TWAI (BLOCK0) Represents whether TWAI function is disabled or en = False R/W (0b0) abled.\\ 1: disabled\\ 0: enabled\\ KM_DISABLE_DEPLOY_MODE (BLOCK0) Represents whether the deploy mode of key manager = 0 R/W (0x0) is disable or not. \\ 1: disabled \\ 0: enabled.\\ KM_RND_SWITCH_CYCLE (BLOCK0) Set the bits to control key manager random number = 0 R/W (0b00) switch cycle. 0: control by register. 1: 8 km clk cycles. 2: 16 km cycles. 3: 32 km cycles KM_DEPLOY_ONLY_ONCE (BLOCK0) Set each bit to control whether corresponding key = 0 R/W (0x0) can only be deployed once. 1 is true; 0 is false. bit 0: ecsda; bit 1: xts; bit2: hmac; bit3: ds DIS_DIRECT_BOOT (BLOCK0) Represents whether direct boot mode is disabled or = False R/W (0b0) enabled.\\ 1: disabled\\ 0: enabled\\ UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00) HYS_EN_PAD (BLOCK0) Represents whether the hysteresis function of corr = False R/W (0b0) esponding PAD is enabled.\\ 1: enabled\\ 0:disable d\\ HUK_GEN_STATE (BLOCK0) Set the bits to control validation of HUK generate = 0 R/W (0b000000000) mode.\\ Odd of 1 is invalid.\\ Even of 1 is valid .\\ XTAL_48M_SEL (BLOCK0) Represents whether XTAL frequency is 48MHz or not. = 1 R/W (0b001) If not; 40MHz XTAL will be used. If this field co ntains Odd number bit 1: Enable 48MHz XTAL\ Even n umber bit 1: Enable 40MHz XTAL XTAL_48M_SEL_MODE (BLOCK0) Specify the XTAL frequency selection is decided by = True R/W (0b1) eFuse or strapping-PAD-state. 1: eFuse\\ 0: strap ping-PAD-state ECC_FORCE_CONST_TIME (BLOCK0) Represents whether to force ecc to use const-time = False R/W (0b0) calculation mode. \\ 1: Enable. \\ 0: Disable PSRAM_CAP (BLOCK1) Psram capacity = 0 R/W (0b000) PSRAM_VENDOR (BLOCK1) Psram vendor = 0 R/W (0b00) TEMP (BLOCK1) Temp (die embedded inside) = 0 R/W (0b00) TRIM_N_BIAS (BLOCK1) PADC CAL N bias = 0 R/W (0b00000) TRIM_P_BIAS (BLOCK1) PADC CAL P bias = 0 R/W (0b00000) BLOCK_USR_DATA (BLOCK3) User data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W Flash fuses: FLASH_TPUW (BLOCK0) Represents the flash waiting time after power-up; = 0 R/W (0x0) in unit of ms. When the value less than 15; the wa iting time is the programmed value. Otherwise; the waiting time is 2 times the programmed value FORCE_SEND_RESUME (BLOCK0) Represents whether ROM code is forced to send a re = False R/W (0b0) sume command during SPI boot.\\ 1: forced\\ 0:not forced\\ FLASH_CAP (BLOCK1) Flash capacity = 0 R/W (0b000) FLASH_VENDOR (BLOCK1) Flash vendor = 0 R/W (0b000) Identity fuses: WAFER_VERSION_MINOR (BLOCK1) Minor chip version = 0 R/W (0x0) WAFER_VERSION_MAJOR (BLOCK1) Minor chip version = 0 R/W (0b00) DISABLE_WAFER_VERSION_MAJOR (BLOCK1) Disables check of wafer version major = False R/W (0b0) DISABLE_BLK_VERSION_MAJOR (BLOCK1) Disables check of blk version major = False R/W (0b0) BLK_VERSION_MINOR (BLOCK1) BLK_VERSION_MINOR of BLOCK2 = 0 R/W (0b000) BLK_VERSION_MAJOR (BLOCK1) BLK_VERSION_MAJOR of BLOCK2 = 0 R/W (0b00) PKG_VERSION (BLOCK1) Package version = 0 R/W (0b000) PA_TRIM_VERSION (BLOCK1) PADC CAL PA trim version = 0 R/W (0b000) OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W Jtag fuses: JTAG_SEL_ENABLE (BLOCK0) Represents whether the selection between usb_to_jt = False R/W (0b0) ag and pad_to_jtag through strapping gpio15 when b oth EFUSE_DIS_PAD_JTAG and EFUSE_DIS_USB_JTAG are equal to 0 is enabled or disabled.\\ 1: enabled\\ 0: disabled\\ SOFT_DIS_JTAG (BLOCK0) Represents whether JTAG is disabled in soft way.\\ = 0 R/W (0b000) Odd number: disabled\\ Even number: enabled\\ DIS_PAD_JTAG (BLOCK0) Represents whether JTAG is disabled in the hard wa = False R/W (0b0) y(permanently).\\ 1: disabled\\ 0: enabled\\ Mac fuses: MAC (BLOCK1) MAC address = 60:55:f9:f9:54:1c (OK) R/W MAC_EXT (BLOCK1) Represents the extended bits of MAC address = ff:fe (OK) R/W CUSTOM_MAC (BLOCK3) Custom MAC = 00:00:00:00:00:00 (OK) R/W MAC_EUI64 (BLOCK1) calc MAC_EUI64 = MAC[0]:MAC[1]:MAC[2]:MAC_EXT[0]:M = 60:55:f9:ff:fe:f9:54:1c (OK) R/W AC_EXT[1]:MAC[3]:MAC[4]:MAC[5] Security fuses: DIS_FORCE_DOWNLOAD (BLOCK0) Represents whether the function that forces chip i = False R/W (0b0) nto download mode is disabled or enabled.\\ 1: dis abled\\ 0: enabled\\ SPI_DOWNLOAD_MSPI_DIS (BLOCK0) Represents whether SPI0 controller during boot_mod = False R/W (0b0) e_download is disabled or enabled.\\ 1: disabled\\ 0: enabled\\ DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0) led or enabled(except in SPI boot mode).\\ 1: disa bled\\ 0: enabled\\ FORCE_USE_KEY_MANAGER_KEY (BLOCK0) Set each bit to control whether corresponding key = 0 R/W (0x0) must come from key manager. 1 is true; 0 is false. bit 0: ecsda; bit 1: xts; bit2: hmac; bit3: ds FORCE_DISABLE_SW_INIT_KEY (BLOCK0) Set this bit to disable software written init key; = False R/W (0b0) and force use efuse_init_key SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) and disables otherwise SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) KEY_PURPOSE_0 (BLOCK0) Represents the purpose of Key0 = USER R/W (0x0) KEY_PURPOSE_1 (BLOCK0) Represents the purpose of Key1 = USER R/- (0x0) KEY_PURPOSE_2 (BLOCK0) Represents the purpose of Key2 = USER R/W (0x0) KEY_PURPOSE_3 (BLOCK0) Represents the purpose of Key3 = USER R/W (0x0) KEY_PURPOSE_4 (BLOCK0) Represents the purpose of Key4 = USER R/- (0x0) KEY_PURPOSE_5 (BLOCK0) Represents the purpose of Key5 = USER R/W (0x0) SEC_DPA_LEVEL (BLOCK0) Represents the spa secure level by configuring the = 0 R/W (0b00) clock random divide mode SECURE_BOOT_EN (BLOCK0) Represents whether secure boot is enabled or disab = False R/W (0b0) led.\\ 1: enabled\\ 0: disabled\\ SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Represents whether revoking aggressive secure boot = False R/W (0b0) is enabled or disabled.\\ 1: enabled.\\ 0: disabl ed\\ KM_XTS_KEY_LENGTH_256 (BLOCK0) Set this bitto configure flash encryption use xts- = False R/W (0b0) 128 key. else use xts-256 key DIS_DOWNLOAD_MODE (BLOCK0) Represents whether Download mode is disabled or en = False R/W (0b0) abled.\\ 1: disabled\\ 0: enabled\\ LOCK_KM_KEY (BLOCK0) Represetns whether to lock the efuse xts key.\\ 1. = False R/W (0b0) Lock\\ 0: Unlock\\ ENABLE_SECURITY_DOWNLOAD (BLOCK0) Represents whether security download is enabled or = False R/W (0b0) disabled.\\ 1: enabled\\ 0: disabled\\ SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000) ck feature SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST VERIFY ON WAKE is disabled = False R/W (0b0) or enabled when Secure Boot is enabled.\\ 1: disa bled\\ 0: enabled\\ XTS_DPA_PSEUDO_LEVEL (BLOCK0) Represents the pseudo round level of xts-aes anti- = 0 R/W (0b00) dpa attack.\\ 3: High.\\ 2: Moderate 1. Low\\ 0: D isabled\\ XTS_DPA_CLK_ENABLE (BLOCK0) Represents whether xts-aes anti-dpa attack clock i = False R/W (0b0) s enabled.\\ 1. Enable.\\ 0: Disable.\\ ECDSA_DISABLE_P192 (BLOCK0) Represents whether to disable P192 curve in ECDSA. = False R/W (0b0) \\ 1: Disabled.\\ 0: Not disable BLOCK_KEY0 (BLOCK4) Purpose: USER Key0 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY1 (BLOCK5) Purpose: USER Key1 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY2 (BLOCK6) Purpose: USER Key2 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY3 (BLOCK7) Purpose: USER Key3 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY4 (BLOCK8) Purpose: USER Key4 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLOCK_KEY5 (BLOCK9) Purpose: USER Key5 or user data = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W Usb fuses: DIS_USB_JTAG (BLOCK0) Represents whether the function of usb switch to j = False R/W (0b0) tag is disabled or enabled.\\ 1: disabled\\ 0: ena bled\\ USB_EXCHG_PINS (BLOCK0) Represents whether the D+ and D- pins is exchanged = False R/W (0b0) .\\ 1: exchanged\\ 0: not exchanged\\ DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) Represents whether print from USB-Serial-JTAG is d = False R/W (0b0) isabled or enabled.\\ 1: disabled\\ 0: enabled\\ DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Represents whether the USB-Serial-JTAG download fu = False R/W (0b0) nction is disabled or enabled.\\ 1: Disable\\ 0: E nable\\ Vdd fuses: VDD_SPI_AS_GPIO (BLOCK0) Represents whether vdd spi pin is functioned as gp = False R/W (0b0) io.\\ 1: functioned\\ 0: not functioned\\ Wdt fuses: WDT_DELAY_SEL (BLOCK0) Represents the threshold level of the RTC watchdog = 0 R/W (0b00) STG0 timeout.\\ 0: Original threshold configurati on value of STG0 *2 \\1: Original threshold config uration value of STG0 *4 \\2: Original threshold c onfiguration value of STG0 *8 \\3: Original thresh old configuration value of STG0 *16 \\ --- METRICS --- - Files Extracted: 11 - Estimated Token Budget: ~40682 tokens - Recency Window: Active (< 180 days) - Canonical Reference: https://codewiki.google/github.com/espressif/esptool