docs: Add note about bootloader size for flash encryption & secure boot

diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst
index e925ee6182e0ddc213c0210c885721df16b20ba8..c36839ef4ae4e0c637faf889e8a243483955e32a 100644 (file)
--- a/docs/en/security/flash-encryption.rst
+++ b/docs/en/security/flash-encryption.rst
@@ -55,6 +55,8 @@ Process to enable flash encryption:
 
 - Build and flash the bootloader, partition table and factory app image as normal. These partitions are initially written to the flash unencrypted.
 
+.. note:: The bootloader app binary ``bootloader.bin`` may become too large when both secure boot and flash encryption are enabled. See :ref:`secure-boot-bootloader-size`.
+
 - On first boot, the bootloader sees :ref:`FLASH_CRYPT_CNT` is set to 0 (factory default) so it generates a flash encryption key using the hardware random number generator. This key is stored in efuse. The key is read and write protected against further software access.
 
 - All of the encrypted partitions are then encrypted in-place by the bootloader. Encrypting in-place can take some time (up to a minute for large partitions.)

diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst
index da9a203d36abd610b1484c2f8d06c305639cf523..7910fa3654e9350e297982f06db28513302d4fe1 100644 (file)
--- a/docs/en/security/secure-boot.rst
+++ b/docs/en/security/secure-boot.rst
@@ -55,6 +55,20 @@ The following keys are used by the secure boot process:
 
   - The private key from this key pair *must be securely kept private*, as anyone who has this key can authenticate to any bootloader that is configured with secure boot and the matching public key.
 
+.. _secure-boot-bootloader-size:
+
+Bootloader Size
+---------------
+
+When secure boot is enabled the bootloader app binary ``bootloader.bin`` may exceed the default bootloader size limit. This is especially likely if flash encryption is enabled as well. The default size limit is 0x7000 (28672) bytes (partition table offset 0x8000 - bootloader offset 0x1000).
+
+If the bootloader becomes too large, the ESP32 will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum.
+
+Options to work around this are:
+
+- Reduce :envvar:`bootloader log level <CONFIG_LOG_BOOTLOADER_LEVEL>`. Setting log level to Warning, Error or None all significantly reduce the final binary size (but may make it harder to debug).
+- Set :envvar:`partition table offset <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 :doc:`partition table </api-guides/partition-tables>` 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.)
+
 .. _secure-boot-howto:
 
 How To Enable Secure Boot