xref: /freebsd/contrib/llvm-project/lld/docs/WebAssembly.rst (revision 2f513db72b034fd5ef7f080b11be5c711c15186a)
1WebAssembly lld port
2====================
3
4The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
5a WebAssembly binary as its output.  For the most part it tries to mimic the
6behaviour of traditional ELF linkers and specifically the ELF lld port.  Where
7possible the command line flags and the semantics should be the same.
8
9
10Object file format
11------------------
12
13The WebAssembly object file format used by LLVM and LLD is specified as part of
14the WebAssembly tool conventions on linking_.
15
16This is the object format that the llvm will produce when run with the
17``wasm32-unknown-unknown`` target.
18
19Usage
20-----
21
22The WebAssembly version of lld is installed as **wasm-ld**.  It shared many
23common linker flags with **ld.lld** but also includes several
24WebAssembly-specific options:
25
26.. option:: --no-entry
27
28  Don't search for the entry point symbol (by default ``_start``).
29
30.. option:: --export-table
31
32  Export the function table to the environment.
33
34.. option:: --import-table
35
36  Import the function table from the environment.
37
38.. option:: --export-all
39
40  Export all symbols (normally combined with --no-gc-sections)
41
42.. option:: --export-dynamic
43
44  When building an executable, export any non-hidden symbols.  By default only
45  the entry point and any symbols marked with --export/--export-all are
46  exported.
47
48.. option:: --global-base=<value>
49
50  Address at which to place global data.
51
52.. option:: --no-merge-data-segments
53
54  Disable merging of data segments.
55
56.. option:: --stack-first
57
58  Place stack at start of linear memory rather than after data.
59
60.. option:: --compress-relocations
61
62  Relocation targets in the code section 5-bytes wide in order to potentially
63  occomate the largest LEB128 value.  This option will cause the linker to
64  shirnk the code section to remove any padding from the final output.  However
65  because it effects code offset, this option is not comatible with outputing
66  debug information.
67
68.. option:: --allow-undefined
69
70  Allow undefined symbols in linked binary.
71
72.. option:: --import-memory
73
74  Import memory from the environment.
75
76.. option:: --initial-memory=<value>
77
78  Initial size of the linear memory. Default: static data size.
79
80.. option:: --max-memory=<value>
81
82  Maximum size of the linear memory. Default: unlimited.
83
84By default the function table is neither imported nor exported, but defined
85for internal use only.
86
87Behaviour
88---------
89
90In general, where possible, the WebAssembly linker attempts to emulate the
91behaviour of a traditional ELF linker, and in particular the ELF port of lld.
92For more specific details on how this is achieved see the tool conventions on
93linking_.
94
95Function Signatures
96~~~~~~~~~~~~~~~~~~~
97
98One way in which the WebAssembly linker differs from traditional native linkers
99is that function signature checking is strict in WebAssembly.  It is a
100validation error for a module to contain a call site that doesn't agree with
101the target signature.  Even though this is undefined behaviour in C/C++, it is not
102uncommon to find this in real-world C/C++ programs.  For example, a call site in
103one compilation unit which calls a function defined in another compilation
104unit but with too many arguments.
105
106In order not to generate such invalid modules, lld has two modes of handling such
107mismatches: it can simply error-out or it can create stub functions that will
108trap at runtime (functions that contain only an ``unreachable`` instruction)
109and use these stub functions at the otherwise invalid call sites.
110
111The default behaviour is to generate these stub function and to produce
112a warning.  The ``--falal-warnings`` flag can be used to disable this behaviour
113and error out if mismatched are found.
114
115Imports and Exports
116~~~~~~~~~~~~~~~~~~~
117
118When building a shared library any symbols marked as ``visibility=default`` will
119be exported.  When building an executable, only the entry point and symbols
120flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default.  In LLVM the
121``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list
122which corresponds to ``__attribute__((used))`` in C/C++ sources.
123
124In addition, symbols can be exported via the linker command line using
125``--export``.
126
127Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
128used to export symbol in the executable which are marked as
129``visibility=default``.
130
131Garbage Collection
132~~~~~~~~~~~~~~~~~~
133
134Since WebAssembly is designed with size in mind the linker defaults to
135``--gc-sections`` which means that all unused functions and data segments will
136be stripped from the binary.
137
138The symbols which are preserved by default are:
139
140- The entry point (by default ``_start``).
141- Any symbol which is to be exported.
142- Any symbol transitively referenced by the above.
143
144Weak Undefined Functions
145~~~~~~~~~~~~~~~~~~~~~~~~
146
147On native platforms, calls to weak undefined functions end up as calls to the
148null function pointer.  With WebAssembly, direct calls must reference a defined
149function (with the correct signature).  In order to handle this case the linker
150will generate function a stub containing only the ``unreachable`` instruction
151and use this for any direct references to an undefined weak function.
152
153For example a runtime call to a weak undefined function ``foo`` will up trapping
154on ``unreachable`` inside and linker-generated function called
155``undefined:foo``.
156
157Missing features
158----------------
159
160- Merging of data section similar to ``SHF_MERGE`` in the ELF world is not
161  supported.
162- No support for creating shared libraries.  The spec for shared libraries in
163  WebAssembly is still in flux:
164  https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
165
166.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md
167