[LLD] Add CLASS syntax to SECTIONS (#95323)

This allows the input section matching algorithm to be separated from
output section descriptions. This allows a group of sections to be
assigned to multiple output sections, providing an explicit version of
--enable-non-contiguous-regions's spilling that doesn't require altering
global linker script matching behavior with a flag. It also makes the
linker script language more expressive even if spilling is not intended,
since input section matching can be done in a different order than
sections are placed in an output section.

The implementation reuses the backend mechanism provided by
--enable-non-contiguous-regions, so it has roughly similar semantics and
limitations. In particular, sections cannot be spilled into or out of
INSERT, OVERWRITE_SECTIONS, or /DISCARD/. The former two aren't
intrinsic, so it may be possible to relax those restrictions later.

2 files changed, 52 insertions, 7 deletions

diff --git a/lld/docs/ELF/linker_script.rst b/lld/docs/ELF/linker_script.rst
index 7a35534be096..c9cb47fc0553 100644
--- a/lld/docs/ELF/linker_script.rst
+++ b/lld/docs/ELF/linker_script.rst
@@ -198,13 +198,52 @@ the current location to a max-page-size boundary, ensuring that the next
 LLD will insert ``.relro_padding`` immediately before the symbol assignment
 using ``DATA_SEGMENT_RELRO_END``.
 
+Section Classes
+~~~~~~~~~~~~~~~
+
+The ``CLASS`` keyword inside a ``SECTIONS`` command defines classes of input
+sections:
+
+::
+
+  SECTIONS {
+    CLASS(class_name) {
+      input-section-description
+      input-section-description
+      ...
+    }
+  }
+
+Input section descriptions refer to a class using ``CLASS(class_name)``
+instead of the usual filename and section name patterns. For example:
+
+::
+
+  SECTIONS {
+    CLASS(c) { *(.rodata.earlier) }
+    .rodata { *(.rodata) CLASS(c) (*.rodata.later) }
+  }
+
+Input sections that are assigned to a class are not matched by later patterns,
+just as if they had been assigned to an earlier output section. If a class is
+referenced in multiple output sections, when a memory region would overflow,
+the linker spills input sections from a reference to later references rather
+than failing the link.
+
+Classes cannot reference other classes; an input section is assigned to at most
+one class.
+
+Sections cannot be specified to possibly spill into or out of
+``INSERT [AFTER|BEFORE]``, ``OVERWRITE_SECTIONS``, or ``/DISCARD/``.
+
 Non-contiguous regions
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The flag ``--enable-non-contiguous-regions`` allows input sections to spill to
-later matches rather than causing the link to fail by overflowing a memory
-region. Unlike GNU ld, ``/DISCARD/`` only matches previously-unmatched sections
-(i.e., the flag does not affect it). Also, if a section fails to fit at any of
-its matches, the link fails instead of discarding the section. Accordingly, the
-GNU flag ``--enable-non-contiguous-regions-warnings`` is not implemented, as it
-exists to warn about such occurrences.
+The flag ``--enable-non-contiguous-regions`` provides a version of the above
+spilling functionality that is more compatible with GNU LD. It allows input
+sections to spill to later pattern matches. (This globally changes the behavior
+of patterns.) Unlike GNU ld, ``/DISCARD/`` only matches previously-unmatched
+sections (i.e., the flag does not affect it). Also, if a section fails to fit
+at any of its matches, the link fails instead of discarding the section.
+Accordingly, the GNU flag ``--enable-non-contiguous-regions-warnings`` is not
+implemented, as it exists to warn about such occurrences.
diff --git a/lld/docs/ReleaseNotes.rst b/lld/docs/ReleaseNotes.rst
index e9d3c12b7654..6d09de10e719 100644
--- a/lld/docs/ReleaseNotes.rst
+++ b/lld/docs/ReleaseNotes.rst
@@ -29,6 +29,12 @@ ELF Improvements
 * ``-z nosectionheader`` has been implemented to omit the section header table.
   The operation is similar to ``llvm-objcopy --strip-sections``.
   (`#101286 <https://github.com/llvm/llvm-project/pull/101286>`_)
+* Section ``CLASS`` linker script syntax binds input sections to named classes,
+  which are referenced later one or more times. This provides access to the
+  automatic spilling mechanism of `--enable-non-contiguous-regions` without
+  globally changing the semantics of section matching. It also independently
+  increases the expressive power of linker scripts.
+  (`#95323 <https://github.com/llvm/llvm-project/pull/95323>`_)
 
 Breaking changes
 ----------------