diff options
Diffstat (limited to 'docs/WebAssembly.rst')
| -rw-r--r-- | docs/WebAssembly.rst | 78 |
1 files changed, 65 insertions, 13 deletions
diff --git a/docs/WebAssembly.rst b/docs/WebAssembly.rst index 424c1a10c7e73..41522163bb855 100644 --- a/docs/WebAssembly.rst +++ b/docs/WebAssembly.rst @@ -4,21 +4,17 @@ WebAssembly lld port The WebAssembly version of lld takes WebAssembly binaries as inputs and produces a WebAssembly binary as its output. For the most part it tries 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. +possible the 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`` target. To build llvm with WebAssembly support -currently requires enabling the experimental backed using -``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``. +The WebAssembly object file format used by LLVM and LLD is specified as part of +the WebAssembly tool conventions on linking_. +This is the object format that the llvm will produce when run with the +``wasm32-unknown-unknown`` target. Usage ----- @@ -88,10 +84,52 @@ WebAssembly-specific options: By default the function table is neither imported nor exported, but defined for internal use only. -When building shared libraries symbols are exported if they are marked -as ``visibility=default``. When building executables only the entry point is -exported by default. In addition any symbol included on the command line via -``--export`` is also exported. +Behaviour +--------- + +In general, where possible, the WebAssembly linker attempts to emulate the +behaviour of a traditional ELF linker, and in particular the ELF port of lld. +For more specific details on how this is achieved see the tool conventions on +linking_. + +Function Signatures +~~~~~~~~~~~~~~~~~~~ + +One way in which the WebAssembly linker differs from traditional native linkers +is that function signature checking is strict in WebAssembly. It is a +validation error for a module to contain a call site that doesn't agree with +the target signature. Even though this is undefined behaviour in C/C++, it is not +uncommon to find this in real-world C/C++ programs. For example, a call site in +one compilation unit which calls a function defined in another compilation +unit but with too many arguments. + +In order not to generate such invalid modules, lld has two modes of handling such +mismatches: it can simply error-out or it can create stub functions that will +trap at runtime (functions that contain only an ``unreachable`` instruction) +and use these stub functions at the otherwise invalid call sites. + +The default behaviour is to generate these stub function and to produce +a warning. The ``--falal-warnings`` flag can be used to disable this behaviour +and error out if mismatched are found. + +Imports and Exports +~~~~~~~~~~~~~~~~~~~ + +When building a shared library any symbols marked as ``visibility=default`` will +be exported. When building an executable, only the entry point and symbols +flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default. In LLVM the +``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list +which corresponds to ``__attribute__((used))`` in C/C++ sources. + +In addition, symbols can be exported via the linker command line using +``--export``. + +Finally, just like with native ELF linker the ``--export-dynamic`` flag can be +used to export symbol in the executable which are marked as +``visibility=default``. + +Garbage Collection +~~~~~~~~~~~~~~~~~~ Since WebAssembly is designed with size in mind the linker defaults to ``--gc-sections`` which means that all unused functions and data segments will @@ -103,6 +141,18 @@ The symbols which are preserved by default are: - Any symbol which is to be exported. - Any symbol transitively referenced by the above. +Weak Undefined Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +On native platforms, calls to weak undefined functions end up as calls to the +null function pointer. With WebAssembly, direct calls must reference a defined +function (with the correct signature). In order to handle this case the linker +will generate function a stub containing only the ``unreachable`` instruction +and use this for any direct references to an undefined weak function. + +For example a runtime call to a weak undefined function ``foo`` will up trapping +on ``unreachable`` inside and linker-generated function called +``undefined:foo``. Missing features ---------------- @@ -112,3 +162,5 @@ Missing features - No support for creating shared libraries. The spec for shared libraries in WebAssembly is still in flux: https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md + +.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md |