Magic-Mirror/llvm-capstone
1
0
Fork 0
mirror of https://github.com/capstone-engine/llvm-capstone.git synced 2024-12-14 11:39:35 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Revert "[WebAssembly] Update docs"

Browse Source 
This change reverts rL343155.  It broke the builtbot, even though
it works for me locally:
http://lab.llvm.org:8011/builders/lld-sphinx-docs/builds/26336

Must be a sphinx version issue I guess.

llvm-svn: 343156
This commit is contained in:
Sam Clegg 2018-09-27 00:42:49 +00:00
parent 77ab7c1b30
commit bd37e09355
2 changed files with 18 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
lld/docs/README.txt
View File

@ -6,4 +6,7 @@ currently tested with Sphinx 1.1.3.
We currently use the 'nature' theme and a Beaker inspired structure.
See sphinx_intro.rst for more details.
To rebuild documents into html:
[/lld/docs]> make html

97
lld/docs/WebAssembly.rst
View File

@ -1,10 +1,13 @@
WebAssembly lld port
====================
Note: The WebAssembly port is still a work in progress and is be lacking
certain features.
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.
a WebAssembly binary as its output. For the most part this port tried 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.
Object file format
@ -20,86 +23,14 @@ currently requires enabling the experimental backed using
``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
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:
.. option:: --no-entry
Don't search for the entry point symbol (by default ``_start``).
.. option:: --export-table
Export the function table to the environment.
.. option:: --import-table
Import the function table from the environment.
.. option:: --export-all
Export all symbols (normally combined with --no-gc-sections)
.. option:: --[no-]export-default
Export symbols marked as 'default' visibility. Default: true
.. option:: --global-base=<value>
Address at which to place global data
.. option:: --[no-]merge-data-segments
Enable/Disble merging of data segments. Default: true
.. option:: --stack-first
Place stack at start of linear memory rather than after data
.. option:: --compress-relocations
Compress the relocation targets in the code section.
.. option:: --allow-undefined
Allow undefined symbols in linked binary
.. option:: --import-memory
Import memory from the environment
.. option:: --initial-memory=<value>
Initial size of the linear memory. Default: static data size
.. option:: --max-memory=<value>
Maximum size of the linear memory. Default: unlimited
By default the function table is neither imported nor exported.
Symbols are exported if they are marked as ``visibility=default`` at compile
time or if they are included on the command line via ``--export``.
Since WebAssembly is designed with size in mind the linker defaults to
``--gc-sections`` which means that all un-used 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.
Missing features
----------------
- Merging of data section similiar to ``SHF_MERGE`` in the ELF world is not
supported.
- No support for creating shared libaries. The spec for shared libraries in
WebAssembly is still in flux:
https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
There are several key features that are not yet implement in the WebAssembly
ports:
- COMDAT support. This means that support for C++ is still very limited.
- Function stripping. Currently there is no support for ``--gc-sections`` so
functions and data from a given object will linked as a unit.
- Section start/end symbols. The synthetic symbols that mark the start and
of data regions are not yet created in the output file.