Update README, change wasi primitive lib position and add some except…

…ion checks (#146)

Add exception throw when some initial checks fail in executing main or specific function

README.md

@@ -14,87 +14,122 @@ WebAssembly Micro Runtime (WAMR) is a standalone WebAssembly (WASM) runtime with
 Current Features of WAMR
 =========================
 - WASM interpreter (AOT is planned)
-- Supports for a subset of Libc API.
-- Supports for [WASI API](https://github.com/WebAssembly/WASI)
 - Provides embedding C API
 - 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
-- The purely asynchronized programming model
-- Menu configuration for easy platform integration
-- Supports micro-service and pub-sub event inter-app communication models
-- Easy to extend to support remote FW application management from host or cloud
+- Supports libc for WASM applications in two modes: the built-in libc subset for embedded environment and [WASI](https://github.com/WebAssembly/WASI) for standard libc
+- The WASM application framework and asynchronized app programming model
+- Supports for micro-service and pub-sub event inter-app communication models
+- Supports remote WASM application management from either host or cloud
+- Menu configuration for easy integration of application libraries
 
 Application framework architecture
 ===================================
 
-By using the iwasm VM core, we are flexible to build different application frameworks for the specific domains. 
+By using the iwasm VM core, we are flexible to build different application frameworks for the specific domains.
 
 The WAMR has offered a comprehensive application framework for device and IoT usages. The framework solves many common requirements for building a real project:
 - Modular design for more language runtimes support
 - Inter application communication
 - Remote application management
-- WASM APP programming model and API extension mechanism 
+- WASM APP programming model and API extension mechanism
 
 <img src="./doc/pics/wamr-arch.JPG" width="80%">
 
 
 
-Build WAMR Core and run WASM applications
-================================================
+Build WAMR
+==========
 
-WAMR VM core (iwasm) can support building on different platforms:
+## Build WAMR VM core
+
+
+WAMR VM core (iwasm) can support building for different target platforms:
 - Linux
 - Zephyr
 - Mac
 - VxWorks
 - AliOS-Things
-- Docker
 - Intel Software Guard Extention (SGX)
 
-After building the iwasm, we can compile some basic WASM applications and run it from the WAMR core. As the WAMR core doesn't include the extended application library, your WASM applications can only use the [WAMR built-in APIs](./doc/wamr_api.md).     
+See [Build WAMR VM core](./doc/build_wamr.md) for the detailed instructions.
 
-See the [doc/building.md](./doc/building.md) for the detailed instructions.
+## Libc building options
 
+WAMR supports WASI for standard libc library as well as a [built-in libc subset](./doc/wamr_api.md) for tiny footprint.
 
-Embed WAMR 
-===========
+WASI is supported for following platforms and enabled by default building:
+- Linux
 
-WAMR can be built into a standalone executable which takes the WASM application file name as input, and then executes it. In some other situations, the WAMR source code is embedded the product code and built into the final product. 
 
-WAMR provides a set of C API for loading the WASM module, instantiating the module and invoking a WASM function from a native call. 
 
-See the [doc/embed_wamr.md](./doc/embed_wamr.md) for the details.
+## Embed WAMR VM core
 
-WAMR application programming library
-===================================
+WAMR can be built into a standalone executable which takes the WASM application file name as input, and then executes it. In some other situations, the WAMR source code is embedded the product code and built into the final product.
+
+WAMR provides a set of C API for loading the WASM module, instantiating the module and invoking a WASM function from a native call.  See [Embed WAMR VM core](./doc/embed_wamr.md) for the details.
+
+The WAMR application framework supports dynamically installing WASM application remotely by embedding the WAMR VM core. It can be used as reference for how to use the embedding API's.
+
+
+## Integrate  WAMR application library
+
+The WAMR provides an application framework which supports event driven programming model as below:
 
-WAMR defined event driven programming model:
 - Single thread per WASM app instance
 - App must implement system callbacks: on_init, on_destroy
 
+Application programming API sets are available as below:
+
+- Timer
+- Micro service (Request/Response) and Pub/Sub inter-app communication
+- Sensor
+- Connectivity and data transmission
+- 2D graphic UI (based on littlevgl)
+
+See [WAMR application library](./doc/wamr_api.md) for the details.
+
+One WAMR runtime version can also select a subsets from the WAMR application library. Refer to the sample "simple" for how to integrate API sets into WAMR building.
+
+
+
+## Build WAMR with customized application library
+
+In general when you build a WAMR version for a specific project, you probably will create additional API's for the applications. The API's can be expansion or modification to the standard WAMR application library.
+
+The extended application library should be created in the folder [core/iwasm/lib/app-libs](./core/iwasm/lib/app-libs/). See the [doc/export_native_api.md](./doc/export_native_api.md) for the details.
+
+
+
+# Create WASM application SDK
+
+When you ship your WAMR runtime with the products, you will need to distribute the associated WASM application SDK for the application developers to develop WASM applications for your products. At the most time, the WASM application SDK should have a version match with the runtime distribution.
+
+
+
+Typically there are a few components in a WASM APP SDK package:
+
+* **WASI-SDK**: only needed when WASI is enabled in the runtime. It can be a link to the WASI-SDK GitHub or the full offline copy.
+* **sysroot** folder: only needed when WASI is not enabled in the runtime. copied from [test-tools/toolchain/sysroot](./test-tools/toolchain/sysroot)
+* **app-lib** folder: copied from [core/iwasm/lib/app-libs](./core/iwasm/lib/app-libs/)
+* **cmake toolchain** file: copied from [test-tools/toolchain/wamr_toolchain.cmake](./test-tools/toolchain/wamr_toolchain.cmake)
+* optionally with some guide documents and samples
+
+
+
+Build WASM applications
+===================================
 
-In general there are a few API classes for the WASM application programming:
-- WAMR Built-in API: WAMR core provides a minimal libc API set for WASM APP
-- WAMR application libraries: 
-  - Timer
-  - Micro service (Request/Response)
-  - Pub/Sub
-  - Sensor
-  - Connection and data transmission
-  - 2D graphic UI (based on littlevgl)
-- User extended native API: extend the native API to the WASM applications
-- 3rd party libraries: Programmers can download any 3rd party C/C++ source code and build it together with the WASM APP code
+WebAssembly as a new binary instruction can be viewed as a virtual architecture. If the WASM application is developed in C/C++ language,  developers can use conventional cross-compilation procedure to build the WASM application.  cmake is the recommended building tool and Clang is the preferred compiler. While emcc may still work but it is not guaranteed.
 
-See the [doc/wamr_api.md](./doc/wamr_api.md) for the details.
+Refer to [Build WASM applications](doc/build_wasm_app.md) for details.
 
 
 Samples and demos
 =================
 
 The WAMR samples are located in folder [./samples](./samples). A sample usually contains the WAMR runtime build, WASM applications and test tools. The WARM provides following samples:
 - [Simple](./samples/simple/README.md): The runtime is integrated with most of the WAMR APP libaries and multiple WASM applications are provided for using different WASM API set.
-- [littlevgl](./samples/littlevgl/README.md): Demostrating the graphic user interface application usage on WAMR. The whole [LittlevGL](https://github.com/littlevgl/) 2D user graphic library and the UI application is built into WASM application.  
+- [littlevgl](./samples/littlevgl/README.md): Demostrating the graphic user interface application usage on WAMR. The whole [LittlevGL](https://github.com/littlevgl/) 2D user graphic library and the UI application is built into WASM application.
 - [gui](./samples/gui/README.md): Moved the [LittlevGL](https://github.com/littlevgl/) library into the runtime and defined a WASM application interface by wrapping the littlevgl API.
 - [IoT-APP-Store-Demo](./test-tools/IoT-APP-Store-Demo/README.md): A web site for demostrating a WASM APP store usage where we can remotely install and uninstall WASM application on remote devices.
 
@@ -109,9 +144,9 @@ The graphic user interface demo photo:
 Releases and acknowledgments
 ============================
 
-WAMR is a community efforts. Since Intel Corp contributed the first release of this open source project, this project has received many good contributions from the community. 
+WAMR is a community efforts. Since Intel Corp contributed the first release of this open source project, this project has received many good contributions from the community.
 
-See the [major features releasing history and contributor names](./doc/release_ack.md)   
+See the [major features releasing history and contributor names](./doc/release_ack.md)
 
 
 Roadmap

core/iwasm/lib/native/libc/wasm_libc.cmake

@@ -6,7 +6,7 @@ set (WASM_LIBC_DIR ${CMAKE_CURRENT_LIST_DIR})
 include_directories(${WASM_LIBC_DIR})
 
 
-file (GLOB_RECURSE source_all ${WASM_LIBC_DIR}/*.c)
+file (GLOB source_all ${WASM_LIBC_DIR}/*.c)
 
 set (WASM_LIBC_SOURCE ${source_all})
 

core/iwasm/products/darwin/CMakeLists.txt

@@ -61,8 +61,8 @@ if (CMAKE_SIZEOF_VOID_P EQUAL 8)
 endif ()
 
 if (NOT DEFINED WASM_ENABLE_WASI)
-  # Enable wasi support by default
-  set (WASM_ENABLE_WASI 1)
+  # Disable wasi support by default
+  set (WASM_ENABLE_WASI 0)
 endif ()
 
 if (WASM_ENABLE_WASI EQUAL 1)
@@ -95,7 +95,7 @@ enable_language (ASM)
 include (../../runtime/platform/${PLATFORM}/platform.cmake)
 include (../../runtime/utils/utils.cmake)
 include (../../runtime/vmcore-wasm/vmcore.cmake)
-include (../../runtime/wasmtime-wasi-c/wasi.cmake)
+include (../../lib/native/libc/wasmtime-wasi-c/wasi.cmake)
 include (../../lib/native/base/wasm_lib_base.cmake)
 include (../../lib/native/libc/wasm_libc.cmake)
 include (${SHARED_LIB_DIR}/platform/${PLATFORM}/shared_platform.cmake)

core/iwasm/products/darwin/main.c

@@ -129,6 +129,7 @@ app_instance_repl(wasm_module_inst_t module_inst)
     return NULL;
 }
 
+#if WASM_ENABLE_WASI != 0
 static bool
 validate_env_str(char *env)
 {
@@ -145,6 +146,7 @@ validate_env_str(char *env)
 
     return true;
 }
+#endif
 
 #define USE_GLOBAL_HEAP_BUF 0
 

core/iwasm/products/linux-sgx/CMakeLists.txt

@@ -96,7 +96,7 @@ enable_language (ASM)
 include (../../runtime/platform/${PLATFORM}/platform.cmake)
 include (../../runtime/utils/utils.cmake)
 include (../../runtime/vmcore-wasm/vmcore.cmake)
-include (../../runtime/wasmtime-wasi-c/wasi.cmake)
+include (../../lib/native/libc/wasmtime-wasi-c/wasi.cmake)
 include (../../lib/native/base/wasm_lib_base.cmake)
 include (../../lib/native/libc/wasm_libc.cmake)
 include (${SHARED_LIB_DIR}/platform/${PLATFORM}/shared_platform.cmake)

core/iwasm/products/linux/CMakeLists.txt

@@ -92,7 +92,7 @@ enable_language (ASM)
 include (../../runtime/platform/${PLATFORM}/platform.cmake)
 include (../../runtime/utils/utils.cmake)
 include (../../runtime/vmcore-wasm/vmcore.cmake)
-include (../../runtime/wasmtime-wasi-c/wasi.cmake)
+include (../../lib/native/libc/wasmtime-wasi-c/wasi.cmake)
 include (../../lib/native/base/wasm_lib_base.cmake)
 include (../../lib/native/libc/wasm_libc.cmake)
 include (${SHARED_LIB_DIR}/platform/${PLATFORM}/shared_platform.cmake)

core/iwasm/products/linux/main.c

@@ -156,6 +156,7 @@ app_instance_repl(wasm_module_inst_t module_inst)
     return NULL;
 }
 
+#if WASM_ENABLE_WASI != 0
 static bool
 validate_env_str(char *env)
 {
@@ -172,6 +173,7 @@ validate_env_str(char *env)
 
     return true;
 }
+#endif
 
 #define USE_GLOBAL_HEAP_BUF 0
 

core/iwasm/products/vxworks/CMakeLists.txt

@@ -78,8 +78,8 @@ if (CMAKE_SIZEOF_VOID_P EQUAL 8)
 endif ()
 
 if (NOT DEFINED WASM_ENABLE_WASI)
-  # Enable wasi support by default
-  set (WASM_ENABLE_WASI 1)
+  # Disable wasi support by default
+  set (WASM_ENABLE_WASI 0)
 endif ()
 
 if (WASM_ENABLE_WASI EQUAL 1)
@@ -110,7 +110,7 @@ enable_language (ASM)
 include (../../runtime/platform/${PLATFORM}/platform.cmake)
 include (../../runtime/utils/utils.cmake)
 include (../../runtime/vmcore-wasm/vmcore.cmake)
-include (../../runtime/wasmtime-wasi-c/wasi.cmake)
+include (../../lib/native/libc/wasmtime-wasi-c/wasi.cmake)
 include (../../lib/native/base/wasm_lib_base.cmake)
 include (../../lib/native/libc/wasm_libc.cmake)
 include (${SHARED_LIB_DIR}/platform/${PLATFORM}/shared_platform.cmake)

core/iwasm/products/vxworks/main.c

@@ -156,6 +156,7 @@ app_instance_repl(wasm_module_inst_t module_inst)
     return NULL;
 }
 
+#if WASM_ENABLE_WASI != 0
 static bool
 validate_env_str(char *env)
 {
@@ -172,6 +173,7 @@ validate_env_str(char *env)
 
     return true;
 }
+#endif
 
 static char global_heap_buf[512 * 1024] = { 0 };
 

core/iwasm/runtime/vmcore-wasm/wasm_application.c

@@ -105,11 +105,17 @@ wasm_application_execute_main(WASMModuleInstance *module_inst,
 #endif
 
     func = resolve_main_function(module_inst);
-    if (!func || func->is_import_func)
+    if (!func || func->is_import_func) {
+        wasm_runtime_set_exception(module_inst,
+                                   "lookup main function failed.");
         return false;
+    }
 
-    if (!check_main_func_type(func->u.func->func_type))
+    if (!check_main_func_type(func->u.func->func_type)) {
+        wasm_runtime_set_exception(module_inst,
+                                   "invalid function type of main function.");
         return false;
+    }
 
     if (func->u.func->func_type->param_count) {
         for (i = 0; i < argc; i++)
@@ -120,8 +126,11 @@ wasm_application_execute_main(WASMModuleInstance *module_inst,
 
         if (total_size >= UINT32_MAX
             || !(argv_buf_offset =
-                    wasm_runtime_module_malloc(module_inst, (uint32)total_size)))
+                    wasm_runtime_module_malloc(module_inst, (uint32)total_size))) {
+            wasm_runtime_set_exception(module_inst,
+                                       "allocate memory failed.");
             return false;
+        }
 
         argv_buf = p = wasm_runtime_addr_app_to_native(module_inst, argv_buf_offset);
         argv_offsets = (int32*)(p + total_argv_size);
@@ -209,25 +218,28 @@ wasm_application_execute_func(WASMModuleInstance *module_inst,
     int32 i, p;
     uint64 total_size;
     const char *exception;
+    char buf[128];
 
     wasm_assert(argc >= 0);
     func = resolve_function(module_inst, name);
     if (!func || func->is_import_func) {
-        LOG_ERROR("Wasm lookup function %s failed.\n", name);
+        snprintf(buf, sizeof(buf), "lookup function %s failed.", name);
+        wasm_runtime_set_exception(module_inst, buf);
         return false;
     }
 
     type = func->u.func->func_type;
     if (type->param_count != (uint32)argc) {
-        LOG_ERROR("Wasm prepare param failed: invalid param count.\n");
+        wasm_runtime_set_exception(module_inst,
+                                   "invalid input argument count.");
         return false;
     }
 
     argc1 = func->param_cell_num;
     total_size = sizeof(uint32) * (uint64)(argc1 > 2 ? argc1 : 2);
     if (total_size >= UINT32_MAX
         || (!(argv1 = wasm_malloc((uint32)total_size)))) {
-        LOG_ERROR("Wasm prepare param failed: malloc failed.\n");
+        wasm_runtime_set_exception(module_inst, "allocate memory failed.");
         return false;
     }
 
@@ -236,7 +248,8 @@ wasm_application_execute_func(WASMModuleInstance *module_inst,
         char *endptr = NULL;
         wasm_assert(argv[i] != NULL);
         if (argv[i][0] == '\0') {
-            LOG_ERROR("Wasm prepare param failed: invalid num (%s).\n", argv[i]);
+            snprintf(buf, sizeof(buf), "invalid input argument %d.", i);
+            wasm_runtime_set_exception(module_inst, buf);
             goto fail;
         }
         switch (type->types[i]) {
@@ -303,11 +316,15 @@ wasm_application_execute_func(WASMModuleInstance *module_inst,
             }
         }
         if (endptr && *endptr != '\0' && *endptr != '_') {
-            LOG_ERROR("Wasm prepare param failed: invalid num (%s).\n", argv[i]);
+            snprintf(buf, sizeof(buf), "invalid input argument %d: %s.",
+                     i, argv[i]);
+            wasm_runtime_set_exception(module_inst, buf);
             goto fail;
         }
         if (errno != 0) {
-            LOG_ERROR("Wasm prepare param failed: errno %d.\n", errno);
+            snprintf(buf, sizeof(buf),
+                     "prepare function argument error, errno: %d.", errno);
+            wasm_runtime_set_exception(module_inst, buf);
             goto fail;
         }
     }