alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

doc: Add notes about bootloader compatibility

Browse Source
This commit is contained in:
Angus Gratton 2021-04-06 10:18:19 +10:00
parent 94ac251091
commit 7f9cfc17be
2 changed files with 26 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/en/api-guides/bootloader.rst
View File

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

1
docs/en/api-guides/startup.rst
View File

@ -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