Debugging: add docs to describe how to perform guest debugging. (#13097)

* Debugging: add docs to describe how to perform guest debugging.

* Update docs/examples-debugging-guest.md

Co-authored-by: Nick Fitzgerald <fitzgen@gmail.com>

---------

Co-authored-by: Nick Fitzgerald <fitzgen@gmail.com>

Author: cfallin

docs/examples-debugging-guest.md

@@ -0,0 +1,61 @@
+# Guest (Wasm-only) Debugging with `lldb`
+
+The following steps describe how to use `lldb` to debug the Wasm guest
+on its own -- as if it were running on a virtual Wasm-instruction-set
+computer with hostcalls as single-step indivisible actions. This
+functionality, called "guest debugging", allows for disassembly and
+single instruction stepping at the Wasm bytecode level.
+
+1. Compile your WebAssembly with debug info enabled, usually `-g`; for
+   example:
+
+    ```console
+    clang foo.c -g -o foo.wasm
+    ```
+
+2. Ensure that you have a build of Wasmtime that has the `gdbstub`
+   feature enabled, which is off by default:
+   
+   - Published CLI binary releases already have this feature.
+   - If building from source, use `cargo build --features gdbstub`.
+
+3. Run Wasmtime, enabling the gdbstub server:
+
+    ```console
+    wasmtime run -g 1234 foo.wasm
+    
+    Debugger: Debugger listening on 127.0.0.1:1234
+    Debugger: In LLDB, attach with: process connect --plugin wasm connect://127.0.0.1:1234
+    ```
+    
+   This will start a "debug server" waiting on local TCP port 1234 for
+   a debugger to connect. Execution will not start until the debugger
+   connects and issues a "continue" command.
+   
+4. Run LLDB, connect and debug.
+
+   You'll need a recent version of LLDB (v32 or later) with Wasm
+   support enabled. The [wasi-sdk] distribution provides such a
+   build.
+   
+    ```console
+    /opt/wasi-sdk/bin/lldb
+    (lldb) process connect --plugin wasm connect://0:1234
+    Process 1 stopped
+    * thread #1, stop reason = signal SIGTRAP
+        frame #0: 0x00000000
+    error: memory read failed for 0x0
+    (lldb) b my_function
+    (lldb) continue
+    ```
+    
+   and use LLDB like normal, setting breakpoints, continuing and
+   stepping, examining memory and variable state, etc.
+   
+This functionality should work on any platform that Wasmtime runs on:
+debugging is based on code instrumentation, so does not depend on any
+native system debugging interfaces or introspection capabilities; and
+is supported on all native-compilation ISAs and on Pulley, Wasmtime's
+bytecode platform that runs everywhere.
+   
+[wasi-sdk]: https://github.com/WebAssembly/wasi-sdk/

docs/examples-debugging-native-debugger.md

@@ -1,4 +1,4 @@
-# Debugging with `gdb` and `lldb`
+# Native (Wasm + runtime) Debugging with `gdb` and `lldb`
 
 The following steps describe how to use `gdb` or `lldb` to debug both the Wasm
 guest and the host (i.e. the Wasmtime CLI or your Wasmtime-embedding program) at

docs/examples-debugging.md

@@ -3,6 +3,9 @@
 Wasmtime currently provides the following support for debugging misbehaving
 WebAssembly:
 
+* We can [live debug and step through the guest Wasm on its
+  own.](./examples-debugging-guest.md)
+
 * We can [live debug and step through the guest Wasm and the host at the same
   time with `gdb` or `lldb`.](./examples-debugging-native-debugger.md)