Skip to content

Commit 4bc3b35

Browse files
authored
[lld/ELF] Add documentation on large sections (#82560)
Fixes #82438
1 parent 1d2eced commit 4bc3b35

5 files changed

+53
-0
lines changed
3.66 KB
Loading
3.66 KB
Loading

lld/docs/ELF/large_sections.rst

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
Large data sections
2+
===================
3+
4+
When linking very large binaries, lld may report relocation overflows like
5+
6+
::
7+
8+
relocation R_X86_64_PC32 out of range: 2158227201 is not in [-2147483648, 2147483647]
9+
10+
This happens when running into architectural limitations. For example, in x86-64
11+
PIC code, a reference to a static global variable is typically done with a
12+
``R_X86_64_PC32`` relocation, which is a 32-bit signed offset from the PC. That
13+
means if the global variable is laid out further than 2GB (2^31 bytes) from the
14+
instruction referencing it, we run into a relocation overflow.
15+
16+
lld normally lays out sections as follows:
17+
18+
.. image:: section_layout.png
19+
20+
The largest relocation pressure is usually from ``.text`` to the beginning of
21+
``.rodata`` or ``.text`` to the end of ``.bss``.
22+
23+
Some code models offer a tradeoff between relocation pressure and performance.
24+
For example, x86-64's medium code model splits global variables into small and
25+
large globals depending on if their size is over a certain threshold. Large
26+
globals are placed further away from text and we use 64-bit references to refer
27+
to them.
28+
29+
Large globals are placed in separate sections from small globals, and those
30+
sections have a "large" section flag, e.g. ``SHF_X86_64_LARGE`` for x86-64. The
31+
linker places large sections on the outer edges of the binary, making sure they
32+
do not affect affect the distance of small globals to text. The large versions
33+
of ``.rodata``, ``.bss``, and ``.data`` are ``.lrodata``, ``.lbss``, and
34+
``.ldata``, and they are laid out as follows:
35+
36+
.. image:: large_section_layout_pic.png
37+
38+
We try to keep the number of ``PT_LOAD`` segments to a minimum, so we place
39+
large sections next to the small sections with the same RWX permissions when
40+
possible.
41+
42+
``.lbss`` is right after ``.bss`` so that they are merged together and we
43+
minimize the number of segments with ``p_memsz > p_filesz``.
44+
45+
Note that the above applies to PIC code. For less common non-PIC code with
46+
absolute relocations instead of relative relocations, 32-bit relocations
47+
typically assume that symbols are in the lower 2GB of the address space. So for
48+
non-PIC code, large sections should be placed after all small sections to avoid
49+
``.lrodata`` pushing small symbols out of the lower 2GB of the address space.
50+
``-z lrodata-after-bss`` changes the layout to be:
51+
52+
.. image:: large_section_layout_nopic.png

lld/docs/ELF/section_layout.png

1.83 KB
Loading

lld/docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,7 @@ document soon.
166166
error_handling_script
167167
Partitions
168168
ReleaseNotes
169+
ELF/large_sections
169170
ELF/linker_script
170171
ELF/start-stop-gc
171172
ELF/warn_backrefs

0 commit comments

Comments
 (0)