diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/AtomLLD.rst | 5 | ||||
| -rw-r--r-- | docs/C++11.rst | 9 | ||||
| -rw-r--r-- | docs/Driver.rst | 3 | ||||
| -rw-r--r-- | docs/NewLLD.rst | 46 | ||||
| -rw-r--r-- | docs/Readers.rst | 3 | ||||
| -rw-r--r-- | docs/ReleaseNotes.rst | 96 | ||||
| -rw-r--r-- | docs/conf.py | 6 | ||||
| -rw-r--r-- | docs/design.rst | 3 | ||||
| -rw-r--r-- | docs/development.rst | 9 | ||||
| -rw-r--r-- | docs/index.rst | 184 |
10 files changed, 208 insertions, 156 deletions
diff --git a/docs/AtomLLD.rst b/docs/AtomLLD.rst index 4d36ac60a7db..614e568d1997 100644 --- a/docs/AtomLLD.rst +++ b/docs/AtomLLD.rst @@ -1,6 +1,9 @@ ATOM-based lld ============== +Note: this document discuss Mach-O port of LLD. For ELF and COFF, +see :doc:`index`. + ATOM-based lld is a new set of modular code for creating linker tools. Currently it supports Mach-O. @@ -46,9 +49,7 @@ Contents design getting_started - ReleaseNotes development - windows_support open_projects sphinx_intro diff --git a/docs/C++11.rst b/docs/C++11.rst deleted file mode 100644 index 0c4391e7b037..000000000000 --- a/docs/C++11.rst +++ /dev/null @@ -1,9 +0,0 @@ -C++11 -===== - -Originally, LLD was developed in C++11 unlike the rest of LLVM. Now, all of -LLVM, LLD, and Clang are developed using C++11. See the `LLVM Coding -Standards`_ for details on the precise subset of C++11 supported by the various -host compilers. - -.. _LLVM Coding Standards: http://llvm.org/docs/CodingStandards.html diff --git a/docs/Driver.rst b/docs/Driver.rst index f1105ffb32ce..27b378712a6c 100644 --- a/docs/Driver.rst +++ b/docs/Driver.rst @@ -2,6 +2,9 @@ Driver ====== +Note: this document discuss Mach-O port of LLD. For ELF and COFF, +see :doc:`index`. + .. contents:: :local: diff --git a/docs/NewLLD.rst b/docs/NewLLD.rst index cffea7c02dea..67f6b368b0e4 100644 --- a/docs/NewLLD.rst +++ b/docs/NewLLD.rst @@ -1,42 +1,6 @@ The ELF and COFF Linkers ======================== -We started rewriting the ELF (Unix) and COFF (Windows) linkers in May 2015. -Since then, we have been making a steady progress towards providing -drop-in replacements for the system linkers. - -Currently, the Windows support is mostly complete and is about 2x faster -than the linker that comes as a part of Micrsoft Visual Studio toolchain. - -The ELF support is in progress and is able to link large programs -such as Clang or LLD itself. Unless your program depends on linker scripts, -you can expect it to be linkable with LLD. -It is currently about 1.2x to 2x faster than GNU gold linker. -We aim to make it a drop-in replacement for the GNU linker. - -We expect that FreeBSD is going to be the first large system -to adopt LLD as the system linker. -We are working on it in collaboration with the FreeBSD project. - -The linkers are notably small; as of October 2016, -the COFF linker is about 7k lines and the ELF linker is about 18k lines, -while gold is 165K lines. - -The linkers are designed to be as fast and simple as possible. -Because it is simple, it is easy to extend to support new features. -It already supports several advanced features such section garbage -collection and identical code folding. - -The COFF linker supports i386, x86-64 and ARM. The ELF linker supports -i386, x86-64, x32, MIPS32, MIPS64, PowerPC, AMDGPU, ARM and Aarch64, -although the quality varies depending on platform. By default, LLD -provides support for all targets because the amount of code we have for -each target is so small. We do not even provide a way to disable -targets at compile time. - -There are a few key design choices that we made to achieve these goals. -We will describe them in this document. - The ELF Linker as a Library --------------------------- @@ -126,7 +90,7 @@ between speed, simplicity and extensibility. Visiting the same archive files multiple makes the linker slower. - Here is how LLD approached the problem. Instead of memorizing only undefined symbols, + Here is how LLD approaches the problem. Instead of memorizing only undefined symbols, we program LLD so that it memorizes all symbols. When it sees an undefined symbol that can be resolved by extracting an object file from an archive file it previously visited, it immediately extracts the file and link it. @@ -169,7 +133,7 @@ it would slow down the linker by 10%. So, don't do that. On the other hand, you don't have to pursue efficiency when handling files. -Important Data Strcutures +Important Data Structures ------------------------- We will describe the key data structures in LLD in this section. @@ -216,7 +180,7 @@ Once you understand their functions, the code of the linker should look obvious * SymbolTable SymbolTable is basically a hash table from strings to Symbols - with a logic to resolve symbol conflicts. It resolves conflicts by symbol type. + with logic to resolve symbol conflicts. It resolves conflicts by symbol type. - If we add Defined and Undefined symbols, the symbol table will keep the former. - If we add Defined and Lazy symbols, it will keep the former. @@ -269,11 +233,11 @@ There are mainly three actors in this linker. * Driver - The linking process is driven by the driver. The driver + The linking process is driven by the driver. The driver: - processes command line options, - creates a symbol table, - - creates an InputFile for each input file and put all symbols in it into the symbol table, + - creates an InputFile for each input file and puts all symbols within into the symbol table, - checks if there's no remaining undefined symbols, - creates a writer, - and passes the symbol table to the writer to write the result to a file. diff --git a/docs/Readers.rst b/docs/Readers.rst index f9499635b72c..b69a0b34fabe 100644 --- a/docs/Readers.rst +++ b/docs/Readers.rst @@ -3,6 +3,9 @@ Developing lld Readers ====================== +Note: this document discuss Mach-O port of LLD. For ELF and COFF, +see :doc:`index`. + Introduction ------------ diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index 07fc7dd04e7f..0d75311e4bce 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,101 +1,37 @@ ======================= -LLD 4.0.0 Release Notes +LLD 5.0.0 Release Notes ======================= .. contents:: :local: +.. warning:: + These are in-progress notes for the upcoming LLVM 5.0.0 release. + Release notes for previous releases can be found on + `the Download Page <http://releases.llvm.org/download.html>`_. + Introduction ============ -LLD is a linker which supports ELF (Unix), COFF (Windows) and Mach-O -(macOS). It is generally faster than the GNU BFD/gold linkers or the -MSVC linker. - -LLD is designed to be a drop-in replacement for the system linkers, so -that users don't need to change their build systems other than swapping -the linker command. - -This document contains the release notes for LLD 4.0.0. +This document contains the release notes for the LLD linker, release 5.0.0. Here we describe the status of LLD, including major improvements from the previous release. All LLD releases may be downloaded from the `LLVM releases web site <http://llvm.org/releases/>`_. - -What's New in LLD 4.0? -====================== +Non-comprehensive list of changes in this release +================================================= ELF Improvements ---------------- -LLD provides much better compatibility with the GNU linker than before. -Now it is able to link the entire FreeBSD base system including the kernel -out of the box. We are working closely with the FreeBSD project to -make it usable as the system linker in a future release of the operating -system. - -Multi-threading performance has been improved, and multi-threading -is now enabled by default. Combined with other optimizations, LLD 4.0 -is about 1.5 times faster than LLD 3.9 when linking large programs -in our test environment. - -Other notable changes are listed below: - -* Error messages contain more information than before. If debug info - is available, the linker prints out not only the object file name - but the source location of unresolved symbols. - -* Error messages are printed in red just like Clang by default. You - can disable it by passing ``-no-color-diagnostics``. - -* LLD's version string is now embedded in a .comment section in the - result output file. You can dump it with this command: ``objdump -j -s - .comment <file>``. - -* The ``-Map`` option is supported. With that, you can print out section - and symbol information to a specified file. This feature is useful - for analyzing link results. - -* The file format for the ``-reproduce`` option has changed from cpio to - tar. - -* When creating a copy relocation for a symbol, LLD now scans the - DSO's header to see if the symbol is in a read-only segment. If so, - space for the copy relocation is reserved in .bss.rel.ro instead of - .bss. This fixes a security issue that read-only data in a DSO - becomes writable if it is copied by a copy relocation. This issue - was disclosed originally on the - `binutils mailing list <https://sourceware.org/ml/libc-alpha/2016-12/msg00914.html>`_. - -* Compressed input sections are supported. - -* ``--oformat binary``, ``--section-start``, ``-Tbss``, ``-Tdata``, - ``-Ttext``, ``-b binary``, ``-build-id=uuid``, ``-no-rosegment``, - ``-nopie``, ``-nostdlib``, ``-omagic``, ``-retain-symbols-file``, - ``-sort-section``, ``-z max-page-size`` and ``-z wxneeded`` are - supported. - -* A lot of linker script directives have been added. - -* Default image base address for x86-64 has changed from 0x10000 to - 0x200000 to make it huge-page friendly. - -* ARM port now supports GNU ifunc, the ARM C++ exceptions ABI, TLS - relocations and static linking. Problems with ``dlopen()`` on systems - using eglibc fixed. - -* MIPS port now supports input files in new R6 revision of MIPS ABIs - or N32 ABI. Generated file now contains .MIPS.abiflags section and - complete set of ELF headers flags. - -* Relocations produced by the ``-mxgot`` compiler flag is supported - for MIPS. Now it is possible to generate "large" GOT that exceeds the 64K - limit. +* Item 1. COFF Improvements ----------------- -* Performance on Windows has been improved by parallelizing parts of the - linker and optimizing file system operations. As a result of these - improvements, LLD 4.0 has been measured to be about 2.5 times faster - than LLD 3.9 when linking a large Chromium DLL. +* Item 1. + +MachO Improvements +------------------ + +* Item 1. diff --git a/docs/conf.py b/docs/conf.py index 8abd6f4facbb..410b33e98ace 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,10 +47,10 @@ copyright = u'2011-%d, LLVM Project' % date.today().year # |version| and |release|, also used in various other places throughout the # built documents. # -# The short X.Y version. -version = '4' +# The short version. +version = '5' # The full version, including alpha/beta/rc tags. -release = '4' +release = '5' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/design.rst b/docs/design.rst index 14d180936902..1e111f979bb5 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -3,6 +3,9 @@ Linker Design ============= +Note: this document discuss Mach-O port of LLD. For ELF and COFF, +see :doc:`index`. + Introduction ------------ diff --git a/docs/development.rst b/docs/development.rst index 918e1778b801..ce91341d665f 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -3,12 +3,10 @@ Development =========== -lld is developed as part of the `LLVM <http://llvm.org>`_ project. - -Using C++11 in lld ------------------- +Note: this document discuss Mach-O port of LLD. For ELF and COFF, +see :doc:`index`. -:doc:`C++11`. +lld is developed as part of the `LLVM <http://llvm.org>`_ project. Creating a Reader ----------------- @@ -43,6 +41,5 @@ information on writing documentation for the project, see the .. toctree:: :hidden: - C++11 Readers Driver diff --git a/docs/index.rst b/docs/index.rst index d019c4f9fd8c..6d9780458d10 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,25 +1,179 @@ -.. _index: - -lld - The LLVM Linker +LLD - The LLVM Linker ===================== -lld contains two linkers whose architectures are different from each other. +LLD is a linker from the LLVM project. That is a drop-in replacement +for system linkers and runs much faster than them. It also provides +features that are useful for toolchain developers. -.. toctree:: - :maxdepth: 1 +The linker supports ELF (Unix), PE/COFF (Windows) and Mach-O (macOS) +in descending order of completeness. Internally, LLD consists of three +different linkers. The ELF port is the one that will be described in +this document. The PE/COFF port is almost complete except the lack of +the Windows debug info (PDB) support. The Mach-O port is built based +on a different architecture than the ELF or COFF ports. For the +details about Mach-O, please read :doc:`AtomLLD`. - NewLLD - AtomLLD +Features +-------- + +- LLD is a drop-in replacement for the GNU linkers. That accepts the + same command line arguments and linker scripts as GNU. + + We are currently working closely with the FreeBSD project to make + LLD default system linker in future versions of the operating + system, so we are serious about addressing compatibility issues. As + of February 2017, LLD is able to link the entire FreeBSD/amd64 base + system including the kernel. With a few work-in-progress patches it + can link approximately 95% of the ports collection on AMD64. For the + details, see `FreeBSD quarterly status report + <https://www.freebsd.org/news/status/report-2016-10-2016-12.html#Using-LLVM%27s-LLD-Linker-as-FreeBSD%27s-System-Linker>`_. + +- LLD is very fast. When you link a large program on a multicore + machine, you can expect that LLD runs more than twice as fast as GNU + gold linker. Your milage may vary, though. + +- It supports various CPUs/ABIs including x86-64, x86, x32, AArch64, + ARM, MIPS 32/64 big/little-endian, PowerPC, PowerPC 64 and AMDGPU. + Among these, x86-64 is the most well-supported target and have + reached production quality. AArch64 and MIPS seem decent too. x86 + should be OK but not well tested yet. ARM support is being developed + actively. + +- It is always a cross-linker, meaning that it always supports all the + above targets however it was built. In fact, we don't provide a + build-time option to enable/disable each target. This should make it + easy to use our linker as part of a cross-compile toolchain. + +- You can embed LLD to your program to eliminate dependency to + external linkers. All you have to do is to construct object files + and command line arguments just like you would do to invoke an + external linker and then call the linker's main function, + ``lld::elf::link``, from your code. + +- It is small. We are using LLVM libObject library to read from object + files, so it is not completely a fair comparison, but as of February + 2017, LLD/ELF consists only of 21k lines of C++ code while GNU gold + consists of 198k lines of C++ code. + +- Link-time optimization (LTO) is supported by default. Essentially, + all you have to do to do LTO is to pass the ``-flto`` option to clang. + Then clang creates object files not in the native object file format + but in LLVM bitcode format. LLD reads bitcode object files, compile + them using LLVM and emit an output file. Because in this way LLD can + see the entire program, it can do the whole program optimization. + +- Some very old features for ancient Unix systems (pre-90s or even + before that) have been removed. Some default settings have been + tuned for the 21st century. For example, the stack is marked as + non-executable by default to tighten security. + +Performance +----------- + +This is a link time comparison on a 2-socket 20-core 40-thread Xeon +E5-2680 2.80 GHz machine with an SSD drive. + +LLD is much faster than the GNU linkers for large programs. That's +fast for small programs too, but because the link time is short +anyway, the difference is not very noticeable in that case. + +Note that this is just a benchmark result of our environment. +Depending on number of available cores, available amount of memory or +disk latency/throughput, your results may vary. + +============ =========== ============ ============= ====== +Program Output size GNU ld GNU gold [1]_ LLD +ffmpeg dbg 91 MiB 1.59s 1.15s 0.78s +mysqld dbg 157 MiB 7.09s 2.49s 1.31s +clang dbg 1.45 GiB 86.76s 21.93s 8.38s +chromium dbg 1.52 GiB 142.30s [2]_ 40.86s 12.69s +============ =========== ============ ============= ====== + +.. [1] With the ``--threads`` option to enable multi-threading support. + +.. [2] Since GNU ld doesn't support the ``-icf=all`` option, we + removed that from the command line for GNU ld. GNU ld would be + slower than this if it had that option support. For gold and + LLD, we use ``-icf=all``. -Source ------- +Build +----- -lld is available in the LLVM SVN repository:: +If you have already checked out LLVM using SVN, you can check out LLD +under ``tools`` directory just like you probably did for clang. For the +details, see `Getting Started with the LLVM System +<http://llvm.org/docs/GettingStarted.html>`_. - svn co http://llvm.org/svn/llvm-project/lld/trunk lld +If you haven't checkout out LLVM, the easiest way to build LLD is to +checkout the entire LLVM projects/sub-projects from a git mirror and +build that tree. You need `cmake` and of course a C++ compiler. -lld is also available via the read-only git mirror:: +.. code-block:: console - git clone http://llvm.org/git/lld.git + $ git clone https://github.com/llvm-project/llvm-project/ + $ mkdir build + $ cd build + $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm + $ make install -Put it in llvm's tools/ directory, rerun cmake, then build target lld. +Using LLD +--------- + +LLD is installed as ``ld.lld``. On Unix, linkers are invoked by +compiler drivers, so you are not expected to use that command +directly. There are a few ways to tell compiler drivers to use ld.lld +instead of the default linker. + +The easiest way to do that is to overwrite the default linker. After +installing LLD to somewhere on your disk, you can create a symbolic +link by doing ``ln -s /path/to/ld.lld /usr/bin/ld`` so that +``/usr/bin/ld`` is resolved to LLD. + +If you don't want to change the system setting, you can use clang's +``-fuse-ld`` option. In this way, you want to set ``-fuse-ld=lld`` to +LDFLAGS when building your programs. + +LLD leaves its name and version number to a ``.comment`` section in an +output. If you are in doubt whether you are successfully using LLD or +not, run ``objdump -s -j .comment <output-file>`` and examine the +output. If the string "Linker: LLD" is included in the output, you are +using LLD. + +History +------- + +Here is a brief project history of the ELF and COFF ports. + +- May 2015: We decided to rewrite the COFF linker and did that. + Noticed that the new linker is much faster than the MSVC linker. + +- July 2015: The new ELF port was developed based on the COFF linker + architecture. + +- September 2015: The first patches to support MIPS and AArch64 landed. + +- October 2015: Succeeded to self-host the ELF port. We have noticed + that the linker was faster than the GNU linkers, but we weren't sure + at the time if we would be able to keep the gap as we would add more + features to the linker. + +- July 2016: Started working on improving the linker script support. + +- December 2016: Succeeded to build the entire FreeBSD base system + including the kernel. We had widen the performance gap against the + GNU linkers. + +Internals +--------- + +For the internals of the linker, please read :doc:`NewLLD`. It is a bit +outdated but the fundamental concepts remain valid. We'll update the +document soon. + +.. toctree:: + :maxdepth: 1 + + NewLLD + AtomLLD + windows_support + ReleaseNotes |