diff --git a/Kconfig b/Kconfig index 3f31cef691..5e8f3ec82a 100644 --- a/Kconfig +++ b/Kconfig @@ -647,7 +647,7 @@ mainmenu "Espressif IoT Development Framework Configuration" choice COMPILER_ORPHAN_SECTIONS prompt "Orphan sections handling" - default COMPILER_ORPHAN_SECTIONS_WARNING + default COMPILER_ORPHAN_SECTIONS_ERROR depends on !IDF_TARGET_LINUX help If the linker finds orphan sections, it attempts to place orphan sections after sections of the same @@ -655,6 +655,11 @@ mainmenu "Espressif IoT Development Framework Configuration" That means that orphan sections could placed between sections defined in IDF linker scripts. This could lead to corruption of the binary image. Configure the linker action here. + config COMPILER_ORPHAN_SECTIONS_ERROR + bool "Fail if orphan sections found" + help + Fails the link step with an error if orphan sections are detected. + config COMPILER_ORPHAN_SECTIONS_WARNING bool "Place with warning" help diff --git a/docs/en/migration-guides/release-6.x/6.0/build-system.rst b/docs/en/migration-guides/release-6.x/6.0/build-system.rst new file mode 100644 index 0000000000..1b6f2dd699 --- /dev/null +++ b/docs/en/migration-guides/release-6.x/6.0/build-system.rst @@ -0,0 +1,26 @@ +Build System +============ + +:link_to_translation:`zh_CN:[中文]` + +Linker Orphan-Handling Behavior Changed to Error +------------------------------------------------ + +Starting with ESP-IDF v6.0, the build system no longer allows orphan sections in the final ELF file. The linker will now produce an error if any orphan sections are encountered during linking. + +.. note:: + + An *orphan section* is a section that is not explicitly placed into any output section by the linker script and is not discarded during linking. + +How to Resolve Orphan Section Errors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you encounter an orphan section error during linking, you can resolve it using one of the following methods: + +1. Remove the code or data that causes the orphan section, if it's unused or unnecessary. +2. Explicitly place the orphan section using a :ref:`linker fragment file `. +3. Suppress errors by setting :ref:`CONFIG_COMPILER_ORPHAN_SECTIONS` to ``warning`` or ``place``. + +.. warning:: + + The option 3 is **not recommended**, as orphan sections may indicate misconfigured memory mapping or unintentional behavior in your application. diff --git a/docs/en/migration-guides/release-6.x/6.0/index.rst b/docs/en/migration-guides/release-6.x/6.0/index.rst index 0c383b402b..d62ea27dca 100644 --- a/docs/en/migration-guides/release-6.x/6.0/index.rst +++ b/docs/en/migration-guides/release-6.x/6.0/index.rst @@ -6,6 +6,7 @@ Migration from 5.5 to 6.0 .. toctree:: :maxdepth: 1 + build-system peripherals security tools diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst new file mode 100644 index 0000000000..bbfec461eb --- /dev/null +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst @@ -0,0 +1,26 @@ +迁移构建系统至 ESP-IDF v6.0 +=================================== + +:link_to_translation:`en:[English]` + +链接器孤立段处理行为变更为报错 +------------------------------- + +从 ESP-IDF v6.0 开始,构建系统不再允许最终 ELF 文件中存在孤立段。如果链接过程中发现任何孤立段,链接器将报错。 + +.. note:: + + *孤立段* 是指未被链接脚本显式放置到任何输出段,且在链接过程中未被丢弃的段。 + +如何解决孤立段错误 +~~~~~~~~~~~~~~~~~~~~ + +如果在链接时遇到孤立段错误,可通过以下任一方式解决: + +1. 移除导致孤立段的代码或数据(若未使用或不必要)。 +2. 使用 :ref:`链接器片段文件 ` 显式放置孤立段。 +3. 通过设置 :ref:`CONFIG_COMPILER_ORPHAN_SECTIONS` 为 ``warning`` 或 ``place`` 来抑制错误。 + +.. warning:: + + 方案3 **不推荐使用**,因为孤立段可能意味着内存映射配置存在问题,或应用程序中存在非预期行为。 diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst index 4d848eb47a..7229b90a50 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst @@ -6,6 +6,7 @@ .. toctree:: :maxdepth: 1 - security + build-system peripherals + security tools diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake index 72504c061c..18d6955fa7 100644 --- a/tools/cmake/project.cmake +++ b/tools/cmake/project.cmake @@ -879,6 +879,9 @@ macro(project project_name) if(CONFIG_COMPILER_ORPHAN_SECTIONS_WARNING) # Print warnings if orphan sections are found target_link_options(${project_elf} PRIVATE "-Wl,--orphan-handling=warn") + elseif(CONFIG_COMPILER_ORPHAN_SECTIONS_ERROR) + # Throw error if orphan sections are found + target_link_options(${project_elf} PRIVATE "-Wl,--orphan-handling=error") endif() unset(idf_target) endif() diff --git a/tools/idf_py_actions/hints.yml b/tools/idf_py_actions/hints.yml index a0a75b1cb2..a6835c55b8 100644 --- a/tools/idf_py_actions/hints.yml +++ b/tools/idf_py_actions/hints.yml @@ -434,7 +434,7 @@ - re: "unplaced orphan section" - hint: "Avoid creating custom sections. Please refer to the 'Linker Script Generation' article in the IDF documentation to address this. Or set option CONFIG_COMPILER_ORPHAN_SECTIONS_PLACE (not recommended)." + hint: "An orphan section was detected during linking stage. For more information run 'idf.py docs -sp migration-guides/release-6.x/build-system.html#linker-orphan-handling-behavior-changed-to-error'." - re: "the current mclk multiple cannot perform integer division"