+

+ +

+

Boot Mode Selection

+

This guide explains how to select the boot mode correctly and describes the boot log messages of ESP32-P4.

+

Warning

+

The ESP32-P4 has a 45k ohm internal pull-up/pull-down resistor at GPIO35 (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 ESP32-P4 strapping pins can also be found in the ESP32-P4 Datasheet, 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

+

GPIO35

+

The ESP32-P4 will enter the serial bootloader when GPIO35 is held low on reset. Otherwise it will run the program in flash.

+ ++++ + + + + + + + + + + + + + +

GPIO35 Input	Mode
Low/GND	ROM serial bootloader for esptool
High/VCC	Normal execution mode

+

GPIO35 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 GPIO35 low when pressed.

+

GPIO36

+

GPIO36 must also be driven High, in order to enter the serial bootloader reliably. The strapping combination of GPIO36 = 0 and GPIO35 = 0 is invalid and will trigger unexpected behavior.

+

In normal boot mode (GPIO35 high), GPIO36 is ignored.

+

Other Pins

+

As well as the above mentioned pins, other ones influence the serial bootloader, please consult the ESP32-P4 Datasheet, section “Strapping Pins”.

+

Automatic Bootloader

+

esptool resets ESP32-P4 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 GPIO35 and EN (CHIP_PU) pins of ESP32-P4, thus changes in the voltage levels of DTR and RTS will boot the ESP32-P4 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 GPIO35 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 manually switching to bootloader.

+

Make the following connections for esptool to automatically enter the bootloader of an ESP32-P4 chip:

+ + + + + + + + + + + + + + +

ESP Pin	Serial Pin
EN	RTS
GPIO35	DTR

+

In Linux serial ports by default will assert RTS when nothing is attached to them. This can hold the ESP32-P4 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 ESP32-P4 development boards use an automatic reset circuit for EN & GPIO35 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 GPIO35 and EN (CHIP_PU)
The DTR and RTS lines are configured differently
There are no such serial control lines at all

+

Manual Bootloader

+

Depending on the kind of hardware you have, it may also be possible to manually put your ESP32-P4 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 (GPIO35) and press the EN button (EN (CHIP_PU)).
For other types of hardware, try pulling GPIO35 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 GPIO35) while you start esptool and keep it down during reset.

+

Boot Log

+

Boot Mode Message

+

After reset, the second line printed by the ESP32-P4 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 ESP32-P4 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:

+

0x04 - GPIO36
0x08 - GPIO35

+

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) - ESP32-P4 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 GPIO36 has been pulled high when GPIO35 is low).

+

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

+

Invalid header <value at 0x2000>
+

+

+

This fatal error indicates that the bootloader tried to read the software bootloader header at address 0x2000 but failed to read valid data. Possible reasons for this include:

+

There isn’t actually a bootloader at offset 0x2000 (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.

+

Software Bootloader Header Info

+

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 0x2000:

+

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.
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 esp32p4 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.

+

+ + +

+

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, `5` = 32MB, `6` = 64MB) + Low four bits - Flash frequency (`0` = 40MHz, `1` = 26MHz, `2` = 20MHz, `0xf` = 80MHz) +
4-7	Entry point address

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)

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

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.

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.

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.

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

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”

Byte	Name	Description	Input Data	Output Data
`0x02`	FLASH_BEGIN	Begin Flash Download	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	Four 32-bit words: data size, sequence number, `0`, `0`, then data. Uses Checksum.
`0x04`	FLASH_END	Finish Flash Download	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	Total size, number of data packets, data size in one packet, memory offset
`0x06`	MEM_END	Finish RAM Download	Two 32-bit words: execute flag, entry point address
`0x07`	MEM_DATA	RAM Download Data	Four 32-bit words: data size, sequence number, `0`, `0`, then data. Uses Checksum.
`0x08`	SYNC	Sync Frame	36 bytes: `0x07 0x07 0x12 0x20`, followed by 32 x `0x55`
`0x09`	WRITE_REG	Write 32-bit memory address	Four 32-bit words: address, value, mask and delay (in microseconds)
`0x0a`	READ_REG	Read 32-bit memory address	Address as 32-bit word	Read data as 32-bit word in `value` field.
`0x0b`	SPI_SET_PARAMS	Configure SPI flash	Six 32-bit words: id, total size in bytes, block size, sector size, page size, status mask.
`0x0d`	SPI_ATTACH	Attach SPI flash	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	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	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	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	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	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		32 bits `flags`, 1 byte `flash_crypt_cnt`, 7x1 byte `key_purposes`, 32-bit word `chip_id`, 32-bit word `eco_version`

Boot Mode Selection

Select Bootloader Mode

GPIO35

GPIO36

Other Pins

Automatic Bootloader

Manual Bootloader

Boot Log

Boot Mode Message

Later Boot Messages

Early Flash Read Error

Software Bootloader Header Info

Software Bootloader Load Segments

Firmware Image Format

File Header

Extended File Header

Segment

Footer

Analyzing a Binary Image

Serial Protocol

Packet Description

Low Level Protocol

Command Packet

Response Packet

Status Bytes

ROM Loader Errors

Stub Loader Status & Error

Commands

Supported by Stub Loader and ROM Loader

Supported by Stub Loader Only

Supported in Secure Download Mode

Checksum

Functional Description

Initialization

Initialization - Chip Type Detection

ESP32-P4 Chip Detection

Overview of Detection for All Chips

Writing Data

Verifying Uploaded Data

SPI Configuration Commands

SPI Attach Command

SPI Set Parameters

32-Bit Read/Write

Reading Flash

Tracing Esptool Serial Communications