[WebAssembly] Initial wasm linker implementation

This linker backend is still a work in progress but is
enough to link simple programs including linking against
library archives.

Differential Revision: https://reviews.llvm.org/D34851

llvm-svn: 318539

3 files changed, 52 insertions, 13 deletions

diff --git a/lld/docs/NewLLD.rst b/lld/docs/NewLLD.rst
index fb796a4d0a9..5ae7944c394 100644
--- a/lld/docs/NewLLD.rst
+++ b/lld/docs/NewLLD.rst
@@ -1,5 +1,5 @@
-The ELF and COFF Linkers
-========================
+The ELF, COFF and Wasm Linkers
+==============================
 
 The ELF Linker as a Library
 ---------------------------
@@ -33,11 +33,12 @@ between speed, simplicity and extensibility.
 
   We implemented the linkers as native linkers for each file format.
 
-  The two linkers share the same design but do not share code.
+  The linkers share the same design but share very little code.
   Sharing code makes sense if the benefit is worth its cost.
-  In our case, ELF and COFF are different enough that we thought the layer to
-  abstract the differences wouldn't worth its complexity and run-time cost.
-  Elimination of the abstract layer has greatly simplified the implementation.
+  In our case, the object formats are different enough that we thought the layer
+  to abstract the differences wouldn't be worth its complexity and run-time
+  cost.  Elimination of the abstract layer has greatly simplified the
+  implementation.
 
 * Speed by design
 
diff --git a/lld/docs/WebAssembly.rst b/lld/docs/WebAssembly.rst
new file mode 100644
index 00000000000..1df8fa3a82b
--- /dev/null
+++ b/lld/docs/WebAssembly.rst
@@ -0,0 +1,36 @@
+WebAssembly lld port
+====================
+
+Note: The WebAssembly port is still a work in progress and is be lacking
+certain features.
+
+The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
+a WebAssembly binary as its output.  For the most part this port tried to mimic
+the behaviour of traditional ELF linkers and specifically the ELF lld port.
+Where possible that command line flags and the semantics should be the same.
+
+
+Object file format
+------------------
+
+The format the input object files that lld expects is specified as part of the
+the WebAssembly tool conventions
+https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md.
+
+This is object format that the llvm will produce when run with the
+``wasm32-unknown-unknown-wasm`` target.  To build llvm with WebAssembly support
+currently requires enabling the experimental backed using
+``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
+
+
+Missing features
+----------------
+
+There are several key features that are not yet implement in the WebAssembly
+ports:
+
+- COMDAT support.  This means that support for C++ is still very limited.
+- Function stripping.  Currently there is no support for ``--gc-sections`` so
+  functions and data from a given object will linked as a unit.
+- Section start/end symbols.  The synthetic symbols that mark the start and
+  of data regions are not yet created in the output file.
diff --git a/lld/docs/index.rst b/lld/docs/index.rst
index 624a73d9408..f4bf3be9bf2 100644
--- a/lld/docs/index.rst
+++ b/lld/docs/index.rst
@@ -5,13 +5,14 @@ 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.
 
-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`.
+The linker supports ELF (Unix), PE/COFF (Windows), Mach-O (macOS) and
+WebAssembly in descending order of completeness. Internally, LLD consists of
+several 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 WebAssembly port is still a work in
+progress (See :doc:`WebAssembly`).  The Mach-O port is built based on a
+different architecture than the others. For the details about Mach-O, please
+read :doc:`AtomLLD`.
 
 Features
 --------
@@ -172,5 +173,6 @@ document soon.
 
    NewLLD
    AtomLLD
+   WebAssembly
    windows_support
    ReleaseNotes