Bootloader Size

When secure boot is enabled the bootloader app binary bootloader.bin may exceed the bootloader binary size limit and overlap with the partition table. This is especially likely if flash encryption is enabled as well. When using the default CONFIG_PARTITION_TABLE_OFFSET value 0x8000, the size limit is 0x7000 (28672) bytes.

If the bootloader binary is too large, then the bootloader build will fail with an error “Bootloader binary size [..] is too large for partition table offset”. If the bootloader binary is flashed anyhow then the ESP32-S2 will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum.

Note

The bootloader size check only happens in the CMake Build System, when using the legacy GNU Make Build System the size is not checked but the ESP32-S2 will fail to boot if bootloader is too large.

When Secure Boot V2 is enabled, there is also an absolute binary size limit of 64KB (0x10000 bytes) (excluding the 4KB signature), because the bootloader is first loaded into a fixed size buffer for verification.

Options to work around this are:

  • Set bootloader compiler optimization back to “Size” if it has been changed from this default value.

  • Reduce bootloader log level. Setting log level to Warning, Error or None all significantly reduce the final binary size (but may make it harder to debug).

  • Set CONFIG_PARTITION_TABLE_OFFSET to a higher value than 0x8000, to place the partition table later in the flash. This increases the space available for the bootloader. If the partition table CSV file contains explicit partition offsets, they will need changing so no partition has an offset lower than CONFIG_PARTITION_TABLE_OFFSET + 0x1000. (This includes the default partition CSV files supplied with ESP-IDF.)

Note that because of the absolute binary size limit, when using Secure Boot V2 there is no benefit to moving the partition table any higher than offset 0x12000.