lld/docs/ELF/large_sections.rst

   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 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