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 39Output section description 40~~~~~~~~~~~~~~~~~~~~~~~~~~ 41 42The 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 51Output section address 52---------------------- 53 54When an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``. 55 56The ELF specification says: 57 58> The value of sh_addr must be congruent to 0, modulo the value of sh_addralign. 59 60The presence of ``address`` can cause the condition unsatisfied. LLD will warn. 61GNU ld from Binutils 2.35 onwards will reduce sh_addralign so that 62sh_addr=0 (modulo sh_addralign). 63 64Output section alignment 65------------------------ 66 67sh_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 71When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``, 72GNU ld will set sh_addralign to ``ALIGN(section_align)``. 73 74Output section LMA 75------------------ 76 77A 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 89The two keywords cannot be specified at the same time. 90 91If 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. 97