diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000000..ea0d9a3040 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,90 @@ +# Summary: structure of chapters and subchapters of the book + +* [WAMR Document Home Page](gitbook/home_page.md) + +## Basics + +* [Introduction](gitbook/basics/introduction/README.md) + * [WebAssembly](gitbook/basics/introduction/webassembly.md) + * [WAMR Project](gitbook/basics/introduction/wamr_project.md) + * [Security Feature](gitbook/basics/introduction/security_feature.md) + +* [Getting Started](gitbook/basics/getting-started/README.md) + * [Host Environment Preparation](gitbook/basics/getting-started/host_prerequsites.md) + * [Hello-world Program On Host](gitbook/basics/getting-started/on_host.md) + * [Docker Environment Preparation](doc/devcontainer.md) + * [Hello-world Program On Docker](gitbook/basics/getting-started/on_docker.md) + * [Build And Run WASM Application](doc/build_wasm_app.md) + * [More Tools To Create WASM Application](doc/other_wasm_compilers.md) + +## WAMR In Practice + +* [Tutorial](gitbook/tutorial/README.md) + * [WAMR Running Modes](gitbook/tutorial/running-modes/README.md) + * [Build Tutorial](gitbook/tutorial/build-tutorial/README.md) + * [Build iwasm](doc/build_wamr.md) + * [Build wamrc](gitbook/tutorial/build-tutorial/build_wamrc.md) + * [Language Embedding](gitbook/tutorial/language-embedding/README.md) + * [C/C++](doc/embed_wamr.md) + * [Python](language-bindings/python/README.md) + * [Go](language-bindings/go/README.md) + * [Debugging & IDE Support](gitbook/tutorial/debugging%26IDE-support/README.md) + * [WAMR Source Debugging With LLDB](doc/source_debugging.md) + * [VS Code Support](test-tools/wamr-ide/README.md) + * [Enable Debugging In VS Code](test-tools/wamr-ide/VSCode-Extension/README.md) + * [Move LLDB Binaries](test-tools/wamr-ide/VSCode-Extension/resource/debug/README.md) + +* [Advance Tutorial](gitbook/advance-tutorial/README.md) + * [Performance Test](gitbook/advance-tutorial/performance-benchmark/README.md) + * [PolyBench](tests/benchmarks/polybench/README.md) + * [CoreMark](tests/benchmarks/coremark/README.md) + * [Sightglass](tests/benchmarks/sightglass/README.md) + * [JetStream2](tests/benchmarks/jetstream/README.md) + * [Memory Usage Tunning](doc/memory_tune.md) + * [WAMR Porting Guide](doc/port_wamr.md) + +* [Features](gitbook/features/README.md) + * [Export Native APIs To WASM Applications](doc/export_native_api.md) + * [Example 1: Export C Functions to WASM](samples/basic/README.md) + * [Example 2: Using "native-lib"](samples/native-lib/README.md) + * [Multiple Modules As Dependencies](doc/multi_module.md) + * [Multi-modules Example](samples/multi-module/README.md) + * [Multi-thread, Pthread APIs And Thread Management](doc/pthread_library.md) + * [Multi-thread Example](samples/multi-thread/README.md) + * [Linux SGX(Intel Software Guard Extension) Support](doc/linux_sgx.md) + * [Linux SGX Remote Attestation](samples/sgx-ra/README.md) + * [XIP(Execution In Place) Support](doc/xip.md) + * [Socket Support](doc/socket_api.md) + * [Example: Use Socket Api in WAMR](samples/socket-api/README.md) + * [Post-MVP Features](gitbook/features/demo-examples/README.md) + * [WASM C API](samples/wasm-c-api/README.md) + * [128-bit SIMD](samples/workload/README.md) + * [Reference Types](samples/ref-types/README.md) + +* [More Examples](gitbook/examples/README.md) + * [File Interaction Of WASI](samples/file/README.md) + * [Same WASM Program Executing Concurrently](samples/spawn-thread/README.md) + * [Build And Run Workload](samples/workload/README.md) + +* [User Case](gitbook/features/user-case/README.md) + +## Programmer's Manual + +* [Programmer's Manual](gitbook/programmer's-manual/README.md) + * [C API Lists](gitbook/programmer's-manual/C_API_Lists.md) + +## Community + +* [How To Contribute](CONTRIBUTING.md) + +* [WAMR On Github](https://github.com/bytecodealliance/wasm-micro-runtime) + +* [WAMR Blogs](https://bytecodealliance.github.io/wamr.dev/) + +## Appendix + +* [Appendix A. Background Knowledge And Glossary Of Terms](gitbook/appendix/background_knowledge.md) + +* [Appendix B. WebAssembly Details](gitbook/appendix/webassembly_details.md) + +* [Appendix C. Complete WAMR Guide](README.md) diff --git a/gitbook/advance-tutorial/README.md b/gitbook/advance-tutorial/README.md new file mode 100644 index 0000000000..4a02cc026c --- /dev/null +++ b/gitbook/advance-tutorial/README.md @@ -0,0 +1,7 @@ +# Advance tutorial + +Welcome to the chapter of the advanced tutorial. + +If you care about performance(don't we all?), want to know whether WAMR stands out among other wasm runtimes with respect to your demands, or wish to fine-tune your wasm application's memory footprint. You could refer to [this section](performance-benchmark/README.md) + +In later sections, you can find the tutorial on how to use [application framework](../../doc/wamr_api.md) and [dynamic management](remote-applicatoin-management/README.md). Also, there is a tutorial on [how to port WAMR to the platform](../../doc/port_wamr.md) diff --git a/gitbook/advance-tutorial/performance-benchmark/README.md b/gitbook/advance-tutorial/performance-benchmark/README.md new file mode 100644 index 0000000000..84095e5d0f --- /dev/null +++ b/gitbook/advance-tutorial/performance-benchmark/README.md @@ -0,0 +1,18 @@ +# Performance Test + +Like word on the street said(no way it's just us saying!) or you may saw in previous chapters(maybe multiple times), WAMR is a **lightweight** standalone WebAssembly (WASM) runtime with **small footprint**, **high performance** and highly configurable features. + +Well, you don't have to take our word for it. You could run the [Benchmarks in our repo](https://github.com/bytecodealliance/wasm-micro-runtime/tree/main/tests/benchmarks) and decide whether the performance is good enough. + +We provide multiple benchmarks that you could try: + +- [PolyBench](../../../tests/benchmarks/polybench/README.md) +- [CoreMark](../../../tests/benchmarks/coremark/README.md) +- [Sightglass](../../../tests/benchmarks/sightglass/README.md) +- [JetStream2](../../../tests/benchmarks/jetstream/README.md) + +For the memory footprint, you can refer to the links below. + +- [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 + +And in the next section, we provide tutorials on memory usage tuning. You can [profile memory usage](../../../doc/build_wamr.md#enable-memory-profiling-experiment) and [tunning memory usage](../../../doc/memory_tune.md) diff --git a/gitbook/advance-tutorial/remote-applicatoin-management/README.md b/gitbook/advance-tutorial/remote-applicatoin-management/README.md new file mode 100644 index 0000000000..d1d2568feb --- /dev/null +++ b/gitbook/advance-tutorial/remote-applicatoin-management/README.md @@ -0,0 +1,7 @@ +# Remote application management + +The WAMR application manager supports **remote application management**(check out local directory {WAMR-DIR}/core/app-mgr or [same directory on GitHub](https://github.com/bytecodealliance/wasm-micro-runtime/tree/main/core/app-mgr) for more) from the host environment or the cloud through any physical communications such as TCP, UPD, UART, BLE, etc. Its modular design makes it able to support application management for different managed runtimes. + +The tool **host_tool** (check out local directory {WAMR-DIR}/test-tools/host-tool or [same directory on GitHub](https://github.com/bytecodealliance/wasm-micro-runtime/tree/main/test-tools/host-tool) for more) communicates to the WAMR app manager for installing/uninstalling the wasm applications on the companion chip from the host system. + +We have two example demos of the use of **host_tool**. One is the [simple example](../../../samples/simple/README.md) using the tool "host_tool" to remotely install/uninstall wasm applications from the WAMR runtime over either TCP socket or UART cable; the other is the [IoT App Store Demo](../../../test-tools/IoT-APP-Store-Demo/README.md) showing the concept of remotely managing the device applications from the cloud. diff --git a/gitbook/appendix/background_knowledge.md b/gitbook/appendix/background_knowledge.md new file mode 100644 index 0000000000..61c1719d2f --- /dev/null +++ b/gitbook/appendix/background_knowledge.md @@ -0,0 +1,61 @@ +# Some background knowledge + +In this section, we aggregate some basic background knowledge and jargon in our project field. This section could be served as a refresher for those who have left academia for a while and cannot fully recall all the weary details and exact meaning of jargon in the Compiler course. Also, it would be a great primer for those who did not take such a course and are interested in such a field(and, of course, our fantastic WAMR project). + +We think providing such a section would be nice so that you do not have to Google around. If there is anything you find inaccurate, you think should be included, or even better, you have something for us that would perfect this section, do feel free to reach out to us on [GitHub](https://github.com/bytecodealliance/wasm-micro-runtime)! + +Let's dive right into our exciting recitation/learning journey without further ado! + +## 1. Compiler + +### 1.1 What is a Compiler? + +Strictly speaking(formal definition you usually find in textbooks), the compiler is a special computer program, a system program(serves as a platform for other software), to be more precise. It takes a source program as input and outputs a target program. The source program is written in the source programming language, and usually, it is a high-level programming language such as C/C++, Java, Rust, and so on. The target program is written in a target programming language would be a low-level programming language like assembly. Take C/C++ as an example, the input for the GCC compiler(component) is a C/C++ translation unit(a source file along with any header it used), and the output is platform-dependent assembly code. + +However, in our daily life, what we usually mean when we refer to the word compiler is the compiler toolchain, which comprises a compiler, assembler, and linker. The assembler is in charge of translating the compiled translation unit(object file) from assembly to truly machine-readable machine code. The linker is used to link all the parts of the program(object files) into one executable file. Together, they can translate our human-readable source code(potentially many files) into a program that can run on the machine. + +For now, we will mainly focus on the more strict definition because I think the concept and algorithm compiler use more closely pertain to our WAMR project. + + + +### 1.2 Structure and algorithm involved + + + +Since we alright know what a compiler is, now let's learn more details about compilers. First, let's talk about the structure of the compiler and the algorithm related to each part. Typically, the compiler consists of three parts, Front End, Optimizer and Back End: + +- Front End: in some sense, this part is more "mature." The theory involved and actual implementation is more or less stable nowadays. Its primary purpose is to gather textual information from source-language programs and understand it syntactically and semantically. After that, it encodes the knowledge it has into Intermediate Representation. The theory behind Front End is formal language theory(Scanners & Parsers) and lattice theory(Elaboration for type checking). + +- Optimizer: as the name suggests, the Optimizer's goal is to optimize our program's performance. Clever readers may be conscious of the difficulty when they hear the word "optimize." Indeed, the Optimizer is very challenging to design and implement since it's a vital part of compiler infrastructure and imposes a heavy performance impact. It analyses the input IR and transforms it into definitive IR, usually through multiple passes, gradually accumulating knowledge of the program and applying a better(hopefully) transformation to it. The output(definitive IR) is semantically equivalent to the input IR to preserve the original meaning of the program we are compiling. The theories and algorithms that could be used for Optimizer are too many to list here. Here are examples: Number theory, some graph algorithms for static analysis, and fixed-point algorithms for data-flow analysis. It's still an active field that attracts many people to research. + +- Back End: the Back End is in charge of mapping programs (in IR form) to low-level code forms that can run on the target machine. Usually, there is more than one Back End, so the compiler is portable for different platforms (ISA). Its main functionality includes instruction selection, register allocation, and instruction scheduling, in which many algorithms are applied, like heuristic search, graph coloring, and some dynamic programming. Like Optimizer, the Back End has many open problems to tackle and also is a field many people hold great interest in. + +## 2. Interpreter + +### 2.1 What is an Interpreter? + +The Interpreter is also a system computer program. Like the compiler, it takes a source program as input; but instead of outputting a target program, it directly executes the program line by line and returns the corresponding results. One thing worth noting is that it's not uncommon for an interpreter to adapt widely used techniques in the compilers to improve its performance. Sometimes they are even used together. + +Based on the levels of the source language(high or low) and compilation strategies, the interpreters can be divided into several different categories. Let's look at them in more detail in the following section. + +### 2.2 Technique and jargon in Interpreter + +- Bytecode: + + The bytecode is a kind of low-level programming language in a very highly optimized and compact format. It could be the target language for the compiler. Because the instruction-like bytecode can be executed line by line in an interpreter on any platform, regardless of what hardware-related ISA it uses, it is also called p-code(portable). One example of bytecode you may be familiar with is Java bytecode. + +- Ahead-of-time(AOT) and Just-in-time(JIT) compilation: + + - AOT: as the name suggests, the AOT compilation means that the compilation happens before the program run time. Normally the target language after AOT compilation is some low-level machine code or bytecode. Then the compiled code can be executed by either a process VM or a normal computer. + + - JIT: just in time compilation is a technique widely adopted by the Interpreter to improve its performance. It detects the heavily used code section when interpreting the program and compiles them into more efficient machine code. When that code section is called again, the machine code is executed rather than having the bytecode interpreted. + +## 3. Virtual machines + +When it comes to the word "Virtual Machines," we usually would remember or refer to that System virtual machines managed by hypervisors such as KVM, VirtualBox, or VMware. We often use them as a substitute for real computers to resolve dependency or compatibility issues for courses or daily work. + +But there is also another type of virtual machine you may have heard of(even you may get really confused at first) and related more closely to the field where our project is. Process (application) virtual machines provide an environment independent of hardware, aiming to run computer programs written in a certain language. Take JVM as an example. It provides an environment for Java bytecode to execute across many platforms. + +## 4. Runtime system + +It's a rather vague term that is really difficult to explain or understand. To make things worse, when people sometimes refer to it as runtime, it's easily confused with compilation runtime, runtime library. The runtime system is an infrastructure that participates in the creation and running of our program. Typically, the components are the execution environment(Application VM maybe) to provide a place for the program to run, and the compiler front end or/and compiler back end to do the necessary analysis, transformation(from source code to bytecode), and optimization. diff --git a/gitbook/appendix/webassembly_details.md b/gitbook/appendix/webassembly_details.md new file mode 100644 index 0000000000..ea11a4ffb4 --- /dev/null +++ b/gitbook/appendix/webassembly_details.md @@ -0,0 +1,6 @@ +--- +description: "This page is under construction/refinement. p.s. wanna hear a construction joke? we are still working on it" +--- +# WebAssembly details + +Meanwhile, if you can't wait to learn more about Wasm, check out this book: _WebAssembly in Action_. It's a great book showcasing wasm basics and how to use wasm with JavaScript inside a browser. diff --git a/gitbook/basics/getting-started/README.md b/gitbook/basics/getting-started/README.md new file mode 100644 index 0000000000..4a6ca20e6b --- /dev/null +++ b/gitbook/basics/getting-started/README.md @@ -0,0 +1,13 @@ +# Getting started: a hello world program + +In this chapter, you'll learn how to run a simple hello world wasm program on your host or the Docker environment using WAMR. The docker tutorial is recommended so you don't have to worry about all the platform-related dependencies and compatibility problems. The hello world program will give you a taste of what our WAMR could do as server-side runtime and ready you for a more detailed guide at the end of this chapter. The [latter guide](../../../doc/build_wasm_app.md) covers the meaning of the compile and build option in detail and gives suggestions on fine-tuning your wasm module. More example programs can be found in [chapter 4. features](../../features/README.md) + +Now, here is the last piece of gibberish before you get your hand dirty: + +Clone our source code repo and use + +```sh +git clone https://github.com/bytecodealliance/wasm-micro-runtime.git +``` + +Or download from use any way you like diff --git a/gitbook/basics/getting-started/host_prerequsites.md b/gitbook/basics/getting-started/host_prerequsites.md new file mode 100644 index 0000000000..d6ab33cf82 --- /dev/null +++ b/gitbook/basics/getting-started/host_prerequsites.md @@ -0,0 +1,40 @@ +# Prerequisites for your host environment + +## Ubuntu + +First, install the needed packages and libraries. + +```sh +apt-get update \ + && apt-get install -y apt-transport-https apt-utils build-essential \ + ca-certificates curl g++-multilib git gnupg \ + libgcc-9-dev lib32gcc-9-dev lsb-release \ + ninja-build ocaml ocamlbuild python2.7 \ + software-properties-common tree tzdata \ + unzip valgrind vim wget zip --no-install-recommends +``` + +Then install CMake and wasi-sdk-16.0 + +```sh +wget --progress=dot:giga -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | tee /usr/share/keyrings/kitware-archive-keyring.gpg > /dev/null \ + && echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ bionic main' | tee /etc/apt/sources.list.d/kitware.list >/dev/null \ + && apt-get update \ + && rm /usr/share/keyrings/kitware-archive-keyring.gpg \ + && apt-get install -y kitware-archive-keyring --no-install-recommends \ + && apt-get install -y cmake --no-install-recommends + +wget -c --progress=dot:giga https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-16/wasi-sdk-16.0-linux.tar.gz -P /opt \ + && tar xf /opt/wasi-sdk-16.0-linux.tar.gz -C /opt \ + && ln -fs /opt/wasi-sdk-16.0 /opt/wasi-sdk \ + && rm /opt/wasi-sdk-16.0-linux.tar.gz +``` + +This should be sufficient to build WAMR and run our hello world program. + \ No newline at end of file diff --git a/gitbook/basics/getting-started/on_docker.md b/gitbook/basics/getting-started/on_docker.md new file mode 100644 index 0000000000..2dd7c77a71 --- /dev/null +++ b/gitbook/basics/getting-started/on_docker.md @@ -0,0 +1,26 @@ +# Using docker + +Now that we have set up docker, we could run the following command directly in VS Code terminal(or the bash of your if you prefer ssh docker container directly). + +Similarly, build iwasm vmcore. + +```sh +cd product-mini/platforms/linux +mkdir build && cd build +cmake .. +make +``` + +Then you are ready to go to the directory that contains the hello world program and copy our iwasm vmcore + +```sh +cp iwasm ../../../app-samples/hello-world +cd ../../../app-samples/hello-world +./build.sh +``` + +Now you can execute your first wasm program! + +```sh +./iwasm test.wasm +``` diff --git a/gitbook/basics/getting-started/on_host.md b/gitbook/basics/getting-started/on_host.md new file mode 100644 index 0000000000..df8689ffb7 --- /dev/null +++ b/gitbook/basics/getting-started/on_host.md @@ -0,0 +1,26 @@ +# Compile, build and test hello world on the host + +Now we have our host set up, we can build our hello world program and run it using WAMR. + +First, build iwasm vmcore on your platform. + +```sh +cd ${WAMR-dir}/product-mini/platforms/${your platform} +mkdir build && cd build +cmake .. +make +``` + +Then you are ready to go to the directory that contains the hello world program and copy our iwasm vmcore + +```sh +cp iwasm ../../../app-samples/hello-world +cd ${WAMR-dir}/product-mini/app-samples/hello-world +./build.sh +``` + +Now you could execute your first wasm program! + +```sh +./iwasm test.wasm +``` diff --git a/gitbook/basics/introduction/README.md b/gitbook/basics/introduction/README.md new file mode 100644 index 0000000000..6886d072b8 --- /dev/null +++ b/gitbook/basics/introduction/README.md @@ -0,0 +1,5 @@ +# Introduction + +In this chapter, we will introduce you to some basic knowledge about [WebAssembly](./webassembly.md) and our project [WAMR](./wamr_project.md). And discuss the security feature that Webassembly language itself and WAMR's enhancement can bring in [this section](./security_feature.md) + +We understand because our backgrounds vary, some terms in the following section may sound familiar but vague. We have a primer in [Appendix A](../../appendix/background_knowledge.md) gathering some details about background knowledge(compiler, interpreter, runtime system, all other jargon) that may be helpful and free you from googling around. You are more than welcome to check it out. diff --git a/gitbook/basics/introduction/security_feature.md b/gitbook/basics/introduction/security_feature.md new file mode 100644 index 0000000000..f375b99f1c --- /dev/null +++ b/gitbook/basics/introduction/security_feature.md @@ -0,0 +1,147 @@ +# The Security of WebAssembly and WAMR's implementation + +WebAssembly is a cutting-edge programming language that helps Web applications such as PhotoShop Online run at native speed in the browser and offers a sandbox mechanism to protect the host environment from malicious attacks cross the world. Beyond the browser, the Wasm can be executed in standalone runtime such as WAMR safely without the need of additional security support from OS and HW. + +## WebAssembly Security Overview + +The security features of WebAssembly(More detailed Wasm language-level security features can be found on the official [WebAssembly website](https://webassembly.org/docs/security/)) + +WebAssembly (Wasm) is designed with two key security goals: + +1. protecting users from malicious or faulty modules + +2. providing developers with robust tools for building secure applications. + +### User Protection + +Each WebAssembly module executes within a sandboxed environment separated from the host runtime using fault isolation techniques. This implies: + +- Applications execute independently, and can't escape the sandbox without going through appropriate APIs. +- Applications generally execute deterministically with limited exceptions. + +Modules must also comply with the security policies of the host environment, such as the same-origin policy in browsers or POSIX on other platforms. + +### Developer Safety Tools + +WebAssembly's design emphasizes security by removing unsafe execution features while maintaining compatibility with C/C++ programs. + +Key safety features include: + +- **Control-flow Integrity (CFI):** + - Modules must declare all accessible functions and their types at load time, enforcing structured control flow. + - Immutable, non-observable compiled code prevents control-flow hijacking attacks. + +- **Function Calls:** + - Calls must reference a valid function index. + - Indirect function calls are checked at runtime for type signature compatibility. + - A protected call stack prevents buffer overflows, ensuring safe returns. + - Branches are restricted to valid destinations within the current function. + +- **Variable Handling:** + - Local variables (fixed scope) are initialized to zero and stored in the protected call stack. + - Global variables are stored in the global index space and can be imported from external modules. + - Variables with unclear static scope (e.g., structs or address-of operator) are stored in isolated linear memory, which has bounds checking and zero-initialization by default. + +- **Traps:** + - Used to terminate execution and signal errors (e.g., invalid index, type mismatch, stack overflow, out-of-bounds memory access, or illegal arithmetic). + - In a browser, traps trigger a JavaScript exception. Future updates may support custom module-defined trap handlers. + +Future improvements may introduce multiple memory sections and finer memory controls (e.g., shared memory, page protection). + +### Memory Safety + +WebAssembly improves memory safety by eliminating common bugs found in traditional C/C++ programs: + +- **Buffer Overflows**: Local and global variables are fixed-size and stored by index, preventing buffer overflows from affecting adjacent memory. Linear memory regions, though, can overwrite objects, but bounds checking and control-flow integrity (CFI) prevent direct code injection, so mitigation like DEP or SSP is unnecessary. + +- **Pointer Safety**: Unsafe pointer usage, like dereferencing unallocated memory or accessing freed memory, is minimized. WebAssembly removes pointer semantics for function calls and variables with fixed scope, and invalid index references result in load-time validation errors or runtime traps. Linear memory is bounds-checked at the region level and zero-initialized by default. + +- **Control Flow Protection**: Although WebAssembly prevents direct code injection, code reuse attacks targeting indirect calls are still possible. However, conventional ROP attacks are infeasible due to CFI, which enforces valid call targets declared at load time. + +- **Potential Vulnerabilities**: Race conditions (e.g., TOCTOU) and side-channel attacks (e.g., timing attacks) are possible, as WebAssembly offers no scheduling guarantees. Future enhancements may introduce memory randomization, code diversification, and bounded pointers to strengthen protection. + +### Control-Flow Integrity (CFI) + +Wasm ensures CFI for both direct and indirect function calls as well as function returns. It uses explicit function section indexes and runtime type checks to verify safe transitions. However, as mentioned above, while these mechanisms prevent most code injection, indirect call exploits using code reuse techniques are still possible. + +Developers can enhance security by enabling fine-grained CFI through Clang/LLVM's WebAssembly support, which adds richer type-level checks and mitigates indirect call attacks, albeit with minor performance trade-offs. + +## WAMR Security Features + +The WebAssembly Micro Runtime (WAMR) is designed to provide an efficient, secure, and lightweight runtime for WebAssembly on standalone devices. It offers a full coverage of the WebAssembly specification and added additional security enhancements to ensure safe execution of Wasm modules. + +### Wasm Language Security Features + +WAMR enforces WebAssembly language-level security features rigorously, ensuring that each Wasm module undergoes comprehensive validation at the loading phase and that execution conforms to the WebAssembly specification during runtime. + +#### Module Validation + +Before execution, WAMR validates the Wasm module to ensure it adheres to the WebAssembly specification. This involves several key checks: + +- **Format Validation**: Ensuring the binary is well-formed and compliant with the Wasm format. This checks the structure, ensuring correct definitions for functions, memory segments, tables, and types. + +- **Type Checking**: All function signatures, local variables, and global variables are verified against their declared types. This ensures type safety across calls and memory operations. + +- **Control Flow Integrity**: Verifies the function call graph to ensure that all function indices and signatures are valid and that function calls do not violate control-flow safety rules. + +- **Operand Stack Integrity**: WAMR ensures that operand stack overflows and underflows are checked during validation. For each function, the number of values pushed and popped from the operand stack must match the declared function signature, avoiding stack imbalances. + +- **Memory and Table Boundaries**: Ensures that memory and table sizes do not exceed predefined limits and that access to these regions remains within bounds. + +#### Module Execution + +During runtime, WAMR ensures that execution strictly conforms to the WebAssembly spec and maintains the security guarantees made at load time: + +- **Memory Safety**: Memory access, both direct and indirect, is rigorously checked. WAMR prevents out-of-bounds access, helping mitigate common vulnerabilities like buffer overflows. + + - Implementation of **Boundary Checks**: WAMR can leverage either software boundary checks or hardware boundary checks. For software boundary checks, before each memory access, the address is validated to ensure it falls within the allowable bounds of the allocated memory. For hardware boundary checks, protection mechanisms such as `mmap`-based memory protection, where sections of memory can be made non-writable or non-executable to prevent invalid memory address access. + +- Like previously mentioned, applications generally execute deterministically with **limited exceptions**, which can be handled in the runtime rather than simply crushing or causing undefined behavior. The exceptions that WAMR can handle include but are not limited to: + + - EXCE_UNREACHABLE: Triggered when unreachable code is executed. + - EXCE_OUT_OF_MEMORY: Signaled when the runtime runs out of memory. + - EXCE_OUT_OF_BOUNDS_MEMORY_ACCESS: Raised when memory access goes out of bounds. + - EXCE_INTEGER_OVERFLOW: Detects integer overflow during arithmetic operations. + - EXCE_INTEGER_DIVIDE_BY_ZERO: Handles division by zero in integer operations. + - EXCE_INVALID_CONVERSION_TO_INTEGER: Raised when an invalid conversion to an integer occurs. + - EXCE_INVALID_FUNCTION_TYPE_INDEX: Triggered when an invalid function type index is accessed. + - EXCE_INVALID_FUNCTION_INDEX: Signaled when an invalid function index is used. + - EXCE_UNDEFINED_ELEMENT: Raised when accessing an undefined element. + - EXCE_UNINITIALIZED_ELEMENT: Triggered when an uninitialized element is accessed. + - EXCE_CALL_UNLINKED_IMPORT_FUNC: Handles calls to unlinked imported functions. + - EXCE_NATIVE_STACK_OVERFLOW: Triggered when the native stack exceeds its limit. + - EXCE_UNALIGNED_ATOMIC: Raised when an unaligned atomic operation is attempted. + - EXCE_AUX_STACK_OVERFLOW: Signals that the auxiliary stack has overflowed. + - EXCE_AUX_STACK_UNDERFLOW: Triggered when the auxiliary stack is underflowed. + - EXCE_OUT_OF_BOUNDS_TABLE_ACCESS: Raised when accessing a table out of bounds. + - EXCE_OPERAND_STACK_OVERFLOW: Signaled when the operand stack overflows. + +These features, combined with the robust validation and execution checks, ensure that WAMR achieves comprehensive security for running WebAssembly modules. + +### Extra Enhancements on Security + +WAMR goes beyond the standard WebAssembly security features by offering additional mechanisms to enhance the security of applications, particularly in the areas of native API access control and hardware-based security. + +#### Native API Export Control + +WAMR allows WebAssembly applications to interact with the host environment through **exported native APIs**. However, unrestricted access to these APIs can introduce security risks, such as unauthorized system calls or resource manipulation. To mitigate these risks, WAMR implements a **fine-grained access control** mechanism for native APIs: + +- **Restricted API Access**: Developers can explicitly define which native APIs are exposed to WebAssembly modules, limiting the surface area for potential misuse. This allows for precise control over which system resources (e.g., file system, networking, I/O devices) can be accessed by a module. + +- **Custom API Policies**: WAMR supports customizable policies, enabling developers to set permissions and constraints on how WebAssembly modules can interact with native APIs. This is particularly useful for sandboxing untrusted code while still allowing necessary functionality under controlled conditions. + +- **API Call Validation**: All calls to native APIs are validated at runtime to ensure that they conform to the defined policies, preventing unauthorized or malicious API usage. + +#### Intel SGX Remote Attestation + +WAMR enhances security for trusted execution environments (TEEs) through its support for **Intel Software Guard Extensions (SGX)**, which provides hardware-level security features, including **remote attestation**: + +- **SGX Integration**: WAMR can run WebAssembly modules within an SGX enclave, a protected area of execution that provides isolation from the rest of the system. This ensures that even if the host machine is compromised, the code and data within the enclave remain secure. + +- **Remote Attestation**: WAMR supports SGX remote attestation, allowing remote parties to verify that a WebAssembly module is running inside a genuine SGX enclave. This involves generating and sending an **attestation report**, which proves the authenticity of the enclave and the integrity of the code running inside it. + + - **Endorsement of Trusted Execution**: The attestation process ensures that the WebAssembly module and its execution environment have not been tampered with, providing assurance to remote users that the module is running in a secure, trusted state. + +- **Sealing and Unsealing**: WAMR supports SGX's data sealing features, enabling WebAssembly modules to securely store sensitive data on disk. Sealed data can only be accessed by the same enclave in future executions, protecting it from unauthorized access even if the host system is compromised. + +These features enhance WAMR’s security, making it suitable for use cases that require both flexible native API access and strong hardware-backed guarantees of code integrity and confidentiality. diff --git a/gitbook/basics/introduction/wamr_project.md b/gitbook/basics/introduction/wamr_project.md new file mode 100644 index 0000000000..0cba5b084c --- /dev/null +++ b/gitbook/basics/introduction/wamr_project.md @@ -0,0 +1,65 @@ +# WAMR project + + In this section, we will introduce the basics of project WAMR to you. In each brief introduction section, you are more than welcome to jump to details of that section triggering your interest. + +## What is it? + +WebAssembly Micro Runtime (WAMR) is a [Bytecode Alliance](https://bytecodealliance.org/) project. A lightweight standalone WebAssembly (WASM) runtime with a small footprint, high performance, and highly configurable features for applications across from embedded, IoT, edge to Trusted Execution Environment (TEE), smart contract, cloud-native, and so on. + +## Why you may want to use it + + + +As we explained in the previous section, WebAssembly is great for code reuse on the server side with the help of runtime like our Project WAMR. So the most straightforward way is to use WAMR to run your WASM program. + +It's not limited to simply being a command line application that runs your wasm program. You could also use it as a library, integrated into your application to run any wasm program inside your application. Although most user cases are embedding WAMR in their C/C++ program, we do support other [language-binding](../../tutorial/language-embedding/README.md) so that you could use WAMR in some language you prefer. + +## Component of WAMR + + + +There are four parts of WAMR. Two main parts of WAMR are: + +1. The "iwasm" VM core to run WASM applications. It has many features and achieves several functionalities. The complete list of features and examples demonstrating it can be found in [Features](../../features/README.md). Here are some brief introductions of some features that may interest you: + + - Flexibility: It supports multiple running modes to provide the ideal responsive time and performance on your demand. The running mode includes interpreter mode, AOT mode (Ahead-of-Time compilation), and JIT modes (Just-in-Time compilation, LLVM JIT, and Fast JIT are supported). Details on how to build and use each mode properly and where you may want to use it can be found in [Tutorial](../../tutorial/README.md) + + - High Performance: WAMR achieves nearly native speed by AOT and JIT modes. It also has a small runtime binary size (~85K for interpreter and ~50K for AOT) and low memory usage + + - Portability: It supports many architectures and platforms. + + The architectures it supports: + + - X86-64, X86-32 + - ARM, THUMB (ARMV7 Cortex-M7 and Cortex-A15 are tested) + - AArch64 (Cortex-A57 and Cortex-A53 are tested) + - RISCV64, RISCV32 (RISC-V LP64 and RISC-V LP64D are tested) + - XTENSA, MIPS, ARC + + The platforms it supports: + + - [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), [Windows (MinGW)](../../../doc/build_wamr.md#mingw) + + - [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) + + It enables true cross-platform development experience. You can even port WAMR to a new platform following [this tutorial](../../../doc/port_wamr.md). Though it's unlikely since we support many platforms, having such features is comforting. + + - Security: It has Linux SGX (Intel Software Guard Extension) support. Through this unique application isolation technology, your application data is as safe as it can be. + +2. The "wamrc" AOT compiler to compile WASM files into AOT files for best performance and smaller runtime footprint, which is run by "iwasm" VM Core + + Both the wasm binary files and AOT files are supported by iwasm. The wamrc AOT compiler compiles a wasm binary file to an AOT file, which can also be run by iwasm. The speed by AOT and JIT are near to native. + +The other 2 parts are: + +1. Application framework: + + The WAMR application manager supports remote application management from the host environment or the cloud through any physical communications such as TCP, UPD, UART, BLE, etc. Its modular design makes it able to support application management for different managed runtimes. + +2. Application manager: + + By using the iwasm VM core, we are flexible to build different application frameworks for specific domains, although it would take quite some effort. + + The WAMR has offered a comprehensive framework for programming WASM applications for device and IoT usages. The framework supports running multiple applications that are based on the event-driven programming model. Here are the supporting API sets by the WAMR application framework library : + + - Timer, Inter-app communication (request/response and pub/sub), Sensor, Connectivity and data transmission, 2D graphic UI diff --git a/gitbook/basics/introduction/webassembly.md b/gitbook/basics/introduction/webassembly.md new file mode 100644 index 0000000000..65e2fe3521 --- /dev/null +++ b/gitbook/basics/introduction/webassembly.md @@ -0,0 +1,52 @@ +# WebAssembly + +In this section, you will learn the basics of WebAssembly. More details about WebAssembly can be found in [Appendix B](../../appendix/webassembly_details.md) + +## Overview + +Like its name suggest, in a sense, it is related to the Web and Assembly. Web means that it, like many other forerunners, like asm.js, trying to improve JavaScript's performance in Browsers. And the Assembly means that the format of WebAssembly is not a human-readable format but a compact binary format that is more efficient for Browsers to use. To conclude, WebAssembly (Wasm) is a compact, binary instruction format tailored for a stack-based virtual machine. It serves as a portable compilation target for various programming languages, enabling smooth deployment across both client and server environments on the web. It aims to provide benefits such as: + +- High Performance + + Wasm is built for fast execution and compact encoding, allowing programs to be efficiently transmitted and quickly loaded. By leveraging the common hardware capabilities across platforms, WebAssembly can run at near-native speeds. + +- Secure Execution Environment + + Wasm operates within a memory-safe, sandboxed environment, which can be implemented even inside existing JavaScript engines. When integrated into web applications, it adheres to the same-origin policy and browser-based permission models, ensuring robust security. + +- Open and Debuggable Format + + Wasm is designed with a textual representation that aids in debugging, testing, and optimization. This human-readable format allows developers to experiment, learn, and even hand-code Wasm modules. When viewed on the web, this text format makes Wasm modules easily accessible for inspection. + +- A Core Part of the Open Web + + Built to uphold the versionless and backward-compatible nature of the web, WebAssembly seamlessly interacts with JavaScript and can access web APIs. Beyond web applications, Wasm is versatile and supports other non-web environments as well. + +In [The State of WebAssembly 2023](https://www.cncf.io/reports/the-state-of-webassembly-2023/) from SlashData, Linux Foundation, and the Cloud Native Computing Foundation, some key insights into the current status and adoption of WebAssembly can be found. Including the top reason why people want to use WebAssembly: + +- Faster loading times 23% +- Exploring new use cases and technologies 22% +- Sharing code between projects 20% +- Improved performance over JavaScript 20% +- Efficient execution of computationally intensive tasks 19% +- Binaries run anywhere 18% +- Sandboxed security 18% +- Language agnostic 18% + +What makes it even better is that, like Javascript, shortly after the appearance of WebAssembly, it is not limited to the browser. It could also be used server-side. Many WebAssembly runtimes are out there, including our project WAMR. + +## How does it work + +### A browser example + +The most straightforward place you could think of when it comes to the use of WebAssembly is in the browser. + +Emscripten is a compiler toolchain for WebAssembly. It took the C/C++(or any other programming language LLVM frontend support) source program as input and translated it into the WebAssembly target program module. + +Optionally, an HTML and a Javascript file are generated alongside a wasm file, so the plumbing JS code is ready for you to call your wasm module. And you could open HTML on your browser to see the result of your wasm program. + +Here is the more detailed [emscripten official tutorial](https://emscripten.org/docs/getting_started/Tutorial.html) you could follow to write your hello world wasm program and run it on the browser. + +### A server-side example + +A hello world example using our WAMR can be found [here](../getting-started/README.md) diff --git a/gitbook/examples/README.md b/gitbook/examples/README.md new file mode 100644 index 0000000000..300a39f926 --- /dev/null +++ b/gitbook/examples/README.md @@ -0,0 +1,11 @@ +# More Examples + +In this chapter, we provide some extra useful examples to demonstrate how you may want to use WAMR: + +- [File Interaction Of WASI](../../samples/file/README.md): Demonstrating the supported file interaction API of WASI. This sample can also demonstrate the SGX IPFS (Intel Protected File System), enabling an enclave to seal and unseal data at rest. + +- [GUI Examples](gui-examples/README.md): We provide two examples that both use [LVGL library](https://github.com/lvgl/lvgl) + +- [Concurrent WASM Application](../../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. + +- [Workload](../../samples/workload/README.md): Demonstrating how to build and run some complex workloads, e.g., tensorflow-lite, XNNPACK, wasm-av1, meshoptimizer, and bwa. diff --git a/gitbook/features/README.md b/gitbook/features/README.md new file mode 100644 index 0000000000..de538076c8 --- /dev/null +++ b/gitbook/features/README.md @@ -0,0 +1,39 @@ +--- +description: "This page is under construction/refinement. p.s. wanna hear a construction joke? we are still working on it" +--- +# Features And Examples + + + +In this chapter, you can see the complete list of features that WAMR support. And for each feature, we have an example followed demonstrating the usage of such a feature. + +## IWASM features + +### 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 work 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) +- [Berkeley/Posix Socket support](../../doc/socket_api.md), ref to [document](../../doc/socket_api.md) and [sample](../../samples/socket-api) +- Language bindings: [Go](../../language-bindings/go/README.md), [Python](../../language-bindings/python/README.md) + +### WASM post-MVP features + +There are many post-MVP features for WASM. We support some of them. You can see the details in [this section](demo-examples/README.md) + +- [wasm-c-api](https://github.com/WebAssembly/wasm-c-api) +- [128-bit SIMD](https://github.com/WebAssembly/simd) +- [Reference Types](https://github.com/WebAssembly/reference-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) diff --git a/gitbook/features/demo-examples/README.md b/gitbook/features/demo-examples/README.md new file mode 100644 index 0000000000..8f6c89155f --- /dev/null +++ b/gitbook/features/demo-examples/README.md @@ -0,0 +1,15 @@ +# WASM post-MVP features + +The ones we support: + +- [wasm-c-api](https://github.com/WebAssembly/wasm-c-api), ref to [document](../../../doc/wasm_c_api.md) and [sample](../../../samples/wasm-c-api) + +- [128-bit SIMD](https://github.com/WebAssembly/simd), ref to [samples/workload](../../../samples/workload/README.md) + +- [Reference Types](https://github.com/WebAssembly/reference-types), ref to [document](../../../doc/ref_types.md) and [sample](../../../samples/ref-types) + +Other 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) +- [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) diff --git a/gitbook/features/user-case/README.md b/gitbook/features/user-case/README.md new file mode 100644 index 0000000000..dea2acbcc6 --- /dev/null +++ b/gitbook/features/user-case/README.md @@ -0,0 +1,10 @@ +# User case + +WAMR is widely used in a lot of 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) diff --git a/gitbook/home_page.md b/gitbook/home_page.md new file mode 100644 index 0000000000..831c167f01 --- /dev/null +++ b/gitbook/home_page.md @@ -0,0 +1,15 @@ +# Welcome + +Welcome to the home page of WAMR documentation, [WebAssembly Micro Runtime](https://github.com/bytecodealliance/wasm-micro-runtime) is an open-source project under [Bytecode Alliance](https://bytecodealliance.org/). As the name suggests, it is a lightweight standalone WebAssembly (WASM) runtime with a small footprint, high performance, and highly configurable features for applications across from embedded, IoT, edge Trusted Execution Environment (TEE), smart contract, cloud-native, and so on. + +## How to navigate the documentation + +If you are a complete beginner who just stepped into the world of WebAssembly or just looking to kill some time and learn something fun, start with [appendix A. background knowledge 101](appendix/background_knowledge.md) and our [chapter 1. introduction](basics/introduction/README.md). Also, you could learn how to run a hello world server-side wasm application using runtime WAMR in [chapter 2. getting started](basics/getting-started/README.md). + +Suppose you are somewhat familiar with WebAssembly and want to explore what WAMR can do for you as a user and developer. You could first check out [chapter 3. tutorial on how to use WAMR](tutorial/README.md), including [introduction to different running modes](tutorial/running-modes/README.md), how to [build different running modes](tutorial/build-tutorial/README.md), how to [embed WAMR into your application](tutorial/language-embedding/README.md) and how to [debug with WAMR](tutorial/debugging%26IDE-support/README.md). Then you could visit the complete list of [chapter 5. features](features/README.md) WAMR supported to see whether specific feature interest you and would serve your demands well. If the time comes when you start to optimize and consider improving performance or want to utilize the advanced feature, including **application framework** and **dynamic management**. In that case, you could find them in [chapter 4. advance tutorial](advance-tutorial/README.md). + +And, of course, you can always utilize the search function in the top right corner to locate whichever topic you are interested in + +## Social + +Feel free to check out our [blog](https://bytecodealliance.github.io/wamr.dev/) from time to time! We have some great blogs that either showcase some WAMR features and use cases or discuss some interesting topics on WAMR/WASM. diff --git a/gitbook/programmer's-manual/C_API_Lists.md b/gitbook/programmer's-manual/C_API_Lists.md new file mode 100644 index 0000000000..abaef36e81 --- /dev/null +++ b/gitbook/programmer's-manual/C_API_Lists.md @@ -0,0 +1,3 @@ +# Complete C/C++ API Lists + +The complete C/C++ lists for embedding the WAMR VM core can be found in the header file [wasm_export.h](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/core/iwasm/include/wasm_export.h). diff --git a/gitbook/programmer's-manual/README.md b/gitbook/programmer's-manual/README.md new file mode 100644 index 0000000000..fa098060ce --- /dev/null +++ b/gitbook/programmer's-manual/README.md @@ -0,0 +1,6 @@ +--- +description: "This page is under construction/refinement. p.s. wanna hear a construction joke? we are still working on it" +--- +# Programmer's Manual + +Complete List of C APIs can be found [here](gitbook/programmer's_manual/C_API_Lists.md) diff --git a/gitbook/tutorial/README.md b/gitbook/tutorial/README.md new file mode 100644 index 0000000000..85b63677f0 --- /dev/null +++ b/gitbook/tutorial/README.md @@ -0,0 +1,9 @@ +# Tutorial + +In this chapter, we want to walk you through the basic development knowledge and skills of WARM you may need so that you are ready to write your wasm application with WARM. + +For starters, you could learn how to compile different running mode of WAMR and their usage in [this section](build-tutorial/README.md). + +Then, as we said before, WAMR is not limited to being a command line application that runs wasm code. You could also [embed WAMR](language-embedding/README.md) into your application. + +And don't forget the one important stage of developing, namely debugging. We cover it in [this section](debugging%26IDE-support/README.md). diff --git a/gitbook/tutorial/build-tutorial/README.md b/gitbook/tutorial/build-tutorial/README.md new file mode 100644 index 0000000000..dee388f970 --- /dev/null +++ b/gitbook/tutorial/build-tutorial/README.md @@ -0,0 +1,36 @@ +--- +description: "This page is under construction/refinement. p.s. wanna hear a construction joke? we are still working on it" +--- +# build tutorial + +In this chapter, we provide a detailed tutorial on how to build [iwasm vmcore](../../../doc/build_wamr.md) and [wamrc](build_wamrc.md). + +## Quick build matrix + +Our powerful **iwasm vmcore** provide various running mode you could choose using the compile CMake option. Here is the matrix for different running mode and their attributes: + +| Running mode | CMake build options | Pros and Cons | +| ----------- | ----------- | --------- | +| AOT | none(default) | | +| Classic Interpreter | -DWAMR_BUILD_FAST_INTERP=0 | | +| Fast Interpreter | none(default) | | +| LLVM JIT | -DWAMR_BUILD_JIT=1 | | +| Fast JIT | -DWAMR_BUILD_FAST_JIT=1 | | + +## Supported architectures and platforms + +Here is a list of architectures and platforms WAMR support. You could click on the link for quick reference. + +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) +- RISCV64, RISCV32 (RISC-V LP64 and RISC-V LP64D are tested) +- XTENSA, MIPS, ARC + +The 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), [Windows (MinGW)](../../../doc/build_wamr.md#mingw) + +- [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) diff --git a/gitbook/tutorial/build-tutorial/build_wamrc.md b/gitbook/tutorial/build-tutorial/build_wamrc.md new file mode 100644 index 0000000000..891d7d7d44 --- /dev/null +++ b/gitbook/tutorial/build-tutorial/build_wamrc.md @@ -0,0 +1,23 @@ +# How to Build wamrc AOT compiler + +Both the WASM binary file and AOT file are supported by iwasm. The wamrc AOT compiler compiles wasm binary file to AOT file, which can also be run by iwasm. Execute the following commands to build **wamrc** compiler for Linux: + +```shell +cd wamr-compiler +./build_llvm.sh (or "./build_llvm_xtensa.sh" to support xtensa target) +mkdir build && cd build +cmake .. (or "cmake .. -DWAMR_BUILD_PLATFORM=darwin" for MacOS) +make +# wamrc is generated under current directory +``` + +For **Windows**： + +```shell +cd wamr-compiler +python build_llvm.py +mkdir build && cd build +cmake .. +cmake --build . --config Release +# wamrc.exe is generated under .\Release directory +``` diff --git a/gitbook/tutorial/debugging&IDE-support/README.md b/gitbook/tutorial/debugging&IDE-support/README.md new file mode 100644 index 0000000000..e03d0e7a92 --- /dev/null +++ b/gitbook/tutorial/debugging&IDE-support/README.md @@ -0,0 +1,3 @@ +# debugging & IDE support + +Has concern about debugging when it comes to a newly emerging technique like wasm? No worries, we got you covered. You could either [debug directly with lldb](../../../doc/source_debugging.md), or you could even [debug using VS Code](../../../test-tools/wamr-ide/README.md) diff --git a/gitbook/tutorial/language-embedding/README.md b/gitbook/tutorial/language-embedding/README.md new file mode 100644 index 0000000000..14c92a22f1 --- /dev/null +++ b/gitbook/tutorial/language-embedding/README.md @@ -0,0 +1,9 @@ +# language embedding + +As we mentioned before, WAMR is not only a server-side runtime for a wasm application but also a library that you could embed in your application. What's even better is that we support several programming languages so that you can choose your favorite language to embed WAMR to run the wasm app. + +The language WAMR support embedding: + +- [C/C++](../../../doc/embed_wamr.md) +- [Python](../../../language-bindings/python/README.md) +- [Go](../../../language-bindings/go/README.md) diff --git a/gitbook/tutorial/running-modes/README.md b/gitbook/tutorial/running-modes/README.md new file mode 100644 index 0000000000..c5f3c909d5 --- /dev/null +++ b/gitbook/tutorial/running-modes/README.md @@ -0,0 +1,29 @@ +--- +description: "This page is under construction/refinement. p.s. wanna hear a construction joke? we are still working on it" +--- + +# WAMR Running Modes + +## Brief Introduction + +In this section, we want to introduce running modes and their difference to you + +### "iwasm" VM core running mode + +It could run an AOT file(compiled by wamrc AOT compiler) in AOT running mode + +- AOT: Ahead-of-Time compilation. As you can guess from the name, we first need to use the *wamrc* compiler to compile wasm file to the AOT file. Then it could be run with our *iwasm* vmcore. In this running mode, we could achieve the nearly native speed(the best of all running modes) with very small footprint and quick startup + +It could run wasm applications in Interpreter/JIT running mode: + +- Interpreter: + Interpreters are very useful when debugging or studying, but their performance is relatively poor compared with other running modes. We support two running modes of the interpreter: + - Classic Interpreter: plain interpreter running mode + - Fast Interpreter: as you can guess from the name, the fast interpreter runs ~2X faster than the classic interpreter but consumes about 2X memory to hold the pre-compiled code. +- JIT: + Using the Just-in-Time compilation technique, we could make iwasm run much faster than Interpreter mode and sometimes very close to the speed of AOT running mode. We support two running modes of JIT: + - LLVM JIT: the JIT engine is implemented based on LLVM codegen. The performance of LLVM JIT is better than Fast JIT, with ~2x of the latter. But the startup time is slower than Fast JIT. + - Fast JIT: the JIT engine is implemented based on self-implemented codegen and asmjit encoder library. It is a lightweight JIT engine with small footprint, quick startup, good portability and relatively good performance. Currently it supports x86-64 target and Linux/Linux-SGX/MacOS platforms. The performance of Fast JIT is ~50% of the performance of LLVM JIT. + + +For more detailed introduction, kindly refer to this article(**incoming**) in our blog. diff --git a/samples/basic/README.md b/samples/basic/README.md index 32e7ed6501..45530ff7f1 100644 --- a/samples/basic/README.md +++ b/samples/basic/README.md @@ -1,4 +1,6 @@ - +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/basic" +--- The "basic" sample project ============== diff --git a/samples/file/README.md b/samples/file/README.md index 98f0cc3a71..a90892ead0 100644 --- a/samples/file/README.md +++ b/samples/file/README.md @@ -1,3 +1,6 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/file" +--- # "file" sample introduction This sample demonstrates the supported file interaction API of WASI. diff --git a/samples/multi-module/README.md b/samples/multi-module/README.md index 5aac0a5f45..8e5d8fe8fc 100644 --- a/samples/multi-module/README.md +++ b/samples/multi-module/README.md @@ -1,3 +1,6 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/multi-module" +--- # WAMR MULTI-MODUEL SAMPLE **WAMR supports *multi-module* in both *interpreter* mode and *aot* mode.** diff --git a/samples/multi-thread/README.md b/samples/multi-thread/README.md new file mode 100644 index 0000000000..ccd23730ee --- /dev/null +++ b/samples/multi-thread/README.md @@ -0,0 +1,3 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/multi-thread" +--- \ No newline at end of file diff --git a/samples/native-lib/README.md b/samples/native-lib/README.md index 8af01b23ca..2ce5e8ff62 100644 --- a/samples/native-lib/README.md +++ b/samples/native-lib/README.md @@ -1,3 +1,6 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/native-lib" +--- # "native-lib" sample introduction This sample demonstrates how to write required interfaces in native library, build it into a shared library and register the shared library to iwasm. diff --git a/samples/ref-types/README.md b/samples/ref-types/README.md new file mode 100644 index 0000000000..d8eb205cca --- /dev/null +++ b/samples/ref-types/README.md @@ -0,0 +1,3 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/ref-types" +--- \ No newline at end of file diff --git a/samples/sgx-ra/README.md b/samples/sgx-ra/README.md index 179a074b87..42240b303f 100644 --- a/samples/sgx-ra/README.md +++ b/samples/sgx-ra/README.md @@ -1,3 +1,6 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/sgx-ra" +--- "sgx-ra" sample introduction ============== diff --git a/samples/socket-api/README.md b/samples/socket-api/README.md index f172c5b172..1122967c09 100644 --- a/samples/socket-api/README.md +++ b/samples/socket-api/README.md @@ -1,3 +1,6 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/socket-api" +--- # "socket-api" sample introduction This sample demonstrates how to use WAMR socket-api to develop wasm network applications. diff --git a/samples/spawn-thread/README.md b/samples/spawn-thread/README.md new file mode 100644 index 0000000000..ec32364710 --- /dev/null +++ b/samples/spawn-thread/README.md @@ -0,0 +1,3 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/spawn-thread" +--- \ No newline at end of file diff --git a/samples/wasm-c-api/README.md b/samples/wasm-c-api/README.md index 22595d1559..205c57b1a0 100644 --- a/samples/wasm-c-api/README.md +++ b/samples/wasm-c-api/README.md @@ -1,3 +1,6 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/wasm-c-api" +--- WAMR supports *wasm-c-api* in both *interpreter* mode and *aot* mode. Before staring, we need to download and install [WABT](https://github.com/WebAssembly/wabt/releases/latest). diff --git a/samples/workload/README.md b/samples/workload/README.md index af13d5d3e9..8f9371723e 100644 --- a/samples/workload/README.md +++ b/samples/workload/README.md @@ -1,3 +1,6 @@ +--- +description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/workload" +--- All workloads have similar requirement of software dependencies, including **emsdk** and **binaryen** > There might be slight differences when using MacOS and other Linux distro than Ubuntu. This document targets