contrib/llvm-project/lld/docs/WebAssembly.rst

   1 WebAssembly lld port
   2 ====================
   3
   4 The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
   5 a WebAssembly binary as its output.  For the most part it tries to mimic the
   6 behaviour of traditional ELF linkers and specifically the ELF lld port.  Where
   7 possible the command line flags and the semantics should be the same.
   8
   9
  10 Object file format
  11 ------------------
  12
  13 The WebAssembly object file format used by LLVM and LLD is specified as part of
  14 the WebAssembly tool conventions on linking_.
  15
  16 This is the object format that the llvm will produce when run with the
  17 ``wasm32-unknown-unknown`` target.
  18
  19 Usage
  20 -----
  21
  22 The WebAssembly version of lld is installed as **wasm-ld**.  It shared many
  23 common linker flags with **ld.lld** but also includes several
  24 WebAssembly-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 as exports (either via the command line
  46   or via the `export-name` source attribute) are 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 are 5-bytes wide in order to
  63   potentially accommodate the largest LEB128 value.  This option will cause the
  64   linker to shrink the code section to remove any padding from the final
  65   output.  However because it affects code offset, this option is not
  66   compatible with outputting 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
  84 By default the function table is neither imported nor exported, but defined
  85 for internal use only.
  86
  87 Behaviour
  88 ---------
  89
  90 In general, where possible, the WebAssembly linker attempts to emulate the
  91 behaviour of a traditional ELF linker, and in particular the ELF port of lld.
  92 For more specific details on how this is achieved see the tool conventions on
  93 linking_.
  94
  95 Function Signatures
  96 ~~~~~~~~~~~~~~~~~~~
  97
  98 One way in which the WebAssembly linker differs from traditional native linkers
  99 is that function signature checking is strict in WebAssembly.  It is a
 100 validation error for a module to contain a call site that doesn't agree with
 101 the target signature.  Even though this is undefined behaviour in C/C++, it is not
 102 uncommon to find this in real-world C/C++ programs.  For example, a call site in
 103 one compilation unit which calls a function defined in another compilation
 104 unit but with too many arguments.
 105
 106 In order not to generate such invalid modules, lld has two modes of handling such
 107 mismatches: it can simply error-out or it can create stub functions that will
 108 trap at runtime (functions that contain only an ``unreachable`` instruction)
 109 and use these stub functions at the otherwise invalid call sites.
 110
 111 The default behaviour is to generate these stub function and to produce
 112 a warning.  The ``--fatal-warnings`` flag can be used to disable this behaviour
 113 and error out if mismatched are found.
 114
 115 Imports and Exports
 116 ~~~~~~~~~~~~~~~~~~~
 117
 118 When building a shared library any symbols marked as ``visibility=default`` will
 119 be exported.
 120
 121 When building an executable, only the entry point (``_start``) and symbols with
 122 the ``WASM_SYMBOL_EXPORTED`` flag are exported by default.  In LLVM the
 123 ``WASM_SYMBOL_EXPORTED`` flag is set by the ``wasm-export-name`` attribute which
 124 in turn can be set using ``__attribute__((export_name))`` clang attribute.
 125
 126 In addition, symbols can be exported via the linker command line using
 127 ``--export``.
 128
 129 Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
 130 used to export symbols in the executable which are marked as
 131 ``visibility=default``.
 132
 133 Garbage Collection
 134 ~~~~~~~~~~~~~~~~~~
 135
 136 Since WebAssembly is designed with size in mind the linker defaults to
 137 ``--gc-sections`` which means that all unused functions and data segments will
 138 be stripped from the binary.
 139
 140 The symbols which are preserved by default are:
 141
 142 - The entry point (by default ``_start``).
 143 - Any symbol which is to be exported.
 144 - Any symbol transitively referenced by the above.
 145
 146 Weak Undefined Functions
 147 ~~~~~~~~~~~~~~~~~~~~~~~~
 148
 149 On native platforms, calls to weak undefined functions end up as calls to the
 150 null function pointer.  With WebAssembly, direct calls must reference a defined
 151 function (with the correct signature).  In order to handle this case the linker
 152 will generate function a stub containing only the ``unreachable`` instruction
 153 and use this for any direct references to an undefined weak function.
 154
 155 For example a runtime call to a weak undefined function ``foo`` will up trapping
 156 on ``unreachable`` inside and linker-generated function called
 157 ``undefined:foo``.
 158
 159 Missing features
 160 ----------------
 161
 162 - Merging of data section similar to ``SHF_MERGE`` in the ELF world is not
 163   supported.
 164 - No support for creating shared libraries.  The spec for shared libraries in
 165   WebAssembly is still in flux:
 166   https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
 167
 168 .. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md