15ffd83dbSDimitry AndricLinker Script implementation notes and policy 25ffd83dbSDimitry Andric============================================= 35ffd83dbSDimitry Andric 45ffd83dbSDimitry AndricLLD implements a large subset of the GNU ld linker script notation. The LLD 55ffd83dbSDimitry Andricimplementation policy is to implement linker script features as they are 65ffd83dbSDimitry Andricdocumented in the ld `manual <https://sourceware.org/binutils/docs/ld/Scripts.html>`_ 75ffd83dbSDimitry AndricWe consider it a bug if the lld implementation does not agree with the manual 85ffd83dbSDimitry Andricand it is not mentioned in the exceptions below. 95ffd83dbSDimitry Andric 105ffd83dbSDimitry AndricThe ld manual is not a complete specification, and is not sufficient to build 115ffd83dbSDimitry Andrican implementation. In particular some features are only defined by the 125ffd83dbSDimitry Andricimplementation and have changed over time. 135ffd83dbSDimitry Andric 145ffd83dbSDimitry AndricThe lld implementation policy for properties of linker scripts that are not 155ffd83dbSDimitry Andricdefined by the documentation is to follow the GNU ld implementation wherever 165ffd83dbSDimitry Andricpossible. We reserve the right to make different implementation choices where 175ffd83dbSDimitry Andricit is appropriate for LLD. Intentional deviations will be documented in this 185ffd83dbSDimitry Andricfile. 195ffd83dbSDimitry Andric 20*16d6b3b3SDimitry AndricSymbol assignment 21*16d6b3b3SDimitry Andric~~~~~~~~~~~~~~~~~ 22*16d6b3b3SDimitry Andric 23*16d6b3b3SDimitry AndricA symbol assignment looks like: 24*16d6b3b3SDimitry Andric 25*16d6b3b3SDimitry Andric:: 26*16d6b3b3SDimitry Andric 27*16d6b3b3SDimitry Andric symbol = expression; 28*16d6b3b3SDimitry Andric symbol += expression; 29*16d6b3b3SDimitry Andric 30*16d6b3b3SDimitry AndricThe first form defines ``symbol``. If ``symbol`` is already defined, it will be 31*16d6b3b3SDimitry Andricoverridden. The other form requires ``symbol`` to be already defined. 32*16d6b3b3SDimitry Andric 33*16d6b3b3SDimitry AndricFor a simple assignment like ``alias = aliasee;``, the ``st_type`` field is 34*16d6b3b3SDimitry Andriccopied from the original symbol. Any arithmetic operation (e.g. ``+ 0`` will 35*16d6b3b3SDimitry Andricreset ``st_type`` to ``STT_NOTYPE``. 36*16d6b3b3SDimitry Andric 37*16d6b3b3SDimitry AndricThe ``st_size`` field is set to 0. 38*16d6b3b3SDimitry Andric 395ffd83dbSDimitry AndricOutput section description 405ffd83dbSDimitry Andric~~~~~~~~~~~~~~~~~~~~~~~~~~ 415ffd83dbSDimitry Andric 425ffd83dbSDimitry AndricThe description of an output section looks like: 435ffd83dbSDimitry Andric 445ffd83dbSDimitry Andric:: 455ffd83dbSDimitry Andric 465ffd83dbSDimitry Andric section [address] [(type)] : [AT(lma)] [ALIGN(section_align)] [SUBALIGN](subsection_align)] { 475ffd83dbSDimitry Andric output-section-command 485ffd83dbSDimitry Andric ... 495ffd83dbSDimitry Andric } [>region] [AT>lma_region] [:phdr ...] [=fillexp] [,] 505ffd83dbSDimitry Andric 515ffd83dbSDimitry AndricOutput section address 525ffd83dbSDimitry Andric---------------------- 535ffd83dbSDimitry Andric 545ffd83dbSDimitry AndricWhen an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``. 555ffd83dbSDimitry Andric 565ffd83dbSDimitry AndricThe ELF specification says: 575ffd83dbSDimitry Andric 585ffd83dbSDimitry Andric> The value of sh_addr must be congruent to 0, modulo the value of sh_addralign. 595ffd83dbSDimitry Andric 605ffd83dbSDimitry AndricThe presence of ``address`` can cause the condition unsatisfied. LLD will warn. 615ffd83dbSDimitry AndricGNU ld from Binutils 2.35 onwards will reduce sh_addralign so that 625ffd83dbSDimitry Andricsh_addr=0 (modulo sh_addralign). 635ffd83dbSDimitry Andric 645ffd83dbSDimitry AndricOutput section alignment 655ffd83dbSDimitry Andric------------------------ 665ffd83dbSDimitry Andric 675ffd83dbSDimitry Andricsh_addralign of an *OutputSection* *S* is the maximum of 685ffd83dbSDimitry Andric``ALIGN(section_align)`` and the maximum alignment of the input sections in 695ffd83dbSDimitry Andric*S*. 705ffd83dbSDimitry Andric 715ffd83dbSDimitry AndricWhen an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``, 725ffd83dbSDimitry AndricGNU ld will set sh_addralign to ``ALIGN(section_align)``. 735ffd83dbSDimitry Andric 745ffd83dbSDimitry AndricOutput section LMA 755ffd83dbSDimitry Andric------------------ 765ffd83dbSDimitry Andric 775ffd83dbSDimitry AndricA load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``. 785ffd83dbSDimitry Andric 795ffd83dbSDimitry Andric- ``AT(lma)`` specifies the exact load address. If the linker script does not 805ffd83dbSDimitry Andric have a PHDRS command, then a new loadable segment will be generated. 815ffd83dbSDimitry Andric- ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region`` 825ffd83dbSDimitry Andric means the default region is used. Note, GNU ld propagates the previous LMA 835ffd83dbSDimitry Andric memory region when ``address`` is not specified. The LMA is set to the 845ffd83dbSDimitry Andric current location of the memory region aligned to the section alignment. 855ffd83dbSDimitry Andric If the linker script does not have a PHDRS command, then if 865ffd83dbSDimitry Andric ``lma_region`` is different from the ``lma_region`` for 875ffd83dbSDimitry Andric the previous OutputSection a new loadable segment will be generated. 885ffd83dbSDimitry Andric 895ffd83dbSDimitry AndricThe two keywords cannot be specified at the same time. 905ffd83dbSDimitry Andric 915ffd83dbSDimitry AndricIf neither ``AT(lma)`` nor ``AT>lma_region`` is specified: 925ffd83dbSDimitry Andric 935ffd83dbSDimitry Andric- If the previous section is also in the default LMA region, and the two 945ffd83dbSDimitry Andric section have the same memory regions, the difference between the LMA and the 955ffd83dbSDimitry Andric VMA is computed to be the same as the previous difference. 965ffd83dbSDimitry Andric- Otherwise, the LMA is set to the VMA. 97