Merge branch 'feature/change-orphan-handling-behavior-to-error' into 'master'

feat(build): change orphan-handling behavior to error

Closes IDF-9792 and DOC-11408

See merge request espressif/esp-idf!39566

Author: Lapshin

Kconfig

@@ -647,14 +647,19 @@ 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
                 attribute such as code vs data, loadable vs non-loadable, etc.
                 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

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 <ldgen-linker-fragment-files>`.
+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.

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

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:`链接器片段文件 <ldgen-linker-fragment-files>` 显式放置孤立段。
+3. 通过设置 :ref:`CONFIG_COMPILER_ORPHAN_SECTIONS` 为 ``warning`` 或 ``place`` 来抑制错误。
+
+.. warning::
+
+   方案3 **不推荐使用**，因为孤立段可能意味着内存映射配置存在问题，或应用程序中存在非预期行为。

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

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()

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"