1Linker Script implementation notes and policy 2============================================= 3 4LLD implements a large subset of the GNU ld linker script notation. The LLD 5implementation policy is to implement linker script features as they are 6documented 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 manual 8and it is not mentioned in the exceptions below. 9 10The ld manual is not a complete specification, and is not sufficient to build 11an implementation. In particular some features are only defined by the 12implementation and have changed over time. 13 14The lld implementation policy for properties of linker scripts that are not 15defined by the documentation is to follow the GNU ld implementation wherever 16possible. We reserve the right to make different implementation choices where 17it is appropriate for LLD. Intentional deviations will be documented in this 18file. 19 20Symbol assignment 21~~~~~~~~~~~~~~~~~ 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 be 31overridden. The other form requires ``symbol`` to be already defined. 32 33For a simple assignment like ``alias = aliasee;``, the ``st_type`` field is 34copied from the original symbol. Any arithmetic operation (e.g. ``+ 0`` will 35reset ``st_type`` to ``STT_NOTYPE``. 36 37The ``st_size`` field is set to 0. 38 39SECTIONS command 40~~~~~~~~~~~~~~~~ 41 42A ``SECTIONS`` command looks like: 43 44:: 45 46 SECTIONS { 47 section-command 48 section-command 49 ... 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 some 56output sections which should be inserted after or before the specified anchor 57section. The insertion occurs after input sections have been mapped to output 58sections 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 similar 62to 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 72Output section description 73~~~~~~~~~~~~~~~~~~~~~~~~~~ 74 75The 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 84Output section address 85---------------------- 86 87When an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``. 88 89The ELF specification says: 90 91> The value of sh_addr must be congruent to 0, modulo the value of sh_addralign. 92 93The presence of ``address`` can cause the condition unsatisfied. LLD will warn. 94GNU ld from Binutils 2.35 onwards will reduce sh_addralign so that 95sh_addr=0 (modulo sh_addralign). 96 97Output section alignment 98------------------------ 99 100sh_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 104When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``, 105GNU ld will set sh_addralign to ``ALIGN(section_align)``. 106 107Output section LMA 108------------------ 109 110A 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 122The two keywords cannot be specified at the same time. 123 124If 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 131Overwrite sections 132~~~~~~~~~~~~~~~~~~ 133 134An ``OVERWRITE_SECTIONS`` command looks like: 135 136:: 137 138 OVERWRITE_SECTIONS { 139 output-section-description 140 output-section-description 141 ... 142 } 143 144Unlike a ``SECTIONS`` command, ``OVERWRITE_SECTIONS`` does not specify a 145section order or suppress the built-in rules. 146 147If a described output section description also appears in a ``SECTIONS`` 148command, the ``OVERWRITE_SECTIONS`` command wins; otherwise, the output section 149will be added somewhere following the usual orphan section placement rules. 150 151If a described output section description also appears in an ``INSERT 152[AFTER|BEFORE]`` command, the description will be provided by the 153description in the ``OVERWRITE_SECTIONS`` command while the insert command 154still applies (possibly after orphan section placement). It is recommended to 155leave the brace empty (i.e. ``section : {}``) for the insert command, because 156its description will be ignored anyway. 157