From 7f9cfc17beb49886838468df461f8141abc16bf9 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 6 Apr 2021 10:18:19 +1000 Subject: [PATCH] doc: Add notes about bootloader compatibility --- docs/en/api-guides/bootloader.rst | 25 +++++++++++++++++++++++++ docs/en/api-guides/startup.rst | 1 + 2 files changed, 26 insertions(+) diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index 9ad2e70a60..395efe2bc6 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/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 `: 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. diff --git a/docs/en/api-guides/startup.rst b/docs/en/api-guides/startup.rst index 51f41d7a70..a4deae02eb 100644 --- a/docs/en/api-guides/startup.rst +++ b/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