Update document and fix wasm_runtime_call_wasm_a issue (#1005)

Update document memory_tune.md: fix embed wamr link error,
fix description error of wasm operand stack size, update picture.

Fix wasm_runtime_call_wasm_a issue reported by #1003 and update
sample basic to call this API.

Author: wenyongh

core/iwasm/common/wasm_runtime_common.c

@@ -1629,7 +1629,7 @@ wasm_runtime_call_wasm_a(WASMExecEnv *exec_env,
     }
 
     parse_args_to_uint32_array(type, args, argv);
-    if (!(ret = wasm_runtime_call_wasm(exec_env, function, num_args, argv)))
+    if (!(ret = wasm_runtime_call_wasm(exec_env, function, argc, argv)))
         goto fail2;
 
     parse_uint32_array_to_results(type, argv, results);

doc/memory_tune.md

@@ -8,8 +8,8 @@ The memory model of WAMR can be basically described as below:
 <center><img src="./pics/wamr_memory_model.png" width="75%" height="75%"></img></center>
 
 Note:
-- **global heap**: the heap to allocate memory for runtime data structures, including wasm module, wasm module instance, exec env, wasm operand stack and so on. It is initialized by `wasm_runtime_init` or `wasm_runtime_full_init`. And for `wasm_runtime_full_init`, developer can specify the memory allocation mode with `RuntimeInitArgs *init_args`: allocate memory from a user defined byte buffer, from user defined allocation function, or from the platform's os_malloc function. Refer to [wasm_export.h](../core/iwasm/include/wasm_export.h#L98-L141) and [Embedding WAMR guideline](doc/embed_wamr.md#the-runtime-initialization) for more details. And developer can use `wasm_runtime_malloc/wasm_runtime_free` to allocate/free memory from/to the global heap.
-- **wasm operand stack**: the stack to store the operands required by wasm bytecodes as WebAssembly is based on a stack machine. If the exec_env is created by developer with `wasm_runtime_create_exec_env`, then its size is specified by `wasm_runtime_create_exec_env`, or if the exec_env is created by runtime, e.g. creating exec_env in a sub thread, the size is specified by `wasm_runtime_instantiate`.
+- **global heap**: the heap to allocate memory for runtime data structures, including wasm module, wasm module instance, exec env, wasm operand stack and so on. It is initialized by `wasm_runtime_init` or `wasm_runtime_full_init`. And for `wasm_runtime_full_init`, developer can specify the memory allocation mode with `RuntimeInitArgs *init_args`: allocate memory from a user defined byte buffer, from user defined allocation function, or from the platform's os_malloc function. Refer to [wasm_export.h](../core/iwasm/include/wasm_export.h#L98-L141) and [Embedding WAMR guideline](./embed_wamr.md#the-runtime-initialization) for more details. And developer can use `wasm_runtime_malloc/wasm_runtime_free` to allocate/free memory from/to the global heap.
+- **wasm operand stack**: the stack to store the operands required by wasm bytecodes as WebAssembly is based on a stack machine. If the exec_env is created by developer with `wasm_runtime_create_exec_env`, then its size is specified by `wasm_runtime_create_exec_env`, otherwise if the exec_env is created by runtime internally, e.g. by `wasm_application_execute_main` or `wasm_application_execute_func`, then the size is specified by `wasm_runtime_instantiate`.
 - **linear memory**: a contiguous, mutable array of raw bytes. It is created with an initial size but might be grown dynamically. For most compilers, e.g. wasi-sdk, emsdk, rustc or asc, normally it includes three parts, data area, auxiliary stack area and heap area. For wasi-sdk, the initial/max size can be specified with `-Wl,--initial-memory=n1,--max-memory=n2`, for emsdk, the initial/max size can be specified with `-s INITIAL_MEMORY=n1 -s MAXIMUM_MEMORY=n2 -s ALLOW_MEMORY_GROWTH=1` or `-s TOTAL_MEMORY=n`, and for asc, they can be specified with `--initialMemory` and `--maximumMemory` flags.
 - **aux stack**: the auxiliary stack resides in linear memory to store some temporary data when calling wasm functions, for example, calling a wasm function with complex struct arguments. For wasi-sdk, the size can be specified with `-z stack-size=n`, for emsdk, the size can be specified with `-s TOTAL_STACK=n`.
 - **app heap and libc heap**: the heap to allocate memory for wasm app, note that app heap is created only when the malloc/free functions (or __new/__release functions for AssemblyScript) are not exported and runtime can not detect the libc heap. To export the malloc/free functions, for wasi-sdk and emsdk, developer can use `-Wl,--export=malloc -Wl,--export=free` options, for asc, developer can use `--exportRuntime` option. For app heap, the size is specified by `wasm_runtime_instantiate`. It is recommended to export the malloc/free functions and disable app heap in single thread mode, and for multi-threading, as the libc heap isn't thread-safe, it is recommended to remove the dlmalloc.o from libc.a for wasi-sdk and use `-s MALLOC="none"` for emsdk, refer to [WAMR pthread library](./pthread_library.md) for more details. And developer can use `wasm_runtime_module_malloc/wasm_runtime_module_free` to allocate/free memory from/to app heap (or libc heap if malloc/free functions are exported).

doc/pics/wamr_memory_model.png

@@ -22,7 +22,7 @@ cd ${CURR_DIR}
 mkdir -p cmake_build
 cd cmake_build
 cmake ..
-make
+make -j ${nproc}
 if [ $? != 0 ];then
     echo "BUILD_FAIL basic exit as $?\n"
     exit 2

samples/basic/build.sh

@@ -123,28 +123,28 @@ main(int argc, char *argv_main[])
         goto fail;
     }
 
-    uint32 argv[4];
-    double arg_d = 0.000101;
-    argv[0] = 10;
-    // the second arg will occupy two array elements
-    memcpy(&argv[1], &arg_d, sizeof(arg_d));
-    *(float *)(argv + 3) = 300.002;
-
     if (!(func = wasm_runtime_lookup_function(module_inst, "generate_float",
                                               NULL))) {
         printf("The generate_float wasm function is not found.\n");
         goto fail;
     }
 
+    wasm_val_t results[1] = { { .kind = WASM_F32, .of.f32 = 0 } };
+    wasm_val_t arguments[3] = {
+        { .kind = WASM_I32, .of.i32 = 10 },
+        { .kind = WASM_F64, .of.f64 = 0.000101 },
+        { .kind = WASM_F32, .of.f32 = 300.002 },
+    };
+
     // pass 4 elements for function arguments
-    if (!wasm_runtime_call_wasm(exec_env, func, 4, argv)) {
+    if (!wasm_runtime_call_wasm_a(exec_env, func, 1, results, 3, arguments)) {
         printf("call wasm function generate_float failed. %s\n",
                wasm_runtime_get_exception(module_inst));
         goto fail;
     }
 
     float ret_val;
-    memcpy(&ret_val, argv, sizeof(float));
+    ret_val = results[0].of.f32;
     printf("Native finished calling wasm function generate_float(), returned a "
            "float value: %ff\n",
            ret_val);