christoph/wamr
1
Fork 0
Code Releases Activity

Update documents (#981)

Browse Source 
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
2022-01-25 16:37:31 +08:00
committed by GitHub
parent 4bc6074273
commit b256cb3a53
8 changed files with 179 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
doc/build_wamr.md
View File

@ -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,14 +232,23 @@ 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

22
doc/build_wasm_app.md
View File

@ -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
View 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:
![WAMR memory model](./pics/wamr_memory_model.png "WAMR memory model")
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
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

6
doc/pthread_library.md
View File

@ -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
```

6
doc/source_debugging.md
View File

@ -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
```

19
doc/wasm_c_api.md
View File

@ -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