Skip to content

Commit 5edd85d

Browse files
yamtyamt
authored
doc: Separate source_debugging.md into two files (#2932)
The original file was confusing as it contains both of interpreter and aot debugging information intermixed.
1 parent 8318333 commit 5edd85d

File tree

3 files changed

+217
-206
lines changed

3 files changed

+217
-206
lines changed

‎doc/source_debugging.md

+2-206
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
11
# WAMR source debugging
22

3-
References:
4-
- [Blog: WAMR source debugging basic](https://bytecodealliance.github.io/wamr.dev/blog/wamr-source-debugging-basic/)
5-
- [Blog: Debugging wasm with VSCode](https://bytecodealliance.github.io/wamr.dev/blog/debugging-wasm-with-vscode/)
6-
7-
WAMR supports source level debugging based on DWARF (normally used in C/C++/Rust), source map (normally used in AssemblyScript) is not supported.
8-
9-
**The lldb's ability to debug wasm application is based on the patch [Add class WasmProcess for WebAssembly debugging](https://reviews.llvm.org/D78801). Thanks very much to the author @paolosev for such a great work!**
10-
113
## Build wasm application with debug information
124
To debug your application, you need to compile them with debug information. You can use `-g` option when compiling the source code if you are using wasi-sdk (also work for emcc and rustc):
135
``` bash
@@ -20,205 +12,9 @@ llvm-dwarfdump-12 test.wasm
2012
```
2113

2214
## Debugging with interpreter
23-
1. Install dependent libraries
24-
``` bash
25-
apt update && apt install cmake make g++ libxml2-dev -y
26-
```
27-
28-
2. Build iwasm with source debugging feature
29-
``` bash
30-
cd ${WAMR_ROOT}/product-mini/platforms/linux
31-
mkdir build && cd build
32-
cmake .. -DWAMR_BUILD_DEBUG_INTERP=1
33-
make
34-
```
35-
> Note: On MacOS M1 environment, pass the additional `-DWAMR_DISABLE_HW_BOUND_CHECK=1` cmake configuration.
36-
37-
3. Execute iwasm with debug engine enabled
38-
``` bash
39-
iwasm -g=127.0.0.1:1234 test.wasm
40-
# Use port = 0 to allow a random assigned debug port
41-
```
42-
43-
4. Build customized lldb
44-
``` bash
45-
git clone --branch release/13.x --depth=1 https://github.com/llvm/llvm-project
46-
cd llvm-project
47-
git apply ${WAMR_ROOT}/build-scripts/lldb_wasm.patch
48-
mkdir build-lldb
49-
cmake -S ./llvm -B build-lldb \
50-
-G Ninja \
51-
-DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;lldb" \
52-
-DLLVM_TARGETS_TO_BUILD:STRING="X86;WebAssembly" \
53-
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DLLVM_BUILD_BENCHMARKS:BOOL=OFF \
54-
-DLLVM_BUILD_DOCS:BOOL=OFF -DLLVM_BUILD_EXAMPLES:BOOL=OFF \
55-
-DLLVM_BUILD_LLVM_DYLIB:BOOL=OFF -DLLVM_BUILD_TESTS:BOOL=OFF \
56-
-DLLVM_ENABLE_BINDINGS:BOOL=OFF -DLLVM_INCLUDE_BENCHMARKS:BOOL=OFF \
57-
-DLLVM_INCLUDE_DOCS:BOOL=OFF -DLLVM_INCLUDE_EXAMPLES:BOOL=OFF \
58-
-DLLVM_INCLUDE_TESTS:BOOL=OFF -DLLVM_ENABLE_LIBXML2:BOOL=ON
59-
cmake --build build-lldb --target lldb --parallel $(nproc)
60-
# The lldb is generated under build-lldb/bin/lldb
61-
```
62-
> Note: If using `CommandLineTools` on MacOS, make sure only one SDK is present in `/Library/Developer/CommandLineTools/SDKs`.
63-
64-
> You can download pre-built `wamr-lldb` binaries from [here](https://github.com/bytecodealliance/wasm-micro-runtime/releases).
6515

66-
5. Launch customized lldb and connect to iwasm
67-
``` bash
68-
lldb
69-
(lldb) process connect -p wasm connect://127.0.0.1:1234
70-
```
71-
Then you can use lldb commands to debug your applications. Please refer to [lldb document](https://lldb.llvm.org/use/tutorial.html) for command usage.
16+
See [Debuggging with interpreter](source_debugging_interpreter.md).
7217

7318
## Debugging with AOT
7419

75-
> Note: AOT debugging is experimental and only a few debugging capabilities are supported.
76-
77-
1. Build lldb (assume you have already built llvm)
78-
``` bash
79-
cd ${WAMR_ROOT}/core/deps/llvm/build
80-
cmake ../llvm -DLLVM_ENABLE_PROJECTS="clang;lldb" -DLLDB_INCLUDE_TESTS=OFF
81-
make -j $(nproc)
82-
```
83-
84-
2. Build wamrc with debugging feature
85-
``` bash
86-
cd ${WAMR_ROOT}/wamr-compiler
87-
mkdir build && cd build
88-
cmake .. -DWAMR_BUILD_DEBUG_AOT=1
89-
make -j $(nproc)
90-
```
91-
92-
3. Build iwasm with debugging feature
93-
``` bash
94-
cd ${WAMR_ROOT}/product-mini/platforms/linux
95-
mkdir build && cd build
96-
cmake .. -DWAMR_BUILD_DEBUG_AOT=1
97-
make
98-
```
99-
100-
4. Compile wasm module to AOT module
101-
``` bash
102-
wamrc -o test.aot test.wasm
103-
```
104-
105-
5. Execute iwasm using lldb
106-
107-
Then you can use lldb commands to debug both wamr runtime and your wasm application in ***current terminal***.
108-
109-
``` bash
110-
% lldb iwasm -- test.aot
111-
(lldb) target create "iwasm"
112-
Current executable set to 'iwasm' (x86_64).
113-
(lldb) settings set -- target.run-args "test.aot"
114-
(lldb) settings set plugin.jit-loader.gdb.enable on
115-
(lldb) b main
116-
Breakpoint 1: where = iwasm`main + 48 at main.c:294:11, address = 0x0000000100001020
117-
(lldb) run
118-
Process 27954 launched: '/tmp/bin/iwasm' (x86_64)
119-
Process 27954 stopped
120-
* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
121-
frame #0: 0x0000000100001020 iwasm`main(argc=2, argv=0x00007ff7bfeff678) at main.c:294:11
122-
291 int
123-
292 main(int argc, char *argv[])
124-
293 {
125-
-> 294 int32 ret = -1;
126-
295 char *wasm_file = NULL;
127-
296 const char *func_name = NULL;
128-
297 uint8 *wasm_file_buf = NULL;
129-
Target 0: (iwasm) stopped.
130-
(lldb) c
131-
Process 27954 resuming
132-
1 location added to breakpoint 1
133-
error: need to add support for DW_TAG_base_type 'void' encoded with DW_ATE = 0x0, bit_size = 0
134-
Process 27954 stopped
135-
* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.2
136-
frame #0: 0x00000001002980a0 JIT(0x100298004)`main(exenv=0x0000000301808200) at hello.c:6:9
137-
3 int
138-
4 main(void)
139-
5 {
140-
-> 6 printf("hello\n");
141-
7
142-
8 return 0;
143-
9 }
144-
Target 0: (iwasm) stopped.
145-
(lldb) br l
146-
Current breakpoints:
147-
1: name = 'main', locations = 2, resolved = 2, hit count = 2
148-
1.1: where = iwasm`main + 48 at main.c:294:11, address = 0x0000000100001020, resolved, hit count = 1
149-
1.2: where = JIT(0x100298004)`main + 12 at hello.c:6:9, address = 0x00000001002980a0, resolved, hit count = 1
150-
151-
(lldb)
152-
```
153-
154-
* In the above example,
155-
156-
* The first `main` function, which is in `main.c`, is the main
157-
function of the iwasm command.
158-
159-
* The second `main` function, which is in `hello.c`, is the main
160-
function of the AOT-compiled wasm module.
161-
162-
* WAMR AOT debugging uses the GDB JIT loader mechanism to load
163-
the debug info of the debugee module.
164-
On some platforms including macOS, you need to enable it explicitly.
165-
(`settings set plugin.jit-loader.gdb.enable on`)
166-
167-
References:
168-
169-
* https://github.com/llvm/llvm-project/blob/main/llvm/docs/DebuggingJITedCode.rst
170-
* https://sourceware.org/gdb/current/onlinedocs/gdb/JIT-Interface.html
171-
172-
## Enable debugging in embedders (for interpreter)
173-
174-
There are three steps to enable debugging in embedders
175-
176-
1. Set the debug parameters when initializing the runtime environment:
177-
``` c
178-
RuntimeInitArgs init_args;
179-
memset(&init_args, 0, sizeof(RuntimeInitArgs));
180-
181-
/* ... */
182-
strcpy(init_args.ip_addr, "127.0.0.1");
183-
init_args.instance_port = 1234;
184-
/*
185-
* Or set port to 0 to use a port assigned by os
186-
* init_args.instance_port = 0;
187-
*/
188-
189-
if (!wasm_runtime_full_init(&init_args)) {
190-
return false;
191-
}
192-
```
193-
194-
2. Use `wasm_runtime_start_debug_instance` to create the debug instance:
195-
``` c
196-
/*
197-
initialization, loading and instantiating
198-
...
199-
*/
200-
exec_env = wasm_runtime_create_exec_env(module_inst, stack_size);
201-
uint32_t debug_port = wasm_runtime_start_debug_instance(exec_env);
202-
```
203-
204-
3. Enable source debugging features during building
205-
206-
You can use `-DWAMR_BUILD_DEBUG_INTERP=1` during cmake configuration
207-
208-
Or you can set it directly in `cmake` files:
209-
``` cmake
210-
set (WAMR_BUILD_DEBUG_INTERP 1)
211-
```
212-
213-
### Attentions
214-
- 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.
215-
216-
> 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.
217-
218-
- 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.
219-
220-
- If you are running `lldb` on non-linux platforms, please use `platform select remote-linux` command in lldb before connecting to the runtime:
221-
```
222-
(lldb) platform select remote-linux
223-
(lldb) process connect -p wasm connect://127.0.0.1:1234
224-
```
20+
See [Debuggging with AOT](source_debugging_aot.md).

‎doc/source_debugging_aot.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# WAMR source debugging (AOT)
2+
3+
## Debugging with AOT
4+
5+
> Note: AOT debugging is experimental and only a few debugging capabilities are supported.
6+
7+
1. Build lldb (assume you have already built llvm)
8+
``` bash
9+
cd ${WAMR_ROOT}/core/deps/llvm/build
10+
cmake ../llvm -DLLVM_ENABLE_PROJECTS="clang;lldb" -DLLDB_INCLUDE_TESTS=OFF
11+
make -j $(nproc)
12+
```
13+
14+
2. Build wamrc with debugging feature
15+
``` bash
16+
cd ${WAMR_ROOT}/wamr-compiler
17+
mkdir build && cd build
18+
cmake .. -DWAMR_BUILD_DEBUG_AOT=1
19+
make -j $(nproc)
20+
```
21+
22+
3. Build iwasm with debugging feature
23+
``` bash
24+
cd ${WAMR_ROOT}/product-mini/platforms/linux
25+
mkdir build && cd build
26+
cmake .. -DWAMR_BUILD_DEBUG_AOT=1
27+
make
28+
```
29+
30+
4. Compile wasm module to AOT module
31+
``` bash
32+
wamrc -o test.aot test.wasm
33+
```
34+
35+
5. Execute iwasm using lldb
36+
37+
Then you can use lldb commands to debug both wamr runtime and your wasm application in ***current terminal***.
38+
39+
``` bash
40+
% lldb iwasm -- test.aot
41+
(lldb) target create "iwasm"
42+
Current executable set to 'iwasm' (x86_64).
43+
(lldb) settings set -- target.run-args "test.aot"
44+
(lldb) settings set plugin.jit-loader.gdb.enable on
45+
(lldb) b main
46+
Breakpoint 1: where = iwasm`main + 48 at main.c:294:11, address = 0x0000000100001020
47+
(lldb) run
48+
Process 27954 launched: '/tmp/bin/iwasm' (x86_64)
49+
Process 27954 stopped
50+
* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
51+
frame #0: 0x0000000100001020 iwasm`main(argc=2, argv=0x00007ff7bfeff678) at main.c:294:11
52+
291 int
53+
292 main(int argc, char *argv[])
54+
293 {
55+
-> 294 int32 ret = -1;
56+
295 char *wasm_file = NULL;
57+
296 const char *func_name = NULL;
58+
297 uint8 *wasm_file_buf = NULL;
59+
Target 0: (iwasm) stopped.
60+
(lldb) c
61+
Process 27954 resuming
62+
1 location added to breakpoint 1
63+
error: need to add support for DW_TAG_base_type 'void' encoded with DW_ATE = 0x0, bit_size = 0
64+
Process 27954 stopped
65+
* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.2
66+
frame #0: 0x00000001002980a0 JIT(0x100298004)`main(exenv=0x0000000301808200) at hello.c:6:9
67+
3 int
68+
4 main(void)
69+
5 {
70+
-> 6 printf("hello\n");
71+
7
72+
8 return 0;
73+
9 }
74+
Target 0: (iwasm) stopped.
75+
(lldb) br l
76+
Current breakpoints:
77+
1: name = 'main', locations = 2, resolved = 2, hit count = 2
78+
1.1: where = iwasm`main + 48 at main.c:294:11, address = 0x0000000100001020, resolved, hit count = 1
79+
1.2: where = JIT(0x100298004)`main + 12 at hello.c:6:9, address = 0x00000001002980a0, resolved, hit count = 1
80+
81+
(lldb)
82+
```
83+
84+
* In the above example,
85+
86+
* The first `main` function, which is in `main.c`, is the main
87+
function of the iwasm command.
88+
89+
* The second `main` function, which is in `hello.c`, is the main
90+
function of the AOT-compiled wasm module.
91+
92+
* WAMR AOT debugging uses the GDB JIT loader mechanism to load
93+
the debug info of the debugee module.
94+
On some platforms including macOS, you need to enable it explicitly.
95+
(`settings set plugin.jit-loader.gdb.enable on`)
96+
97+
References:
98+
99+
* https://github.com/llvm/llvm-project/blob/main/llvm/docs/DebuggingJITedCode.rst
100+
* https://sourceware.org/gdb/current/onlinedocs/gdb/JIT-Interface.html

0 commit comments

Comments
 (0)