Update documents (bytecodealliance#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.
davisson2003 · Jan 25, 2022 · b256cb3 · b256cb3
1 parent 4bc6074
commit b256cb3
Show file tree

Hide file tree

Showing 8 changed files with 181 additions and 72 deletions.
diff --git a/README.md b/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
-
-- 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)
-
-### 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)
+### Key features
+
+- 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)
+
+### 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)