1===========================
2lld |release| Release Notes
3===========================
4
5.. contents::
6    :local:
7
8.. only:: PreRelease
9
10  .. warning::
11     These are in-progress notes for the upcoming LLVM |release| release.
12     Release notes for previous releases can be found on
13     `the Download Page <https://releases.llvm.org/download.html>`_.
14
15Introduction
16============
17
18This document contains the release notes for the lld linker, release |release|.
19Here we describe the status of lld, including major improvements
20from the previous release. All lld releases may be downloaded
21from the `LLVM releases web site <https://llvm.org/releases/>`_.
22
23Non-comprehensive list of changes in this release
24=================================================
25
26ELF Improvements
27----------------
28
29* When ``--threads=`` is not specified, the number of concurrency is now capped to 16.
30  A large ``--thread=`` can harm performance, especially with some system
31  malloc implementations like glibc's.
32  (`D147493 <https://reviews.llvm.org/D147493>`_)
33* ``--remap-inputs=`` and ``--remap-inputs-file=`` are added to remap input files.
34  (`D148859 <https://reviews.llvm.org/D148859>`_)
35* ``--lto=`` is now available to support ``clang -funified-lto``
36  (`D123805 <https://reviews.llvm.org/D123805>`_)
37* ``--lto-CGO[0-3]`` is now available to control ``CodeGenOpt::Level`` independent of the LTO optimization level.
38  (`D141970 <https://reviews.llvm.org/D141970>`_)
39* ``--check-dynamic-relocations=`` is now correct 32-bit targets when the addend is larger than 0x80000000.
40  (`D149347 <https://reviews.llvm.org/D149347>`_)
41* ``--print-memory-usage`` has been implemented for memory regions.
42  (`D150644 <https://reviews.llvm.org/D150644>`_)
43* ``SHF_MERGE``, ``--icf=``, and ``--build-id=fast`` have switched to 64-bit xxh3.
44  (`D154813 <https://reviews.llvm.org/D154813>`_)
45* Quoted output section names can now be used in linker scripts.
46  (`#60496 <https://github.com/llvm/llvm-project/issues/60496>`_)
47* ``MEMORY`` can now be used without a ``SECTIONS`` command.
48  (`D145132 <https://reviews.llvm.org/D145132>`_)
49* ``REVERSE`` can now be used in input section descriptions to reverse the order of input sections.
50  (`D145381 <https://reviews.llvm.org/D145381>`_)
51* Program header assignment can now be used within ``OVERLAY``. This functionality was accidentally lost in 2020.
52  (`D150445 <https://reviews.llvm.org/D150445>`_)
53* Operators ``^`` and ``^=`` can now be used in linker scripts.
54* LoongArch is now supported.
55* ``DT_AARCH64_MEMTAG_*`` dynamic tags are now supported.
56  (`D143769 <https://reviews.llvm.org/D143769>`_)
57* AArch32 port now supports BE-8 and BE-32 modes for big-endian.
58  (`D140201 <https://reviews.llvm.org/D140201>`_)
59  (`D140202 <https://reviews.llvm.org/D140202>`_)
60  (`D150870 <https://reviews.llvm.org/D150870>`_)
61* ``R_ARM_THM_ALU_ABS_G*`` relocations are now supported.
62  (`D153407 <https://reviews.llvm.org/D153407>`_)
63* ``.ARM.exidx`` sections may start at non-zero output section offset.
64  (`D148033 <https://reviews.llvm.org/D148033>`_)
65* Arm Cortex-M Security Extensions is now implemented.
66  (`D139092 <https://reviews.llvm.org/D139092>`_)
67* BTI landing pads are now added to PLT entries accessed by range extension thunks or relative vtables.
68  (`D148704 <https://reviews.llvm.org/D148704>`_)
69  (`D153264 <https://reviews.llvm.org/D153264>`_)
70* AArch64 short range thunk has been implemented to mitigate the performance loss of a long range thunk.
71  (`D148701 <https://reviews.llvm.org/D148701>`_)
72* ``R_AVR_8_LO8/R_AVR_8_HI8/R_AVR_8_HLO8/R_AVR_LO8_LDI_GS/R_AVR_HI8_LDI_GS`` have been implemented.
73  (`D147100 <https://reviews.llvm.org/D147100>`_)
74  (`D147364 <https://reviews.llvm.org/D147364>`_)
75* ``--no-power10-stubs`` now works for PowerPC64.
76* ``DT_PPC64_OPT`` is now supported;
77  (`D150631 <https://reviews.llvm.org/D150631>`_)
78* ``PT_RISCV_ATTRIBUTES`` is added to include the SHT_RISCV_ATTRIBUTES section.
79  (`D152065 <https://reviews.llvm.org/D152065>`_)
80* ``R_RISCV_PLT32`` is added to support C++ relative vtables.
81  (`D143115 <https://reviews.llvm.org/D143115>`_)
82* RISC-V global pointer relaxation has been implemented. Specify ``--relax-gp`` to enable the linker relaxation.
83  (`D143673 <https://reviews.llvm.org/D143673>`_)
84* The symbol value of ``foo`` is correctly handled when ``--wrap=foo`` and RISC-V linker relaxation are used.
85  (`D151768 <https://reviews.llvm.org/D151768>`_)
86* x86-64 large data sections are now placed away from code sections to alleviate relocation overflow pressure.
87  (`D150510 <https://reviews.llvm.org/D150510>`_)
88
89Breaking changes
90----------------
91
92COFF Improvements
93-----------------
94
95* lld-link can now find libraries with relative paths that are relative to
96  `/libpath`. Before it would only be able to find libraries relative to the
97  current directory.
98  I.e. ``lld-link /libpath:c:\relative\root relative\path\my.lib`` where before
99  we would have to do ``lld-link /libpath:c:\relative\root\relative\path my.lib``
100* lld-link learned -print-search-paths that will print all the paths where it will
101  search for libraries.
102* By default lld-link will now search for libraries in the toolchain directories.
103  Specifically it will search:
104  ``<toolchain>/lib``, ``<toolchain>/lib/clang/<version>/lib`` and
105  ``<toolchain>/lib/clang/<version>/lib/windows``.
106
107MinGW Improvements
108------------------
109
110* A warning is now printed if the linked module contains runtime pseudo
111  relocations that are too narrow, that can end up producing runtime
112  errors if loaded too far away from the referenced DLL in the address
113  space. (`D154777 <https://reviews.llvm.org/D154777>`_)
114
115MachO Improvements
116------------------
117
118WebAssembly Improvements
119------------------------
120
121Fixes
122#####
123
124* Arm exception index tables (.ARM.exidx sections) are now output
125  correctly when they are at a non zero offset within their output
126  section. (`D148033 <https://reviews.llvm.org/D148033>`_)
127