[source debug] refine some code in source debugging (#856)

- move the wait_cond from exec_env to debug_instance, so the debug thread can be waken up by any threads
- process more general query message from debugger
- refine debug instance create/destroy mechanism
- avoid creating debug instance during module instantiating
- avoid blocking execution thread during creating debug instance
- update related documents

doc/build_wamr.md

@@ -146,6 +146,10 @@ Currently we only profile the memory consumption of module, module_instance and
 > Note: The WAMR application entry (`core/iwasm/common/wasm_application.c`) encapsulate some common process to instantiate, execute the wasm functions and print the results. Some platform related APIs are used in these functions, so you can enable this flag to exclude this file if your platform doesn't support those APIs.
 > *Don't enable this flag if you are building `product-mini`*
 
+#### **Enable source debugging features**
+- **WAMR_BUILD_DEBUG_INTERP**=1/0, default to 0 if not set
+> Note: There are some other setup required by source debugging, please refer to [source_debugging.md](./source_debugging.md) for more details.
+
 **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/source_debugging.md

@@ -89,3 +89,51 @@ lldb-12 iwasm -- test.aot
 ```
 
 Then you can use lldb commands to debug both wamr runtime and your wasm application in ***current terminal***
+
+## Enable debugging in embedders (for interpreter)
+
+There are three steps to enable debugging in embedders
+
+1. Set the debug parameters when initializing the runtime environment:
+    ``` c
+    RuntimeInitArgs init_args;
+    memset(&init_args, 0, sizeof(RuntimeInitArgs));
+
+    /* ... */
+    strcpy(init_args.ip_addr, "127.0.0.1");
+    init_args.instance_port = 1234;
+    /*
+    * Or set port to 0 to use a port assigned by os
+    * init_args.instance_port = 0;
+    */
+
+    if (!wasm_runtime_full_init(&init_args)) {
+        return false;
+    }
+    ```
+
+2. Use `wasm_runtime_start_debug_instance` to create the debug instance:
+    ``` c
+    /*
+        initialization, loading and instantiating
+        ...
+    */
+    exec_env = wasm_runtime_create_exec_env(module_inst, stack_size);
+    uint32_t debug_port = wasm_runtime_start_debug_instance();
+    ```
+
+3. Enable source debugging features during building
+
+    You can use `-DWAMR_BUILD_DEBUG_INTERP=1` during cmake configuration
+
+    Or you can set it directly in `cmake` files:
+    ``` cmake
+    set (WAMR_BUILD_DEBUG_INTERP 1)
+    ```
+
+### Attentions
+- Debugging `multi-thread wasm module` is not supported, if your wasm module use pthread APIs (see [pthread_library.md](./pthread_library.md)), or the embedder use `wasm_runtime_spawn_thread` to create new wasm threads, then there may be **unexpected behaviour** during debugging.
+
+    > Note: This attention is about "wasm thread" rather than native threads. Executing wasm functions in several different native threads will **not** affect the normal behaviour of debugging feature.
+
+- When using source debugging features, **don't** create multiple `wasm_instance` from the same `wasm_module`, because the debugger may change the bytecode (set/unset breakpoints) of the `wasm_module`. If you do need several instance from the same bytecode, you need to copy the bytecode to a new butter, then load a new `wasm_module`, and then instantiate the new wasm module to get the new instance.