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