lld/docs/ELF/linker_script.rst

   1 Linker Script implementation notes and policy
   2 =============================================
   3
   4 LLD implements a large subset of the GNU ld linker script notation. The LLD
   5 implementation policy is to implement linker script features as they are
   6 documented in the ld `manual <https://sourceware.org/binutils/docs/ld/Scripts.html>`_
   7 We consider it a bug if the lld implementation does not agree with the manual
   8 and it is not mentioned in the exceptions below.
   9
  10 The ld manual is not a complete specification, and is not sufficient to build
  11 an implementation. In particular some features are only defined by the
  12 implementation and have changed over time.
  13
  14 The lld implementation policy for properties of linker scripts that are not
  15 defined by the documentation is to follow the GNU ld implementation wherever
  16 possible. We reserve the right to make different implementation choices where
  17 it is appropriate for LLD. Intentional deviations will be documented in this
  18 file.
  19
  20 Symbol assignment
  21 ~~~~~~~~~~~~~~~~~
  22
  23 A symbol assignment looks like:
  24
  25 ::
  26
  27   symbol = expression;
  28   symbol += expression;
  29
  30 The first form defines ``symbol``. If ``symbol`` is already defined, it will be
  31 overridden. The other form requires ``symbol`` to be already defined.
  32
  33 For a simple assignment like ``alias = aliasee;``, the ``st_type`` field is
  34 copied from the original symbol. Any arithmetic operation (e.g. ``+ 0`` will
  35 reset ``st_type`` to ``STT_NOTYPE``.
  36
  37 The ``st_size`` field is set to 0.
  38
  39 SECTIONS command
  40 ~~~~~~~~~~~~~~~~
  41
  42 A ``SECTIONS`` command looks like:
  43
  44 ::
  45
  46   SECTIONS {
  47     section-command
  48     section-command
  49     ...
  50   } [INSERT [AFTER|BEFORE] anchor_section;]
  51
  52 Each section-command can be a symbol assignment, an output section description,
  53 or an overlay description.
  54
  55 When the ``INSERT`` keyword is present, the ``SECTIONS`` command describes some
  56 output sections which should be inserted after or before the specified anchor
  57 section. The insertion occurs after input sections have been mapped to output
  58 sections but before orphan sections have been processed.
  59
  60 In the case where no linker script has been provided or every ``SECTIONS``
  61 command is followed by ``INSERT``, LLD applies built-in rules which are similar
  62 to GNU ld's internal linker scripts.
  63
  64 - Align the first section in a ``PT_LOAD`` segment according to
  65   ``-z noseparate-code``, ``-z separate-code``, or
  66   ``-z separate-loadable-segments``
  67 - Define ``__bss_start``, ``end``, ``_end``, ``etext``, ``_etext``, ``edata``,
  68   ``_edata``
  69 - Sort ``.ctors.*``/``.dtors.*``/``.init_array.*``/``.fini_array.*`` and
  70   PowerPC64 specific ``.toc``
  71 - Place input ``.text.*`` into output ``.text``, and handle certain variants
  72   (``.text.hot.``, ``.text.unknown.``, ``.text.unlikely.``, etc) in the
  73   presence of ``-z keep-text-section-prefix``.
  74
  75 Output section description
  76 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  77
  78 The 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-command
  84     ...
  85   } [>region] [AT>lma_region] [:phdr ...] [=fillexp] [,]
  86
  87 Output section address
  88 ----------------------
  89
  90 When an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``.
  91
  92 The ELF specification says:
  93
  94 > The value of sh_addr must be congruent to 0, modulo the value of sh_addralign.
  95
  96 The presence of ``address`` can cause the condition unsatisfied. LLD will warn.
  97 GNU ld from Binutils 2.35 onwards will reduce sh_addralign so that
  98 sh_addr=0 (modulo sh_addralign).
  99
 100 Output section type
 101 -------------------
 102
 103 When an *OutputSection* *S* has ``(type)``, LLD will set ``sh_type`` or
 104 ``sh_flags`` of *S*. ``type`` is one of:
 105
 106 - ``NOLOAD``: set ``sh_type`` to ``SHT_NOBITS``.
 107 - ``COPY``, ``INFO``, ``OVERLAY``: clear the ``SHF_ALLOC`` bit in ``sh_flags``.
 108 - ``TYPE=<value>``: set ``sh_type`` to the specified value. ``<value>`` must be
 109   an integer or one of ``SHT_PROGBITS, SHT_NOTE, SHT_NOBITS, SHT_INIT_ARRAY,
 110   SHT_FINI_ARRAY, SHT_PREINIT_ARRAY``.
 111
 112 When ``sh_type`` is specified, it is an error if an input section in *S* has a
 113 different type.
 114
 115 Output section alignment
 116 ------------------------
 117
 118 sh_addralign of an *OutputSection* *S* is the maximum of
 119 ``ALIGN(section_align)`` and the maximum alignment of the input sections in
 120 *S*.
 121
 122 When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``,
 123 GNU ld will set sh_addralign to ``ALIGN(section_align)``.
 124
 125 Output section LMA
 126 ------------------
 127
 128 A load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``.
 129
 130 - ``AT(lma)`` specifies the exact load address. If the linker script does not
 131   have a PHDRS command, then a new loadable segment will be generated.
 132 - ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region``
 133   means the default region is used. Note, GNU ld propagates the previous LMA
 134   memory region when ``address`` is not specified. The LMA is set to the
 135   current location of the memory region aligned to the section alignment.
 136   If the linker script does not have a PHDRS command, then if
 137   ``lma_region`` is different from the ``lma_region`` for
 138   the previous OutputSection a new loadable segment will be generated.
 139
 140 The two keywords cannot be specified at the same time.
 141
 142 If neither ``AT(lma)`` nor ``AT>lma_region`` is specified:
 143
 144 - If the previous section is also in the default LMA region, and the two
 145   section have the same memory regions, the difference between the LMA and the
 146   VMA is computed to be the same as the previous difference.
 147 - Otherwise, the LMA is set to the VMA.
 148
 149 Overwrite sections
 150 ~~~~~~~~~~~~~~~~~~
 151
 152 An ``OVERWRITE_SECTIONS`` command looks like:
 153
 154 ::
 155
 156   OVERWRITE_SECTIONS {
 157     output-section-description
 158     output-section-description
 159     ...
 160   }
 161
 162 Unlike a ``SECTIONS`` command, ``OVERWRITE_SECTIONS``  does not specify a
 163 section order or suppress the built-in rules.
 164
 165 If a described output section description also appears in a ``SECTIONS``
 166 command, the ``OVERWRITE_SECTIONS`` command wins; otherwise, the output section
 167 will be added somewhere following the usual orphan section placement rules.
 168
 169 If a described output section description also appears in an ``INSERT
 170 [AFTER|BEFORE]`` command, the description will be provided by the
 171 description in the ``OVERWRITE_SECTIONS`` command while the insert command
 172 still applies (possibly after orphan section placement). It is recommended to
 173 leave the brace empty (i.e. ``section : {}``) for the insert command, because
 174 its description will be ignored anyway.
 175
 176 Built-in functions
 177 ~~~~~~~~~~~~~~~~~~
 178
 179 ``DATA_SEGMENT_RELRO_END(offset, exp)`` defines the end of the ``PT_GNU_RELRO``
 180 segment when ``-z relro`` (default) is in effect. Sections between
 181 ``DATA_SEGMENT_ALIGN`` and ``DATA_SEGMENT_RELRO_END`` are considered RELRO.
 182
 183 The typical use case is ``. = DATA_SEGMENT_RELRO_END(0, .);`` followed by
 184 writable but non-RELRO sections. LLD ignores ``offset`` and ``exp`` and aligns
 185 the current location to a max-page-size boundary, ensuring that the next
 186 ``PT_LOAD`` segment will not overlap with the ``PT_GNU_RELRO`` segment.
 187
 188 LLD will insert ``.relro_padding`` immediately before the symbol assignment
 189 using ``DATA_SEGMENT_RELRO_END``.