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 ``-z noseparate-code``,
  65   ``-z separate-code``, or ``-z separate-loadable-segments``
  66 - Define ``__bss_start``, ``end``, ``_end``, ``etext``, ``_etext``, ``edata``, ``_edata``
  67 - Sort ``.ctors.*``/``.dtors.*``/``.init_array.*``/``.fini_array.*`` and PowerPC64 specific ``.toc``
  68 - Place input ``.text.*`` into output ``.text``, and handle certain variants
  69   (``.text.hot.``, ``.text.unknown.``, ``.text.unlikely.``, etc) in the precense of
  70   ``-z keep-text-section-prefix``.
  71
  72 Output section description
  73 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  74
  75 The description of an output section looks like:
  76
  77 ::
  78
  79   section [address] [(type)] : [AT(lma)] [ALIGN(section_align)] [SUBALIGN](subsection_align)] {
  80     output-section-command
  81     ...
  82   } [>region] [AT>lma_region] [:phdr ...] [=fillexp] [,]
  83
  84 Output section address
  85 ----------------------
  86
  87 When an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``.
  88
  89 The ELF specification says:
  90
  91 > The value of sh_addr must be congruent to 0, modulo the value of sh_addralign.
  92
  93 The presence of ``address`` can cause the condition unsatisfied. LLD will warn.
  94 GNU ld from Binutils 2.35 onwards will reduce sh_addralign so that
  95 sh_addr=0 (modulo sh_addralign).
  96
  97 Output section type
  98 -------------------
  99
 100 When an *OutputSection* *S* has ``(type)``, LLD will set ``sh_type`` or
 101 ``sh_flags`` of *S*. ``type`` is one of:
 102
 103 - ``NOLOAD``: set ``sh_type`` to ``SHT_NOBITS``.
 104 - ``COPY``, ``INFO``, ``OVERLAY``: clear the ``SHF_ALLOC`` bit in ``sh_flags``.
 105 - ``TYPE=<value>``: set ``sh_type`` to the specified value. ``<value>`` must be
 106   an integer or one of ``SHT_PROGBITS, SHT_NOTE, SHT_NOBITS, SHT_INIT_ARRAY,
 107   SHT_FINI_ARRAY, SHT_PREINIT_ARRAY``.
 108
 109 When ``sh_type`` is specified, it is an error if an input section in *S* has a
 110 different type.
 111
 112 Output section alignment
 113 ------------------------
 114
 115 sh_addralign of an *OutputSection* *S* is the maximum of
 116 ``ALIGN(section_align)`` and the maximum alignment of the input sections in
 117 *S*.
 118
 119 When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``,
 120 GNU ld will set sh_addralign to ``ALIGN(section_align)``.
 121
 122 Output section LMA
 123 ------------------
 124
 125 A load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``.
 126
 127 - ``AT(lma)`` specifies the exact load address. If the linker script does not
 128   have a PHDRS command, then a new loadable segment will be generated.
 129 - ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region``
 130   means the default region is used. Note, GNU ld propagates the previous LMA
 131   memory region when ``address`` is not specified. The LMA is set to the
 132   current location of the memory region aligned to the section alignment.
 133   If the linker script does not have a PHDRS command, then if
 134   ``lma_region`` is different from the ``lma_region`` for
 135   the previous OutputSection a new loadable segment will be generated.
 136
 137 The two keywords cannot be specified at the same time.
 138
 139 If neither ``AT(lma)`` nor ``AT>lma_region`` is specified:
 140
 141 - If the previous section is also in the default LMA region, and the two
 142   section have the same memory regions, the difference between the LMA and the
 143   VMA is computed to be the same as the previous difference.
 144 - Otherwise, the LMA is set to the VMA.
 145
 146 Overwrite sections
 147 ~~~~~~~~~~~~~~~~~~
 148
 149 An ``OVERWRITE_SECTIONS`` command looks like:
 150
 151 ::
 152
 153   OVERWRITE_SECTIONS {
 154     output-section-description
 155     output-section-description
 156     ...
 157   }
 158
 159 Unlike a ``SECTIONS`` command, ``OVERWRITE_SECTIONS``  does not specify a
 160 section order or suppress the built-in rules.
 161
 162 If a described output section description also appears in a ``SECTIONS``
 163 command, the ``OVERWRITE_SECTIONS`` command wins; otherwise, the output section
 164 will be added somewhere following the usual orphan section placement rules.
 165
 166 If a described output section description also appears in an ``INSERT
 167 [AFTER|BEFORE]`` command, the description will be provided by the
 168 description in the ``OVERWRITE_SECTIONS`` command while the insert command
 169 still applies (possibly after orphan section placement). It is recommended to
 170 leave the brace empty (i.e. ``section : {}``) for the insert command, because
 171 its description will be ignored anyway.