From 555c511d28cb3760a063c7a8071a6f66f1635941 Mon Sep 17 00:00:00 2001 From: Alexey Lapshin Date: Mon, 2 Jun 2025 11:20:06 +0700 Subject: [PATCH] feat(build): change orphan-handling behavior to error --- Kconfig | 7 ++++- .../release-6.x/6.0/build-system.rst | 26 +++++++++++++++++++ .../release-6.x/6.0/index.rst | 1 + .../release-6.x/6.0/build-system.rst | 26 +++++++++++++++++++ .../release-6.x/6.0/index.rst | 3 ++- tools/cmake/project.cmake | 3 +++ tools/idf_py_actions/hints.yml | 2 +- 7 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 docs/en/migration-guides/release-6.x/6.0/build-system.rst create mode 100644 docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst 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..3e912fb629 --- /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..8a17fd096e --- /dev/null +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst @@ -0,0 +1,26 @@ +Build System +============ + +:link_to_translation:`en:[English]` + +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/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 5d7bba52a9..c9aa7514f8 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"