Update documents (#981)
Update README.md, add "Getting Started", “Performance and Footprint”, ”Use Cases", and refine some sections. Add memory tune document and fix wasm-c-api document.
This commit is contained in:
Wenyong Huang
GitHub
parent
4bc6074273
commit
b256cb3a53
98
README.md
98
README.md
@ -1,46 +1,55 @@
|
||||
WebAssembly Micro Runtime
|
||||
=========================
|
||||
[Build WAMR VM core](./doc/build_wamr.md) | [Embed WAMR](./doc/embed_wamr.md) | [Export native function](./doc/export_native_api.md) | [Build WASM applications](./doc/build_wasm_app.md) | [Samples](https://github.com/bytecodealliance/wasm-micro-runtime#samples)
|
||||
[Build WAMR](./doc/build_wamr.md) | [Build AOT Compiler](./README.md#build-wamrc-aot-compiler) | [Embed WAMR](./doc/embed_wamr.md) | [Export Native API](./doc/export_native_api.md) | [Build WASM Apps](./doc/build_wasm_app.md) | [Samples](./README.md#samples)
|
||||
|
||||
**A [Bytecode Alliance][BA] project**
|
||||
|
||||
[BA]: https://bytecodealliance.org/
|
||||
|
||||
WebAssembly Micro Runtime (WAMR) is a standalone WebAssembly (WASM) runtime with a small footprint. It includes a few parts as below:
|
||||
- The **"iwasm" VM core**, supporting WebAssembly interpreter, ahead of time compilation (AoT) and Just-in-Time compilation (JIT)
|
||||
WebAssembly Micro Runtime (WAMR) is a lightweight standalone WebAssembly (WASM) runtime with small footprint, high performance and highly configurable features for applications cross from embedded, IoT, edge to Trusted Execution Environment (TEE), smart contract, cloud native applications and so on. It includes a few parts as below:
|
||||
- The [**"iwasm" VM core**](./README.md#iwasm-vm-core) to run WASM applications, supporting interpreter mode, AOT mode (Ahead-of-Time compilation) and JIT mode (Just-in-Time compilation)
|
||||
|
||||
- The **application framework** and the supporting API's for the WASM applications
|
||||
- The [**"wamrc" AOT compiler**](./README.md#build-wamrc-aot-compiler) to compile WASM file into AOT file for best performance and smaller runtime footprint, which is run by "iwasm" VM Core
|
||||
|
||||
- The **dynamic management** of the WASM applications
|
||||
- The [**application framework**](./README.md#application-framework) and the supporting APIs for the WASM applications
|
||||
|
||||
- The [**dynamic management**](./README.md#remote-application-management) of the WASM applications
|
||||
|
||||
Getting started
|
||||
==================
|
||||
- [Build iwasm VM core](./doc/build_wamr.md) on [Linux](./doc/build_wamr.md#linux), [SGX](./doc/linux_sgx.md), [MacOS](./doc/build_wamr.md#macos) and [Windows](./doc/build_wamr.md#windows), and [Build wamrc AOT compiler](./README.md#build-wamrc-aot-compiler)
|
||||
- [Embed WAMR into host applications](./doc/embed_wamr.md)
|
||||
- [Register native APIs for WASM applications](./doc/export_native_api.md)
|
||||
- [Build WASM applications](./doc/build_wasm_app.md)
|
||||
- [Port WAMR to a new platform](./doc/port_wamr.md)
|
||||
- [Benchmarks](./tests/benchmarks) and [Samples](./samples)
|
||||
|
||||
iwasm VM core
|
||||
=========================
|
||||
|
||||
### key features
|
||||
### Key features
|
||||
|
||||
- 100% compliant to the W3C WASM MVP
|
||||
- Small runtime binary size (85K for interpreter and 50K for AoT) and low memory usage
|
||||
- Near to native speed by AoT
|
||||
- Self-implemented module loader enables AoT working cross Linux, SGX and MCU systems
|
||||
- Choices of WASM application libc support: the built-in libc subset for the embedded environment or [WASI](https://github.com/WebAssembly/WASI) for standard libc
|
||||
- [Embeddable with the supporting C API's](./doc/embed_wamr.md)
|
||||
- [The mechanism for exporting native API's to WASM applications](./doc/export_native_api.md)
|
||||
- [Multiple modules as dependencies](./doc/multi_module.md), ref to [sample](samples/multi-module)
|
||||
- [Thread management and pthread library](./doc/pthread_library.md), ref to [sample](samples/multi-thread)
|
||||
- [Linux SGX (Intel Software Guard Extension) support](./doc/linux_sgx.md)
|
||||
- [Source debugging](./doc/source_debugging.md)
|
||||
- [XIP (Execution In Place) support](./doc/xip.md)
|
||||
- Full compliant to the W3C WASM MVP
|
||||
- Small runtime binary size (~85K for interpreter and ~50K for AOT) and low memory usage
|
||||
- Near to native speed by AOT and JIT
|
||||
- Self-implemented AOT module loader to enable AOT working on Linux, Windows, MacOS, Android, SGX and MCU systems
|
||||
- Choices of WASM application libc support: the built-in libc subset for the embedded environment or [WASI](https://github.com/WebAssembly/WASI) for the standard libc
|
||||
- [The simple C APIs to embed WAMR into host environment](./doc/embed_wamr.md), see [how to integrate WAMR](./doc/embed_wamr.md) and the [API list](./core/iwasm/include/wasm_export.h)
|
||||
- [The mechanism to export native APIs to WASM applications](./doc/export_native_api.md), see [how to register native APIs](./doc/export_native_api.md)
|
||||
- [Multiple modules as dependencies](./doc/multi_module.md), ref to [document](./doc/multi_module.md) and [sample](samples/multi-module)
|
||||
- [Multi-thread, pthread APIs and thread management](./doc/pthread_library.md), ref to [document](./doc/pthread_library.md) and [sample](samples/multi-thread)
|
||||
- [Linux SGX (Intel Software Guard Extension) support](./doc/linux_sgx.md), ref to [document](./doc/linux_sgx.md)
|
||||
- [Source debugging support](./doc/source_debugging.md), ref to [document](./doc/source_debugging.md)
|
||||
- [WAMR-IDE (Experimental)](./test-tools/wamr-ide) to develop WebAssembly applications with build, run and debug support, ref to [document](./test-tools/wamr-ide)
|
||||
- [XIP (Execution In Place) support](./doc/xip.md), ref to [document](./doc/xip.md)
|
||||
|
||||
### post-MVP features
|
||||
- [Non-trapping float-to-int conversions](https://github.com/WebAssembly/nontrapping-float-to-int-conversions)
|
||||
- [Sign-extension operators](https://github.com/WebAssembly/sign-extension-ops)
|
||||
- [Bulk memory operations](https://github.com/WebAssembly/bulk-memory-operations)
|
||||
- [Shared memory](https://github.com/WebAssembly/threads/blob/main/proposals/threads/Overview.md#shared-linear-memory)
|
||||
- [Multi-value](https://github.com/WebAssembly/multi-value)
|
||||
### WASM post-MVP features
|
||||
- [wasm-c-api](https://github.com/WebAssembly/wasm-c-api), ref to [document](doc/wasm_c_api.md) and [sample](samples/wasm-c-api)
|
||||
- [Tail-call](https://github.com/WebAssembly/tail-call)
|
||||
- [128-bit SIMD](https://github.com/WebAssembly/simd), ref to [samples/workload](samples/workload)
|
||||
- [Reference Types](https://github.com/WebAssembly/reference-types), ref to [document](doc/ref_types.md) and [sample](samples/ref-types)
|
||||
- [Non-trapping float-to-int conversions](https://github.com/WebAssembly/nontrapping-float-to-int-conversions)
|
||||
- [Sign-extension operators](https://github.com/WebAssembly/sign-extension-ops), [Bulk memory operations](https://github.com/WebAssembly/bulk-memory-operations)
|
||||
- [Multi-value](https://github.com/WebAssembly/multi-value), [Tail-call](https://github.com/WebAssembly/tail-call), [Shared memory](https://github.com/WebAssembly/threads/blob/main/proposals/threads/Overview.md#shared-linear-memory)
|
||||
|
||||
### Supported architectures and platforms
|
||||
|
||||
@ -49,22 +58,21 @@ The iwasm supports the following architectures:
|
||||
- X86-64, X86-32
|
||||
- ARM, THUMB (ARMV7 Cortex-M7 and Cortex-A15 are tested)
|
||||
- AArch64 (Cortex-A57 and Cortex-A53 are tested)
|
||||
- MIPS
|
||||
- XTENSA
|
||||
- RISCV64, RISCV32 (RISC-V LP64 and RISC-V LP64D are tested)
|
||||
- XTENSA, MIPS, ARC
|
||||
|
||||
Following platforms are supported. Refer to [WAMR porting guide](./doc/port_wamr.md) for how to port WAMR to a new platform.
|
||||
Following platforms are supported, click each link below for how to build iwasm on that platform. Refer to [WAMR porting guide](./doc/port_wamr.md) for how to port WAMR to a new platform.
|
||||
|
||||
- [Linux](./doc/build_wamr.md#linux), [Linux SGX (Intel Software Guard Extension)](./doc/linux_sgx.md), [MacOS](./doc/build_wamr.md#macos), [Android](./doc/build_wamr.md#android), [Windows](./doc/build_wamr.md#windows)
|
||||
- [Zephyr](./doc/build_wamr.md#zephyr), [AliOS-Things](./doc/build_wamr.md#alios-things), [VxWorks](./doc/build_wamr.md#vxworks), [NuttX](./doc/build_wamr.md#nuttx), [RT-Thread](./doc/build_wamr.md#RT-Thread)
|
||||
- [Zephyr](./doc/build_wamr.md#zephyr), [AliOS-Things](./doc/build_wamr.md#alios-things), [VxWorks](./doc/build_wamr.md#vxworks), [NuttX](./doc/build_wamr.md#nuttx), [RT-Thread](./doc/build_wamr.md#RT-Thread), [ESP-IDF](./doc/build_wamr.md#esp-idf)
|
||||
|
||||
### Build iwasm VM core (mini product)
|
||||
|
||||
WAMR supports building the iwasm VM core only (no app framework) to the mini product. The WAMR mini product takes the WASM application file name or AoT file name as input and then executes it. For the detailed procedure, please see **[build WAMR VM core](./doc/build_wamr.md)** and **[build and run WASM application](./doc/build_wasm_app.md)**. Also we can click the link of each platform above to see how to build iwasm on it.
|
||||
WAMR supports building the iwasm VM core only (no app framework) to the mini product. The WAMR mini product takes the WASM application file name or AOT file name as input and then executes it. For the detailed procedure, please see **[build WAMR VM core](./doc/build_wamr.md)** and **[build and run WASM application](./doc/build_wasm_app.md)**. Also we can click the link of each platform above to see how to build iwasm on it.
|
||||
|
||||
### Build wamrc AoT compiler
|
||||
### Build wamrc AOT compiler
|
||||
|
||||
Both wasm binary file and AoT file are supported by iwasm. The wamrc AoT compiler is to compile wasm binary file to AoT file which can also be run by iwasm. Execute following commands to build **wamrc** compiler for Linux:
|
||||
Both wasm binary file and AOT file are supported by iwasm. The wamrc AOT compiler is to compile wasm binary file to AOT file which can also be run by iwasm. Execute following commands to build **wamrc** compiler for Linux:
|
||||
|
||||
```shell
|
||||
cd wamr-compiler
|
||||
@ -85,6 +93,27 @@ cmake --build . --config Release
|
||||
# wamrc.exe is generated under .\Release directory
|
||||
```
|
||||
|
||||
### Performance and Footprint
|
||||
|
||||
- [Performance and footprint data](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/Performance): checkout [here](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/Performance) for the performance and footprint data
|
||||
- [Memory usage tunning](./doc/memory_tune.md): checkout [here](./doc/memory_tune.md) for the memory model and how to tune the memory usage
|
||||
- [Memory usage profiling](./doc/build_wamr.md#enable-memory-profiling-experiment): checkout [here](./doc/build_wamr.md#enable-memory-profiling-experiment) for how to profile the memory usage
|
||||
- [Benchmarks](./tests/benchmarks): checkout these links for how to run the benchmarks: [PolyBench](./tests/benchmarks/polybench), [CoreMark](./tests/benchmarks/coremark), [Sightglass](./tests/benchmarks/sightglass), [JetStream2](./tests/benchmarks/jetstream)
|
||||
|
||||
### User cases
|
||||
|
||||
WAMR is widely used in a lot areas, here are some cases:
|
||||
- [Hyperledger Private Data Objects](https://github.com/hyperledger-labs/private-data-objects/blob/main/common/interpreter/wawaka_wasm/README.md)
|
||||
- [Inclavare Containers](https://github.com/alibaba/inclavare-containers)
|
||||
- [Fassm](https://github.com/faasm/faasm)
|
||||
- [Waft](https://developer.aliyun.com/article/787582)
|
||||
- [Envoy Proxy](https://github.com/envoyproxy/envoy)
|
||||
- [Apache Teaclave](https://teaclave.apache.org/docs/executing-wasm)
|
||||
|
||||
The 2021 [WebAssembly Open Day](https://www.sofastack.tech/activities/sofa-meetup-13) was hold, check out [here](https://www.sofastack.tech/activities/sofa-meetup-13) for the details, and here are the videos:
|
||||
- [Video1](https://www.bilibili.com/video/BV1EZ4y1X7md?from=search&seid=6209423751443457915&spm_id_from=333.337.0.0), [Video2](https://www.bilibili.com/video/BV1p44y1J7ag?from=search&seid=6209423751443457915&spm_id_from=333.337.0.0), [Video3](https://www.bilibili.com/video/BV1j34y1r7CR?from=search&seid=6209423751443457915&spm_id_from=333.337.0.0), [Video4](https://www.bilibili.com/video/BV1gY411p7gx?from=search&seid=6209423751443457915&spm_id_from=333.337.0.0)
|
||||
- [Video5](https://www.bilibili.com/video/BV1gS4y1M7kF?from=search&seid=6209423751443457915&spm_id_from=333.337.0.0), [Video6](https://www.bilibili.com/video/BV1NF411B79W?from=search&seid=6209423751443457915&spm_id_from=333.337.0.0), [Video7](https://www.bilibili.com/video/BV1dL411j7uB?from=search&seid=6209423751443457915&spm_id_from=333.337.0.0)
|
||||
|
||||
Application framework
|
||||
===================================
|
||||
|
||||
@ -121,7 +150,7 @@ The WAMR [samples](./samples) integrate the iwasm VM core, application manager a
|
||||
|
||||
- [**basic**](./samples/basic): Demonstrating how to use runtime exposed API's to call WASM functions, how to register native functions and call them, and how to call WASM function from native function.
|
||||
- **[simple](./samples/simple/README.md)**: The runtime is integrated with most of the WAMR APP libraries, and a few WASM applications are provided for testing the WAMR APP API set. It uses **built-in libc** and executes apps in **interpreter** mode by default.
|
||||
- **[littlevgl](./samples/littlevgl/README.md)**: Demonstrating the graphic user interface application usage on WAMR. The whole [LittleVGL](https://github.com/lvgl/) 2D user graphic library and the UI application are built into WASM application. It uses **WASI libc** and executes apps in **AoT mode** by default.
|
||||
- **[littlevgl](./samples/littlevgl/README.md)**: Demonstrating the graphic user interface application usage on WAMR. The whole [LittleVGL](https://github.com/lvgl/) 2D user graphic library and the UI application are built into WASM application. It uses **WASI libc** and executes apps in **AOT mode** by default.
|
||||
- **[gui](./samples/gui/README.md)**: Move the [LittleVGL](https://github.com/lvgl/) library into the runtime and define a WASM application interface by wrapping the littlevgl API. It uses **WASI libc** and executes apps in **interpreter** mode by default.
|
||||
- **[multi-thread](./samples/multi-thread/)**: Demonstrating how to run wasm application which creates multiple threads to execute wasm functions concurrently, and uses mutex/cond by calling pthread related API's.
|
||||
- **[spawn-thread](./samples/spawn-thread)**: Demonstrating how to execute wasm functions of the same wasm application concurrently, in threads created by host embedder or runtime, but not the wasm application itself.
|
||||
@ -150,13 +179,10 @@ exception. See the LICENSE file for details. This license allows you to freely
|
||||
use, modify, distribute and sell your own products based on WAMR.
|
||||
Any contributions you make will be under the same license.
|
||||
|
||||
|
||||
|
||||
# More resources
|
||||
|
||||
Check out the [Wiki documents ](https://github.com/bytecodealliance/wasm-micro-runtime/wiki) for more resources:
|
||||
|
||||
- [Performance and footprint data](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/Performance)
|
||||
- [Community news and events](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/Events)
|
||||
- [Roadmap](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/Roadmap)
|
||||
- [WAMR TSC meetings](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/TSC-meeting)
|
||||
|
||||
@ -37,7 +37,7 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM
|
||||
|
||||
NOTE: the fast interpreter runs ~2X faster than classic interpreter, but consumes about 2X memory to hold the WASM bytecode code.
|
||||
|
||||
#### **Configure AoT and JIT**
|
||||
#### **Configure AOT and JIT**
|
||||
|
||||
- **WAMR_BUILD_AOT**=1/0, default to enable if not set
|
||||
- **WAMR_BUILD_JIT**=1/0, default to disable if not set
|
||||
@ -99,7 +99,7 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM
|
||||
> Note: if it is enabled, the call stack will be dumped when exception occurs.
|
||||
|
||||
> - For interpreter mode, the function names are firstly extracted from *custom name section*, if this section doesn't exist or the feature is not enabled, then the name will be extracted from the import/export sections
|
||||
> - For AoT/JIT mode, the function names are extracted from import/export section, please export as many functions as possible (for `wasi-sdk` you can use `-Wl,--export-all`) when compiling wasm module, and add `--enable-dump-call-stack` option to wamrc during compiling AoT module.
|
||||
> - For AOT/JIT mode, the function names are extracted from import/export section, please export as many functions as possible (for `wasi-sdk` you can use `-Wl,--export-all`) when compiling wasm module, and add `--enable-dump-call-stack` option to wamrc during compiling AOT module.
|
||||
|
||||
#### **Enable memory profiling (Experiment)**
|
||||
- **WAMR_BUILD_MEMORY_PROFILING**=1/0, default to disable if not set
|
||||
@ -203,13 +203,23 @@ mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
# iwasm is generated under current directory
|
||||
```
|
||||
|
||||
|
||||
By default in Linux, the interpreter, AOT and WASI are enabled, and JIT is disabled.
|
||||
By default in Linux, the `fast interpreter`, `AOT` and `Libc WASI` are enabled, and JIT is disabled.
|
||||
And the build target is set to X86_64 or X86_32 depending on the platform's bitwidth.
|
||||
|
||||
To enable WASM JIT, firstly we should build LLVM:
|
||||
To run a wasm file with interpreter mode:
|
||||
```Bash
|
||||
iwasm <wasm file>
|
||||
```
|
||||
To run an AOT file, firstly please refer to [Build wamrc AOT compiler](../README.md#build-wamrc-aot-compiler) to build wamrc, and then:
|
||||
```Bash
|
||||
wamrc -o <AOT file> <WASM file>
|
||||
iwasm <AOT file>
|
||||
```
|
||||
|
||||
To enable the `JIT` mode, firstly we should build LLVM:
|
||||
|
||||
``` Bash
|
||||
cd product-mini/platforms/linux/
|
||||
@ -222,13 +232,22 @@ Then pass argument `-DWAMR_BUILD_JIT=1` to cmake to enable WASM JIT:
|
||||
mkdir build
|
||||
cd build
|
||||
cmake .. -DWAMR_BUILD_JIT=1
|
||||
# or "cmake .. -DWAMR_BUILD_JIT=1 -DWAMR_BUILD_LAZY_JIT=0" to disable LLVM Lazy JIT and enable LLVM MC JIT
|
||||
make
|
||||
```
|
||||
|
||||
By default, the Lazy JIT is enabled to speedup the lanuching process and reduce the JIT compilation time
|
||||
By default, the LLVM Orc Lazy JIT is enabled to speedup the lanuching process and reduce the JIT compilation time
|
||||
by creating threads to compile the WASM functions parallely, and for the main thread, the functions in the
|
||||
module will not be compiled until they are firstly called and haven't been compiled by the compilation threads.
|
||||
To disable it, please pass argument `-DWAMR_BUILD_LAZY_JIT=0` to cmake.
|
||||
To disable it and enable LLVM MC JIT instead, please pass argument `-DWAMR_BUILD_LAZY_JIT=0` to cmake.
|
||||
|
||||
To disable `fast interpreter` and enable `classic interpreter` instead:
|
||||
``` Bash
|
||||
mkdir build
|
||||
cd build
|
||||
cmake .. -DWAMR_BUILD_FAST_INTERP=0
|
||||
make
|
||||
```
|
||||
|
||||
Linux SGX (Intel Software Guard Extension)
|
||||
-------------------------
|
||||
@ -252,9 +271,24 @@ mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
# iwasm is generated under current directory
|
||||
```
|
||||
By default in MacOS, the `fast interpreter`, `AOT` and `Libc WASI` are enabled, and JIT is disabled.
|
||||
And the build target is set to X86_64 or X86_32 depending on the platform's bitwidth.
|
||||
|
||||
To run a wasm file with interpreter mode:
|
||||
```Bash
|
||||
iwasm <wasm file>
|
||||
```
|
||||
To run an AOT file, firstly please refer to [Build wamrc AOT compiler](../README.md#build-wamrc-aot-compiler) to build wamrc, and then:
|
||||
```Bash
|
||||
wamrc -o <AOT file> <WASM file>
|
||||
iwasm <AOT file>
|
||||
```
|
||||
Note:
|
||||
WAMR provides some features which can be easily configured by passing options to cmake, please see [WAMR vmcore cmake building configurations](./build_wamr.md#wamr-vmcore-cmake-building-configurations) for details. Currently in MacOS, interpreter, AoT, and builtin libc are enabled by default.
|
||||
For how to build the `JIT` mode and `classic interpreter` mode, please refer to [Build iwasm on Linux](./build_wamr.md#linux).
|
||||
|
||||
WAMR provides some features which can be easily configured by passing options to cmake, please see [WAMR vmcore cmake building configurations](./build_wamr.md#wamr-vmcore-cmake-building-configurations) for details. Currently in MacOS, interpreter, AOT, and builtin libc are enabled by default.
|
||||
|
||||
Windows
|
||||
-------------------------
|
||||
@ -271,8 +305,24 @@ mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
cmake --build . --config Release
|
||||
# ./Release/iwasm.exe is generated
|
||||
```
|
||||
The executable file is `build/Release/iwasm.exe`
|
||||
|
||||
By default in Windows, the `fast interpreter`, `AOT` and `Libc WASI` are enabled, and JIT is disabled.
|
||||
|
||||
To run a wasm file with interpreter mode:
|
||||
```Bash
|
||||
iwasm.exe <wasm file>
|
||||
```
|
||||
To run an AOT file, firstly please refer to [Build wamrc AOT compiler](../README.md#build-wamrc-aot-compiler) to build wamrc, and then:
|
||||
```Bash
|
||||
wamrc.exe -o <AOT file> <WASM file>
|
||||
iwasm.exe <AOT file>
|
||||
```
|
||||
Note:
|
||||
For how to build the `JIT` mode and `classic interpreter` mode, please refer to [Build iwasm on Linux](./build_wamr.md#linux).
|
||||
|
||||
WAMR provides some features which can be easily configured by passing options to cmake, please see [WAMR vmcore cmake building configurations](./build_wamr.md#wamr-vmcore-cmake-building-configurations) for details. Currently in Windows, interpreter, AOT, and builtin libc are enabled by default.
|
||||
|
||||
VxWorks
|
||||
-------------------------
|
||||
@ -326,7 +376,7 @@ west espressif install
|
||||
After that set `ESPRESSIF_TOOLCHAIN_PATH` according to the output, for example `~/.espressif/tools/zephyr`.
|
||||
|
||||
Note:
|
||||
WAMR provides some features which can be easily configured by passing options to cmake, please see [WAMR vmcore cmake building configurations](./build_wamr.md#wamr-vmcore-cmake-building-configurations) for details. Currently in Zephyr, interpreter, AoT and builtin libc are enabled by default.
|
||||
WAMR provides some features which can be easily configured by passing options to cmake, please see [WAMR vmcore cmake building configurations](./build_wamr.md#wamr-vmcore-cmake-building-configurations) for details. Currently in Zephyr, interpreter, AOT and builtin libc are enabled by default.
|
||||
|
||||
|
||||
AliOS-Things
|
||||
|
||||
@ -1,12 +1,13 @@
|
||||
# Build WASM applications
|
||||
|
||||
|
||||
# Prepare WASM building environments
|
||||
Prepare WASM building environments
|
||||
==================================
|
||||
|
||||
For C and C++, WASI-SDK version 12.0+ is the major tool supported by WAMR to build WASM applications. Also, we can use [Emscripten SDK (EMSDK)](https://github.com/emscripten-core/emsdk), but it is not recommended. And there are some other compilers such as the standard clang compiler, which might also work [here](./other_wasm_compilers.md).
|
||||
|
||||
To install WASI SDK, please download the [wasi-sdk release](https://github.com/CraneStation/wasi-sdk/releases) and extract the archive to default path `/opt/wasi-sdk`.
|
||||
|
||||
The official *wasi-sdk release* doesn't fully support *latest 128-bit SIMD spec* yet. WARM provides a script in [build-wasi-sdk](../test-tools/build-wasi-sdk/) to generate
|
||||
The official *wasi-sdk release* doesn't fully support *latest 128-bit SIMD spec* yet. WAMR provides a script in [build-wasi-sdk](../test-tools/build-wasi-sdk/) to generate
|
||||
another wasi-sdk with *llvm-13* from source code and installs it at *../test-tools/wasi-sdk*. If you plan to build WASM applications with *latest 128-bit SIMD*, please use it instead of the official release.
|
||||
|
||||
And [sample workloads](../samples/workload) are using the self-compiled wasi-sdk.
|
||||
@ -37,7 +38,7 @@ $ cargo build --release --target wasm32-wasi
|
||||
|
||||
|
||||
Build WASM applications with wasi-sdk
|
||||
=========================
|
||||
=====================================
|
||||
|
||||
You can write a simple ```test.c``` as the first sample.
|
||||
|
||||
@ -165,7 +166,12 @@ Please ref to [pthread library](./pthread_library.md) for more details.
|
||||
|
||||
## 4. Build wasm app with SIMD support
|
||||
|
||||
Normally we should install emsdk and use its SSE header files, please ref to workload samples, e.g. [bwa CMakeLists.txt](../samples/workload/bwa/CMakeLists.txt) and [wasm-av1 CMakeLists.txt](../samples/workload/wasm-av1/CMakeLists.txt) for more details.
|
||||
The official *wasi-sdk release* doesn't fully support *latest 128-bit SIMD spec* yet. WARM provides a script in [build-wasi-sdk](../test-tools/build-wasi-sdk/) to generate
|
||||
another wasi-sdk with *llvm-13* from source code and installs it at *../test-tools/wasi-sdk*. If you plan to build WASM applications with *latest 128-bit SIMD*, please use it instead of the official release.
|
||||
|
||||
And also you can install emsdk and use its SSE header files, please ref to workload samples, e.g. [bwa CMakeLists.txt](../samples/workload/bwa/CMakeLists.txt) and [wasm-av1 CMakeLists.txt](../samples/workload/wasm-av1/CMakeLists.txt) for more details.
|
||||
|
||||
For both wasi-sdk and emsdk, please add the option `-msimd128` for clang or emcc to generate WASM application with SIMD bytecodes.
|
||||
|
||||
# Build WASM applications with emsdk
|
||||
|
||||
@ -264,9 +270,9 @@ $ cmake <same as above>
|
||||
You will get ```hello_world``` which is the WASM app binary.
|
||||
|
||||
|
||||
# Compile WASM to AoT module
|
||||
# Compile WASM to AOT module
|
||||
|
||||
Please ensure the wamrc was already generated and available in your shell PATH. Then we can use wamrc to compile WASM app binary to WAMR AoT binary.
|
||||
Please ensure the wamrc was already generated and available in your shell PATH. Then we can use wamrc to compile WASM app binary to WAMR AOT binary.
|
||||
|
||||
``` Bash
|
||||
wamrc -o test.aot test.wasm
|
||||
@ -326,7 +332,7 @@ Examples: wamrc -o test.aot test.wasm
|
||||
|
||||
|
||||
Run WASM app in WAMR mini product build
|
||||
========================
|
||||
=======================================
|
||||
|
||||
Run the test.wasm or test.aot with WAMR mini product build:
|
||||
``` Bash
|
||||
|
||||
28
doc/memory_tune.md
Normal file
28
doc/memory_tune.md
Normal file
@ -0,0 +1,28 @@
|
||||
Memory model and memory usage tunning
|
||||
=====================================
|
||||
|
||||
## The memory model
|
||||
|
||||
The memory model of WAMR can be basically described as below:
|
||||
|
||||
|
||||
|
||||
Note:
|
||||
- **global heap**: the heap to allocate memory for runtime data structures, including wasm module, wasm module instance, exec env, wasm operand stack and so on. It is initialized by `wasm_runtime_init` or `wasm_runtime_full_init`. And for `wasm_runtime_full_init`, developer can specify the memory allocation mode with `RuntimeInitArgs *init_args`: allocate memory from a user defined byte buffer, from user defined allocation function, or from the platform's os_malloc function. Refer to [wasm_export.h](../core/iwasm/include/wasm_export.h#L98-L141) and [Embedding WAMR guideline](doc/embed_wamr.md#the-runtime-initialization) for more details. And developer can use `wasm_runtime_malloc/wasm_runtime_free` to allocate/free memory from/to the global heap.
|
||||
- **wasm operand stack**: the stack to store the operands required by wasm bytecodes as WebAssembly is based on a stack machine. If the exec_env is created by developer with `wasm_runtime_create_exec_env`, then its size is specified by `wasm_runtime_create_exec_env`, or if the exec_env is created by runtime, e.g. creating exec_env in a sub thread, the size is specified by `wasm_runtime_instantiate`.
|
||||
- **linear memory**: a contiguous, mutable array of raw bytes. It is created with an initial size but might be grown dynamically. For most compilers, e.g. wasi-sdk, emsdk, rustc or asc, normally it includes three parts, data area, auxiliary stack area and heap area. For wasi-sdk, the initial/max size can be specified with `-Wl,--initial-memory=n1,--max-memory=n2`, for emsdk, the initial/max size can be specified with `-s INITIAL_MEMORY=n1 -s MAXIMUM_MEMORY=n2 -s ALLOW_MEMORY_GROWTH=1` or `-s TOTAL_MEMORY=n`, and for asc, they can be specified with `--initialMemory` and `--maximumMemory` flags.
|
||||
- **aux stack**: the auxiliary stack resides in linear memory to store some temporary data when calling wasm functions, for example, calling a wasm function with complex struct arguments. For wasi-sdk, the size can be specified with `-z stack-size=n`, for emsdk, the size can be specified with `-s TOTAL_STACK=n`.
|
||||
- **app heap and libc heap**: the heap to allocate memory for wasm app, note that app heap is created only when the malloc/free functions (or __new/__release functions for AssemblyScript) are not exported and runtime can not detect the libc heap. To export the malloc/free functions, for wasi-sdk and emsdk, developer can use `-Wl,--export=malloc -Wl,--export=free` options, for asc, developer can use `--exportRuntime` option. For app heap, the size is specified by `wasm_runtime_instantiate`. It is recommended to export the malloc/free functions and disable app heap in single thread mode, and for multi-threading, as the libc heap isn't thread-safe, it is recommended to remove the dlmalloc.o from libc.a for wasi-sdk and use `-s MALLOC="none"` for emsdk, refer to [WAMR pthread library](./pthread_library.md) for more details. And developer can use `wasm_runtime_module_malloc/wasm_runtime_module_free` to allocate/free memory from/to app heap (or libc heap if malloc/free functions are exported).
|
||||
- **__data_end global and __heap_base global**: two globals exported by wasm application to indicate the end of data area and the base address of libc heap. For WAMR, it is recommended to export them as when there are no possible memory grow operations, runtime will truncate the linear memory into the size indicated by `__heap_base`, so as to reduce the footprint, or at least one page (64KB) is required by linear memory.
|
||||
|
||||
## Tune the memory usage
|
||||
|
||||
Normally there are some methods to tune the memory usage:
|
||||
- set the global heap size with `wasm_runtime_full_init`
|
||||
- set the wasm operand stack size with `wasm_runtime_create_exec_env` or `wasm_runtime_instantiate`
|
||||
- set the linear memory size
|
||||
- set the auxiliary stack size
|
||||
- export `malloc/free` functions to use libc heap and disable app heap
|
||||
- set the app heap size with `wasm_runtime_instantiate`
|
||||
- use `nostdlib` mode, add `-Wl,--strip-all`: refer to [How to reduce the footprint](./build_wasm_app.md#2-how-to-reduce-the-footprint) of building wasm app for more details
|
||||
- use XIP mode, refer to [WAMR XIP (Execution In Place) feature introduction](./xip.md) for more details
|
||||
BIN
doc/pics/wamr_memory_model.png
Executable file
BIN
doc/pics/wamr_memory_model.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
@ -99,9 +99,9 @@ emcc -O3 -mbulk-memory -matomics -s MALLOC="none" \
|
||||
main.c -o test.wasm
|
||||
```
|
||||
|
||||
**Build AoT module**
|
||||
**Build AOT module**
|
||||
|
||||
You can build the wasm module into AoT module with pthread support, please pass option `--enable-multi-thread` to wamrc:
|
||||
You can build the wasm module into AOT module with pthread support, please pass option `--enable-multi-thread` to wamrc:
|
||||
``` bash
|
||||
wamrc --enable-multi-thread -o test.aot test.wasm
|
||||
```
|
||||
@ -114,7 +114,7 @@ cmake .. -DWAMR_BUILD_LIB_PTHREAD=1
|
||||
make
|
||||
# Then you can run the wasm module above:
|
||||
./iwasm test.wasm
|
||||
# Or the AoT module:
|
||||
# Or the AOT module:
|
||||
# ./iwasm test.aot
|
||||
```
|
||||
|
||||
|
||||
@ -53,9 +53,9 @@ Then you can use lldb commands to debug your applications. Please refer to [lldb
|
||||
|
||||
> Known issue: `step over` on some function may be treated as `step in`, it will be fixed later.
|
||||
|
||||
## Debugging with AoT
|
||||
## Debugging with AOT
|
||||
|
||||
> Note: AoT debugging is experimental and only a few debugging capabilities are supported.
|
||||
> Note: AOT debugging is experimental and only a few debugging capabilities are supported.
|
||||
|
||||
1. Build lldb (assume you have already built llvm)
|
||||
``` bash
|
||||
@ -80,7 +80,7 @@ cmake .. -DWAMR_BUILD_DEBUG_AOT=1
|
||||
make
|
||||
```
|
||||
|
||||
4. Compile wasm module to AoT module
|
||||
4. Compile wasm module to AOT module
|
||||
``` bash
|
||||
wamrc -o test.aot test.wasm
|
||||
```
|
||||
|
||||
@ -1,16 +1,15 @@
|
||||
# wasm-c-api introduction
|
||||
|
||||
All samples come from the commit 340fd9528cc3b26d22fe30ee1628c8c3f2b8c53b
|
||||
of [wasm-c-api][https://github.com/WebAssembly/wasm-c-api].
|
||||
of [wasm-c-api](https://github.com/WebAssembly/wasm-c-api).
|
||||
|
||||
Every user should be familiar with *APIs* listed in
|
||||
[wasm.h][https://github.com/WebAssembly/wasm-c-api/blob/master/include/wasm.h].
|
||||
Developer can learn these *APIs* from
|
||||
[wasm.h](https://github.com/WebAssembly/wasm-c-api/blob/master/include/wasm.h).
|
||||
|
||||
all [examples][https://github.com/WebAssembly/wasm-c-api/tree/master/example] are
|
||||
very helpful for learning.
|
||||
And here are [examples](https://github.com/WebAssembly/wasm-c-api/tree/master/example) which
|
||||
are helpful.
|
||||
|
||||
Currently, we support partial of APIs and are going to support the rest of
|
||||
them in next releases.
|
||||
|
||||
a summary of unsupported APIs
|
||||
Currently WAMR supports most of the APIs, the unsupported APIs are listed as below:
|
||||
|
||||
- References
|
||||
|
||||
@ -26,7 +25,7 @@ WASM_API_EXTERN void wasm_module_serialize(const wasm_module_t*, own wasm_byte_v
|
||||
WASM_API_EXTERN own wasm_module_t* wasm_module_deserialize(wasm_store_t*, const wasm_byte_vec_t*);
|
||||
```
|
||||
|
||||
we tend to grow a table or a memory by opcode only and not support growing both
|
||||
Currently growing a table or memory by wasm opcode is supported and it is not supported to grow them
|
||||
by host-side function callings.
|
||||
|
||||
- Table Grow APIs
|
||||
|
||||
Reference in New Issue
Block a user