From 86e14d46b763e122414e1696e287ecf63ca7494c Mon Sep 17 00:00:00 2001 From: Almir Okato Date: Fri, 12 Dec 2025 20:04:55 -0300 Subject: [PATCH 1/2] espressif: update default bootloader.conf files These changes reflects the default flash layout configuration for most of Espressif boards on Zephyr. Signed-off-by: Almir Okato --- boot/espressif/port/esp32/bootloader.conf | 12 ++++++------ boot/espressif/port/esp32c2/bootloader.conf | 14 +++++++------- boot/espressif/port/esp32c3/bootloader.conf | 12 ++++++------ boot/espressif/port/esp32c6/bootloader.conf | 12 ++++++------ boot/espressif/port/esp32h2/bootloader.conf | 12 ++++++------ boot/espressif/port/esp32s2/bootloader.conf | 12 ++++++------ boot/espressif/port/esp32s3/bootloader.conf | 12 ++++++------ 7 files changed, 43 insertions(+), 43 deletions(-) diff --git a/boot/espressif/port/esp32/bootloader.conf b/boot/espressif/port/esp32/bootloader.conf index 2c94b7b117..0d0948ca89 100644 --- a/boot/espressif/port/esp32/bootloader.conf +++ b/boot/espressif/port/esp32/bootloader.conf @@ -9,12 +9,12 @@ CONFIG_ESP_FLASH_SIZE=4MB CONFIG_ESP_BOOTLOADER_SIZE=0xF000 CONFIG_ESP_BOOTLOADER_OFFSET=0x1000 -CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000 -CONFIG_ESP_APPLICATION_SIZE=0x100000 -CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000 +CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000 +CONFIG_ESP_APPLICATION_SIZE=0x150000 +CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x170000 CONFIG_ESP_MCUBOOT_WDT_ENABLE=y -CONFIG_ESP_SCRATCH_OFFSET=0x210000 -CONFIG_ESP_SCRATCH_SIZE=0x40000 +CONFIG_ESP_SCRATCH_OFFSET=0x3E0000 +CONFIG_ESP_SCRATCH_SIZE=0x1F000 # When enabled, prevents updating image to an older version # CONFIG_ESP_DOWNGRADE_PREVENTION=y @@ -107,5 +107,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0 # to not overlap with other flash regions) # CONFIG_EFUSE_VIRTUAL=1 # CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 # CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 diff --git a/boot/espressif/port/esp32c2/bootloader.conf b/boot/espressif/port/esp32c2/bootloader.conf index 9fc0994e71..b9a9b898b3 100644 --- a/boot/espressif/port/esp32c2/bootloader.conf +++ b/boot/espressif/port/esp32c2/bootloader.conf @@ -6,15 +6,15 @@ # CONFIG_ESP_BOOT_SWAP_USING_MOVE=y # CONFIG_ESP_BOOT_UPGRADE_ONLY=y -CONFIG_ESP_FLASH_SIZE=4MB +CONFIG_ESP_FLASH_SIZE=2MB CONFIG_ESP_BOOTLOADER_SIZE=0xF000 CONFIG_ESP_BOOTLOADER_OFFSET=0x0000 -CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000 -CONFIG_ESP_APPLICATION_SIZE=0x100000 -CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000 +CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000 +CONFIG_ESP_APPLICATION_SIZE=0xC0000 +CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0xE0000 CONFIG_ESP_MCUBOOT_WDT_ENABLE=y -CONFIG_ESP_SCRATCH_OFFSET=0x210000 -CONFIG_ESP_SCRATCH_SIZE=0x40000 +CONFIG_ESP_SCRATCH_OFFSET=0x1E0000 +CONFIG_ESP_SCRATCH_SIZE=0x1F000 # When enabled, prevents updating image to an older version # CONFIG_ESP_DOWNGRADE_PREVENTION=y @@ -93,5 +93,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0 # to not overlap with other flash regions) # CONFIG_EFUSE_VIRTUAL=1 # CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 # CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 diff --git a/boot/espressif/port/esp32c3/bootloader.conf b/boot/espressif/port/esp32c3/bootloader.conf index 72caf08c88..3912fde725 100644 --- a/boot/espressif/port/esp32c3/bootloader.conf +++ b/boot/espressif/port/esp32c3/bootloader.conf @@ -9,12 +9,12 @@ CONFIG_ESP_FLASH_SIZE=4MB CONFIG_ESP_BOOTLOADER_SIZE=0xF000 CONFIG_ESP_BOOTLOADER_OFFSET=0x0000 -CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000 -CONFIG_ESP_APPLICATION_SIZE=0x100000 -CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000 +CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000 +CONFIG_ESP_APPLICATION_SIZE=0x1C0000 +CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000 CONFIG_ESP_MCUBOOT_WDT_ENABLE=y -CONFIG_ESP_SCRATCH_OFFSET=0x210000 -CONFIG_ESP_SCRATCH_SIZE=0x40000 +CONFIG_ESP_SCRATCH_OFFSET=0x3E0000 +CONFIG_ESP_SCRATCH_SIZE=0x1F000 # When enabled, prevents updating image to an older version # CONFIG_ESP_DOWNGRADE_PREVENTION=y @@ -94,5 +94,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0 # to not overlap with other flash regions) # CONFIG_EFUSE_VIRTUAL=1 # CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 # CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 diff --git a/boot/espressif/port/esp32c6/bootloader.conf b/boot/espressif/port/esp32c6/bootloader.conf index 95cd6e59a6..9008c249c2 100644 --- a/boot/espressif/port/esp32c6/bootloader.conf +++ b/boot/espressif/port/esp32c6/bootloader.conf @@ -9,12 +9,12 @@ CONFIG_ESP_FLASH_SIZE=4MB CONFIG_ESP_BOOTLOADER_SIZE=0xF000 CONFIG_ESP_BOOTLOADER_OFFSET=0x0000 -CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000 -CONFIG_ESP_APPLICATION_SIZE=0x100000 -CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000 +CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000 +CONFIG_ESP_APPLICATION_SIZE=0x1C0000 +CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000 CONFIG_ESP_MCUBOOT_WDT_ENABLE=y -CONFIG_ESP_SCRATCH_OFFSET=0x210000 -CONFIG_ESP_SCRATCH_SIZE=0x40000 +CONFIG_ESP_SCRATCH_OFFSET=0x3E0000 +CONFIG_ESP_SCRATCH_SIZE=0x1F000 # When enabled, prevents updating image to an older version # CONFIG_ESP_DOWNGRADE_PREVENTION=y @@ -94,5 +94,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0 # to not overlap with other flash regions) CONFIG_EFUSE_VIRTUAL=1 CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 diff --git a/boot/espressif/port/esp32h2/bootloader.conf b/boot/espressif/port/esp32h2/bootloader.conf index 0b99797c2d..e91c448999 100644 --- a/boot/espressif/port/esp32h2/bootloader.conf +++ b/boot/espressif/port/esp32h2/bootloader.conf @@ -9,12 +9,12 @@ CONFIG_ESP_FLASH_SIZE=4MB CONFIG_ESP_BOOTLOADER_SIZE=0xF000 CONFIG_ESP_BOOTLOADER_OFFSET=0x0000 -CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000 -CONFIG_ESP_APPLICATION_SIZE=0x100000 -CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000 +CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000 +CONFIG_ESP_APPLICATION_SIZE=0x1C0000 +CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000 CONFIG_ESP_MCUBOOT_WDT_ENABLE=y -CONFIG_ESP_SCRATCH_OFFSET=0x210000 -CONFIG_ESP_SCRATCH_SIZE=0x40000 +CONFIG_ESP_SCRATCH_OFFSET=0x3E0000 +CONFIG_ESP_SCRATCH_SIZE=0x1F000 # When enabled, prevents updating image to an older version # CONFIG_ESP_DOWNGRADE_PREVENTION=y @@ -96,5 +96,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0 # to not overlap with other flash regions) # CONFIG_EFUSE_VIRTUAL=1 # CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 # CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 diff --git a/boot/espressif/port/esp32s2/bootloader.conf b/boot/espressif/port/esp32s2/bootloader.conf index 6c40adb488..9268e7a32d 100644 --- a/boot/espressif/port/esp32s2/bootloader.conf +++ b/boot/espressif/port/esp32s2/bootloader.conf @@ -9,12 +9,12 @@ CONFIG_ESP_FLASH_SIZE=4MB CONFIG_ESP_BOOTLOADER_SIZE=0xF000 CONFIG_ESP_BOOTLOADER_OFFSET=0x1000 -CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000 -CONFIG_ESP_APPLICATION_SIZE=0x100000 -CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000 +CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000 +CONFIG_ESP_APPLICATION_SIZE=0x1C0000 +CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000 CONFIG_ESP_MCUBOOT_WDT_ENABLE=y -CONFIG_ESP_SCRATCH_OFFSET=0x210000 -CONFIG_ESP_SCRATCH_SIZE=0x40000 +CONFIG_ESP_SCRATCH_OFFSET=0x3E0000 +CONFIG_ESP_SCRATCH_SIZE=0x1F000 # When enabled, prevents updating image to an older version # CONFIG_ESP_DOWNGRADE_PREVENTION=y @@ -90,5 +90,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0 # to not overlap with other flash regions) # CONFIG_EFUSE_VIRTUAL=1 # CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 # CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 diff --git a/boot/espressif/port/esp32s3/bootloader.conf b/boot/espressif/port/esp32s3/bootloader.conf index b27e509604..3bee3240d7 100644 --- a/boot/espressif/port/esp32s3/bootloader.conf +++ b/boot/espressif/port/esp32s3/bootloader.conf @@ -9,12 +9,12 @@ CONFIG_ESP_FLASH_SIZE=4MB CONFIG_ESP_BOOTLOADER_SIZE=0xF000 CONFIG_ESP_BOOTLOADER_OFFSET=0x0000 -CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000 -CONFIG_ESP_APPLICATION_SIZE=0x100000 -CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000 +CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000 +CONFIG_ESP_APPLICATION_SIZE=0x150000 +CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x170000 CONFIG_ESP_MCUBOOT_WDT_ENABLE=y -CONFIG_ESP_SCRATCH_OFFSET=0x210000 -CONFIG_ESP_SCRATCH_SIZE=0x40000 +CONFIG_ESP_SCRATCH_OFFSET=0x3E0000 +CONFIG_ESP_SCRATCH_SIZE=0x1F000 # When enabled, prevents updating image to an older version # CONFIG_ESP_DOWNGRADE_PREVENTION=y @@ -114,5 +114,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0 # to not overlap with other flash regions) # CONFIG_EFUSE_VIRTUAL=1 # CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 # CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 From d262a0be15b801b61de8b38b7a7e8cc519c31068 Mon Sep 17 00:00:00 2001 From: Almir Okato Date: Fri, 12 Dec 2025 20:08:07 -0300 Subject: [PATCH 2/2] espressif: update readme-espressif.md documentation Add note for the required version of ESP-IDF HAL sources. Update general instructions. Signed-off-by: Almir Okato --- docs/readme-espressif.md | 62 ++++++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 15 deletions(-) diff --git a/docs/readme-espressif.md b/docs/readme-espressif.md index 1fe6c6e88f..59e7a1a04b 100644 --- a/docs/readme-espressif.md +++ b/docs/readme-espressif.md @@ -7,6 +7,13 @@ dependent, therefore, the system environment including toolchains, must be set a standalone build version means that ESP-IDF and its toolchain are used as source. For 3rd parties framework, HAL path and toolchain must be set. +--- +***Note*** + +*Current compatible ESP-IDF version for HAL sources is `v5.1.6`* + +--- + Documentation about the MCUboot bootloader design, operation and features can be found in the [design document](design.md). @@ -16,7 +23,7 @@ The current port is available for use in the following SoCs within the OSes: | | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C2 | ESP32-C6 | ESP32-H2 | | :----: | :-------: | :-------: | :-------: | :-------: | :---------: | :-------: | :---------: | -| Zephyr | Supported | Supported | Supported | Supported | Supported | Supported | In progress | +| Zephyr | Supported | Supported | Supported | Supported | Supported | Supported | Supported | | NuttX | Supported | Supported | Supported | Supported | In progress | Supported | Supported | Notice that any customization in the memory layout from the OS application must be done aware of @@ -44,7 +51,12 @@ The following instructions considers a MCUboot Espressif port standalone build. ``` 3. If ESP-IDF is the chosen option for use as HAL layer and the system already have ESP-IDF - installed, ensure that the environment is set: + installed, ensure that it is the current compatible version and the environment is set: + + ```bash + cd + git checkout v5.1.6 + ``` ```bash /install.sh @@ -140,18 +152,27 @@ Additional configuration related to MCUboot features and slot partitioning may b ninja -C build/ flash ``` - If `MCUBOOT_FLASH_PORT` arg was not passed to `cmake`, the default `PORT` for flashing will be - `/dev/ttyUSB0`. + If the below arguments were not passed to `cmake` build step, the default values for each on + the flashing operation will be as following: - Alternatively: + - `MCUBOOT_FLASH_PORT`: "/dev/ttyUSB0" + - `ESP_BAUD_RATE`: 115200 + - `ESP_FLASH_MODE`: "dio" + - `ESP_FLASH_FREQ`: "40m" for ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6; + "60m" for ESP32-C2; + "24m" for ESP32-H2. + + Alternatively, `esptool` can be used for flashing directly: ```bash - esptool.py -p -b --before default_reset --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq 40m build/mcuboot_.bin + esptool.py -p -b --before default_reset --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq build/mcuboot_.bin ``` --- ***Note*** + Ensure that the flash parameters like ``, ``, `` matches + the same parameters from `cmake` step and configuration file. You may adjust the port `` (like `/dev/ttyUSB0`) and baud rate `` (like `2000000`) according to the connection with your board. You can also skip `` and `` parameters so that esptool tries to automatically detect it. @@ -209,7 +230,7 @@ Additional configuration related to MCUboot features and slot partitioning may b 2. Flash the signed application: ```bash - esptool.py -p -b --before default_reset --after hard_reset --chip write_flash --flash_mode dio --flash_size --flash_freq 40m + esptool.py -p -b --before default_reset --after hard_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` # [Downgrade prevention](#downgrade-prevention) @@ -366,10 +387,14 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=1 # to not overlap with other flash regions) CONFIG_EFUSE_VIRTUAL=1 CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 ``` + +Observe that the region defined by `CONFIG_EFUSE_VIRTUAL_OFFSET` and `CONFIG_EFUSE_VIRTUAL_SIZE` +must not overlap with other flash regions. + --- --- @@ -420,10 +445,13 @@ key are correct and you did not forget anything before flashing.* --- Flash the bootloader as following, with `--after no_reset` flag, so you can reset the device only -when assured: +when assured. Also ensure that the flash parameters like ``, ``, +`` matches the same parameters from `cmake` step and configuration file, this is +important because `esptool` may modify the binary if it detects that these parameters are +different from what they were on the building. ```bash -esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq 40m +esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` ### [Secure Boot Process](#secure-boot-process) @@ -510,10 +538,14 @@ CONFIG_SECURE_BOOT_ALLOW_JTAG=1 # to not overlap with other flash regions) CONFIG_EFUSE_VIRTUAL=1 CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 -CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000 +CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 ``` + +Observe that the region defined by `CONFIG_EFUSE_VIRTUAL_OFFSET` and `CONFIG_EFUSE_VIRTUAL_SIZE` +must not overlap with other flash regions. + --- --- @@ -583,11 +615,11 @@ the SPI Flash. Flash the bootloader and application normally: ```bash -esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq 40m +esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` ```bash -esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq 40m +esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` On the **first boot**, the bootloader will: @@ -642,11 +674,11 @@ of generate a new one. Flashing the bootloader and application: ```bash -esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq 40m +esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` ```bash -esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq 40m +esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` On the **first boot**, the bootloader will: