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

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

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"