contrib/llvm-project/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 Output section description
  40 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  41
  42 The description of an output section looks like:
  43
  44 ::
  45
  46   section [address] [(type)] : [AT(lma)] [ALIGN(section_align)] [SUBALIGN](subsection_align)] {
  47     output-section-command
  48     ...
  49   } [>region] [AT>lma_region] [:phdr ...] [=fillexp] [,]
  50
  51 Output section address
  52 ----------------------
  53
  54 When an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``.
  55
  56 The ELF specification says:
  57
  58 > The value of sh_addr must be congruent to 0, modulo the value of sh_addralign.
  59
  60 The presence of ``address`` can cause the condition unsatisfied. LLD will warn.
  61 GNU ld from Binutils 2.35 onwards will reduce sh_addralign so that
  62 sh_addr=0 (modulo sh_addralign).
  63
  64 Output section alignment
  65 ------------------------
  66
  67 sh_addralign of an *OutputSection* *S* is the maximum of
  68 ``ALIGN(section_align)`` and the maximum alignment of the input sections in
  69 *S*.
  70
  71 When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``,
  72 GNU ld will set sh_addralign to ``ALIGN(section_align)``.
  73
  74 Output section LMA
  75 ------------------
  76
  77 A load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``.
  78
  79 - ``AT(lma)`` specifies the exact load address. If the linker script does not
  80   have a PHDRS command, then a new loadable segment will be generated.
  81 - ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region``
  82   means the default region is used. Note, GNU ld propagates the previous LMA
  83   memory region when ``address`` is not specified. The LMA is set to the
  84   current location of the memory region aligned to the section alignment.
  85   If the linker script does not have a PHDRS command, then if
  86   ``lma_region`` is different from the ``lma_region`` for
  87   the previous OutputSection a new loadable segment will be generated.
  88
  89 The two keywords cannot be specified at the same time.
  90
  91 If neither ``AT(lma)`` nor ``AT>lma_region`` is specified:
  92
  93 - If the previous section is also in the default LMA region, and the two
  94   section have the same memory regions, the difference between the LMA and the
  95   VMA is computed to be the same as the previous difference.
  96 - Otherwise, the LMA is set to the VMA.