Import reference-types feature (#612)

Implement spec reference-types proposal for interpreter, AOT and JIT, update documents and add sample. And upgrade AOT_CURRENT_VERSION to 3 as AOT file format and AOT module instance layout are changed.

Signed-off-by: Wenyong Huang <wenyong.huang@intel.com>

doc/build_wamr.md

@@ -135,6 +135,9 @@ Currently we only profile the memory consumption of module, module_instance and
 >
 > and then use `cmake -DWAMR_BH_VPRINTF=my_vprintf ..` to pass the callback function, or add `BH_VPRINTF=my_vprintf` macro for the compiler, e.g. add line `add_defintions(-DBH_VPRINTF=my_vprintf)` in CMakeListst.txt.
 
+#### **Enable reference types feature**
+- **WAMR_BUILD_REF_TYPES**=1/0, default to disable if not set
+
 **Combination of configurations:**
 
 We can combine the configurations. For example, if we want to disable interpreter, enable AOT and WASI, we can run command:

doc/export_native_api.md

@@ -85,7 +85,7 @@ The function signature field in **NativeSymbol** structure is a string for descr
 
 Each letter in the "()" represents a parameter type, and the one following after ")" represents the return value type. The meaning of each letter:
 
-- '**i**': i32 
+- '**i**': i32 or externref (for externref, developer should use `wasm_externref_obj2ref()` to map host object to externref index firstly)
 - '**I**': i64 
 - '**f**': f32
 - '**F**': f64

doc/ref_types.md

@@ -0,0 +1,22 @@
+# WAMR reference-types introduction
+
+WebAssembly [reference-types](https://github.com/WebAssembly/reference-types) proposal introduces the new type `externref` and makes it easier and more efficient to interoperate with host environment, allowing host references to be represented directly by type externref. And WASM modules can talk about host references directly, rather than requiring external glue code running in the host.
+
+WAMR implements the reference-types proposal, allowing developer to pass the host object to WASM application and then restore and access the host object in native lib. In WAMR internal, the external host object is represented as externref index with `uint32` type, developer must firstly map the host object of `void *` type to the externref index, and then pass the index to the function to called as the function's externref argument.
+
+Currently WAMR provides APIs as below:
+```C
+bool
+wasm_externref_obj2ref(wasm_module_inst_t module_inst,
+                       void *extern_obj, uint32_t *p_externref_idx);
+
+WASM_RUNTIME_API_EXTERN bool
+wasm_externref_ref2obj(uint32_t externref_idx, void **p_extern_obj);
+
+WASM_RUNTIME_API_EXTERN bool
+wasm_externref_retain(uint32 externref_idx);
+```
+
+The `wasm_externref_obj2ref()` API is used to map the host object to the externref index, and the `wasm_externref_ref2obj()` API is used to retrieve the original host object mapped. The `wasm_externref_retain()` API is to retain the host object if we don't want the object to be cleaned when it isn't used during externref object reclaim.
+
+Please ref to the [sample](../samples/ref-types) for more details.