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

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