From 12bbb9189cfb0f9094f7f60d0b69ece48cd46a46 Mon Sep 17 00:00:00 2001
From: YAMAMOTO Takashi <yamamoto@midokura.com>
Date: Sat, 17 Sep 2022 22:01:29 +0900
Subject: [PATCH] source_debugging.md: Add some notes about AOT debug (#1496)

---
 doc/source_debugging.md | 68 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 64 insertions(+), 4 deletions(-)

diff --git a/doc/source_debugging.md b/doc/source_debugging.md
index 9292d5da6..a07cebc43 100644
--- a/doc/source_debugging.md
+++ b/doc/source_debugging.md
@@ -86,11 +86,71 @@ wamrc -o test.aot test.wasm
 ```
 
 5. Execute iwasm using lldb
-``` bash
-lldb-12 iwasm -- test.aot
-```
 
-Then you can use lldb commands to debug both wamr runtime and your wasm application in ***current terminal***
+   Then you can use lldb commands to debug both wamr runtime and your wasm application in ***current terminal***.
+
+   ``` bash
+   % lldb iwasm -- test.aot
+   (lldb) target create "iwasm"
+   Current executable set to 'iwasm' (x86_64).
+   (lldb) settings set -- target.run-args  "test.aot"
+   (lldb) settings set plugin.jit-loader.gdb.enable on
+   (lldb) b main
+   Breakpoint 1: where = iwasm`main + 48 at main.c:294:11, address = 0x0000000100001020
+   (lldb) run
+   Process 27954 launched: '/tmp/bin/iwasm' (x86_64)
+   Process 27954 stopped
+   * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
+       frame #0: 0x0000000100001020 iwasm`main(argc=2, argv=0x00007ff7bfeff678) at main.c:294:11
+      291  int
+      292  main(int argc, char *argv[])
+      293  {
+   -> 294      int32 ret = -1;
+      295      char *wasm_file = NULL;
+      296      const char *func_name = NULL;
+      297      uint8 *wasm_file_buf = NULL;
+   Target 0: (iwasm) stopped.
+   (lldb) c
+   Process 27954 resuming
+   1 location added to breakpoint 1
+   error: need to add support for DW_TAG_base_type 'void' encoded with DW_ATE = 0x0, bit_size = 0
+   Process 27954 stopped
+   * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.2
+       frame #0: 0x00000001002980a0 JIT(0x100298004)`main(exenv=0x0000000301808200) at hello.c:6:9
+      3    int
+      4    main(void)
+      5    {
+   -> 6            printf("hello\n");
+      7
+      8            return 0;
+      9    }
+   Target 0: (iwasm) stopped.
+   (lldb) br l
+   Current breakpoints:
+   1: name = 'main', locations = 2, resolved = 2, hit count = 2
+     1.1: where = iwasm`main + 48 at main.c:294:11, address = 0x0000000100001020, resolved, hit count = 1
+     1.2: where = JIT(0x100298004)`main + 12 at hello.c:6:9, address = 0x00000001002980a0, resolved, hit count = 1
+
+   (lldb)
+   ```
+
+   * In the above example,
+
+     * The first `main` function, which is in `main.c`, is the main
+       function of the iwasm command.
+
+     * The second `main` function, which is in `hello.c`, is the main
+       function of the AOT-compiled wasm module.
+
+   * WAMR AOT debugging uses the GDB JIT loader mechanism to load
+     the debug info of the debugee module.
+     On some platforms including macOS, you need to enable it explicitly.
+     (`settings set plugin.jit-loader.gdb.enable on`)
+
+     References:
+
+     * https://github.com/llvm/llvm-project/blob/main/llvm/docs/DebuggingJITedCode.rst
+     * https://sourceware.org/gdb/current/onlinedocs/gdb/JIT-Interface.html
 
 ## Enable debugging in embedders (for interpreter)