-
Notifications
You must be signed in to change notification settings - Fork 0
/
WebAssembly.html
308 lines (282 loc) · 16.8 KB
/
WebAssembly.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>WebAssembly lld port — lld 11 documentation</title>
<link rel="stylesheet" href="_static/llvm.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Windows support" href="windows_support.html" />
<link rel="prev" title="Sphinx Introduction for LLVM Developers" href="sphinx_intro.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html"><img src="_static/logo.png" alt="LLVM Documentation"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="windows_support.html" title="Windows support"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="sphinx_intro.html" title="Sphinx Introduction for LLVM Developers"
accesskey="P">previous</a> |</li>
<li><a href="index.html">lld Home</a> | </li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">WebAssembly lld port</a><ul>
<li><a class="reference internal" href="#object-file-format">Object file format</a></li>
<li><a class="reference internal" href="#usage">Usage</a></li>
<li><a class="reference internal" href="#behaviour">Behaviour</a><ul>
<li><a class="reference internal" href="#function-signatures">Function Signatures</a></li>
<li><a class="reference internal" href="#imports-and-exports">Imports and Exports</a></li>
<li><a class="reference internal" href="#garbage-collection">Garbage Collection</a></li>
<li><a class="reference internal" href="#weak-undefined-functions">Weak Undefined Functions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#missing-features">Missing features</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="sphinx_intro.html"
title="previous chapter">Sphinx Introduction for LLVM Developers</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="windows_support.html"
title="next chapter">Windows support</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/WebAssembly.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="webassembly-lld-port">
<h1>WebAssembly lld port<a class="headerlink" href="#webassembly-lld-port" title="Permalink to this headline">¶</a></h1>
<p>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.</p>
<div class="section" id="object-file-format">
<h2>Object file format<a class="headerlink" href="#object-file-format" title="Permalink to this headline">¶</a></h2>
<p>The WebAssembly object file format used by LLVM and LLD is specified as part of
the WebAssembly tool conventions on <a class="reference external" href="https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md">linking</a>.</p>
<p>This is the object format that the llvm will produce when run with the
<code class="docutils literal notranslate"><span class="pre">wasm32-unknown-unknown</span></code> target.</p>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>The WebAssembly version of lld is installed as <strong>wasm-ld</strong>. It shared many
common linker flags with <strong>ld.lld</strong> but also includes several
WebAssembly-specific options:</p>
<dl class="option">
<dt id="cmdoption-no-entry">
<code class="descname">--no-entry</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-entry" title="Permalink to this definition">¶</a></dt>
<dd><p>Don’t search for the entry point symbol (by default <code class="docutils literal notranslate"><span class="pre">_start</span></code>).</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-export-table">
<code class="descname">--export-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-export-table" title="Permalink to this definition">¶</a></dt>
<dd><p>Export the function table to the environment.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-import-table">
<code class="descname">--import-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-import-table" title="Permalink to this definition">¶</a></dt>
<dd><p>Import the function table from the environment.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-export-all">
<code class="descname">--export-all</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-export-all" title="Permalink to this definition">¶</a></dt>
<dd><p>Export all symbols (normally combined with –no-gc-sections)</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-export-dynamic">
<code class="descname">--export-dynamic</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-export-dynamic" title="Permalink to this definition">¶</a></dt>
<dd><p>When building an executable, export any non-hidden symbols. By default only
the entry point and any symbols marked as exports (either via the command line
or via the <cite>export-name</cite> source attribute) are exported.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-global-base">
<code class="descname">--global-base</code><code class="descclassname">=<value></code><a class="headerlink" href="#cmdoption-global-base" title="Permalink to this definition">¶</a></dt>
<dd><p>Address at which to place global data.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-no-merge-data-segments">
<code class="descname">--no-merge-data-segments</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-merge-data-segments" title="Permalink to this definition">¶</a></dt>
<dd><p>Disable merging of data segments.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-stack-first">
<code class="descname">--stack-first</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-stack-first" title="Permalink to this definition">¶</a></dt>
<dd><p>Place stack at start of linear memory rather than after data.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-compress-relocations">
<code class="descname">--compress-relocations</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-compress-relocations" title="Permalink to this definition">¶</a></dt>
<dd><p>Relocation targets in the code section are 5-bytes wide in order to
potentially accommodate the largest LEB128 value. This option will cause the
linker to shrink the code section to remove any padding from the final
output. However because it affects code offset, this option is not
compatible with outputting debug information.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-allow-undefined">
<code class="descname">--allow-undefined</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-allow-undefined" title="Permalink to this definition">¶</a></dt>
<dd><p>Allow undefined symbols in linked binary.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-import-memory">
<code class="descname">--import-memory</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-import-memory" title="Permalink to this definition">¶</a></dt>
<dd><p>Import memory from the environment.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-initial-memory">
<code class="descname">--initial-memory</code><code class="descclassname">=<value></code><a class="headerlink" href="#cmdoption-initial-memory" title="Permalink to this definition">¶</a></dt>
<dd><p>Initial size of the linear memory. Default: static data size.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-max-memory">
<code class="descname">--max-memory</code><code class="descclassname">=<value></code><a class="headerlink" href="#cmdoption-max-memory" title="Permalink to this definition">¶</a></dt>
<dd><p>Maximum size of the linear memory. Default: unlimited.</p>
</dd></dl>
<p>By default the function table is neither imported nor exported, but defined
for internal use only.</p>
</div>
<div class="section" id="behaviour">
<h2>Behaviour<a class="headerlink" href="#behaviour" title="Permalink to this headline">¶</a></h2>
<p>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
<a class="reference external" href="https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md">linking</a>.</p>
<div class="section" id="function-signatures">
<h3>Function Signatures<a class="headerlink" href="#function-signatures" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">unreachable</span></code> instruction)
and use these stub functions at the otherwise invalid call sites.</p>
<p>The default behaviour is to generate these stub function and to produce
a warning. The <code class="docutils literal notranslate"><span class="pre">--fatal-warnings</span></code> flag can be used to disable this behaviour
and error out if mismatched are found.</p>
</div>
<div class="section" id="imports-and-exports">
<h3>Imports and Exports<a class="headerlink" href="#imports-and-exports" title="Permalink to this headline">¶</a></h3>
<p>When building a shared library any symbols marked as <code class="docutils literal notranslate"><span class="pre">visibility=default</span></code> will
be exported.</p>
<p>When building an executable, only the entry point (<code class="docutils literal notranslate"><span class="pre">_start</span></code>) and symbols with
the <code class="docutils literal notranslate"><span class="pre">WASM_SYMBOL_EXPORTED</span></code> flag are exported by default. In LLVM the
<code class="docutils literal notranslate"><span class="pre">WASM_SYMBOL_EXPORTED</span></code> flag is set by the <code class="docutils literal notranslate"><span class="pre">wasm-export-name</span></code> attribute which
in turn can be set using <code class="docutils literal notranslate"><span class="pre">__attribute__((export_name))</span></code> clang attribute.</p>
<p>In addition, symbols can be exported via the linker command line using
<code class="docutils literal notranslate"><span class="pre">--export</span></code>.</p>
<p>Finally, just like with native ELF linker the <code class="docutils literal notranslate"><span class="pre">--export-dynamic</span></code> flag can be
used to export symbols in the executable which are marked as
<code class="docutils literal notranslate"><span class="pre">visibility=default</span></code>.</p>
</div>
<div class="section" id="garbage-collection">
<h3>Garbage Collection<a class="headerlink" href="#garbage-collection" title="Permalink to this headline">¶</a></h3>
<p>Since WebAssembly is designed with size in mind the linker defaults to
<code class="docutils literal notranslate"><span class="pre">--gc-sections</span></code> which means that all unused functions and data segments will
be stripped from the binary.</p>
<p>The symbols which are preserved by default are:</p>
<ul class="simple">
<li>The entry point (by default <code class="docutils literal notranslate"><span class="pre">_start</span></code>).</li>
<li>Any symbol which is to be exported.</li>
<li>Any symbol transitively referenced by the above.</li>
</ul>
</div>
<div class="section" id="weak-undefined-functions">
<h3>Weak Undefined Functions<a class="headerlink" href="#weak-undefined-functions" title="Permalink to this headline">¶</a></h3>
<p>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 <code class="docutils literal notranslate"><span class="pre">unreachable</span></code> instruction
and use this for any direct references to an undefined weak function.</p>
<p>For example a runtime call to a weak undefined function <code class="docutils literal notranslate"><span class="pre">foo</span></code> will up trapping
on <code class="docutils literal notranslate"><span class="pre">unreachable</span></code> inside and linker-generated function called
<code class="docutils literal notranslate"><span class="pre">undefined:foo</span></code>.</p>
</div>
</div>
<div class="section" id="missing-features">
<h2>Missing features<a class="headerlink" href="#missing-features" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>Merging of data section similar to <code class="docutils literal notranslate"><span class="pre">SHF_MERGE</span></code> in the ELF world is not
supported.</li>
<li>No support for creating shared libraries. The spec for shared libraries in
WebAssembly is still in flux:
<a class="reference external" href="https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md">https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="windows_support.html" title="Windows support"
>next</a> |</li>
<li class="right" >
<a href="sphinx_intro.html" title="Sphinx Introduction for LLVM Developers"
>previous</a> |</li>
<li><a href="index.html">lld Home</a> | </li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2020, LLVM Project.
Last updated on 2020-02-14.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
</div>
</body>
</html>