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

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 @@
+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 <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/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"