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 alignment
  98 ------------------------
  99
 100 sh_addralign of an *OutputSection* *S* is the maximum of
 101 ``ALIGN(section_align)`` and the maximum alignment of the input sections in
 102 *S*.
 103
 104 When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``,
 105 GNU ld will set sh_addralign to ``ALIGN(section_align)``.
 106
 107 Output section LMA
 108 ------------------
 109
 110 A load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``.
 111
 112 - ``AT(lma)`` specifies the exact load address. If the linker script does not
 113   have a PHDRS command, then a new loadable segment will be generated.
 114 - ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region``
 115   means the default region is used. Note, GNU ld propagates the previous LMA
 116   memory region when ``address`` is not specified. The LMA is set to the
 117   current location of the memory region aligned to the section alignment.
 118   If the linker script does not have a PHDRS command, then if
 119   ``lma_region`` is different from the ``lma_region`` for
 120   the previous OutputSection a new loadable segment will be generated.
 121
 122 The two keywords cannot be specified at the same time.
 123
 124 If neither ``AT(lma)`` nor ``AT>lma_region`` is specified:
 125
 126 - If the previous section is also in the default LMA region, and the two
 127   section have the same memory regions, the difference between the LMA and the
 128   VMA is computed to be the same as the previous difference.
 129 - Otherwise, the LMA is set to the VMA.
 130
 131 Overwrite sections
 132 ~~~~~~~~~~~~~~~~~~
 133
 134 An ``OVERWRITE_SECTIONS`` command looks like:
 135
 136 ::
 137
 138   OVERWRITE_SECTIONS {
 139     output-section-description
 140     output-section-description
 141     ...
 142   }
 143
 144 Unlike a ``SECTIONS`` command, ``OVERWRITE_SECTIONS``  does not specify a
 145 section order or suppress the built-in rules.
 146
 147 If a described output section description also appears in a ``SECTIONS``
 148 command, the ``OVERWRITE_SECTIONS`` command wins; otherwise, the output section
 149 will be added somewhere following the usual orphan section placement rules.
 150
 151 If a described output section description also appears in an ``INSERT
 152 [AFTER|BEFORE]`` command, the description will be provided by the
 153 description in the ``OVERWRITE_SECTIONS`` command while the insert command
 154 still applies (possibly after orphan section placement). It is recommended to
 155 leave the brace empty (i.e. ``section : {}``) for the insert command, because
 156 its description will be ignored anyway.