1*5ffd83dbSDimitry AndricLinker Script implementation notes and policy 2*5ffd83dbSDimitry Andric============================================= 3*5ffd83dbSDimitry Andric 4*5ffd83dbSDimitry AndricLLD implements a large subset of the GNU ld linker script notation. The LLD 5*5ffd83dbSDimitry Andricimplementation policy is to implement linker script features as they are 6*5ffd83dbSDimitry Andricdocumented in the ld `manual <https://sourceware.org/binutils/docs/ld/Scripts.html>`_ 7*5ffd83dbSDimitry AndricWe consider it a bug if the lld implementation does not agree with the manual 8*5ffd83dbSDimitry Andricand it is not mentioned in the exceptions below. 9*5ffd83dbSDimitry Andric 10*5ffd83dbSDimitry AndricThe ld manual is not a complete specification, and is not sufficient to build 11*5ffd83dbSDimitry Andrican implementation. In particular some features are only defined by the 12*5ffd83dbSDimitry Andricimplementation and have changed over time. 13*5ffd83dbSDimitry Andric 14*5ffd83dbSDimitry AndricThe lld implementation policy for properties of linker scripts that are not 15*5ffd83dbSDimitry Andricdefined by the documentation is to follow the GNU ld implementation wherever 16*5ffd83dbSDimitry Andricpossible. We reserve the right to make different implementation choices where 17*5ffd83dbSDimitry Andricit is appropriate for LLD. Intentional deviations will be documented in this 18*5ffd83dbSDimitry Andricfile. 19*5ffd83dbSDimitry Andric 20*5ffd83dbSDimitry AndricOutput section description 21*5ffd83dbSDimitry Andric~~~~~~~~~~~~~~~~~~~~~~~~~~ 22*5ffd83dbSDimitry Andric 23*5ffd83dbSDimitry AndricThe description of an output section looks like: 24*5ffd83dbSDimitry Andric 25*5ffd83dbSDimitry Andric:: 26*5ffd83dbSDimitry Andric 27*5ffd83dbSDimitry Andric section [address] [(type)] : [AT(lma)] [ALIGN(section_align)] [SUBALIGN](subsection_align)] { 28*5ffd83dbSDimitry Andric output-section-command 29*5ffd83dbSDimitry Andric ... 30*5ffd83dbSDimitry Andric } [>region] [AT>lma_region] [:phdr ...] [=fillexp] [,] 31*5ffd83dbSDimitry Andric 32*5ffd83dbSDimitry AndricOutput section address 33*5ffd83dbSDimitry Andric---------------------- 34*5ffd83dbSDimitry Andric 35*5ffd83dbSDimitry AndricWhen an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``. 36*5ffd83dbSDimitry Andric 37*5ffd83dbSDimitry AndricThe ELF specification says: 38*5ffd83dbSDimitry Andric 39*5ffd83dbSDimitry Andric> The value of sh_addr must be congruent to 0, modulo the value of sh_addralign. 40*5ffd83dbSDimitry Andric 41*5ffd83dbSDimitry AndricThe presence of ``address`` can cause the condition unsatisfied. LLD will warn. 42*5ffd83dbSDimitry AndricGNU ld from Binutils 2.35 onwards will reduce sh_addralign so that 43*5ffd83dbSDimitry Andricsh_addr=0 (modulo sh_addralign). 44*5ffd83dbSDimitry Andric 45*5ffd83dbSDimitry AndricOutput section alignment 46*5ffd83dbSDimitry Andric------------------------ 47*5ffd83dbSDimitry Andric 48*5ffd83dbSDimitry Andricsh_addralign of an *OutputSection* *S* is the maximum of 49*5ffd83dbSDimitry Andric``ALIGN(section_align)`` and the maximum alignment of the input sections in 50*5ffd83dbSDimitry Andric*S*. 51*5ffd83dbSDimitry Andric 52*5ffd83dbSDimitry AndricWhen an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``, 53*5ffd83dbSDimitry AndricGNU ld will set sh_addralign to ``ALIGN(section_align)``. 54*5ffd83dbSDimitry Andric 55*5ffd83dbSDimitry AndricOutput section LMA 56*5ffd83dbSDimitry Andric------------------ 57*5ffd83dbSDimitry Andric 58*5ffd83dbSDimitry AndricA load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``. 59*5ffd83dbSDimitry Andric 60*5ffd83dbSDimitry Andric- ``AT(lma)`` specifies the exact load address. If the linker script does not 61*5ffd83dbSDimitry Andric have a PHDRS command, then a new loadable segment will be generated. 62*5ffd83dbSDimitry Andric- ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region`` 63*5ffd83dbSDimitry Andric means the default region is used. Note, GNU ld propagates the previous LMA 64*5ffd83dbSDimitry Andric memory region when ``address`` is not specified. The LMA is set to the 65*5ffd83dbSDimitry Andric current location of the memory region aligned to the section alignment. 66*5ffd83dbSDimitry Andric If the linker script does not have a PHDRS command, then if 67*5ffd83dbSDimitry Andric ``lma_region`` is different from the ``lma_region`` for 68*5ffd83dbSDimitry Andric the previous OutputSection a new loadable segment will be generated. 69*5ffd83dbSDimitry Andric 70*5ffd83dbSDimitry AndricThe two keywords cannot be specified at the same time. 71*5ffd83dbSDimitry Andric 72*5ffd83dbSDimitry AndricIf neither ``AT(lma)`` nor ``AT>lma_region`` is specified: 73*5ffd83dbSDimitry Andric 74*5ffd83dbSDimitry Andric- If the previous section is also in the default LMA region, and the two 75*5ffd83dbSDimitry Andric section have the same memory regions, the difference between the LMA and the 76*5ffd83dbSDimitry Andric VMA is computed to be the same as the previous difference. 77*5ffd83dbSDimitry Andric- Otherwise, the LMA is set to the VMA. 78