Merge branch 'feature/relinker_support_flash_suspend' into 'master'

feat(relinker): Support ESP32-C3 platform and SRAM optimization for flash-suspend

See merge request ae_group/esp-iot-solution!839

Author: YuanMingfu-star

tools/cmake_utilities/CHANGELOG.md

@@ -1,11 +1,16 @@
+## v1.1.0 - 2025-01-16
+
+* relinker: support ESP32-C3 and SRAM optimization for flash-suspend
+* relinker: add IDF v5.3.x support
+
 ## v0.5.3 - 2023-09-15
 
 * fix `add_dependencies called with incorrect number of arguments` in `relinker.cmake`
 * `include(cmake_utilities)` is not suggested now, to avoid cmake_utilities dependency issue
 
 ## v0.5.2 - 2023-09-15
 
-* Support work on older ESP-IDF, eg: 4.3.x
+* Support work on older ESP-IDF, eg: 4.3.x 
 
 ## v0.5.1 - 2023-08-22
 

tools/cmake_utilities/Kconfig

@@ -14,6 +14,17 @@ menu "CMake Utilities"
                 "Enable this option to print error information instead of
                     throwing exception when missing function"
 
+        config CU_RELINKER_LINK_SPECIFIC_FUNCTIONS_TO_IRAM
+            bool "Link specific functions to IRAM regardless of ESP-IDF's behavior"
+            default n
+            depends on SPI_FLASH_AUTO_SUSPEND
+            help
+                "Enable this option, although functions' attribution
+                are IRAM_ATTR, or configured to be noflash by link.lf, they will
+                not be linked into IRAM. Only functions specified by relinker
+                configuration file will be linked into IRAM."
+
+
         config CU_RELINKER_ENABLE_CUSTOMIZED_CONFIGURATION_FILES
             bool "Enable customized relinker configuration files"
             default n

tools/cmake_utilities/docs/relinker.md

@@ -2,6 +2,8 @@
 
 In ESP-IDF, some functions are put in SRAM when link stage, the reason is that some functions are critical, we need to put them in SRAM to speed up the program, or the functions will be executed when the cache is disabled. But actually, some functions can be put into Flash, here, we provide a script to let the user set the functions which are located in SRAM by default to put them into Flash, in order to save more SRAM which can be used as heap region later. This happens in the linker stage, so we call it as relinker.
 
+Some SoCs(ESP32-C2 and ESP32-C3) support hardware auto flash-suspend, meaning when reading, writing, or erasing the flash stage, the CPU hardware can switch to run code laying in the flash automatically without any software assist, so that we can link more functions from IRAM to flash.
+
 ## Use
 
 In order to use this feature, you need to include the needed CMake file in your project's CMakeLists.txt after `project(XXXX)`.
@@ -14,28 +16,52 @@ include(relinker)
 
 The relinker feature is disabled by default, in order to use it, you need to enable the option `CU_RELINKER_ENABLE` in menuconfig.
 
-Here are the default configuration files in the folder `cmake_utilities/scripts/relinker/examples/esp32c2`, it's just used as a reference. If you would like to use your own configuration files, please enable option `CU_RELINKER_ENABLE_CUSTOMIZED_CONFIGURATION_FILES` and set the path of your configuration files as following, this path is evaluated relative to the project root directory:
+Here are the default configuration files in the folder `cmake_utilities/scripts/relinker/examples/flash_suspend/XXX (XXX=esp32c2, esp32c3...)` for specific SoC platform when flash_suspend and relinker feature are enabled, please note that the configuration files may be slightly different for different ESP-IDF versions, it's just used as a reference. If you would like to use your own configuration files, please enable option `CU_RELINKER_ENABLE_CUSTOMIZED_CONFIGURATION_FILES` and set the path of your configuration files as following, this path is evaluated relative to the project root directory:
 
 ```
 [*]     Enable customized relinker configuration files
 (path of your configuration files) Customized relinker configuration files path
 ```
 
-> Note: Currently only esp32c2 is supported.
+If you would like to save more RAM, you can try flash-suspend feature, enable options as following:
+
+```
+Component config  --->
+    SPI Flash driver  --->
+        [ ] Use esp_flash implementation in ROM
+        [*] Auto suspend long erase/write operations (READ DOCS FIRST)
+
+CMake Utilities  --->
+    [*] Enable relinker
+    [*]     Link specific functions to IRAM regardless of ESP-IDF's behavior
+```
+
+> Note: Currently supported platform: esp32c2 and esp32c3.
+> Note: Before enable flash-suspend, please check if ESP-IDF supports this flash's flash-suspend feature.
 
 ## Configuration Files
 
-You can refer to the files in the directory of `cmake_utilities/scripts/relinker/examples/esp32c2`:
+You can refer to the files in the directory of `cmake_utilities/scripts/relinker/examples/$ACTION/XXX ($ACTION=iram_strip, flash_suspend) (XXX=esp32c2, esp32c3...)`:
 
 - library.csv
 - object.csv
 - function.csv
 
-For example, if you want to link function `__getreent` from SRAM to Flash, firstly you should add it to `function.csv` file as following:
+1. iram_strip
 
-```
-libfreertos.a,tasks.c.obj,__getreent,
-```
+    For `example/iram_strip`, it includes the functions which you want to relink into Flash after enable the option `CU_RELINKER_ENABLE` and disable the option `CU_RELINKER_LINK_SPECIFIC_FUNCTIONS_TO_IRAM` in menuconfig. If you want to link function `__getreent` from SRAM to Flash, firstly you should add it to `function.csv` file as following:
+
+    ```
+    libfreertos.a,tasks.c.obj,__getreent,
+    ```
+
+2. flash_suspend
+
+    For `example/flash_suspend`, it includes the functions which you want to relink into SRAM after enable the options: `SPI_FLASH_AUTO_SUSPEND`, `CU_RELINKER_ENABLE`, `CU_RELINKER_LINK_SPECIFIC_FUNCTIONS_TO_IRAM` in menuconfig. If you want to link function `__getreent` into SRAM no matter its original locations, firstly you should add it to `function.csv` file as following:
+
+    ```
+    libfreertos.a,tasks.c.obj,__getreent,
+    ```
 
 This means function `__getreent` is in object file `tasks.c.obj`, and object file `tasks.c.obj` is in library `libfreertos.a`.
 
@@ -63,4 +89,14 @@ libfreertos.a,./esp-idf/freertos/libfreertos.a
 
 This means library `libfreertos.a`'s location is `./esp-idf/freertos/libfreertos.a` relative to `build`.
 
-If above related data has exists in corresponding files, please don't add this repeatedly.
+If above related data has exists in corresponding files, please don't add this repeatedly.
+
+## Test Results Reference
+
+| Chip     | example         |                   | SRAM used (Bytes) |                                    |
+| -------- | --------------- | ----------------- | ----------------- | ---------------------------------  |
+|          |                 | Default options   | Enable relinker   | Enable relinker and flash-suspend  |
+| ESP32-C2 | power_save      | 101408            | 91728             | 51360                              |
+| ESP32-C3 | power_save      | 118728            | 99864             | 58312                              |
+
+All of the above examples are compiled on ESP-IDF Tag/v5.3.2 and version v1.1.0 of `cmake_utilities` component, you can view the memory type usage summary by using `idf.py size`, the above data is for reference only.

tools/cmake_utilities/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.0.0"
+version: "1.1.0"
 description: A collection of useful cmake utilities
 url: https://github.com/espressif/esp-iot-solution/tree/master/tools/cmake_utilities
 documentation: https://docs.espressif.com/projects/esp-iot-solution/zh_CN/latest/basic/cmake_utilities.html

tools/cmake_utilities/relinker.cmake

@@ -5,10 +5,15 @@ if(CONFIG_CU_RELINKER_ENABLE)
         message(STATUS "Relinker is enabled.")
         if(CONFIG_IDF_TARGET_ESP32C2)
             set(target "esp32c2")
+        elseif(CONFIG_IDF_TARGET_ESP32C3)
+            set(target "esp32c3")
         else()
             message(FATAL_ERROR "Other targets are not supported.")
         endif()
 
+        set(idf_version "${CONFIG_IDF_INIT_VERSION}")
+        string(REGEX MATCH "^([0-9]+\\.[0-9]+)" version_prefix "${idf_version}")
+
         if(CONFIG_CU_RELINKER_ENABLE_CUSTOMIZED_CONFIGURATION_FILES)
             idf_build_get_property(project_dir PROJECT_DIR)
             get_filename_component(cfg_file_path "${CONFIG_CU_RELINKER_CUSTOMIZED_CONFIGURATION_FILES_PATH}"
@@ -20,7 +25,15 @@ if(CONFIG_CU_RELINKER_ENABLE)
         else()
             set(cfg_file_path ${PROJECT_DIR}/relinker/${target})
             if(NOT EXISTS ${cfg_file_path})
-                set(cfg_file_path ${CMAKE_CURRENT_LIST_DIR}/scripts/relinker/examples/${target})
+                if(version_prefix STREQUAL "5.0" OR version_prefix STREQUAL "5.3")
+                    if(CONFIG_CU_RELINKER_LINK_SPECIFIC_FUNCTIONS_TO_IRAM)
+                        set(cfg_file_path ${CMAKE_CURRENT_LIST_DIR}/scripts/relinker/examples/flash_suspend/${target}/${version_prefix})
+                    else()
+                        set(cfg_file_path ${CMAKE_CURRENT_LIST_DIR}/scripts/relinker/examples/iram_strip/${target}/${version_prefix})
+                    endif()
+                else()
+                    message(FATAL_ERROR "There is no configuration file corresponding to esp-idf/v${version_prefix}, please make a request in github issue")
+                endif()
             endif()
         endif()
 
@@ -37,33 +50,39 @@ if(CONFIG_CU_RELINKER_ENABLE)
         set(link_dst_file "${link_path}/customer_sections.ld")
 
         set(relinker_opts --input     ${link_src_file}
-                        --output    ${link_dst_file}
-                        --library   ${library_file}
-                        --object    ${object_file}
-                        --function  ${function_file}
-                        --sdkconfig ${sdkconfig}
-                        --objdump   ${cmake_objdump})
+                          --output    ${link_dst_file}
+                          --library   ${library_file}
+                          --object    ${object_file}
+                          --function  ${function_file}
+                          --sdkconfig ${sdkconfig}
+                          --target    ${target}
+                          --version   ${version_prefix}
+                          --objdump   ${cmake_objdump})
 
         if(CONFIG_CU_RELINKER_ENABLE_PRINT_ERROR_INFO_WHEN_MISSING_FUNCTION)
-            list(APPEND relinker_opts --missing_function_info True)
+            list(APPEND relinker_opts --missing_function_info)
+        endif()
+
+        if(CONFIG_CU_RELINKER_LINK_SPECIFIC_FUNCTIONS_TO_IRAM)
+            list(APPEND relinker_opts --link_to_iram)
         endif()
 
         idf_build_get_property(link_depends __LINK_DEPENDS)
 
-        add_custom_command(OUTPUT ${link_dst_file}
-                            COMMAND ${python} -B ${relinker_script}
-                                    ${relinker_opts}
-                            COMMAND ${CMAKE_COMMAND} -E copy
-                                    ${link_dst_file}
-                                    ${link_src_file}
-                            COMMAND ${CMAKE_COMMAND} -E echo
-                                    /*relinker*/ >>
-                                    ${link_dst_file}
-                            DEPENDS "${link_depends}"
-                                    "${library_file}"
-                                    "${object_file}"
-                                    "${function_file}"
-                            VERBATIM)
+        add_custom_command(OUTPUT  ${link_dst_file}
+                           COMMAND ${python} -B ${relinker_script}
+                                   ${relinker_opts}
+                           COMMAND ${CMAKE_COMMAND} -E copy
+                                   ${link_dst_file}
+                                   ${link_src_file}
+                           COMMAND ${CMAKE_COMMAND} -E echo
+                                   /*relinker*/ >>
+                                   ${link_dst_file}
+                           DEPENDS "${link_depends}"
+                                   "${library_file}"
+                                   "${object_file}"
+                                   "${function_file}"
+                           VERBATIM)
 
         add_custom_target(customer_sections DEPENDS ${link_dst_file})
         add_dependencies(${project_elf} customer_sections)