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
39SECTIONS command
40~~~~~~~~~~~~~~~~
41
42A ``SECTIONS`` command looks like:
43
44::
45
46  SECTIONS {
47    section-command
48    section-command
49    ...
50  } [INSERT [AFTER|BEFORE] anchor_section;]
51
52Each section-command can be a symbol assignment, an output section description,
53or an overlay description.
54
55When the ``INSERT`` keyword is present, the ``SECTIONS`` command describes some
56output sections which should be inserted after or before the specified anchor
57section. The insertion occurs after input sections have been mapped to output
58sections but before orphan sections have been processed.
59
60In the case where no linker script has been provided or every ``SECTIONS``
61command is followed by ``INSERT``, LLD applies built-in rules which are similar
62to GNU ld's internal linker scripts.
63
64- Align the first section in a ``PT_LOAD`` segment according to
65  ``-z noseparate-code``, ``-z separate-code``, or
66  ``-z separate-loadable-segments``
67- Define ``__bss_start``, ``end``, ``_end``, ``etext``, ``_etext``, ``edata``,
68  ``_edata``
69- Sort ``.ctors.*``/``.dtors.*``/``.init_array.*``/``.fini_array.*`` and
70  PowerPC64 specific ``.toc``
71- Place input ``.text.*`` into output ``.text``, and handle certain variants
72  (``.text.hot.``, ``.text.unknown.``, ``.text.unlikely.``, etc) in the
73  presence of ``-z keep-text-section-prefix``.
74
75Output section description
76~~~~~~~~~~~~~~~~~~~~~~~~~~
77
78The description of an output section looks like:
79
80::
81
82  section [address] [(type)] : [AT(lma)] [ALIGN(section_align)] [SUBALIGN](subsection_align)] {
83    output-section-command
84    ...
85  } [>region] [AT>lma_region] [:phdr ...] [=fillexp] [,]
86
87Output section address
88----------------------
89
90When an *OutputSection* *S* has ``address``, LLD will set sh_addr to ``address``.
91
92The ELF specification says:
93
94> The value of sh_addr must be congruent to 0, modulo the value of sh_addralign.
95
96The presence of ``address`` can cause the condition unsatisfied. LLD will warn.
97GNU ld from Binutils 2.35 onwards will reduce sh_addralign so that
98sh_addr=0 (modulo sh_addralign).
99
100When an output section has no input section, GNU ld will eliminate it if it
101only contains symbol assignments (e.g. ``.foo { symbol = 42; }``). LLD will
102retain such sections unless all the symbol assignments are unreferenced
103``PROVIDED``.
104
105When an output section has no input section but advances the location counter,
106GNU ld sets the ``SHF_WRITE`` flag. LLD sets the SHF_WRITE flag only if the
107preceding output section with non-empty input sections also has the SHF_WRITE
108flag.
109
110Output section type
111-------------------
112
113When an *OutputSection* *S* has ``(type)``, LLD will set ``sh_type`` or
114``sh_flags`` of *S*. ``type`` is one of:
115
116- ``NOLOAD``: set ``sh_type`` to ``SHT_NOBITS``.
117- ``COPY``, ``INFO``, ``OVERLAY``: clear the ``SHF_ALLOC`` bit in ``sh_flags``.
118- ``TYPE=<value>``: set ``sh_type`` to the specified value. ``<value>`` must be
119  an integer or one of ``SHT_PROGBITS, SHT_NOTE, SHT_NOBITS, SHT_INIT_ARRAY,
120  SHT_FINI_ARRAY, SHT_PREINIT_ARRAY``.
121
122When ``sh_type`` is specified, it is an error if an input section in *S* has a
123different type.
124
125Output section alignment
126------------------------
127
128sh_addralign of an *OutputSection* *S* is the maximum of
129``ALIGN(section_align)`` and the maximum alignment of the input sections in
130*S*.
131
132When an *OutputSection* *S* has both ``address`` and ``ALIGN(section_align)``,
133GNU ld will set sh_addralign to ``ALIGN(section_align)``.
134
135Output section LMA
136------------------
137
138A load address (LMA) can be specified by ``AT(lma)`` or ``AT>lma_region``.
139
140- ``AT(lma)`` specifies the exact load address. If the linker script does not
141  have a PHDRS command, then a new loadable segment will be generated.
142- ``AT>lma_region`` specifies the LMA region. The lack of ``AT>lma_region``
143  means the default region is used. Note, GNU ld propagates the previous LMA
144  memory region when ``address`` is not specified. The LMA is set to the
145  current location of the memory region aligned to the section alignment.
146  If the linker script does not have a PHDRS command, then if
147  ``lma_region`` is different from the ``lma_region`` for
148  the previous OutputSection a new loadable segment will be generated.
149
150The two keywords cannot be specified at the same time.
151
152If neither ``AT(lma)`` nor ``AT>lma_region`` is specified:
153
154- If the previous section is also in the default LMA region, and the two
155  section have the same memory regions, the difference between the LMA and the
156  VMA is computed to be the same as the previous difference.
157- Otherwise, the LMA is set to the VMA.
158
159Overwrite sections
160~~~~~~~~~~~~~~~~~~
161
162An ``OVERWRITE_SECTIONS`` command looks like:
163
164::
165
166  OVERWRITE_SECTIONS {
167    output-section-description
168    output-section-description
169    ...
170  }
171
172Unlike a ``SECTIONS`` command, ``OVERWRITE_SECTIONS``  does not specify a
173section order or suppress the built-in rules.
174
175If a described output section description also appears in a ``SECTIONS``
176command, the ``OVERWRITE_SECTIONS`` command wins; otherwise, the output section
177will be added somewhere following the usual orphan section placement rules.
178
179If a described output section description also appears in an ``INSERT
180[AFTER|BEFORE]`` command, the description will be provided by the
181description in the ``OVERWRITE_SECTIONS`` command while the insert command
182still applies (possibly after orphan section placement). It is recommended to
183leave the brace empty (i.e. ``section : {}``) for the insert command, because
184its description will be ignored anyway.
185
186Built-in functions
187~~~~~~~~~~~~~~~~~~
188
189``DATA_SEGMENT_RELRO_END(offset, exp)`` defines the end of the ``PT_GNU_RELRO``
190segment when ``-z relro`` (default) is in effect. Sections between
191``DATA_SEGMENT_ALIGN`` and ``DATA_SEGMENT_RELRO_END`` are considered RELRO.
192
193The typical use case is ``. = DATA_SEGMENT_RELRO_END(0, .);`` followed by
194writable but non-RELRO sections. LLD ignores ``offset`` and ``exp`` and aligns
195the current location to a max-page-size boundary, ensuring that the next
196``PT_LOAD`` segment will not overlap with the ``PT_GNU_RELRO`` segment.
197
198LLD will insert ``.relro_padding`` immediately before the symbol assignment
199using ``DATA_SEGMENT_RELRO_END``.
200