Merge branch 'doc/bootloader_app_compatibility' into 'master'

doc: Add notes about bootloader compatibility

Closes IDF-902

See merge request espressif/esp-idf!13024

docs/en/api-guides/bootloader.rst

@@ -15,6 +15,8 @@ Bootloader is located at the address {IDF_TARGET_BOOTLOADER_OFFSET} in the flash
 
 For a full description of the startup process including the the ESP-IDF bootloader, see :doc:`startup`.
 
+.. _bootloader-compatibility:
+
 Bootloader compatibility
 ------------------------
 
@@ -22,6 +24,29 @@ It is recommended to update to newer :doc:`versions of ESP-IDF </versions>`: whe
 
 The bootloader does not support booting apps from older versions of ESP-IDF. When updating ESP-IDF manually on an existing product that might need to downgrade the app to an older version, keep using the older ESP-IDF bootloader binary as well.
 
+.. note::
+
+   If testing an OTA update for an existing product in production, always test it using the same ESP-IDF bootloader binary that is deployed in production.
+
+.. only:: esp32
+
+    Before ESP-IDF V2.1
+    ^^^^^^^^^^^^^^^^^^^
+
+    Bootloaders built from very old versions of ESP-IDF (before ESP-IDF V2.1) perform less hardware configuration than newer versions. When using a bootloader from these early ESP-IDF versions and building a new app, enable the config option :ref:`CONFIG_ESP32_COMPATIBLE_PRE_V2_1_BOOTLOADERS`.
+
+SPI Flash Configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Each ESP-IDF application or bootloader .bin file contains a header with :ref:`CONFIG_ESPTOOLPY_FLASHMODE`, :ref:`CONFIG_ESPTOOLPY_FLASHFREQ`, :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` embedded in it. These are used to configure the SPI flash during boot.
+
+The :ref:`first-stage-bootloader` in ROM reads the :ref:`second-stage-bootloader` header from flash and uses these settings to load it. However, at this time the system clock speed is lower than configured and not all flash modes are supported.  When the :ref:`second-stage-bootloader` then runs and re-configures the flash, it reads values from the currently selected app binary header not the bootloader header. This allows an OTA update to change the SPI flash settings in use.
+
+.. only:: esp32
+
+   Bootloaders prior to ESP-IDF V4.0 used the bootloader's own header to configure the SPI flash, meaning these values could not be changed in an update. To maintain compatibility with older bootloaders, the app re-initializes the flash settings during app startup using the configuration found in the app header.
+
+
 Factory reset
 -------------
 The user can write a basic working firmware and load it into the factory app partition.

docs/en/api-guides/startup.rst

@@ -108,6 +108,7 @@ This port-layer initialization function initializes the basic C Runtime Environm
    :SOC_SPIRAM_SUPPORTED: - Enable PSRAM if configured.
    - Set the CPU clocks to the frequencies configured for the project.
    :CONFIG_ESP_SYSTEM_MEMPROT_FEATURE: - Initialize memory protection if configured.
+   :esp32: - Reconfigure the main SPI flash based on the app header settings (necessary for compatibility with bootloader versions before ESP-IDF V4.0, see :ref:`bootloader-compatibility`).
    :not CONFIG_FREERTOS_UNICORE: - If the app is configured to run on multiple cores, start the other core and wait for it to initialize as well (inside the similar "port layer" initialization function ``call_start_cpu1``).
 
 .. only:: not CONFIG_FREERTOS_UNICORE