From a57c9427dd70ad1d1d87dd2252b902e60de45abe Mon Sep 17 00:00:00 2001 From: Frederic ST Date: Fri, 10 May 2019 14:05:31 +0200 Subject: [PATCH 01/10] Fix typo on README.md (#6) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4f538436..645977de 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ The application manager component handles the packets that the platform recieved The WebAssembly runtime is the execution environment for WASM applications. -The messaging layer can suppor the API for WASM applications communicate to each other and also the host environment. +The messaging layer can support the API for WASM applications communicate to each other and also the host environment. When Ahead of Time compilation is enabled, the WASM application can be either bytecode or compiled native binary. From 89ad7dc1014dc6757dba64c494d598f7cbf2fab8 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Fri, 10 May 2019 13:07:58 +0100 Subject: [PATCH 02/10] fix typos (#7) Signed-off-by: Eric Engestrom --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 645977de..8efb554d 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Features Architecture ========================= -The application manager component handles the packets that the platform recieved from external through any communication buses such as socket, serial port, PSI. A packet type can be either request, response or event. It will service the request with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URIs, it will filter the resource registeration table and router the request to internal queue of responsible application. +The application manager component handles the packets that the platform received from external through any communication buses such as socket, serial port, PSI. A packet type can be either request, response or event. It will service the request with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URIs, it will filter the resource registration table and router the request to internal queue of responsible application. The WebAssembly runtime is the execution environment for WASM applications. @@ -62,7 +62,7 @@ make ``` Zephyr ------------------------- -You need download Zephyr source code first and embeded WAMR into it. +You need download Zephyr source code first and embedded WAMR into it. ``` Bash git clone https://github.com/zephyrproject-rtos/zephyr.git cd zephyr/samples/ @@ -301,7 +301,7 @@ The pre-defined MACRO `EXPORT_WASM_API` should be used to declare a function exp #define EXPORT_WASM_API(symbol) {#symbol, symbol} ``` -Below code example shows how to extend the library to support `customeized()`: +Below code example shows how to extend the library to support `customized()`: ``` C //lib-export-impl.c void customized() From 13db1976af647952d1e254648d8fe9078bbfc176 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Fri, 10 May 2019 13:09:30 +0100 Subject: [PATCH 03/10] fix iwasm build path (#8) Signed-off-by: Eric Engestrom --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8efb554d..ec7b29f8 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ sudo apt-get install g++-multilib ``` After installing dependencies, build the source code: ``` Bash -cd products/linux/ +cd core/iwasm/products/linux/ mkdir build cd build cmake .. From 76a40bf4f561dac1fe6d2916ac376419cf11d2f8 Mon Sep 17 00:00:00 2001 From: Kyle Mills Date: Fri, 10 May 2019 08:25:04 -0400 Subject: [PATCH 04/10] Fix: (Minor Spelling Issue) (#9) Fix minor spelling issue in the README.md. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ec7b29f8..9be827b7 100644 --- a/README.md +++ b/README.md @@ -353,7 +353,7 @@ int main(int argc, char **argv) } ``` -Comming soon... +Coming soon... ======================== We are preparing the open source for application manager and related cool samples like inter-application communication, application life cycle management, 2D graphic demo and more. You will get updated soon. From 5df8e94c29596b3ec929d77a32969165ad279ed3 Mon Sep 17 00:00:00 2001 From: Wang Xin Date: Fri, 10 May 2019 21:19:47 +0800 Subject: [PATCH 05/10] Update README.md (#11) --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9be827b7..e138be07 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ WebAssembly Micro Runtime (WAMR) is standalone WebAssembly (WASM) runtime with s - Dynamic WASM application management (Not available in github yet. It will be released soon) Why should we use a WASM runtime out of browser? There are a few points which might be meaningful: -1. WASM is already the LLVM official backend target. That means WASM can run any programming languages which can be compiled to LLVM IR. It is a huge advantage comparing to those language bound runtimes like JS, Lua. +1. WASM is already a LLVM official backend target. That means WASM can run any programming languages which can be compiled to LLVM IR. It is a huge advantage comparing to those language bound runtimes like JS, Lua. 2. WASM is an open standard and the growing trend is so fast as it is supported by the whole web ecosystem 3. WASM is designed to be very friendly for compiling to native binary and gaining the native speed. 4. Potentially change the development practices. Imaging we can do both the WASM application development and validation in a browser, then just download the wasm binary code into the target device. @@ -28,7 +28,7 @@ Features Architecture ========================= -The application manager component handles the packets that the platform received from external through any communication buses such as socket, serial port, PSI. A packet type can be either request, response or event. It will service the request with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URIs, it will filter the resource registration table and router the request to internal queue of responsible application. +The application manager component handles the packets that the platform received from external through any communication buses such as socket, serial port, PSI. A packet type can be either request, response or event. The app manager will serve the requests with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URIs, it will filter the resource registration table and router the request to internal queue of responsible application. The WebAssembly runtime is the execution environment for WASM applications. @@ -176,7 +176,7 @@ WASM application library In general, there are 3 kinds of APIs for programming the WASM application: - Built-in APIs: WAMR has already provided a minimal API set for developers. - 3rd party APIs: Programmer can download include any 3rd party C source code, and added into their own WASM app source tree. -- Platform native APIs: The board vendors define these APIs during their making board firmware. They are provided WASM application to invoke like built-in and 3rd party APIs. In this way board vendors extend APIs which can make programmers develop more complicated WASM apps. +- Platform native APIs: WAMR provides a mechanism to export the native API to the WASM applications. Built-in application library @@ -206,7 +206,7 @@ char *strncpy(char *dest, const char *src, unsigned long n); ``` **Base library**
-The basic support like communication, timers etc is already available. The header files is ```lib/app-libs/base/wasm-app.h```, it includes request and response APIs, event pub/sub APIs and timer APIs. Please be noted that they may not work if you have no corresponding framework to work with them. +The basic support for communication, timers etc is already available. You can refer to the header files ```lib/app-libs/base/wasm-app.h``` which contains the definitions for request and response APIs, event pub/sub APIs and timer APIs. Please be noted that these APIs require the native implementations. The API set is listed as below: ``` C typedef void(*request_handler_f)(request_t *) ; @@ -232,7 +232,7 @@ void api_timer_restart(user_timer_t timer, int interval); ``` **Library extension reference**
-Currently we provide the sensor APIs as one library extension sample. The header file ```lib/app-libs/extension/sensor/sensor.h```, the API set is listed as below: +Currently we provide the sensor APIs as one library extension sample. In the header file ```lib/app-libs/extension/sensor/sensor.h```, the API set is defined as below: ``` C sensor_t sensor_open(const char* name, int index, void(*on_sensor_event)(sensor_t, attr_container_t *, void *), From 8c76e17e290598edeb9b6fe1ad33c56c1bc2e170 Mon Sep 17 00:00:00 2001 From: Pieter van Mill Date: Fri, 10 May 2019 16:50:10 +0200 Subject: [PATCH 06/10] Update README.md (#12) Throughout the text I have tried to make it a bit more readable. --- README.md | 114 +++++++++++++++++++++++++++--------------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index e138be07..c1569872 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,40 @@ WebAssembly Micro Runtime ========================= -WebAssembly Micro Runtime (WAMR) is standalone WebAssembly (WASM) runtime with small footprint. It includes a few components: +WebAssembly Micro Runtime (WAMR) is standalone WebAssembly (WASM) runtime with a small footprint. It includes a few components: - WebAssembly VM core -- WASM application programming API (code available, but compilation is depending on the app manager component) -- Dynamic WASM application management (Not available in github yet. It will be released soon) +- WASM application programming API (code available, but compilation depends on the app manager component) +- Dynamic WASM application management (Not available on Github yet. It will be released soon) -Why should we use a WASM runtime out of browser? There are a few points which might be meaningful: -1. WASM is already a LLVM official backend target. That means WASM can run any programming languages which can be compiled to LLVM IR. It is a huge advantage comparing to those language bound runtimes like JS, Lua. -2. WASM is an open standard and the growing trend is so fast as it is supported by the whole web ecosystem -3. WASM is designed to be very friendly for compiling to native binary and gaining the native speed. -4. Potentially change the development practices. Imaging we can do both the WASM application development and validation in a browser, then just download the wasm binary code into the target device. -5. WASM can work without garbage collection. It can be designed to support execution determinics for the time sensitive requirement. +Why should you use a WASM runtime out of your browser? There are a few points where this might be meaningful: +1. WASM is already a LLVM official backend target. That means WASM can run any programming languages which can be compiled to LLVM IR. It is a huge advantage compared to language bound runtimes like JS or Lua. +2. WASM is an open standard and it is fast becoming supported by the whole web ecosystem. +3. WASM is designed to be very friendly for compiling to native binaries and gaining the native speed. +4. It can potentially change the development practices. Imagine we can do both the WASM application development and validation in a browser, then just download the WASM binary code onto the target device. +5. WASM can work without garbage collection. It is designed to support execution determinics for the time sensitive requirement. Features ========================= - WASM interpreter (AOT is planned) -- Provide built-in Libc subset, support "side_module=1" EMCC compilation option -- Provide APIs for embedding runtime into production software -- Provide mechanism for exporting native APIs to WASM applications -- Support programming firmware apps in multi languages (C/C++/Java/Rust/Go/TypeScript etc.) +- Provides built-in Libc subset, supports "side_module=1" EMCC compilation option +- Provides API's for embedding runtime into production software +- Provides a mechanism for exporting native API's to WASM applications +- Supports the programming of firmware apps in a large range of languages (C/C++/Java/Rust/Go/TypeScript etc.) - App sandbox execution environment on embedded OS -- Pure asynchronized programming model +- Purely asynchronized programming model - Menu configuration for easy platform integration -- Support micro service and pub-sub event inter-app communication models +- Supports micro-service and pub-sub event inter-app communication models - Easy to extend to support remote FW application management from host or cloud Architecture ========================= -The application manager component handles the packets that the platform received from external through any communication buses such as socket, serial port, PSI. A packet type can be either request, response or event. The app manager will serve the requests with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URIs, it will filter the resource registration table and router the request to internal queue of responsible application. +The application manager component handles the packets that the platform receives from external sources through any communication buses such as socket, serial port or PSI. A packet type can be either a request, response or event. The app manager will serve the requests with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URI's, it will filter the resource registration table and route the request to the internal queue of the responsible application. The WebAssembly runtime is the execution environment for WASM applications. -The messaging layer can support the API for WASM applications communicate to each other and also the host environment. +The messaging layer can support the API for WASM applications to communicate to each other and also the host environment. -When Ahead of Time compilation is enabled, the WASM application can be either bytecode or compiled native binary. +When Ahead of Time compilation is enabled, the WASM application can be either bytecode or a compiled native binary. @@ -42,12 +42,12 @@ When Ahead of Time compilation is enabled, the WASM application can be either by Build WAMR Core ========================= -Please follow below instructions to build WAMR core on different platforms. +Please follow the instructions below to build the WAMR core on different platforms. Linux ------------------------- -Firstly please install library dependencies of lib gcc. -Use below installation commands for Ubuntu Linux: +First of all please install library dependencies of lib gcc. +Use installation commands below for Ubuntu Linux: ``` Bash sudo apt install lib32gcc-5-dev sudo apt-get install g++-multilib @@ -62,7 +62,7 @@ make ``` Zephyr ------------------------- -You need download Zephyr source code first and embedded WAMR into it. +You need to download the Zephyr source code first and embedded WAMR into it. ``` Bash git clone https://github.com/zephyrproject-rtos/zephyr.git cd zephyr/samples/ @@ -79,18 +79,18 @@ ninja Build WASM app ========================= A popular method to build out WASM binary is to use ```emcc```. -Assuming you are using Linux. Please install emcc from Emscripten EMSDK following below steps: +Assuming you are using Linux, please install emcc from Emscripten EMSDK following the steps below: ``` git clone https://github.com/emscripten-core/emsdk.git emsdk install latest emsdk activate latest ``` -add ```./emsdk_env.sh``` into path to ease future use, or source it everytime. -Emscripten website provides other installtion method beyond Linux. +add ```./emsdk_env.sh``` into the path to ease future use, or source it everytime. +The Emscripten website provides other installtion methods beyond Linux. todo: user should copy the app-libs folder into project and include and build. -You can write a simple ```test.c```as the first sample. +You can write a simple ```test.c``` as the first sample. ``` C #include #include @@ -116,7 +116,7 @@ int main(int argc, char **argv) return 0; } ``` -Use below emcc commmand to build the WASM C source code into WASM binary. +Use the emcc commmand below to build the WASM C source code into the WASM binary. ``` Bash emcc -g -O3 *.c -s WASM=1 -s SIDE_MODULE=1 -s ASSERTIONS=1 -s STACK_OVERFLOW_CHECK=2 \ -s TOTAL_MEMORY=65536 -s TOTAL_STACK=4096 -o test.wasm @@ -125,30 +125,30 @@ You will get ```test.wasm``` which is the WASM app binary. Run WASM app ======================== -Assume you are using Linux, the command to run the test.wasm is +Assume you are using Linux, the command to run the test.wasm is: ``` Bash cd iwasm/products/linux/bin ./iwasm test.wasm ``` -You will get output: +You will get the following output: ``` Hello world! buf ptr: 0x000101ac buf: 1234 ``` -If you would like to run test app on Zephyr, we have embedded test sample into its OS image. You need to execute +If you would like to run the test app on Zephyr, we have embedded a test sample into its OS image. You will need to execute: ``` ninja run ``` Embed WAMR into software production ===================================== -WAMR can be built into a standalone executable which takes WASM application file name as input, and then execute it. To use it in the embedded environment, you should embed WAMR into your own software product. WASM provides a set of APIs for embedders code to load WASM module, instansiate module and invoke WASM function from native call. +WAMR can be built into a standalone executable which takes WASM application file name as input, and then execute it. To use it in the embedded environment, you should embed WAMR into your own software product. WASM provides a set of API's for embedded code to load WASM module, instantiate the module and invoke the WASM function from a native call. -A typical WAMR APIs usage is as below: +A typical WAMR API usage is as described below: ``` C wasm_module_t module; wasm_module_inst_t inst; @@ -173,19 +173,19 @@ A typical WAMR APIs usage is as below: WASM application library ======================== -In general, there are 3 kinds of APIs for programming the WASM application: -- Built-in APIs: WAMR has already provided a minimal API set for developers. -- 3rd party APIs: Programmer can download include any 3rd party C source code, and added into their own WASM app source tree. -- Platform native APIs: WAMR provides a mechanism to export the native API to the WASM applications. +In general, there are 3 kinds of API's for programming the WASM application: +- Built-in API's: WAMR has already provided a minimal API set for developers. +- 3rd party API's: Programmer can download and include any 3rd party C source code, and add it into their own WASM app source tree. +- Platform native API's: WAMR provides a mechanism to export the native API to the WASM application. Built-in application library --------------- -Built-in APIs include Libc APIs, Base library, Extension library reference. +Built-in API's include Libc APIs, Base library and Extension library reference. **Libc APIs**
-It is the minimal Libc APIs like memory allocation and string copy etc. -The header files is ```lib/app-libs/libc/lib-base.h```. The API set is listed as below: +This is the minimal Libc APIs like memory allocation and string copy etc. +The header file is ```lib/app-libs/libc/lib-base.h```. The API set is listed as below: ``` C void *malloc(size_t size); void *calloc(size_t n, size_t size); @@ -206,7 +206,7 @@ char *strncpy(char *dest, const char *src, unsigned long n); ``` **Base library**
-The basic support for communication, timers etc is already available. You can refer to the header files ```lib/app-libs/base/wasm-app.h``` which contains the definitions for request and response APIs, event pub/sub APIs and timer APIs. Please be noted that these APIs require the native implementations. +The basic support for communication, timers etc is already available. You can refer to the header file ```lib/app-libs/base/wasm-app.h``` which contains the definitions for request and response API's, event pub/sub APIs and timer APIs. Please note that these API's require the native implementations. The API set is listed as below: ``` C typedef void(*request_handler_f)(request_t *) ; @@ -232,7 +232,7 @@ void api_timer_restart(user_timer_t timer, int interval); ``` **Library extension reference**
-Currently we provide the sensor APIs as one library extension sample. In the header file ```lib/app-libs/extension/sensor/sensor.h```, the API set is defined as below: +Currently we provide the sensor API's as one library extension sample. In the header file ```lib/app-libs/extension/sensor/sensor.h```, the API set is defined as below: ``` C sensor_t sensor_open(const char* name, int index, void(*on_sensor_event)(sensor_t, attr_container_t *, void *), @@ -245,11 +245,11 @@ bool sensor_close(sensor_t sensor); The mechanism of exporting Native API to WASM application ======================================================= -The basic working flow for WASM application calling into the native API is described as following diagram. +The basic working flow for WASM application calling into the native API is described in the following diagram. -WAMR provides the macro `EXPORT_WASM_API` to enable users to export native API to WASM application. WAMR implemented a base API for timer and messaging by using `EXPORT_WASM_API`. They can be reference point of extending your own library. +WAMR provides the macro `EXPORT_WASM_API` to enable users to export native API to a WASM application. WAMR implemented a base API for the timer and messaging by using `EXPORT_WASM_API`. They can be a reference point for extending your own library. ``` C static NativeSymbol extended_native_symbol_defs[] = { EXPORT_WASM_API(wasm_register_resource), @@ -264,26 +264,26 @@ static NativeSymbol extended_native_symbol_defs[] = { ``` -![#f03c15](https://placehold.it/15/f03c15/000000?text=+) **Security attention:** The WebAssembly application is supposed to access its own memory space, the integrator should carefully design the native function to ensure the memory safe. The native API to be exporte to WASM application must follow the rules: +![#f03c15](https://placehold.it/15/f03c15/000000?text=+) **Security attention:** The WebAssembly application is supposed to access its own memory space, the integrator should carefully design the native function to ensure that the memory is safe. The native API to be exported to the WASM application must follow these rules: - Only use 32 bits number for parameters -- Don’t passing data structure pointer (do data serialization instead) -- Do the pointer address conversion in native API -- Don’t passing function pointer as callback +- Don't pass data to the structure pointer (do data serialization instead) +- Do the pointer address conversion in the native API +- Don’t pass function pointer as callback -Below is a sample of library extension. All invoke across WASM world and native world must be serialized and de-serialized, and native world must do boundary check for every incoming address from WASM world. +Below is a sample of a library extension. All code invoked across WASM and native world must be serialized and de-serialized, and the native world must do a boundary check for every incoming address from the WASM world. Exporting native API steps ========================== -WAMR implemented a framework for developers to export APIs. The procedure to expose the platform APIs in three steps: +WAMR implemented a framework for developers to export API's. Below is the procedure to expose the platform APIs in three steps: **Step 1. Create a header file**
-Declare the APIs for WASM application source project to include. +Declare the API's for your WASM application source project to include. **Step 2. Create a source file**
-Export the platform APIs, for example in ``` products/linux/ext-lib-export.c ``` +Export the platform API's, for example in ``` products/linux/ext-lib-export.c ``` ``` C #include "lib-export.h" @@ -295,7 +295,7 @@ static NativeSymbol extended_native_symbol_defs[] = ``` **Step 3. Register new APIs**
-Use macro EXPORT_WASM_API and EXPORT_WASM_API2 to add exported APIs into the array of ```extended_native_symbol_defs```. +Use the macro `EXPORT_WASM_API` and `EXPORT_WASM_API2` to add exported API's into the array of ```extended_native_symbol_defs```. The pre-defined MACRO `EXPORT_WASM_API` should be used to declare a function export: ``` c #define EXPORT_WASM_API(symbol) {#symbol, symbol} @@ -338,24 +338,24 @@ static NativeSymbol extended_native_symbol_defs[] = ``` Use extended library ------------------------ -In the application source project, it includes the WAMR built-in APIs header file and platform extension header files. -Assume the board vendor extend the library which added a API called customized(). The WASM application would be like this: +In the application source project, it will include the WAMR built-in APIs header file and platform extension header files. +This is assuming the board vendor extends the library which added an API called customized(). The WASM application would be like this: ``` C #include -#include "lib-export-dec.h" // provided by platform vendor +#include "lib-export-dec.h" // provided by the platform vendor int main(int argc, char **argv) { int I; char *buf = “abcd”; - customized(); // customized API provided by platform vendor + customized(); // customized API provided by the platform vendor return i; } ``` Coming soon... ======================== -We are preparing the open source for application manager and related cool samples like inter-application communication, application life cycle management, 2D graphic demo and more. You will get updated soon. +We are preparing the open source code for the application manager and related code samples like inter-application communication, application life cycle management, 2D graphic demo and more. This will get updated soon. Submit issues and request ========================= From 179d34ac780aa68147ee7651b1c40c8fe6545c6f Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Fri, 10 May 2019 16:21:32 +0100 Subject: [PATCH 07/10] delete empty file (#13) Signed-off-by: Eric Engestrom --- projects/README.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 projects/README.md diff --git a/projects/README.md b/projects/README.md deleted file mode 100644 index 792d6005..00000000 --- a/projects/README.md +++ /dev/null @@ -1 +0,0 @@ -# From 108254974fff3e70f9eb248b1fa0c7fa0dc7468a Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Fri, 10 May 2019 16:21:54 +0100 Subject: [PATCH 08/10] add installation directives (#14) Signed-off-by: Eric Engestrom --- core/iwasm/products/linux/CMakeLists.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/core/iwasm/products/linux/CMakeLists.txt b/core/iwasm/products/linux/CMakeLists.txt index 5421d11e..4a955f1b 100644 --- a/core/iwasm/products/linux/CMakeLists.txt +++ b/core/iwasm/products/linux/CMakeLists.txt @@ -75,6 +75,8 @@ add_library (vmlib add_executable (iwasm main.c ext-lib-export.c) +install (TARGETS iwasm DESTINATION bin) + target_link_libraries (iwasm vmlib -lm -ldl -lpthread) add_library (libiwasm SHARED @@ -86,6 +88,8 @@ add_library (libiwasm SHARED ${PLATFORM_SHARED_SOURCE} ${MEM_ALLOC_SHARED_SOURCE}) +install (TARGETS libiwasm DESTINATION lib) + set_target_properties (libiwasm PROPERTIES OUTPUT_NAME iwasm) target_link_libraries (libiwasm -lm -ldl -lpthread) From 31de47bd92f0bdd2c90e6c8f261a65319d09beed Mon Sep 17 00:00:00 2001 From: 0xflotus <0xflotus@gmail.com> Date: Sat, 11 May 2019 14:36:20 +0200 Subject: [PATCH 09/10] Update README.md (#18) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c1569872..585821f8 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ emsdk install latest emsdk activate latest ``` add ```./emsdk_env.sh``` into the path to ease future use, or source it everytime. -The Emscripten website provides other installtion methods beyond Linux. +The Emscripten website provides other installation methods beyond Linux. todo: user should copy the app-libs folder into project and include and build. @@ -116,7 +116,7 @@ int main(int argc, char **argv) return 0; } ``` -Use the emcc commmand below to build the WASM C source code into the WASM binary. +Use the emcc command below to build the WASM C source code into the WASM binary. ``` Bash emcc -g -O3 *.c -s WASM=1 -s SIDE_MODULE=1 -s ASSERTIONS=1 -s STACK_OVERFLOW_CHECK=2 \ -s TOTAL_MEMORY=65536 -s TOTAL_STACK=4096 -o test.wasm From 62605cfb2e599ba61b8517173def370e220edddb Mon Sep 17 00:00:00 2001 From: Johnnie Birch <45402135+jlb6740@users.noreply.github.com> Date: Sat, 11 May 2019 06:05:43 -0700 Subject: [PATCH 10/10] Updates to the Readme (#15) Update README.md --- README.md | 87 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 585821f8..7a369131 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,25 @@ WebAssembly Micro Runtime ========================= -WebAssembly Micro Runtime (WAMR) is standalone WebAssembly (WASM) runtime with a small footprint. It includes a few components: -- WebAssembly VM core -- WASM application programming API (code available, but compilation depends on the app manager component) -- Dynamic WASM application management (Not available on Github yet. It will be released soon) +WebAssembly Micro Runtime (WAMR) is standalone WebAssembly (WASM) runtime designed for a small footprint. It includes: +- A WebAssembly (WASM) VM core +- The supporting APIs for the WASM applications (code is available but compilation depends on the app manager component) +- A mechanism for dynamic management of the WASM application (Not available on Github yet. To be released soon) -Why should you use a WASM runtime out of your browser? There are a few points where this might be meaningful: -1. WASM is already a LLVM official backend target. That means WASM can run any programming languages which can be compiled to LLVM IR. It is a huge advantage compared to language bound runtimes like JS or Lua. -2. WASM is an open standard and it is fast becoming supported by the whole web ecosystem. -3. WASM is designed to be very friendly for compiling to native binaries and gaining the native speed. -4. It can potentially change the development practices. Imagine we can do both the WASM application development and validation in a browser, then just download the WASM binary code onto the target device. +Why should you use a WASM runtime out of your browser? There are a few points where this might be meaningful: +1. WASM is already a LLVM official backend target. That means WASM can run any programming languages which can be compiled to LLVM IR. It is a huge advantage compared to language bound runtimes like JS or Lua. +2. WASM is an open standard and it is fast becoming supported by the whole web ecosystem. +3. WASM is designed to be very friendly for compiling to native binaries and gaining the native speed. +4. It can potentially change the development practices. Imagine we can do both the WASM application development and validation in a browser, then just download the WASM binary code onto the target device. 5. WASM can work without garbage collection. It is designed to support execution determinics for the time sensitive requirement. +6. Maintain the safety goals WASM has of providing a sandboxed execution enviornment for untrusted code. In addition, because WASM is a compilation target, this implies a benefit of being able to target both an execution and security profile that is consistent across popular high-level programming languages. -Features + +Current Features of WAMR ========================= - WASM interpreter (AOT is planned) -- Provides built-in Libc subset, supports "side_module=1" EMCC compilation option +- Provides support for a subset of Lib. +- Supports "side_module=1" EMCC compilation option - Provides API's for embedding runtime into production software - Provides a mechanism for exporting native API's to WASM applications - Supports the programming of firmware apps in a large range of languages (C/C++/Java/Rust/Go/TypeScript etc.) @@ -28,17 +31,17 @@ Features Architecture ========================= -The application manager component handles the packets that the platform receives from external sources through any communication buses such as socket, serial port or PSI. A packet type can be either a request, response or event. The app manager will serve the requests with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URI's, it will filter the resource registration table and route the request to the internal queue of the responsible application. +The application manager component handles the packets that the platform receives from external sources through any communication buses such as a socket, serial port or PSI. A packet type can be either a request, response or an event. The app manager will serve the requests with URI "/applet" and call the runtime glue layer interfaces for installing/uninstalling the application. For other URI's, it will filter the resource registration table and route the request to the internal queue of the responsible application. -The WebAssembly runtime is the execution environment for WASM applications. +- The WebAssembly runtime provides the execution environment for WASM applications. -The messaging layer can support the API for WASM applications to communicate to each other and also the host environment. +- The messaging layer can support the API for WASM applications to communicate to each other and also the host environment. -When Ahead of Time compilation is enabled, the WASM application can be either bytecode or a compiled native binary. +- When ahead of time (AOT) compilation is enabled (TODO), the WASM application could be either WASM or a compiled native binary. - + Build WAMR Core ========================= @@ -47,7 +50,7 @@ Please follow the instructions below to build the WAMR core on different platfor Linux ------------------------- First of all please install library dependencies of lib gcc. -Use installation commands below for Ubuntu Linux: +Use installation commands below for Ubuntu Linux: ``` Bash sudo apt install lib32gcc-5-dev sudo apt-get install g++-multilib @@ -78,17 +81,18 @@ ninja Build WASM app ========================= -A popular method to build out WASM binary is to use ```emcc```. -Assuming you are using Linux, please install emcc from Emscripten EMSDK following the steps below: +A popular method to build a WASM binary is to use ```emcc```. +Assuming you are using Linux, you may install emcc from Emscripten EMSDK following the steps below: ``` git clone https://github.com/emscripten-core/emsdk.git emsdk install latest emsdk activate latest ``` + add ```./emsdk_env.sh``` into the path to ease future use, or source it everytime. The Emscripten website provides other installation methods beyond Linux. -todo: user should copy the app-libs folder into project and include and build. +(TODO) The user should copy the app-libs folder into project and include and build. You can write a simple ```test.c``` as the first sample. ``` C @@ -143,12 +147,12 @@ ninja run Embed WAMR into software production ===================================== -WAMR can be built into a standalone executable which takes WASM application file name as input, and then execute it. To use it in the embedded environment, you should embed WAMR into your own software product. WASM provides a set of API's for embedded code to load WASM module, instantiate the module and invoke the WASM function from a native call. +WAMR can be built into a standalone executable which takes the WASM application file name as input, and then executes it. To use it in the embedded environment you should embed WAMR into your own software product. WASM provides a set of API's for embedded code to load the WASM module, instantiate the module and invoke a WASM function from a native call. -A typical WAMR API usage is as described below: +A typical WAMR API usage is shown below: ``` C wasm_module_t module; wasm_module_inst_t inst; @@ -171,12 +175,12 @@ A typical WAMR API usage is as described below: ``` -WASM application library +WASM application library ======================== -In general, there are 3 kinds of API's for programming the WASM application: -- Built-in API's: WAMR has already provided a minimal API set for developers. -- 3rd party API's: Programmer can download and include any 3rd party C source code, and add it into their own WASM app source tree. -- Platform native API's: WAMR provides a mechanism to export the native API to the WASM application. +In general, there are 3 classes of API's important for the WASM application: +- Built-in API's: WAMR provides a minimal API set for developers. +- 3rd party API's: Programmer can download and include any 3rd party C source code and add it into their own WASM app source tree. +- Platform native API's: WAMR provides a mechanism to export a native API to the WASM application. Built-in application library @@ -184,8 +188,7 @@ Built-in application library Built-in API's include Libc APIs, Base library and Extension library reference. **Libc APIs**
-This is the minimal Libc APIs like memory allocation and string copy etc. -The header file is ```lib/app-libs/libc/lib-base.h```. The API set is listed as below: +This is a minimal set of Libc APIs for memory allocation, string manipulation and printing. The header file is located at ```lib/app-libs/libc/lib-base.h```. The current supported API set is listed here: ``` C void *malloc(size_t size); void *calloc(size_t n, size_t size); @@ -206,8 +209,8 @@ char *strncpy(char *dest, const char *src, unsigned long n); ``` **Base library**
-The basic support for communication, timers etc is already available. You can refer to the header file ```lib/app-libs/base/wasm-app.h``` which contains the definitions for request and response API's, event pub/sub APIs and timer APIs. Please note that these API's require the native implementations. -The API set is listed as below: +Basic support for communication, timers, etc is available. You can refer to the header file ```lib/app-libs/base/wasm-app.h``` which contains the definitions for request and response API's, event pub/sub APIs and timer APIs. Please note that these API's require the native implementations. +The API set is listed below: ``` C typedef void(*request_handler_f)(request_t *) ; typedef void(*response_handler_f)(response_t *, void *) ; @@ -245,11 +248,12 @@ bool sensor_close(sensor_t sensor); The mechanism of exporting Native API to WASM application ======================================================= -The basic working flow for WASM application calling into the native API is described in the following diagram. +The basic working flow for WASM application calling into the native API is shown in the following diagram: + -WAMR provides the macro `EXPORT_WASM_API` to enable users to export native API to a WASM application. WAMR implemented a base API for the timer and messaging by using `EXPORT_WASM_API`. They can be a reference point for extending your own library. +WAMR provides the macro `EXPORT_WASM_API` to enable users to export a native API to a WASM application. WAMR has implemented a base API for the timer and messaging by using `EXPORT_WASM_API`. This can be a point of reference for extending your own library. ``` C static NativeSymbol extended_native_symbol_defs[] = { EXPORT_WASM_API(wasm_register_resource), @@ -263,12 +267,11 @@ static NativeSymbol extended_native_symbol_defs[] = { }; ``` - -![#f03c15](https://placehold.it/15/f03c15/000000?text=+) **Security attention:** The WebAssembly application is supposed to access its own memory space, the integrator should carefully design the native function to ensure that the memory is safe. The native API to be exported to the WASM application must follow these rules: +![#f03c15](https://placehold.it/15/f03c15/000000?text=+) **Security attention:** A WebAssembly application should only have access to its own memory space. As a result, the integrator should carefully design the native function to ensure that the memory accesses are safe. The native API to be exported to the WASM application must: - Only use 32 bits number for parameters -- Don't pass data to the structure pointer (do data serialization instead) -- Do the pointer address conversion in the native API -- Don’t pass function pointer as callback +- Should not pass data to the structure pointer (do data serialization instead) +- Should do the pointer address conversion in the native API +- Should not pass function pointer as callback Below is a sample of a library extension. All code invoked across WASM and native world must be serialized and de-serialized, and the native world must do a boundary check for every incoming address from the WASM world. @@ -338,8 +341,7 @@ static NativeSymbol extended_native_symbol_defs[] = ``` Use extended library ------------------------ -In the application source project, it will include the WAMR built-in APIs header file and platform extension header files. -This is assuming the board vendor extends the library which added an API called customized(). The WASM application would be like this: +In the application source project, it will include the WAMR built-in APIs header file and platform extension header files. Assuming the board vendor extends the library which added an API called customized(), the WASM application would be like this: ``` C #include #include "lib-export-dec.h" // provided by the platform vendor @@ -353,11 +355,10 @@ int main(int argc, char **argv) } ``` -Coming soon... +Future Goals ======================== -We are preparing the open source code for the application manager and related code samples like inter-application communication, application life cycle management, 2D graphic demo and more. This will get updated soon. +The application manager and related code samples like inter-application communication, application life cycle management, 2D graphic demo and more ... Submit issues and request ========================= [Click here to submit. Your feedback is always welcome!](https://github.com/intel/wasm-micro-runtime/issues/new) -