[ELF] Add OVERWRITE_SECTIONS command
This implements https://sourceware.org/bugzilla/show_bug.cgi?id=26404
An `OVERWRITE_SECTIONS` command is a `SECTIONS` variant which contains several
output section descriptions. The output sections do not have specify an order.
Similar to `INSERT [BEFORE|AFTER]`, `LinkerScript::hasSectionsCommand` is not
set, so the built-in rules (see `docs/ELF/linker_script.rst`) still apply.
`OVERWRITE_SECTIONS` can be more convenient than `INSERT` because it does not
need an anchor section.
The initial syntax is intentionally narrow to facilitate backward compatible
extensions in the future. Symbol assignments cannot be used.
This feature is versatile. To list a few usage:
* Use `section : { KEEP(...) }` to retain input sections under GC
* Define encapsulation symbols (start/end) for an output section
* Use `section : ALIGN(...) : { ... }` to overalign an output section (similar to ld64 `-sectalign`)
When an output section is specified by both `OVERWRITE_SECTIONS` and
`INSERT`, `INSERT` is processed after overwrite sections. To make this work,
this patch changes `InsertCommand` to use name based matching instead of pointer
based matching. (This may cause a difference when `INSERT` moves one output
section more than once. Such duplicate commands should not be used in practice
(seems that in GNU ld the output sections may just disappear).)
A linker script can be used without -T/--script. The traditional `SECTIONS`
commands are concatenated, so a wrong rule can be more noticeable from the
section order. This feature if misused can be less noticeable, just like
`INSERT`.
Differential Revision: https://reviews.llvm.org/D103303
diff --git a/lld/docs/ELF/linker_script.rst b/lld/docs/ELF/linker_script.rst
index debddbf..af29996 100644
--- a/lld/docs/ELF/linker_script.rst
+++ b/lld/docs/ELF/linker_script.rst
@@ -36,6 +36,39 @@
The ``st_size`` field is set to 0.
+SECTIONS command
+~~~~~~~~~~~~~~~~
+
+A ``SECTIONS`` command looks like:
+
+::
+
+ SECTIONS {
+ section-command
+ section-command
+ ...
+ } [INSERT [AFTER|BEFORE] anchor_section;]
+
+Each section-command can be a symbol assignment, an output section description,
+or an overlay description.
+
+When the ``INSERT`` keyword is present, the ``SECTIONS`` command describes some
+output sections which should be inserted after or before the specified anchor
+section. The insertion occurs after input sections have been mapped to output
+sections but before orphan sections have been processed.
+
+In the case where no linker script has been provided or every ``SECTIONS``
+command is followed by ``INSERT``, LLD applies built-in rules which are similar
+to GNU ld's internal linker scripts.
+
+- Align the first section in a ``PT_LOAD`` segment according to ``-z noseparate-code``,
+ ``-z separate-code``, or ``-z separate-loadable-segments``
+- Define ``__bss_start``, ``end``, ``_end``, ``etext``, ``_etext``, ``edata``, ``_edata``
+- Sort ``.ctors.*``/``.dtors.*``/``.init_array.*``/``.fini_array.*`` and PowerPC64 specific ``.toc``
+- Place input ``.text.*`` into output ``.text``, and handle certain variants
+ (``.text.hot.``, ``.text.unknown.``, ``.text.unlikely.``, etc) in the precense of
+ ``-z keep-text-section-prefix``.
+
Output section description
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,3 +127,30 @@
section have the same memory regions, the difference between the LMA and the
VMA is computed to be the same as the previous difference.
- Otherwise, the LMA is set to the VMA.
+
+Overwrite sections
+~~~~~~~~~~~~~~~~~~
+
+An ``OVERWRITE_SECTIONS`` command looks like:
+
+::
+
+ OVERWRITE_SECTIONS {
+ output-section-description
+ output-section-description
+ ...
+ }
+
+Unlike a ``SECTIONS`` command, ``OVERWRITE_SECTIONS`` does not specify a
+section order or suppress the built-in rules.
+
+If a described output section description also appears in a ``SECTIONS``
+command, the ``OVERWRITE_SECTIONS`` command wins; otherwise, the output section
+will be added somewhere following the usual orphan section placement rules.
+
+If a described output section description also appears in an ``INSERT
+[AFTER|BEFORE]`` command, the description will be provided by the
+description in the ``OVERWRITE_SECTIONS`` command while the insert command
+still applies (possibly after orphan section placement). It is recommended to
+leave the brace empty (i.e. ``section : {}``) for the insert command, because
+its description will be ignored anyway.
