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 the command line flags and the semantics should be the same.

Object file format

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

The WebAssembly version of lld is installed as wasm-ld. It shared many common linker flags with ld.lld but also includes several WebAssembly-specific options:

--no-entry

Don’t search for the entry point symbol (by default _start).

--export-table

Export the function table to the environment.

--import-table

Import the function table from the environment.

--export-all

Export all symbols (normally combined with –no-gc-sections)

--export-dynamic

When building an executable, export any non-hidden symbols. By default only the entry point and any symbols marked with –export/–export-all are exported.

--global-base=<value>

Address at which to place global data.

--no-merge-data-segments

Disable merging of data segments.

--stack-first

Place stack at start of linear memory rather than after data.

--compress-relocations

Relocation targets in the code section 5-bytes wide in order to potentially occomate the largest LEB128 value. This option will cause the linker to shirnk the code section to remove any padding from the final output. However because it effects code offset, this option is not comatible with outputing debug information.

--allow-undefined

Allow undefined symbols in linked binary.

--import-memory

Import memory from the environment.

--initial-memory=<value>

Initial size of the linear memory. Default: static data size.

--max-memory=<value>

Maximum size of the linear memory. Default: unlimited.

By default the function table is neither imported nor exported, but defined for internal use only.

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 be stripped from the binary.

The symbols which are preserved by default are:

  • The entry point (by default _start).
  • 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