From 2b353bc99c6a7cd062835a7df31fe859aa690bf2 Mon Sep 17 00:00:00 2001 From: TianlongLiang <111852609+TianlongLiang@users.noreply.github.com> Date: Mon, 21 Nov 2022 16:36:33 +0800 Subject: [PATCH 1/5] Import Gitbook v1.0 (#1732) Modify existing documents, add markdown files for Gitbook to generate the webpage --- gitbook/advance-tutorial/README.md | 7 + .../performance-benchmark/README.md | 18 + .../remote-applicatoin-management/README.md | 7 + gitbook/appendix/background_knowledge.md | 61 + gitbook/appendix/webassembly_details.md | 6 + gitbook/basics/getting-started/README.md | 13 + .../getting-started/host_prerequsites.md | 40 + gitbook/basics/getting-started/on_docker.md | 26 + gitbook/basics/getting-started/on_host.md | 26 + gitbook/basics/introduction/README.md | 5 + gitbook/basics/introduction/wamr_project.md | 65 + gitbook/basics/introduction/webassembly.md | 29 + gitbook/examples/README.md | 11 + gitbook/features/README.md | 39 + gitbook/features/demo-examples/README.md | 15 + gitbook/features/user-case/README.md | 10 + gitbook/home_page.md | 15 + gitbook/programmer's-manual/C_API_Lists.md | 1186 +++++++++++++++++ gitbook/programmer's-manual/README.md | 6 + gitbook/tutorial/README.md | 9 + gitbook/tutorial/build-tutorial/README.md | 36 + .../tutorial/build-tutorial/build_wamrc.md | 23 + .../tutorial/debugging&IDE-support/README.md | 3 + gitbook/tutorial/language-embedding/README.md | 9 + gitbook/tutorial/running-modes/README.md | 29 + samples/basic/README.md | 4 +- samples/file/README.md | 3 + samples/multi-module/README.md | 3 + samples/multi-thread/README.md | 3 + samples/native-lib/README.md | 3 + samples/ref-types/README.md | 3 + samples/sgx-ra/README.md | 3 + samples/socket-api/README.md | 3 + samples/spawn-thread/README.md | 3 + samples/wasm-c-api/README.md | 3 + samples/workload/README.md | 3 + 36 files changed, 1727 insertions(+), 1 deletion(-) create mode 100644 gitbook/advance-tutorial/README.md create mode 100644 gitbook/advance-tutorial/performance-benchmark/README.md create mode 100644 gitbook/advance-tutorial/remote-applicatoin-management/README.md create mode 100644 gitbook/appendix/background_knowledge.md create mode 100644 gitbook/appendix/webassembly_details.md create mode 100644 gitbook/basics/getting-started/README.md create mode 100644 gitbook/basics/getting-started/host_prerequsites.md create mode 100644 gitbook/basics/getting-started/on_docker.md create mode 100644 gitbook/basics/getting-started/on_host.md create mode 100644 gitbook/basics/introduction/README.md create mode 100644 gitbook/basics/introduction/wamr_project.md create mode 100644 gitbook/basics/introduction/webassembly.md create mode 100644 gitbook/examples/README.md create mode 100644 gitbook/features/README.md create mode 100644 gitbook/features/demo-examples/README.md create mode 100644 gitbook/features/user-case/README.md create mode 100644 gitbook/home_page.md create mode 100644 gitbook/programmer's-manual/C_API_Lists.md create mode 100644 gitbook/programmer's-manual/README.md create mode 100644 gitbook/tutorial/README.md create mode 100644 gitbook/tutorial/build-tutorial/README.md create mode 100644 gitbook/tutorial/build-tutorial/build_wamrc.md create mode 100644 gitbook/tutorial/debugging&IDE-support/README.md create mode 100644 gitbook/tutorial/language-embedding/README.md create mode 100644 gitbook/tutorial/running-modes/README.md create mode 100644 samples/multi-thread/README.md create mode 100644 samples/ref-types/README.md create mode 100644 samples/spawn-thread/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..3a4f3352df --- /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-recommen +``` + +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..93bb7d56fa --- /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..52e674d23d --- /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..794019d4ed --- /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). + +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/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..6b60ea0acb --- /dev/null +++ b/gitbook/basics/introduction/webassembly.md @@ -0,0 +1,29 @@ +# 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) + +## The origin story of WebAssembly + +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. + +## The other benefits of WebAssembly + +Other than aiming for performance improvement, the other WebAssembly could benefit us by reusing the code in your preferred programming language other than JavaScript. Many programmers from the C/C++ world are excited to utilize the existing code base of their apps or libraries and bring them onto the Web. + +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..e9ccae2d02 --- /dev/null +++ b/gitbook/programmer's-manual/C_API_Lists.md @@ -0,0 +1,1186 @@ +# Complete C/C++ API Lists + +```C +/* + * Copyright (C) 2019 Intel Corporation. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + */ + +#ifndef _WASM_EXPORT_H +#define _WASM_EXPORT_H + +#include +#include +#include "lib_export.h" + +#ifndef WASM_RUNTIME_API_EXTERN +#if defined(_MSC_BUILD) +#if defined(COMPILING_WASM_RUNTIME_API) +#define WASM_RUNTIME_API_EXTERN __declspec(dllexport) +#else +#define WASM_RUNTIME_API_EXTERN __declspec(dllimport) +#endif +#else +#define WASM_RUNTIME_API_EXTERN +#endif +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/* clang-format off */ + +#define get_module_inst(exec_env) \ + wasm_runtime_get_module_inst(exec_env) + +#define validate_app_addr(offset, size) \ + wasm_runtime_validate_app_addr(module_inst, offset, size) + +#define validate_app_str_addr(offset) \ + wasm_runtime_validate_app_str_addr(module_inst, offset) + +#define addr_app_to_native(offset) \ + wasm_runtime_addr_app_to_native(module_inst, offset) + +#define addr_native_to_app(ptr) \ + wasm_runtime_addr_native_to_app(module_inst, ptr) + +#define module_malloc(size, p_native_addr) \ + wasm_runtime_module_malloc(module_inst, size, p_native_addr) + +#define module_free(offset) \ + wasm_runtime_module_free(module_inst, offset) + +#define native_raw_return_type(type, args) type *raw_ret = (type *)(args) + +#define native_raw_get_arg(type, name, args) type name = *((type *)(args++)) + +#define native_raw_set_return(val) *raw_ret = (val) + +#ifndef WASM_MODULE_T_DEFINED +#define WASM_MODULE_T_DEFINED +/* Uninstantiated WASM module loaded from WASM binary file + or AoT binary file*/ +struct WASMModuleCommon; +typedef struct WASMModuleCommon *wasm_module_t; +#endif + +/* Instantiated WASM module */ +struct WASMModuleInstanceCommon; +typedef struct WASMModuleInstanceCommon *wasm_module_inst_t; + +/* Function instance */ +typedef void WASMFunctionInstanceCommon; +typedef WASMFunctionInstanceCommon *wasm_function_inst_t; + +/* WASM section */ +typedef struct wasm_section_t { + struct wasm_section_t *next; + /* section type */ + int section_type; + /* section body, not include type and size */ + uint8_t *section_body; + /* section body size */ + uint32_t section_body_size; +} wasm_section_t, aot_section_t, *wasm_section_list_t, *aot_section_list_t; + +/* Execution environment, e.g. stack info */ +struct WASMExecEnv; +typedef struct WASMExecEnv *wasm_exec_env_t; + +/* Package Type */ +typedef enum { + Wasm_Module_Bytecode = 0, + Wasm_Module_AoT, + Package_Type_Unknown = 0xFFFF +} package_type_t; + +#ifndef MEM_ALLOC_OPTION_DEFINED +#define MEM_ALLOC_OPTION_DEFINED +/* Memory allocator type */ +typedef enum { + /* pool mode, allocate memory from user defined heap buffer */ + Alloc_With_Pool = 0, + /* user allocator mode, allocate memory from user defined + malloc function */ + Alloc_With_Allocator, + /* system allocator mode, allocate memory from system allocator, + or, platform's os_malloc function */ + Alloc_With_System_Allocator, +} mem_alloc_type_t; + +/* Memory allocator option */ +typedef union MemAllocOption { + struct { + void *heap_buf; + uint32_t heap_size; + } pool; + struct { + void *malloc_func; + void *realloc_func; + void *free_func; + } allocator; +} MemAllocOption; +#endif + +/* Memory pool info */ +typedef struct mem_alloc_info_t { + uint32_t total_size; + uint32_t total_free_size; + uint32_t highmark_size; +} mem_alloc_info_t; + +/* WASM runtime initialize arguments */ +typedef struct RuntimeInitArgs { + mem_alloc_type_t mem_alloc_type; + MemAllocOption mem_alloc_option; + + const char *native_module_name; + NativeSymbol *native_symbols; + uint32_t n_native_symbols; + + /* maximum thread number, only used when + WASM_ENABLE_THREAD_MGR is defined */ + uint32_t max_thread_num; + + /* Debug settings, only used when + WASM_ENABLE_DEBUG_INTERP != 0 */ + char ip_addr[128]; + int unused; /* was platform_port */ + int instance_port; + + /* Fast JIT code cache size */ + uint32_t fast_jit_code_cache_size; +} RuntimeInitArgs; + +#ifndef WASM_VALKIND_T_DEFINED +#define WASM_VALKIND_T_DEFINED +typedef uint8_t wasm_valkind_t; +enum wasm_valkind_enum { + WASM_I32, + WASM_I64, + WASM_F32, + WASM_F64, + WASM_ANYREF = 128, + WASM_FUNCREF, +}; +#endif + +#ifndef WASM_VAL_T_DEFINED +#define WASM_VAL_T_DEFINED + +typedef struct wasm_val_t { + wasm_valkind_t kind; + union { + /* also represent a function index */ + int32_t i32; + int64_t i64; + float f32; + double f64; + /* represent a foreign object, aka externref in .wat */ + uintptr_t foreign; + } of; +} wasm_val_t; +#endif + +/** + * Initialize the WASM runtime environment, and also initialize + * the memory allocator with system allocator, which calls os_malloc + * to allocate memory + * + * @return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_init(void); + +/** + * Initialize the WASM runtime environment, and also initialize + * the memory allocator and register native symbols, which are specified + * with init arguments + * + * @param init_args specifies the init arguments + * + * @return return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_full_init(RuntimeInitArgs *init_args); + +/** + * Destroy the WASM runtime environment. + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_destroy(void); + +/** + * Allocate memory from runtime memory environment. + * + * @param size bytes need to allocate + * + * @return the pointer to memory allocated + */ +WASM_RUNTIME_API_EXTERN void * +wasm_runtime_malloc(unsigned int size); + +/** + * Reallocate memory from runtime memory environment + * + * @param ptr the original memory + * @param size bytes need to reallocate + * + * @return the pointer to memory reallocated + */ +WASM_RUNTIME_API_EXTERN void * +wasm_runtime_realloc(void *ptr, unsigned int size); + +/* + * Free memory to runtime memory environment. + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_free(void *ptr); + +/* + * Get memory info, only pool mode is supported now. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_get_mem_alloc_info(mem_alloc_info_t *mem_alloc_info); + +/** + * Get the package type of a buffer. + * + * @param buf the package buffer + * @param size the package buffer size + * + * @return the package type, return Package_Type_Unknown if the type is unknown + */ +WASM_RUNTIME_API_EXTERN package_type_t +get_package_type(const uint8_t *buf, uint32_t size); + +/** + * Check whether a file is an AOT XIP (Execution In Place) file + * + * @param buf the package buffer + * @param size the package buffer size + * + * @return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_is_xip_file(const uint8_t *buf, uint32_t size); + +/** + * Callback to load a module file into a buffer in multi-module feature + */ +typedef bool (*module_reader)(const char *module_name, + uint8_t **p_buffer, uint32_t *p_size); + +/** + * Callback to release the buffer loaded by module_reader callback + */ +typedef void (*module_destroyer)(uint8_t *buffer, uint32_t size); + +/** + * Setup callbacks for reading and releasing a buffer about a module file + * + * @param reader a callback to read a module file into a buffer + * @param destroyer a callback to release above buffer + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_module_reader(const module_reader reader, + const module_destroyer destroyer); +/** + * Give the "module" a name "module_name". + * Can not assign a new name to a module if it already has a name + * + * @param module_name indicate a name + * @param module the target module + * @param error_buf output of the exception info + * @param error_buf_size the size of the exception string + * + * @return true means success, false means failed + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_register_module(const char *module_name, wasm_module_t module, + char *error_buf, uint32_t error_buf_size); + +/** + * Check if there is already a loaded module named module_name in the + * runtime. Repeately loading a module with the same name is not allowed. + * + * @param module_name indicate a name + * + * @return return WASM module loaded, NULL if failed + */ +WASM_RUNTIME_API_EXTERN wasm_module_t +wasm_runtime_find_module_registered(const char *module_name); + +/** + * Load a WASM module from a specified byte buffer. The byte buffer can be + * WASM binary data when interpreter or JIT is enabled, or AOT binary data + * when AOT is enabled. If it is AOT binary data, it must be 4-byte aligned. + * + * Note: In case of AOT XIP modules, the runtime doesn't make modifications + * to the buffer. (Except the "Known issues" mentioned in doc/xip.md.) + * Otherwise, the runtime can make modifications to the buffer for its + * internal purposes. Thus, in general, it isn't safe to create multiple + * modules from a single buffer. + * + * @param buf the byte buffer which contains the WASM/AOT binary data, + * note that the byte buffer must be writable since runtime may + * change its content for footprint and performance purpose, and + * it must be referencable until wasm_runtime_unload is called + * @param size the size of the buffer + * @param error_buf output of the exception info + * @param error_buf_size the size of the exception string + * + * @return return WASM module loaded, NULL if failed + */ +WASM_RUNTIME_API_EXTERN wasm_module_t +wasm_runtime_load(uint8_t *buf, uint32_t size, + char *error_buf, uint32_t error_buf_size); + +/** + * Load a WASM module from a specified WASM or AOT section list. + * + * @param section_list the section list which contains each section data + * @param is_aot whether the section list is AOT section list + * @param error_buf output of the exception info + * @param error_buf_size the size of the exception string + * + * @return return WASM module loaded, NULL if failed + */ +WASM_RUNTIME_API_EXTERN wasm_module_t +wasm_runtime_load_from_sections(wasm_section_list_t section_list, bool is_aot, + char *error_buf, uint32_t error_buf_size); + +/** + * Unload a WASM module. + * + * @param module the module to be unloaded + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_unload(wasm_module_t module); + +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_wasi_args_ex(wasm_module_t module, + const char *dir_list[], uint32_t dir_count, + const char *map_dir_list[], uint32_t map_dir_count, + const char *env[], uint32_t env_count, + char *argv[], int argc, + int stdinfd, int stdoutfd, int stderrfd); + +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_wasi_args(wasm_module_t module, + const char *dir_list[], uint32_t dir_count, + const char *map_dir_list[], uint32_t map_dir_count, + const char *env[], uint32_t env_count, + char *argv[], int argc); + +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_wasi_addr_pool(wasm_module_t module, const char *addr_pool[], + uint32_t addr_pool_size); + +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_wasi_ns_lookup_pool(wasm_module_t module, const char *ns_lookup_pool[], + uint32_t ns_lookup_pool_size); + +/** + * Instantiate a WASM module. + * + * @param module the WASM module to instantiate + * @param stack_size the default stack size of the module instance when the + * exec env's operation stack isn't created by user, e.g. API + * wasm_application_execute_main() and wasm_application_execute_func() + * create the operation stack internally with the stack size specified + * here. And API wasm_runtime_create_exec_env() creates the operation + * stack with stack size specified by its parameter, the stack size + * specified here is ignored. + * @param heap_size the default heap size of the module instance, a heap will + * be created besides the app memory space. Both wasm app and native + * function can allocate memory from the heap. + * @param error_buf buffer to output the error info if failed + * @param error_buf_size the size of the error buffer + * + * @return return the instantiated WASM module instance, NULL if failed + */ +WASM_RUNTIME_API_EXTERN wasm_module_inst_t +wasm_runtime_instantiate(const wasm_module_t module, + uint32_t stack_size, uint32_t heap_size, + char *error_buf, uint32_t error_buf_size); + +/** + * Deinstantiate a WASM module instance, destroy the resources. + * + * @param module_inst the WASM module instance to destroy + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_deinstantiate(wasm_module_inst_t module_inst); + +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_is_wasi_mode(wasm_module_inst_t module_inst); + +WASM_RUNTIME_API_EXTERN wasm_function_inst_t +wasm_runtime_lookup_wasi_start_function(wasm_module_inst_t module_inst); + +/** + * Lookup an exported function in the WASM module instance. + * + * @param module_inst the module instance + * @param name the name of the function + * @param signature the signature of the function, ignored currently + * + * @return the function instance found, NULL if not found + */ +WASM_RUNTIME_API_EXTERN wasm_function_inst_t +wasm_runtime_lookup_function(wasm_module_inst_t const module_inst, + const char *name, const char *signature); + +/** + * Get parameter count of the function instance + * + * @param func_inst the function instance + * @param module_inst the module instance the function instance belongs to + * + * @return the parameter count of the function instance + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_func_get_param_count(wasm_function_inst_t const func_inst, + wasm_module_inst_t const module_inst); + +/** + * Get result count of the function instance + * + * @param func_inst the function instance + * @param module_inst the module instance the function instance belongs to + * + * @return the result count of the function instance + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_func_get_result_count(wasm_function_inst_t const func_inst, + wasm_module_inst_t const module_inst); + +/** + * Get parameter types of the function instance + * + * @param func_inst the function instance + * @param module_inst the module instance the function instance belongs to + * @param param_types the parameter types returned + */ +WASM_RUNTIME_API_EXTERN void +wasm_func_get_param_types(wasm_function_inst_t const func_inst, + wasm_module_inst_t const module_inst, + wasm_valkind_t *param_types); + +/** + * Get result types of the function instance + * + * @param func_inst the function instance + * @param module_inst the module instance the function instance belongs to + * @param result_types the result types returned + */ +WASM_RUNTIME_API_EXTERN void +wasm_func_get_result_types(wasm_function_inst_t const func_inst, + wasm_module_inst_t const module_inst, + wasm_valkind_t *result_types); + +/** + * Create execution environment for a WASM module instance. + * + * @param module_inst the module instance + * @param stack_size the stack size to execute a WASM function + * + * @return the execution environment, NULL if failed, e.g. invalid + * stack size is passed + */ +WASM_RUNTIME_API_EXTERN wasm_exec_env_t +wasm_runtime_create_exec_env(wasm_module_inst_t module_inst, + uint32_t stack_size); + +/** + * Destroy the execution environment. + * + * @param exec_env the execution environment to destroy + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_destroy_exec_env(wasm_exec_env_t exec_env); + +/** + * Get the singleton execution environment for the instance. + * + * Note: The singleton execution environment is the execution + * environment used internally by the runtime for the API functions + * like wasm_application_execute_main, which don't take explicit + * execution environment. It's associated to the corresponding + * module instance and managed by the runtime. The API user should + * not destroy it with wasm_runtime_destroy_exec_env. + * + * @param module_inst the module instance + * + * @return exec_env the execution environment to destroy + */ +WASM_RUNTIME_API_EXTERN wasm_exec_env_t +wasm_runtime_get_exec_env_singleton(wasm_module_inst_t module_inst); + +/** + * Start debug instance based on given execution environment. + * Note: + * The debug instance will be destroyed during destroying the + * execution environment, developers don't need to destroy it + * manually. + * If the cluster of this execution environment has already + * been bound to a debug instance, this function will return true + * directly. + * If developer spawns some exec_env by wasm_runtime_spawn_exec_env, + * don't need to call this function for every spawned exec_env as + * they are sharing the same cluster with the main exec_env. + * + * @param exec_env the execution environment to start debug instance + * @param port the port for the debug server to listen on. + * 0 means automatic assignment. + * -1 means to use the global setting in RuntimeInitArgs. + * + * @return debug port if success, 0 otherwise. + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_runtime_start_debug_instance_with_port(wasm_exec_env_t exec_env, int32_t port); + +/** + * Same as wasm_runtime_start_debug_instance_with_port(env, -1). + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_runtime_start_debug_instance(wasm_exec_env_t exec_env); + +/** + * Initialize the thread environment. + * Note: + * If developer creates a child thread by himself to call the + * the wasm function in that thread, he should call this API + * firstly before calling the wasm function and then call + * wasm_runtime_destroy_thread_env() after calling the wasm + * function. If the thread is created from the runtime API, + * it is unnecessary to call these two APIs. + * + * @return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_init_thread_env(void); + +/** + * Destroy the thread environment + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_destroy_thread_env(void); + +/** + * Whether the thread environment is initialized + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_thread_env_inited(void); + +/** + * Get WASM module instance from execution environment + * + * @param exec_env the execution environment to retrieve + * + * @return the WASM module instance + */ +WASM_RUNTIME_API_EXTERN wasm_module_inst_t +wasm_runtime_get_module_inst(wasm_exec_env_t exec_env); + +/** + * Set WASM module instance of execution environment + * Caution: + * normally the module instance is bound with the execution + * environment one by one, if multiple module instances want + * to share to the same execution environment, developer should + * be responsible for the backup and restore of module instance + * + * @param exec_env the execution environment + * @param module_inst the WASM module instance to set + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_module_inst(wasm_exec_env_t exec_env, + const wasm_module_inst_t module_inst); + +/** + * Call the given WASM function of a WASM module instance with + * arguments (bytecode and AoT). + * + * @param exec_env the execution environment to call the function, + * which must be created from wasm_create_exec_env() + * @param function the function to call + * @param argc total cell number that the function parameters occupy, + * a cell is a slot of the uint32 array argv[], e.g. i32/f32 argument + * occupies one cell, i64/f64 argument occupies two cells, note that + * it might be different from the parameter number of the function + * @param argv the arguments. If the function has return value, + * the first (or first two in case 64-bit return value) element of + * argv stores the return value of the called WASM function after this + * function returns. + * + * @return true if success, false otherwise and exception will be thrown, + * the caller can call wasm_runtime_get_exception to get the exception + * info. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_call_wasm(wasm_exec_env_t exec_env, + wasm_function_inst_t function, + uint32_t argc, uint32_t argv[]); + +/** + * Call the given WASM function of a WASM module instance with + * provided results space and arguments (bytecode and AoT). + * + * @param exec_env the execution environment to call the function, + * which must be created from wasm_create_exec_env() + * @param function the function to call + * @param num_results the number of results + * @param results the pre-alloced pointer to get the results + * @param num_args the number of arguments + * @param args the arguments + * + * @return true if success, false otherwise and exception will be thrown, + * the caller can call wasm_runtime_get_exception to get the exception + * info. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_call_wasm_a(wasm_exec_env_t exec_env, + wasm_function_inst_t function, + uint32_t num_results, wasm_val_t results[], + uint32_t num_args, wasm_val_t *args); + +/** + * Call the given WASM function of a WASM module instance with + * provided results space and variant arguments (bytecode and AoT). + * + * @param exec_env the execution environment to call the function, + * which must be created from wasm_create_exec_env() + * @param function the function to call + * @param num_results the number of results + * @param results the pre-alloced pointer to get the results + * @param num_args the number of arguments + * @param ... the variant arguments + * + * @return true if success, false otherwise and exception will be thrown, + * the caller can call wasm_runtime_get_exception to get the exception + * info. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_call_wasm_v(wasm_exec_env_t exec_env, + wasm_function_inst_t function, + uint32_t num_results, wasm_val_t results[], + uint32_t num_args, ...); + +/** + * Find the unique main function from a WASM module instance + * and execute that function. + * + * @param module_inst the WASM module instance + * @param argc the number of arguments + * @param argv the arguments array, if the main function has return value, + * *(int*)argv stores the return value of the called main function after + * this function returns. + * + * @return true if the main function is called, false otherwise and exception + * will be thrown, the caller can call wasm_runtime_get_exception to get + * the exception info. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_application_execute_main(wasm_module_inst_t module_inst, + int32_t argc, char *argv[]); + +/** + * Find the specified function in argv[0] from a WASM module instance + * and execute that function. + * + * @param module_inst the WASM module instance + * @param name the name of the function to execute. + * to indicate the module name via: $module_name$function_name + * or just a function name: function_name + * @param argc the number of arguments + * @param argv the arguments array + * + * @return true if the specified function is called, false otherwise and + * exception will be thrown, the caller can call wasm_runtime_get_exception + * to get the exception info. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_application_execute_func(wasm_module_inst_t module_inst, + const char *name, int32_t argc, char *argv[]); +/** + * Get exception info of the WASM module instance. + * + * @param module_inst the WASM module instance + * + * @return the exception string + */ +WASM_RUNTIME_API_EXTERN const char * +wasm_runtime_get_exception(wasm_module_inst_t module_inst); + +/** + * Set exception info of the WASM module instance. + * + * @param module_inst the WASM module instance + * + * @param exception the exception string + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_exception(wasm_module_inst_t module_inst, + const char *exception); + +/** + * Clear exception info of the WASM module instance. + * + * @param module_inst the WASM module instance + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_clear_exception(wasm_module_inst_t module_inst); + +/** + * Set custom data to WASM module instance. + * Note: + * If WAMR_BUILD_LIB_PTHREAD is enabled, this API + * will spread the custom data to all threads + * + * @param module_inst the WASM module instance + * @param custom_data the custom data to be set + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_custom_data(wasm_module_inst_t module_inst, + void *custom_data); +/** + * Get the custom data within a WASM module instance. + * + * @param module_inst the WASM module instance + * + * @return the custom data (NULL if not set yet) + */ +WASM_RUNTIME_API_EXTERN void * +wasm_runtime_get_custom_data(wasm_module_inst_t module_inst); + +/** + * Allocate memory from the heap of WASM module instance + * + * Note: wasm_runtime_module_malloc can call heap functions inside + * the module instance and thus cause a memory growth. + * This API needs to be used very carefully when you have a native + * pointers to the module instance memory obtained with + * wasm_runtime_addr_app_to_native or similar APIs. + * + * @param module_inst the WASM module instance which contains heap + * @param size the size bytes to allocate + * @param p_native_addr return native address of the allocated memory + * if it is not NULL, and return NULL if memory malloc failed + * + * @return the allocated memory address, which is a relative offset to the + * base address of the module instance's memory space. Note that + * it is not an absolute address. + * Return non-zero if success, zero if failed. + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_runtime_module_malloc(wasm_module_inst_t module_inst, uint32_t size, + void **p_native_addr); + +/** + * Free memory to the heap of WASM module instance + * + * @param module_inst the WASM module instance which contains heap + * @param ptr the pointer to free + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_module_free(wasm_module_inst_t module_inst, uint32_t ptr); + +/** + * Allocate memory from the heap of WASM module instance and initialize + * the memory with src + * + * @param module_inst the WASM module instance which contains heap + * @param src the source data to copy + * @param size the size of the source data + * + * @return the allocated memory address, which is a relative offset to the + * base address of the module instance's memory space. Note that + * it is not an absolute address. + * Return non-zero if success, zero if failed. + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_runtime_module_dup_data(wasm_module_inst_t module_inst, + const char *src, uint32_t size); + +/** + * Validate the app address, check whether it belongs to WASM module + * instance's address space, or in its heap space or memory space. + * + * @param module_inst the WASM module instance + * @param app_offset the app address to validate, which is a relative address + * @param size the size bytes of the app address + * + * @return true if success, false otherwise. If failed, an exception will + * be thrown. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_validate_app_addr(wasm_module_inst_t module_inst, + uint32_t app_offset, uint32_t size); + +/** + * Similar to wasm_runtime_validate_app_addr(), except that the size parameter + * is not provided. This function validates the app string address, check + * whether it belongs to WASM module instance's address space, or in its heap + * space or memory space. Moreover, it checks whether it is the offset of a + * string that is end with '\0'. + * + * Note: The validation result, especially the NUL termination check, + * is not reliable for a module instance with multiple threads because + * other threads can modify the heap behind us. + * + * @param module_inst the WASM module instance + * @param app_str_offset the app address of the string to validate, which is a + * relative address + * + * @return true if success, false otherwise. If failed, an exception will + * be thrown. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_validate_app_str_addr(wasm_module_inst_t module_inst, + uint32_t app_str_offset); + +/** + * Validate the native address, check whether it belongs to WASM module + * instance's address space, or in its heap space or memory space. + * + * @param module_inst the WASM module instance + * @param native_ptr the native address to validate, which is an absolute + * address + * @param size the size bytes of the app address + * + * @return true if success, false otherwise. If failed, an exception will + * be thrown. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_validate_native_addr(wasm_module_inst_t module_inst, + void *native_ptr, uint32_t size); + +/** + * Convert app address(relative address) to native address(absolute address) + * + * Note that native addresses to module instance memory can be invalidated + * on a memory growth. (Except shared memory, whose native addresses are + * stable.) + * + * @param module_inst the WASM module instance + * @param app_offset the app adress + * + * @return the native address converted + */ +WASM_RUNTIME_API_EXTERN void * +wasm_runtime_addr_app_to_native(wasm_module_inst_t module_inst, + uint32_t app_offset); + +/** + * Convert native address(absolute address) to app address(relative address) + * + * @param module_inst the WASM module instance + * @param native_ptr the native address + * + * @return the app address converted + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_runtime_addr_native_to_app(wasm_module_inst_t module_inst, + void *native_ptr); + +/** + * Get the app address range (relative address) that a app address belongs to + * + * @param module_inst the WASM module instance + * @param app_offset the app address to retrieve + * @param p_app_start_offset buffer to output the app start offset if not NULL + * @param p_app_end_offset buffer to output the app end offset if not NULL + * + * @return true if success, false otherwise. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_get_app_addr_range(wasm_module_inst_t module_inst, + uint32_t app_offset, + uint32_t *p_app_start_offset, + uint32_t *p_app_end_offset); + +/** + * Get the native address range (absolute address) that a native address + * belongs to + * + * @param module_inst the WASM module instance + * @param native_ptr the native address to retrieve + * @param p_native_start_addr buffer to output the native start address + * if not NULL + * @param p_native_end_addr buffer to output the native end address + * if not NULL + * + * @return true if success, false otherwise. + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_get_native_addr_range(wasm_module_inst_t module_inst, + uint8_t *native_ptr, + uint8_t **p_native_start_addr, + uint8_t **p_native_end_addr); + +/** + * Register native functions with same module name + * + * Note: The array `native_symbols` should not be read-only because the + * library can modify it in-place. + * + * Note: After successful call of this function, the array `native_symbols` + * is owned by the library. + * + * @param module_name the module name of the native functions + * @param native_symbols specifies an array of NativeSymbol structures which + * contain the names, function pointers and signatures + * Note: WASM runtime will not allocate memory to clone the data, so + * user must ensure the array can be used forever + * Meanings of letters in function signature: + * 'i': the parameter is i32 type + * 'I': the parameter is i64 type + * 'f': the parameter is f32 type + * 'F': the parameter is f64 type + * 'r': the parameter is externref type, it should be a uintptr_t in host + * '*': the parameter is a pointer (i32 in WASM), and runtime will + * auto check its boundary before calling the native function. + * If it is followed by '~', the checked length of the pointer + * is gotten from the following parameter, if not, the checked + * length of the pointer is 1. + * '~': the parameter is the pointer's length with i32 type, and must + * follow after '*' + * '$': the parameter is a string (i32 in WASM), and runtime will + * auto check its boundary before calling the native function + * @param n_native_symbols specifies the number of native symbols in the array + * + * @return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_register_natives(const char *module_name, + NativeSymbol *native_symbols, + uint32_t n_native_symbols); + +/** + * Register native functions with same module name, similar to + * wasm_runtime_register_natives, the difference is that runtime passes raw + * arguments to native API, which means that the native API should be defined as + * void foo(wasm_exec_env_t exec_env, uint64 *args); + * and native API should extract arguments one by one from args array with macro + * native_raw_get_arg + * and write the return value back to args[0] with macro + * native_raw_return_type and native_raw_set_return + */ +WASM_RUNTIME_API_EXTERN bool +wasm_runtime_register_natives_raw(const char *module_name, + NativeSymbol *native_symbols, + uint32_t n_native_symbols); + +/** + * Get attachment of native function from execution environment + * + * @param exec_env the execution environment to retrieve + * + * @return the attachment of native function + */ +WASM_RUNTIME_API_EXTERN void * +wasm_runtime_get_function_attachment(wasm_exec_env_t exec_env); + +/** + * Set user data to execution environment. + * + * @param exec_env the execution environment + * @param user_data the user data to be set + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_user_data(wasm_exec_env_t exec_env, void *user_data); + +/** + * Get the user data within execution environment. + * + * @param exec_env the execution environment + * + * @return the user data (NULL if not set yet) + */ +WASM_RUNTIME_API_EXTERN void * +wasm_runtime_get_user_data(wasm_exec_env_t exec_env); + +/** + * Dump runtime memory consumption, including: + * Exec env memory consumption + * WASM module memory consumption + * WASM module instance memory consumption + * stack and app heap used info + * + * @param exec_env the execution environment + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_dump_mem_consumption(wasm_exec_env_t exec_env); + +/** + * Dump runtime performance profiler data of each function + * + * @param module_inst the WASM module instance to profile + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_dump_perf_profiling(wasm_module_inst_t module_inst); + +/* wasm thread callback function type */ +typedef void *(*wasm_thread_callback_t)(wasm_exec_env_t, void *); +/* wasm thread type */ +typedef uintptr_t wasm_thread_t; + +/** + * Set the max thread num per cluster. + * + * @param num maximum thread num + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_set_max_thread_num(uint32_t num); + +/** + * Spawn a new exec_env, the spawned exec_env + * can be used in other threads + * + * @param num the original exec_env + * + * @return the spawned exec_env if success, NULL otherwise + */ +WASM_RUNTIME_API_EXTERN wasm_exec_env_t +wasm_runtime_spawn_exec_env(wasm_exec_env_t exec_env); + +/** + * Destroy the spawned exec_env + * + * @param exec_env the spawned exec_env + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_destroy_spawned_exec_env(wasm_exec_env_t exec_env); + +/** + * Spawn a thread from the given exec_env + * + * @param exec_env the original exec_env + * @param tid thread id to be returned to the caller + * @param callback the callback function provided by the user + * @param arg the arguments passed to the callback + * + * @return 0 if success, -1 otherwise + */ +WASM_RUNTIME_API_EXTERN int32_t +wasm_runtime_spawn_thread(wasm_exec_env_t exec_env, wasm_thread_t *tid, + wasm_thread_callback_t callback, void *arg); + +/** + * Wait a spawned thread to terminate + * + * @param tid thread id + * @param retval if not NULL, output the return value of the thread + * + * @return 0 if success, error number otherwise + */ +WASM_RUNTIME_API_EXTERN int32_t +wasm_runtime_join_thread(wasm_thread_t tid, void **retval); + +/** + * Map external object to an internal externref index: if the index + * has been created, return it, otherwise create the index. + * + * @param module_inst the WASM module instance that the extern object + * belongs to + * @param extern_obj the external object to be mapped + * @param p_externref_idx return externref index of the external object + * + * @return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_externref_obj2ref(wasm_module_inst_t module_inst, + void *extern_obj, uint32_t *p_externref_idx); + +/** + * Retrieve the external object from an internal externref index + * + * @param externref_idx the externref index to retrieve + * @param p_extern_obj return the mapped external object of + * the externref index + * + * @return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_externref_ref2obj(uint32_t externref_idx, void **p_extern_obj); + +/** + * Retain an extern object which is mapped to the internal externref + * so that the object won't be cleaned during extern object reclaim + * if it isn't used. + * + * @param externref_idx the externref index of an external object + * to retain + * @return true if success, false otherwise + */ +WASM_RUNTIME_API_EXTERN bool +wasm_externref_retain(uint32_t externref_idx); + +/** + * Dump the call stack to stdout + * + * @param exec_env the execution environment + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_dump_call_stack(wasm_exec_env_t exec_env); + +/** + * Get the size required to store the call stack contents, including + * the space for terminating null byte ('\0') + * + * @param exec_env the execution environment + * + * @return size required to store the contents, 0 means error + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_runtime_get_call_stack_buf_size(wasm_exec_env_t exec_env); + +/** + * Dump the call stack to buffer. + * + * @note this function is not thread-safe, please only use this API + * when the exec_env is not executing + * + * @param exec_env the execution environment + * @param buf buffer to store the dumped content + * @param len length of the buffer + * + * @return bytes dumped to the buffer, including the terminating null + * byte ('\0'), 0 means error and data in buf may be invalid + */ +WASM_RUNTIME_API_EXTERN uint32_t +wasm_runtime_dump_call_stack_to_buf(wasm_exec_env_t exec_env, char *buf, + uint32_t len); + +/** + * Get a custom section by name + * + * @param module_comm the module to find + * @param name name of the custom section + * @param len return the length of the content if found + * + * @return Custom section content (not including the name length + * and name string) if found, NULL otherwise + */ +WASM_RUNTIME_API_EXTERN const uint8_t * +wasm_runtime_get_custom_section(wasm_module_t const module_comm, + const char *name, uint32_t *len); + + +/** + * Get WAMR semantic version + */ +WASM_RUNTIME_API_EXTERN void +wasm_runtime_get_version(uint32_t *major, uint32_t *minor, uint32_t *patch); +/* clang-format on */ + +#ifdef __cplusplus +} +#endif + +#endif /* end of _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 From 0ed955d37cbd9ec9a685c60fe3af6a2c94faa553 Mon Sep 17 00:00:00 2001 From: TianlongLiang <111852609+TianlongLiang@users.noreply.github.com> Date: Tue, 28 May 2024 17:12:57 +0800 Subject: [PATCH 2/5] Fix typo in documents (#3473) --- gitbook/basics/getting-started/host_prerequsites.md | 2 +- gitbook/basics/getting-started/on_host.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/gitbook/basics/getting-started/host_prerequsites.md b/gitbook/basics/getting-started/host_prerequsites.md index 3a4f3352df..d6ab33cf82 100644 --- a/gitbook/basics/getting-started/host_prerequsites.md +++ b/gitbook/basics/getting-started/host_prerequsites.md @@ -11,7 +11,7 @@ apt-get update \ 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-recommen + unzip valgrind vim wget zip --no-install-recommends ``` Then install CMake and wasi-sdk-16.0 diff --git a/gitbook/basics/getting-started/on_host.md b/gitbook/basics/getting-started/on_host.md index 52e674d23d..df8689ffb7 100644 --- a/gitbook/basics/getting-started/on_host.md +++ b/gitbook/basics/getting-started/on_host.md @@ -14,7 +14,7 @@ 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 +cp iwasm ../../../app-samples/hello-world cd ${WAMR-dir}/product-mini/app-samples/hello-world ./build.sh ``` From ad8c5f4dbdd8855368616471dff1f2cb6c95b703 Mon Sep 17 00:00:00 2001 From: JUNSEO PARK <50609962+HoyiTT@users.noreply.github.com> Date: Tue, 28 May 2024 18:15:21 +0900 Subject: [PATCH 3/5] Fix typo in on_docker.md (#3477) --- gitbook/basics/getting-started/on_docker.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gitbook/basics/getting-started/on_docker.md b/gitbook/basics/getting-started/on_docker.md index 93bb7d56fa..2dd7c77a71 100644 --- a/gitbook/basics/getting-started/on_docker.md +++ b/gitbook/basics/getting-started/on_docker.md @@ -14,8 +14,8 @@ 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 +cp iwasm ../../../app-samples/hello-world +cd ../../../app-samples/hello-world ./build.sh ``` From 06a06dee6806a01f73950d84d354959270bc8fc8 Mon Sep 17 00:00:00 2001 From: TianlongLiang <111852609+TianlongLiang@users.noreply.github.com> Date: Mon, 30 Sep 2024 14:41:28 +0800 Subject: [PATCH 4/5] update gitbook on security feature (#3824) --- SUMMARY.md | 90 +++++++++++ gitbook/basics/introduction/README.md | 2 +- .../basics/introduction/security_feature.md | 147 ++++++++++++++++++ gitbook/basics/introduction/webassembly.md | 31 +++- 4 files changed, 265 insertions(+), 5 deletions(-) create mode 100644 SUMMARY.md create mode 100644 gitbook/basics/introduction/security_feature.md 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/basics/introduction/README.md b/gitbook/basics/introduction/README.md index 794019d4ed..6886d072b8 100644 --- a/gitbook/basics/introduction/README.md +++ b/gitbook/basics/introduction/README.md @@ -1,5 +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). +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/webassembly.md b/gitbook/basics/introduction/webassembly.md index 6b60ea0acb..65e2fe3521 100644 --- a/gitbook/basics/introduction/webassembly.md +++ b/gitbook/basics/introduction/webassembly.md @@ -2,13 +2,36 @@ In this section, you will learn the basics of WebAssembly. More details about WebAssembly can be found in [Appendix B](../../appendix/webassembly_details.md) -## The origin story of WebAssembly +## 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. +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: -## The other benefits of WebAssembly +- 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. -Other than aiming for performance improvement, the other WebAssembly could benefit us by reusing the code in your preferred programming language other than JavaScript. Many programmers from the C/C++ world are excited to utilize the existing code base of their apps or libraries and bring them onto the Web. +- 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. From 5513d2455f91dbcba138d33b245f93902696e857 Mon Sep 17 00:00:00 2001 From: TL Date: Fri, 12 Sep 2025 17:19:44 +0800 Subject: [PATCH 5/5] update gitbook --- gitbook/programmer's-manual/C_API_Lists.md | 1185 +------------------- 1 file changed, 1 insertion(+), 1184 deletions(-) diff --git a/gitbook/programmer's-manual/C_API_Lists.md b/gitbook/programmer's-manual/C_API_Lists.md index e9ccae2d02..abaef36e81 100644 --- a/gitbook/programmer's-manual/C_API_Lists.md +++ b/gitbook/programmer's-manual/C_API_Lists.md @@ -1,1186 +1,3 @@ # Complete C/C++ API Lists -```C -/* - * Copyright (C) 2019 Intel Corporation. All rights reserved. - * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - */ - -#ifndef _WASM_EXPORT_H -#define _WASM_EXPORT_H - -#include -#include -#include "lib_export.h" - -#ifndef WASM_RUNTIME_API_EXTERN -#if defined(_MSC_BUILD) -#if defined(COMPILING_WASM_RUNTIME_API) -#define WASM_RUNTIME_API_EXTERN __declspec(dllexport) -#else -#define WASM_RUNTIME_API_EXTERN __declspec(dllimport) -#endif -#else -#define WASM_RUNTIME_API_EXTERN -#endif -#endif - -#ifdef __cplusplus -extern "C" { -#endif - -/* clang-format off */ - -#define get_module_inst(exec_env) \ - wasm_runtime_get_module_inst(exec_env) - -#define validate_app_addr(offset, size) \ - wasm_runtime_validate_app_addr(module_inst, offset, size) - -#define validate_app_str_addr(offset) \ - wasm_runtime_validate_app_str_addr(module_inst, offset) - -#define addr_app_to_native(offset) \ - wasm_runtime_addr_app_to_native(module_inst, offset) - -#define addr_native_to_app(ptr) \ - wasm_runtime_addr_native_to_app(module_inst, ptr) - -#define module_malloc(size, p_native_addr) \ - wasm_runtime_module_malloc(module_inst, size, p_native_addr) - -#define module_free(offset) \ - wasm_runtime_module_free(module_inst, offset) - -#define native_raw_return_type(type, args) type *raw_ret = (type *)(args) - -#define native_raw_get_arg(type, name, args) type name = *((type *)(args++)) - -#define native_raw_set_return(val) *raw_ret = (val) - -#ifndef WASM_MODULE_T_DEFINED -#define WASM_MODULE_T_DEFINED -/* Uninstantiated WASM module loaded from WASM binary file - or AoT binary file*/ -struct WASMModuleCommon; -typedef struct WASMModuleCommon *wasm_module_t; -#endif - -/* Instantiated WASM module */ -struct WASMModuleInstanceCommon; -typedef struct WASMModuleInstanceCommon *wasm_module_inst_t; - -/* Function instance */ -typedef void WASMFunctionInstanceCommon; -typedef WASMFunctionInstanceCommon *wasm_function_inst_t; - -/* WASM section */ -typedef struct wasm_section_t { - struct wasm_section_t *next; - /* section type */ - int section_type; - /* section body, not include type and size */ - uint8_t *section_body; - /* section body size */ - uint32_t section_body_size; -} wasm_section_t, aot_section_t, *wasm_section_list_t, *aot_section_list_t; - -/* Execution environment, e.g. stack info */ -struct WASMExecEnv; -typedef struct WASMExecEnv *wasm_exec_env_t; - -/* Package Type */ -typedef enum { - Wasm_Module_Bytecode = 0, - Wasm_Module_AoT, - Package_Type_Unknown = 0xFFFF -} package_type_t; - -#ifndef MEM_ALLOC_OPTION_DEFINED -#define MEM_ALLOC_OPTION_DEFINED -/* Memory allocator type */ -typedef enum { - /* pool mode, allocate memory from user defined heap buffer */ - Alloc_With_Pool = 0, - /* user allocator mode, allocate memory from user defined - malloc function */ - Alloc_With_Allocator, - /* system allocator mode, allocate memory from system allocator, - or, platform's os_malloc function */ - Alloc_With_System_Allocator, -} mem_alloc_type_t; - -/* Memory allocator option */ -typedef union MemAllocOption { - struct { - void *heap_buf; - uint32_t heap_size; - } pool; - struct { - void *malloc_func; - void *realloc_func; - void *free_func; - } allocator; -} MemAllocOption; -#endif - -/* Memory pool info */ -typedef struct mem_alloc_info_t { - uint32_t total_size; - uint32_t total_free_size; - uint32_t highmark_size; -} mem_alloc_info_t; - -/* WASM runtime initialize arguments */ -typedef struct RuntimeInitArgs { - mem_alloc_type_t mem_alloc_type; - MemAllocOption mem_alloc_option; - - const char *native_module_name; - NativeSymbol *native_symbols; - uint32_t n_native_symbols; - - /* maximum thread number, only used when - WASM_ENABLE_THREAD_MGR is defined */ - uint32_t max_thread_num; - - /* Debug settings, only used when - WASM_ENABLE_DEBUG_INTERP != 0 */ - char ip_addr[128]; - int unused; /* was platform_port */ - int instance_port; - - /* Fast JIT code cache size */ - uint32_t fast_jit_code_cache_size; -} RuntimeInitArgs; - -#ifndef WASM_VALKIND_T_DEFINED -#define WASM_VALKIND_T_DEFINED -typedef uint8_t wasm_valkind_t; -enum wasm_valkind_enum { - WASM_I32, - WASM_I64, - WASM_F32, - WASM_F64, - WASM_ANYREF = 128, - WASM_FUNCREF, -}; -#endif - -#ifndef WASM_VAL_T_DEFINED -#define WASM_VAL_T_DEFINED - -typedef struct wasm_val_t { - wasm_valkind_t kind; - union { - /* also represent a function index */ - int32_t i32; - int64_t i64; - float f32; - double f64; - /* represent a foreign object, aka externref in .wat */ - uintptr_t foreign; - } of; -} wasm_val_t; -#endif - -/** - * Initialize the WASM runtime environment, and also initialize - * the memory allocator with system allocator, which calls os_malloc - * to allocate memory - * - * @return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_init(void); - -/** - * Initialize the WASM runtime environment, and also initialize - * the memory allocator and register native symbols, which are specified - * with init arguments - * - * @param init_args specifies the init arguments - * - * @return return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_full_init(RuntimeInitArgs *init_args); - -/** - * Destroy the WASM runtime environment. - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_destroy(void); - -/** - * Allocate memory from runtime memory environment. - * - * @param size bytes need to allocate - * - * @return the pointer to memory allocated - */ -WASM_RUNTIME_API_EXTERN void * -wasm_runtime_malloc(unsigned int size); - -/** - * Reallocate memory from runtime memory environment - * - * @param ptr the original memory - * @param size bytes need to reallocate - * - * @return the pointer to memory reallocated - */ -WASM_RUNTIME_API_EXTERN void * -wasm_runtime_realloc(void *ptr, unsigned int size); - -/* - * Free memory to runtime memory environment. - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_free(void *ptr); - -/* - * Get memory info, only pool mode is supported now. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_get_mem_alloc_info(mem_alloc_info_t *mem_alloc_info); - -/** - * Get the package type of a buffer. - * - * @param buf the package buffer - * @param size the package buffer size - * - * @return the package type, return Package_Type_Unknown if the type is unknown - */ -WASM_RUNTIME_API_EXTERN package_type_t -get_package_type(const uint8_t *buf, uint32_t size); - -/** - * Check whether a file is an AOT XIP (Execution In Place) file - * - * @param buf the package buffer - * @param size the package buffer size - * - * @return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_is_xip_file(const uint8_t *buf, uint32_t size); - -/** - * Callback to load a module file into a buffer in multi-module feature - */ -typedef bool (*module_reader)(const char *module_name, - uint8_t **p_buffer, uint32_t *p_size); - -/** - * Callback to release the buffer loaded by module_reader callback - */ -typedef void (*module_destroyer)(uint8_t *buffer, uint32_t size); - -/** - * Setup callbacks for reading and releasing a buffer about a module file - * - * @param reader a callback to read a module file into a buffer - * @param destroyer a callback to release above buffer - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_module_reader(const module_reader reader, - const module_destroyer destroyer); -/** - * Give the "module" a name "module_name". - * Can not assign a new name to a module if it already has a name - * - * @param module_name indicate a name - * @param module the target module - * @param error_buf output of the exception info - * @param error_buf_size the size of the exception string - * - * @return true means success, false means failed - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_register_module(const char *module_name, wasm_module_t module, - char *error_buf, uint32_t error_buf_size); - -/** - * Check if there is already a loaded module named module_name in the - * runtime. Repeately loading a module with the same name is not allowed. - * - * @param module_name indicate a name - * - * @return return WASM module loaded, NULL if failed - */ -WASM_RUNTIME_API_EXTERN wasm_module_t -wasm_runtime_find_module_registered(const char *module_name); - -/** - * Load a WASM module from a specified byte buffer. The byte buffer can be - * WASM binary data when interpreter or JIT is enabled, or AOT binary data - * when AOT is enabled. If it is AOT binary data, it must be 4-byte aligned. - * - * Note: In case of AOT XIP modules, the runtime doesn't make modifications - * to the buffer. (Except the "Known issues" mentioned in doc/xip.md.) - * Otherwise, the runtime can make modifications to the buffer for its - * internal purposes. Thus, in general, it isn't safe to create multiple - * modules from a single buffer. - * - * @param buf the byte buffer which contains the WASM/AOT binary data, - * note that the byte buffer must be writable since runtime may - * change its content for footprint and performance purpose, and - * it must be referencable until wasm_runtime_unload is called - * @param size the size of the buffer - * @param error_buf output of the exception info - * @param error_buf_size the size of the exception string - * - * @return return WASM module loaded, NULL if failed - */ -WASM_RUNTIME_API_EXTERN wasm_module_t -wasm_runtime_load(uint8_t *buf, uint32_t size, - char *error_buf, uint32_t error_buf_size); - -/** - * Load a WASM module from a specified WASM or AOT section list. - * - * @param section_list the section list which contains each section data - * @param is_aot whether the section list is AOT section list - * @param error_buf output of the exception info - * @param error_buf_size the size of the exception string - * - * @return return WASM module loaded, NULL if failed - */ -WASM_RUNTIME_API_EXTERN wasm_module_t -wasm_runtime_load_from_sections(wasm_section_list_t section_list, bool is_aot, - char *error_buf, uint32_t error_buf_size); - -/** - * Unload a WASM module. - * - * @param module the module to be unloaded - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_unload(wasm_module_t module); - -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_wasi_args_ex(wasm_module_t module, - const char *dir_list[], uint32_t dir_count, - const char *map_dir_list[], uint32_t map_dir_count, - const char *env[], uint32_t env_count, - char *argv[], int argc, - int stdinfd, int stdoutfd, int stderrfd); - -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_wasi_args(wasm_module_t module, - const char *dir_list[], uint32_t dir_count, - const char *map_dir_list[], uint32_t map_dir_count, - const char *env[], uint32_t env_count, - char *argv[], int argc); - -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_wasi_addr_pool(wasm_module_t module, const char *addr_pool[], - uint32_t addr_pool_size); - -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_wasi_ns_lookup_pool(wasm_module_t module, const char *ns_lookup_pool[], - uint32_t ns_lookup_pool_size); - -/** - * Instantiate a WASM module. - * - * @param module the WASM module to instantiate - * @param stack_size the default stack size of the module instance when the - * exec env's operation stack isn't created by user, e.g. API - * wasm_application_execute_main() and wasm_application_execute_func() - * create the operation stack internally with the stack size specified - * here. And API wasm_runtime_create_exec_env() creates the operation - * stack with stack size specified by its parameter, the stack size - * specified here is ignored. - * @param heap_size the default heap size of the module instance, a heap will - * be created besides the app memory space. Both wasm app and native - * function can allocate memory from the heap. - * @param error_buf buffer to output the error info if failed - * @param error_buf_size the size of the error buffer - * - * @return return the instantiated WASM module instance, NULL if failed - */ -WASM_RUNTIME_API_EXTERN wasm_module_inst_t -wasm_runtime_instantiate(const wasm_module_t module, - uint32_t stack_size, uint32_t heap_size, - char *error_buf, uint32_t error_buf_size); - -/** - * Deinstantiate a WASM module instance, destroy the resources. - * - * @param module_inst the WASM module instance to destroy - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_deinstantiate(wasm_module_inst_t module_inst); - -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_is_wasi_mode(wasm_module_inst_t module_inst); - -WASM_RUNTIME_API_EXTERN wasm_function_inst_t -wasm_runtime_lookup_wasi_start_function(wasm_module_inst_t module_inst); - -/** - * Lookup an exported function in the WASM module instance. - * - * @param module_inst the module instance - * @param name the name of the function - * @param signature the signature of the function, ignored currently - * - * @return the function instance found, NULL if not found - */ -WASM_RUNTIME_API_EXTERN wasm_function_inst_t -wasm_runtime_lookup_function(wasm_module_inst_t const module_inst, - const char *name, const char *signature); - -/** - * Get parameter count of the function instance - * - * @param func_inst the function instance - * @param module_inst the module instance the function instance belongs to - * - * @return the parameter count of the function instance - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_func_get_param_count(wasm_function_inst_t const func_inst, - wasm_module_inst_t const module_inst); - -/** - * Get result count of the function instance - * - * @param func_inst the function instance - * @param module_inst the module instance the function instance belongs to - * - * @return the result count of the function instance - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_func_get_result_count(wasm_function_inst_t const func_inst, - wasm_module_inst_t const module_inst); - -/** - * Get parameter types of the function instance - * - * @param func_inst the function instance - * @param module_inst the module instance the function instance belongs to - * @param param_types the parameter types returned - */ -WASM_RUNTIME_API_EXTERN void -wasm_func_get_param_types(wasm_function_inst_t const func_inst, - wasm_module_inst_t const module_inst, - wasm_valkind_t *param_types); - -/** - * Get result types of the function instance - * - * @param func_inst the function instance - * @param module_inst the module instance the function instance belongs to - * @param result_types the result types returned - */ -WASM_RUNTIME_API_EXTERN void -wasm_func_get_result_types(wasm_function_inst_t const func_inst, - wasm_module_inst_t const module_inst, - wasm_valkind_t *result_types); - -/** - * Create execution environment for a WASM module instance. - * - * @param module_inst the module instance - * @param stack_size the stack size to execute a WASM function - * - * @return the execution environment, NULL if failed, e.g. invalid - * stack size is passed - */ -WASM_RUNTIME_API_EXTERN wasm_exec_env_t -wasm_runtime_create_exec_env(wasm_module_inst_t module_inst, - uint32_t stack_size); - -/** - * Destroy the execution environment. - * - * @param exec_env the execution environment to destroy - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_destroy_exec_env(wasm_exec_env_t exec_env); - -/** - * Get the singleton execution environment for the instance. - * - * Note: The singleton execution environment is the execution - * environment used internally by the runtime for the API functions - * like wasm_application_execute_main, which don't take explicit - * execution environment. It's associated to the corresponding - * module instance and managed by the runtime. The API user should - * not destroy it with wasm_runtime_destroy_exec_env. - * - * @param module_inst the module instance - * - * @return exec_env the execution environment to destroy - */ -WASM_RUNTIME_API_EXTERN wasm_exec_env_t -wasm_runtime_get_exec_env_singleton(wasm_module_inst_t module_inst); - -/** - * Start debug instance based on given execution environment. - * Note: - * The debug instance will be destroyed during destroying the - * execution environment, developers don't need to destroy it - * manually. - * If the cluster of this execution environment has already - * been bound to a debug instance, this function will return true - * directly. - * If developer spawns some exec_env by wasm_runtime_spawn_exec_env, - * don't need to call this function for every spawned exec_env as - * they are sharing the same cluster with the main exec_env. - * - * @param exec_env the execution environment to start debug instance - * @param port the port for the debug server to listen on. - * 0 means automatic assignment. - * -1 means to use the global setting in RuntimeInitArgs. - * - * @return debug port if success, 0 otherwise. - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_runtime_start_debug_instance_with_port(wasm_exec_env_t exec_env, int32_t port); - -/** - * Same as wasm_runtime_start_debug_instance_with_port(env, -1). - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_runtime_start_debug_instance(wasm_exec_env_t exec_env); - -/** - * Initialize the thread environment. - * Note: - * If developer creates a child thread by himself to call the - * the wasm function in that thread, he should call this API - * firstly before calling the wasm function and then call - * wasm_runtime_destroy_thread_env() after calling the wasm - * function. If the thread is created from the runtime API, - * it is unnecessary to call these two APIs. - * - * @return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_init_thread_env(void); - -/** - * Destroy the thread environment - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_destroy_thread_env(void); - -/** - * Whether the thread environment is initialized - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_thread_env_inited(void); - -/** - * Get WASM module instance from execution environment - * - * @param exec_env the execution environment to retrieve - * - * @return the WASM module instance - */ -WASM_RUNTIME_API_EXTERN wasm_module_inst_t -wasm_runtime_get_module_inst(wasm_exec_env_t exec_env); - -/** - * Set WASM module instance of execution environment - * Caution: - * normally the module instance is bound with the execution - * environment one by one, if multiple module instances want - * to share to the same execution environment, developer should - * be responsible for the backup and restore of module instance - * - * @param exec_env the execution environment - * @param module_inst the WASM module instance to set - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_module_inst(wasm_exec_env_t exec_env, - const wasm_module_inst_t module_inst); - -/** - * Call the given WASM function of a WASM module instance with - * arguments (bytecode and AoT). - * - * @param exec_env the execution environment to call the function, - * which must be created from wasm_create_exec_env() - * @param function the function to call - * @param argc total cell number that the function parameters occupy, - * a cell is a slot of the uint32 array argv[], e.g. i32/f32 argument - * occupies one cell, i64/f64 argument occupies two cells, note that - * it might be different from the parameter number of the function - * @param argv the arguments. If the function has return value, - * the first (or first two in case 64-bit return value) element of - * argv stores the return value of the called WASM function after this - * function returns. - * - * @return true if success, false otherwise and exception will be thrown, - * the caller can call wasm_runtime_get_exception to get the exception - * info. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_call_wasm(wasm_exec_env_t exec_env, - wasm_function_inst_t function, - uint32_t argc, uint32_t argv[]); - -/** - * Call the given WASM function of a WASM module instance with - * provided results space and arguments (bytecode and AoT). - * - * @param exec_env the execution environment to call the function, - * which must be created from wasm_create_exec_env() - * @param function the function to call - * @param num_results the number of results - * @param results the pre-alloced pointer to get the results - * @param num_args the number of arguments - * @param args the arguments - * - * @return true if success, false otherwise and exception will be thrown, - * the caller can call wasm_runtime_get_exception to get the exception - * info. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_call_wasm_a(wasm_exec_env_t exec_env, - wasm_function_inst_t function, - uint32_t num_results, wasm_val_t results[], - uint32_t num_args, wasm_val_t *args); - -/** - * Call the given WASM function of a WASM module instance with - * provided results space and variant arguments (bytecode and AoT). - * - * @param exec_env the execution environment to call the function, - * which must be created from wasm_create_exec_env() - * @param function the function to call - * @param num_results the number of results - * @param results the pre-alloced pointer to get the results - * @param num_args the number of arguments - * @param ... the variant arguments - * - * @return true if success, false otherwise and exception will be thrown, - * the caller can call wasm_runtime_get_exception to get the exception - * info. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_call_wasm_v(wasm_exec_env_t exec_env, - wasm_function_inst_t function, - uint32_t num_results, wasm_val_t results[], - uint32_t num_args, ...); - -/** - * Find the unique main function from a WASM module instance - * and execute that function. - * - * @param module_inst the WASM module instance - * @param argc the number of arguments - * @param argv the arguments array, if the main function has return value, - * *(int*)argv stores the return value of the called main function after - * this function returns. - * - * @return true if the main function is called, false otherwise and exception - * will be thrown, the caller can call wasm_runtime_get_exception to get - * the exception info. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_application_execute_main(wasm_module_inst_t module_inst, - int32_t argc, char *argv[]); - -/** - * Find the specified function in argv[0] from a WASM module instance - * and execute that function. - * - * @param module_inst the WASM module instance - * @param name the name of the function to execute. - * to indicate the module name via: $module_name$function_name - * or just a function name: function_name - * @param argc the number of arguments - * @param argv the arguments array - * - * @return true if the specified function is called, false otherwise and - * exception will be thrown, the caller can call wasm_runtime_get_exception - * to get the exception info. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_application_execute_func(wasm_module_inst_t module_inst, - const char *name, int32_t argc, char *argv[]); -/** - * Get exception info of the WASM module instance. - * - * @param module_inst the WASM module instance - * - * @return the exception string - */ -WASM_RUNTIME_API_EXTERN const char * -wasm_runtime_get_exception(wasm_module_inst_t module_inst); - -/** - * Set exception info of the WASM module instance. - * - * @param module_inst the WASM module instance - * - * @param exception the exception string - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_exception(wasm_module_inst_t module_inst, - const char *exception); - -/** - * Clear exception info of the WASM module instance. - * - * @param module_inst the WASM module instance - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_clear_exception(wasm_module_inst_t module_inst); - -/** - * Set custom data to WASM module instance. - * Note: - * If WAMR_BUILD_LIB_PTHREAD is enabled, this API - * will spread the custom data to all threads - * - * @param module_inst the WASM module instance - * @param custom_data the custom data to be set - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_custom_data(wasm_module_inst_t module_inst, - void *custom_data); -/** - * Get the custom data within a WASM module instance. - * - * @param module_inst the WASM module instance - * - * @return the custom data (NULL if not set yet) - */ -WASM_RUNTIME_API_EXTERN void * -wasm_runtime_get_custom_data(wasm_module_inst_t module_inst); - -/** - * Allocate memory from the heap of WASM module instance - * - * Note: wasm_runtime_module_malloc can call heap functions inside - * the module instance and thus cause a memory growth. - * This API needs to be used very carefully when you have a native - * pointers to the module instance memory obtained with - * wasm_runtime_addr_app_to_native or similar APIs. - * - * @param module_inst the WASM module instance which contains heap - * @param size the size bytes to allocate - * @param p_native_addr return native address of the allocated memory - * if it is not NULL, and return NULL if memory malloc failed - * - * @return the allocated memory address, which is a relative offset to the - * base address of the module instance's memory space. Note that - * it is not an absolute address. - * Return non-zero if success, zero if failed. - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_runtime_module_malloc(wasm_module_inst_t module_inst, uint32_t size, - void **p_native_addr); - -/** - * Free memory to the heap of WASM module instance - * - * @param module_inst the WASM module instance which contains heap - * @param ptr the pointer to free - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_module_free(wasm_module_inst_t module_inst, uint32_t ptr); - -/** - * Allocate memory from the heap of WASM module instance and initialize - * the memory with src - * - * @param module_inst the WASM module instance which contains heap - * @param src the source data to copy - * @param size the size of the source data - * - * @return the allocated memory address, which is a relative offset to the - * base address of the module instance's memory space. Note that - * it is not an absolute address. - * Return non-zero if success, zero if failed. - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_runtime_module_dup_data(wasm_module_inst_t module_inst, - const char *src, uint32_t size); - -/** - * Validate the app address, check whether it belongs to WASM module - * instance's address space, or in its heap space or memory space. - * - * @param module_inst the WASM module instance - * @param app_offset the app address to validate, which is a relative address - * @param size the size bytes of the app address - * - * @return true if success, false otherwise. If failed, an exception will - * be thrown. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_validate_app_addr(wasm_module_inst_t module_inst, - uint32_t app_offset, uint32_t size); - -/** - * Similar to wasm_runtime_validate_app_addr(), except that the size parameter - * is not provided. This function validates the app string address, check - * whether it belongs to WASM module instance's address space, or in its heap - * space or memory space. Moreover, it checks whether it is the offset of a - * string that is end with '\0'. - * - * Note: The validation result, especially the NUL termination check, - * is not reliable for a module instance with multiple threads because - * other threads can modify the heap behind us. - * - * @param module_inst the WASM module instance - * @param app_str_offset the app address of the string to validate, which is a - * relative address - * - * @return true if success, false otherwise. If failed, an exception will - * be thrown. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_validate_app_str_addr(wasm_module_inst_t module_inst, - uint32_t app_str_offset); - -/** - * Validate the native address, check whether it belongs to WASM module - * instance's address space, or in its heap space or memory space. - * - * @param module_inst the WASM module instance - * @param native_ptr the native address to validate, which is an absolute - * address - * @param size the size bytes of the app address - * - * @return true if success, false otherwise. If failed, an exception will - * be thrown. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_validate_native_addr(wasm_module_inst_t module_inst, - void *native_ptr, uint32_t size); - -/** - * Convert app address(relative address) to native address(absolute address) - * - * Note that native addresses to module instance memory can be invalidated - * on a memory growth. (Except shared memory, whose native addresses are - * stable.) - * - * @param module_inst the WASM module instance - * @param app_offset the app adress - * - * @return the native address converted - */ -WASM_RUNTIME_API_EXTERN void * -wasm_runtime_addr_app_to_native(wasm_module_inst_t module_inst, - uint32_t app_offset); - -/** - * Convert native address(absolute address) to app address(relative address) - * - * @param module_inst the WASM module instance - * @param native_ptr the native address - * - * @return the app address converted - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_runtime_addr_native_to_app(wasm_module_inst_t module_inst, - void *native_ptr); - -/** - * Get the app address range (relative address) that a app address belongs to - * - * @param module_inst the WASM module instance - * @param app_offset the app address to retrieve - * @param p_app_start_offset buffer to output the app start offset if not NULL - * @param p_app_end_offset buffer to output the app end offset if not NULL - * - * @return true if success, false otherwise. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_get_app_addr_range(wasm_module_inst_t module_inst, - uint32_t app_offset, - uint32_t *p_app_start_offset, - uint32_t *p_app_end_offset); - -/** - * Get the native address range (absolute address) that a native address - * belongs to - * - * @param module_inst the WASM module instance - * @param native_ptr the native address to retrieve - * @param p_native_start_addr buffer to output the native start address - * if not NULL - * @param p_native_end_addr buffer to output the native end address - * if not NULL - * - * @return true if success, false otherwise. - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_get_native_addr_range(wasm_module_inst_t module_inst, - uint8_t *native_ptr, - uint8_t **p_native_start_addr, - uint8_t **p_native_end_addr); - -/** - * Register native functions with same module name - * - * Note: The array `native_symbols` should not be read-only because the - * library can modify it in-place. - * - * Note: After successful call of this function, the array `native_symbols` - * is owned by the library. - * - * @param module_name the module name of the native functions - * @param native_symbols specifies an array of NativeSymbol structures which - * contain the names, function pointers and signatures - * Note: WASM runtime will not allocate memory to clone the data, so - * user must ensure the array can be used forever - * Meanings of letters in function signature: - * 'i': the parameter is i32 type - * 'I': the parameter is i64 type - * 'f': the parameter is f32 type - * 'F': the parameter is f64 type - * 'r': the parameter is externref type, it should be a uintptr_t in host - * '*': the parameter is a pointer (i32 in WASM), and runtime will - * auto check its boundary before calling the native function. - * If it is followed by '~', the checked length of the pointer - * is gotten from the following parameter, if not, the checked - * length of the pointer is 1. - * '~': the parameter is the pointer's length with i32 type, and must - * follow after '*' - * '$': the parameter is a string (i32 in WASM), and runtime will - * auto check its boundary before calling the native function - * @param n_native_symbols specifies the number of native symbols in the array - * - * @return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_register_natives(const char *module_name, - NativeSymbol *native_symbols, - uint32_t n_native_symbols); - -/** - * Register native functions with same module name, similar to - * wasm_runtime_register_natives, the difference is that runtime passes raw - * arguments to native API, which means that the native API should be defined as - * void foo(wasm_exec_env_t exec_env, uint64 *args); - * and native API should extract arguments one by one from args array with macro - * native_raw_get_arg - * and write the return value back to args[0] with macro - * native_raw_return_type and native_raw_set_return - */ -WASM_RUNTIME_API_EXTERN bool -wasm_runtime_register_natives_raw(const char *module_name, - NativeSymbol *native_symbols, - uint32_t n_native_symbols); - -/** - * Get attachment of native function from execution environment - * - * @param exec_env the execution environment to retrieve - * - * @return the attachment of native function - */ -WASM_RUNTIME_API_EXTERN void * -wasm_runtime_get_function_attachment(wasm_exec_env_t exec_env); - -/** - * Set user data to execution environment. - * - * @param exec_env the execution environment - * @param user_data the user data to be set - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_user_data(wasm_exec_env_t exec_env, void *user_data); - -/** - * Get the user data within execution environment. - * - * @param exec_env the execution environment - * - * @return the user data (NULL if not set yet) - */ -WASM_RUNTIME_API_EXTERN void * -wasm_runtime_get_user_data(wasm_exec_env_t exec_env); - -/** - * Dump runtime memory consumption, including: - * Exec env memory consumption - * WASM module memory consumption - * WASM module instance memory consumption - * stack and app heap used info - * - * @param exec_env the execution environment - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_dump_mem_consumption(wasm_exec_env_t exec_env); - -/** - * Dump runtime performance profiler data of each function - * - * @param module_inst the WASM module instance to profile - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_dump_perf_profiling(wasm_module_inst_t module_inst); - -/* wasm thread callback function type */ -typedef void *(*wasm_thread_callback_t)(wasm_exec_env_t, void *); -/* wasm thread type */ -typedef uintptr_t wasm_thread_t; - -/** - * Set the max thread num per cluster. - * - * @param num maximum thread num - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_set_max_thread_num(uint32_t num); - -/** - * Spawn a new exec_env, the spawned exec_env - * can be used in other threads - * - * @param num the original exec_env - * - * @return the spawned exec_env if success, NULL otherwise - */ -WASM_RUNTIME_API_EXTERN wasm_exec_env_t -wasm_runtime_spawn_exec_env(wasm_exec_env_t exec_env); - -/** - * Destroy the spawned exec_env - * - * @param exec_env the spawned exec_env - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_destroy_spawned_exec_env(wasm_exec_env_t exec_env); - -/** - * Spawn a thread from the given exec_env - * - * @param exec_env the original exec_env - * @param tid thread id to be returned to the caller - * @param callback the callback function provided by the user - * @param arg the arguments passed to the callback - * - * @return 0 if success, -1 otherwise - */ -WASM_RUNTIME_API_EXTERN int32_t -wasm_runtime_spawn_thread(wasm_exec_env_t exec_env, wasm_thread_t *tid, - wasm_thread_callback_t callback, void *arg); - -/** - * Wait a spawned thread to terminate - * - * @param tid thread id - * @param retval if not NULL, output the return value of the thread - * - * @return 0 if success, error number otherwise - */ -WASM_RUNTIME_API_EXTERN int32_t -wasm_runtime_join_thread(wasm_thread_t tid, void **retval); - -/** - * Map external object to an internal externref index: if the index - * has been created, return it, otherwise create the index. - * - * @param module_inst the WASM module instance that the extern object - * belongs to - * @param extern_obj the external object to be mapped - * @param p_externref_idx return externref index of the external object - * - * @return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_externref_obj2ref(wasm_module_inst_t module_inst, - void *extern_obj, uint32_t *p_externref_idx); - -/** - * Retrieve the external object from an internal externref index - * - * @param externref_idx the externref index to retrieve - * @param p_extern_obj return the mapped external object of - * the externref index - * - * @return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_externref_ref2obj(uint32_t externref_idx, void **p_extern_obj); - -/** - * Retain an extern object which is mapped to the internal externref - * so that the object won't be cleaned during extern object reclaim - * if it isn't used. - * - * @param externref_idx the externref index of an external object - * to retain - * @return true if success, false otherwise - */ -WASM_RUNTIME_API_EXTERN bool -wasm_externref_retain(uint32_t externref_idx); - -/** - * Dump the call stack to stdout - * - * @param exec_env the execution environment - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_dump_call_stack(wasm_exec_env_t exec_env); - -/** - * Get the size required to store the call stack contents, including - * the space for terminating null byte ('\0') - * - * @param exec_env the execution environment - * - * @return size required to store the contents, 0 means error - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_runtime_get_call_stack_buf_size(wasm_exec_env_t exec_env); - -/** - * Dump the call stack to buffer. - * - * @note this function is not thread-safe, please only use this API - * when the exec_env is not executing - * - * @param exec_env the execution environment - * @param buf buffer to store the dumped content - * @param len length of the buffer - * - * @return bytes dumped to the buffer, including the terminating null - * byte ('\0'), 0 means error and data in buf may be invalid - */ -WASM_RUNTIME_API_EXTERN uint32_t -wasm_runtime_dump_call_stack_to_buf(wasm_exec_env_t exec_env, char *buf, - uint32_t len); - -/** - * Get a custom section by name - * - * @param module_comm the module to find - * @param name name of the custom section - * @param len return the length of the content if found - * - * @return Custom section content (not including the name length - * and name string) if found, NULL otherwise - */ -WASM_RUNTIME_API_EXTERN const uint8_t * -wasm_runtime_get_custom_section(wasm_module_t const module_comm, - const char *name, uint32_t *len); - - -/** - * Get WAMR semantic version - */ -WASM_RUNTIME_API_EXTERN void -wasm_runtime_get_version(uint32_t *major, uint32_t *minor, uint32_t *patch); -/* clang-format on */ - -#ifdef __cplusplus -} -#endif - -#endif /* end of _WASM_EXPORT_H */ -``` +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).