Re-org memory allocation interfaces, add --stack-size and --heap-size option (#193)

doc/embed_wamr.md

@@ -4,13 +4,11 @@ Embedding WAMR guideline
 
 **Note**: All the embedding APIs supported by the runtime are defined under folder [core/iwasm/include](../core/iwasm/include). The API details are available in the header files.
 
-## The initialization procedure
+## The runtime initialization
 
 
 
 ``` C
-  static char global_heap_buf[512 * 1024];
-
   char *buffer, error_buf[128];
   wasm_module_t module;
   wasm_module_inst_t module_inst;
@@ -18,14 +16,15 @@ Embedding WAMR guideline
   wasm_exec_env_t exec_env;
   uint32 size, stack_size = 8092, heap_size = 8092;
 
-  // all the WAMR heap and WASM applications are limited in this buffer
-  bh_memory_init_with_pool(global_heap_buf, sizeof(global_heap_buf));
-
+  // initialize the wasm runtime by default configurations
   wasm_runtime_init();
 
   // read WASM file into a memory buffer
   buffer = read_wasm_binary_to_buffer(…, &size);
 
+  // Add it below if runtime needs to export native functions to WASM APP 
+  // wasm_runtime_register_natives(...)
+
   // parse the WASM file from buffer and create a WASM module
   module = wasm_runtime_load(buffer, size, error_buf, sizeof(error_buf));
 
@@ -37,9 +36,43 @@ Embedding WAMR guideline
                                          sizeof(error_buf));
 ```
 
+The `wasm_runtime_init()`  will use the default memory allocator from the [`core/shared/platform`](../core/shared/platform) for the runtime memory management.
 
 
 
+The WAMR supports to restrict its all memory allocations in a raw buffer.  It ensures the dynamics by the WASM applications won't harm the system availability, which is extremely important for embedded systems. This can be done by using `wasm_runtime_full_init()`. This function also allows you to configure the native APIs for exporting to WASM app.
+
+Refer to the following sample:
+
+```c
+// the native functions that will be exported to WASM app
+static NativeSymbol native_symbols[] = {
+    EXPORT_WASM_API_WITH_SIG(display_input_read, "(*)i"),
+    EXPORT_WASM_API_WITH_SIG(display_flush, "(iiii*)")
+};
+
+// all the runtime memory allocations are retricted in the global_heap_buf array
+static char global_heap_buf[512 * 1024];
+RuntimeInitArgs init_args;
+memset(&init_args, 0, sizeof(RuntimeInitArgs));
+
+// configure the memory allocator for the runtime
+init_args.mem_alloc_type = Alloc_With_Pool;
+init_args.mem_alloc_option.pool.heap_buf = global_heap_buf;
+init_args.mem_alloc_option.pool.heap_size = sizeof(global_heap_buf);
+
+// configure the native functions being exported to WASM app
+init_args.native_module_name = "env";
+init_args.n_native_symbols = sizeof(native_symbols) / sizeof(NativeSymbol);
+init_args.native_symbols = native_symbols;
+
+/* initialize runtime environment with user configurations*/
+if (!wasm_runtime_full_init(&init_args)) {
+        return -1;
+}
+```
+
+
 
 ## Native calls WASM functions and passes parameters
 
@@ -48,7 +81,8 @@ After a module is instantiated, the runtime native can lookup WASM functions by
 ```c
   unit32 argv[2];
 
-  // lookup a WASM function by its name
+  // lookup a WASM function by its name. 
+  // The function signature can NULL here
   func = wasm_runtime_lookup_function(module_inst, "fib", NULL);
 
   // creat a excution environment which can be used by executing WASM functions
@@ -137,6 +171,10 @@ int32
 wasm_runtime_module_dup_data(WASMModuleInstanceCommon *module_inst,
                              const char *src,
                              uint32 size);
+
+// free the memory allocated from module memory space
+void
+wasm_runtime_module_free(wasm_module_inst_t module_inst, int32_t ptr);
 ```
 
 
@@ -155,6 +193,10 @@ if(buffer_for_wasm != 0)
     argv[0] = buffer_for_wasm;  	// pass the buffer address for WASM space.
     argv[1] = 100;					// the size of buffer
     wasm_runtime_call_wasm(exec_env, func, 2, argv);
+    
+    // it is runtime responsibility to release the memory,
+    // unless the WASM app will free the passed pointer in its code
+    wasm_runtime_module_free(module_inst, buffer);
 }
 
 ```
@@ -174,7 +216,7 @@ We can't pass structure data or class objects through the pointer since the memo
   wasm_runtime_deinstantiate(module_inst);
   wasm_runtime_unload(module);
   wasm_runtime_destroy();
-  bh_memory_destroy();
+
 ```