From 52676974e4ae7aa23a51dbec3010027b5cc1f60a Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 13 Oct 2020 17:25:57 +1100 Subject: [PATCH] doc: Add note about moving components or bootloader in an existing project Based on some forum questions, i.e. https://esp32.com/viewtopic.php?f=13&t=16731&sid=107a5d613c97b68cf156b49579534c51 --- docs/en/api-guides/bootloader.rst | 9 ++++++--- docs/en/api-guides/build-system.rst | 3 +++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index 6f39247945..c1f1c150dd 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/docs/en/api-guides/bootloader.rst @@ -61,7 +61,10 @@ The bootloader has the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` opti Customer bootloader --------------------- -The current bootloader implementation allows the customer to override it. To do this, you must copy the folder `/esp-idf/components/bootloader` and then edit `/your_project/components/bootloader/subproject/main/bootloader_main.c`. -In the bootloader space, you can not use the drivers and functions from other components. If necessary, then the required functionality should be placed in the folder bootloader (note that this will increase its size). -It is necessary to monitor its size because there can be overlays in memory with a partition table leading to damage. At the moment the bootloader is limited to the partition table from the address `0x8000`. +The current bootloader implementation allows a project to override it. To do this, you must copy the directory ``/esp-idf/components/bootloader`` to your project components directory and then edit ``/your_project/components/bootloader/subproject/main/bootloader_start.c``. +In the bootloader space, you cannot use the drivers and functions from other components. If necessary, then the required functionality should be placed in the project's ``bootloader`` directory (note that this will increase its size). + +If the bootloader grows too large then it can collide with the partition table, which is flashed at offset 0x8000 by default. Increase the :ref:`partition table offset ` value to place the partition table later in the flash. This increases the space available for the bootloader. + +.. note:: The first time you copy the bootloader into an existing project, the project may fail to build as paths have changed unexpectedly. If this happens, run ``idf.py fullclean`` (or delete the project build directory) and then build again. diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 4841942f90..4470ca2e02 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -353,6 +353,9 @@ contain component sub-directories with the same name, the component in the last with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. If used in this way, the ESP-IDF directory itself can remain untouched. +.. note:: If a component is overridden in an existing project by moving it to a new location, the project will not automatically see the new component path. Run ``idf.py reconfigure`` (or delete the project build folder) and then build again. + + .. _cmake_minimal_component_cmakelists: Minimal Component CMakeLists