250 lines · plain
1Linker Script implementation notes and policy2=============================================3 4LLD implements a large subset of the GNU ld linker script notation. The LLD5implementation policy is to implement linker script features as they are6documented in the ld `manual <https://sourceware.org/binutils/docs/ld/Scripts.html>`_7We consider it a bug if the lld implementation does not agree with the manual8and it is not mentioned in the exceptions below.9 10The ld manual is not a complete specification, and is not sufficient to build11an implementation. In particular some features are only defined by the12implementation and have changed over time.13 14The lld implementation policy for properties of linker scripts that are not15defined by the documentation is to follow the GNU ld implementation wherever16possible. We reserve the right to make different implementation choices where17it is appropriate for LLD. Intentional deviations will be documented in this18file.19 20Symbol assignment21~~~~~~~~~~~~~~~~~22 23A symbol assignment looks like:24 25::26 27 symbol = expression;28 symbol += expression;29 30The first form defines ``symbol``. If ``symbol`` is already defined, it will be31overridden. The other form requires ``symbol`` to be already defined.32 33For a simple assignment like ``alias = aliasee;``, the ``st_type`` field is34copied from the original symbol. Any arithmetic operation (e.g. ``+ 0`` will35reset ``st_type`` to ``STT_NOTYPE``.36 37The ``st_size`` field is set to 0.38 39SECTIONS command40~~~~~~~~~~~~~~~~41 42A ``SECTIONS`` command looks like:43 44::45 46 SECTIONS {47 section-command48 section-command49 ...50 } [INSERT [AFTER|BEFORE] anchor_section;]51 52Each section-command can be a symbol assignment, an output section description,53or an overlay description.54 55When the ``INSERT`` keyword is present, the ``SECTIONS`` command describes some56output sections which should be inserted after or before the specified anchor57section. The insertion occurs after input sections have been mapped to output58sections but before orphan sections have been processed.59 60In the case where no linker script has been provided or every ``SECTIONS``61command is followed by ``INSERT``, LLD applies built-in rules which are similar62to GNU ld's internal linker scripts.63 64- Align the first section in a ``PT_LOAD`` segment according to65 ``-z noseparate-code``, ``-z separate-code``, or66 ``-z separate-loadable-segments``67- Define ``__bss_start``, ``end``, ``_end``, ``etext``, ``_etext``, ``edata``,68 ``_edata``69- Sort ``.ctors.*``/``.dtors.*``/``.init_array.*``/``.fini_array.*`` and70 PowerPC64 specific ``.toc``71- Place input ``.text.*`` into output ``.text``, and handle certain variants72 (``.text.hot.``, ``.text.unknown.``, ``.text.unlikely.``, etc) in the73 presence of ``-z keep-text-section-prefix``.74 75Output section description76~~~~~~~~~~~~~~~~~~~~~~~~~~77 78The description of an output section looks like:79 80::81 82 section [address] [(type)] : [AT(lma)] [ALIGN(section_align)] [SUBALIGN](subsection_align)] {83 output-section-command84 ...85 } [>region] [AT>lma_region] [:phdr ...] [=fillexp] [,]86 87Output section address88----------------------89 90When an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``.91 92The ELF specification says:93 94> The value of sh_addr must be congruent to 0, modulo the value of sh_addralign.95 96The presence of ``address`` can cause the condition unsatisfied. LLD will warn.97GNU ld from Binutils 2.35 onwards will reduce sh_addralign so that98sh_addr=0 (modulo sh_addralign).99 100When an output section has no input section, GNU ld will eliminate it if it101only contains symbol assignments (e.g. ``.foo { symbol = 42; }``). LLD will102retain such sections unless all the symbol assignments are unreferenced103``PROVIDED``.104 105When an output section has no input section but advances the location counter,106GNU ld sets the ``SHF_WRITE`` flag. LLD sets the SHF_WRITE flag only if the107preceding output section with non-empty input sections also has the SHF_WRITE108flag.109 110Output section type111-------------------112 113When an *OutputSection* *S* has ``(type)``, LLD will set ``sh_type`` or114``sh_flags`` of *S*. ``type`` is one of:115 116- ``NOLOAD``: set ``sh_type`` to ``SHT_NOBITS``.117- ``COPY``, ``INFO``, ``OVERLAY``: clear the ``SHF_ALLOC`` bit in ``sh_flags``.118- ``TYPE=<value>``: set ``sh_type`` to the specified value. ``<value>`` must be119 an integer or one of ``SHT_PROGBITS, SHT_NOTE, SHT_NOBITS, SHT_INIT_ARRAY,120 SHT_FINI_ARRAY, SHT_PREINIT_ARRAY``.121 122When ``sh_type`` is specified, it is an error if an input section in *S* has a123different type.124 125Output section alignment126------------------------127 128sh_addralign of an *OutputSection* *S* is the maximum of129``ALIGN(section_align)`` and the maximum alignment of the input sections in130*S*.131 132When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``,133GNU ld will set sh_addralign to ``ALIGN(section_align)``.134 135Output section LMA136------------------137 138A load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``.139 140- ``AT(lma)`` specifies the exact load address. If the linker script does not141 have a PHDRS command, then a new loadable segment will be generated.142- ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region``143 means the default region is used. Note, GNU ld propagates the previous LMA144 memory region when ``address`` is not specified. The LMA is set to the145 current location of the memory region aligned to the section alignment.146 If the linker script does not have a PHDRS command, then if147 ``lma_region`` is different from the ``lma_region`` for148 the previous OutputSection a new loadable segment will be generated.149 150The two keywords cannot be specified at the same time.151 152If neither ``AT(lma)`` nor ``AT>lma_region`` is specified:153 154- If the previous section is also in the default LMA region, and the two155 section have the same memory regions, the difference between the LMA and the156 VMA is computed to be the same as the previous difference.157- Otherwise, the LMA is set to the VMA.158 159Overwrite sections160~~~~~~~~~~~~~~~~~~161 162An ``OVERWRITE_SECTIONS`` command looks like:163 164::165 166 OVERWRITE_SECTIONS {167 output-section-description168 output-section-description169 ...170 }171 172Unlike a ``SECTIONS`` command, ``OVERWRITE_SECTIONS`` does not specify a173section order or suppress the built-in rules.174 175If a described output section description also appears in a ``SECTIONS``176command, the ``OVERWRITE_SECTIONS`` command wins; otherwise, the output section177will be added somewhere following the usual orphan section placement rules.178 179If a described output section description also appears in an ``INSERT180[AFTER|BEFORE]`` command, the description will be provided by the181description in the ``OVERWRITE_SECTIONS`` command while the insert command182still applies (possibly after orphan section placement). It is recommended to183leave the brace empty (i.e. ``section : {}``) for the insert command, because184its description will be ignored anyway.185 186Built-in functions187~~~~~~~~~~~~~~~~~~188 189``DATA_SEGMENT_RELRO_END(offset, exp)`` defines the end of the ``PT_GNU_RELRO``190segment when ``-z relro`` (default) is in effect. Sections between191``DATA_SEGMENT_ALIGN`` and ``DATA_SEGMENT_RELRO_END`` are considered RELRO.192 193The typical use case is ``. = DATA_SEGMENT_RELRO_END(0, .);`` followed by194writable but non-RELRO sections. LLD ignores ``offset`` and ``exp`` and aligns195the current location to a max-page-size boundary, ensuring that the next196``PT_LOAD`` segment will not overlap with the ``PT_GNU_RELRO`` segment.197 198LLD will insert ``.relro_padding`` immediately before the symbol assignment199using ``DATA_SEGMENT_RELRO_END``.200 201Section Classes202~~~~~~~~~~~~~~~203 204The ``CLASS`` keyword inside a ``SECTIONS`` command defines classes of input205sections:206 207::208 209 SECTIONS {210 CLASS(class_name) {211 input-section-description212 input-section-description213 ...214 }215 }216 217Input section descriptions refer to a class using ``CLASS(class_name)``218instead of the usual filename and section name patterns. For example:219 220::221 222 SECTIONS {223 CLASS(c) { *(.rodata.earlier) }224 .rodata { *(.rodata) CLASS(c) (*.rodata.later) }225 }226 227Input sections that are assigned to a class are not matched by later patterns,228just as if they had been assigned to an earlier output section. If a class is229referenced in multiple output sections, when a memory region would overflow,230the linker spills input sections from a reference to later references rather231than failing the link.232 233Classes cannot reference other classes; an input section is assigned to at most234one class.235 236Sections cannot be specified to possibly spill into or out of237``INSERT [AFTER|BEFORE]``, ``OVERWRITE_SECTIONS``, or ``/DISCARD/``.238 239Non-contiguous regions240~~~~~~~~~~~~~~~~~~~~~~241 242The flag ``--enable-non-contiguous-regions`` provides a version of the above243spilling functionality that is more compatible with GNU LD. It allows input244sections to spill to later pattern matches. (This globally changes the behavior245of patterns.) Unlike GNU ld, ``/DISCARD/`` only matches previously-unmatched246sections (i.e., the flag does not affect it). Also, if a section fails to fit247at any of its matches, the link fails instead of discarding the section.248Accordingly, the GNU flag ``--enable-non-contiguous-regions-warnings`` is not249implemented, as it exists to warn about such occurrences.250