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