Add documentation on how to set up and use a Wasm target.

Author: cfallin

gdbstub_arch/src/wasm/mod.rs

@@ -23,9 +23,41 @@
 //! extensions. See the [`self::addr`] submodule for utilities to encode and
 //! decode these synthesized addresses.
 //!
-//! [`Wasm`]: gdbstub::target::ext::wasm::Wasm
+//! To use GDB RSP with these extensions implemented by LLDB:
+//!
+//! 1. Implement the `Target` trait and the [`Wasm`], [`HostInfo`] and
+//!    [`ProcessInfo`] traits on the target implementation for your Wasm
+//!    execution engine/target.
+//! 2. Make use of this `Arch` implementation in your target.
+//! 3. Make use of the [`report_stop_with_regs`] API to report the Wasm PC with
+//!    every stop packet.
+//! 4. Ensure that you have a build of LLDB with the Wasm target enabled. (A
+//!    binary distribution of LLDB with your operating system may not have this,
+//!    but a build from LLVM source will, by default. Once a release of
+//!    [`wasi-sdk`] with [this PR] is made, `wasi-sdk` will distribute such a
+//!    build for all major platforms.)
+//! 5. Start up LLDB and attach it to an endpoint served by `gdbstub` with this
+//!    target:
+//!
+//!        $ .../bin/lldb
+//!        (lldb) process connect --plugin wasm connect://localhost:1234    #
+//! TCP port (for example)
+//!
+//!    then ordinary debugging with breakpoints, step/continue, and state
+//! examination should work.
+//!
+//! See [Wasmtime] for an example of the use of this crate.
+//!
 //! [LLDB-specific Wasm extensions]:
 //!     https://lldb.llvm.org/resources/lldbgdbremote.html#wasm-packets
+//! [`Wasm`]: gdbstub::target::ext::wasm::Wasm
+//! [`HostInfo`]: gdbstub::target::ext::host_info::HostInfo
+//! [`ProcessInfo`]: gdbstub::target::ext::process_info::ProcessInfo
+//! [`report_stop_with_regs`]:
+//!     gdbstub::stub::state_machine::GdbStubStateMachineInner::report_stop_with_regs
+//! [`wasi-sdk`]: https://github.com/WebAssembly/wasi-sdk
+//! [this PR]: https://github.com/WebAssembly/wasi-sdk/pull/596
+//! [Wasmtime]: https://github.com/bytecodealliance/wasmtime
 
 use gdbstub::arch::Arch;