[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/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.