A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! gdbstub protocol implementation in Wasmtime's debug-main world.
mod addr;
mod api;
mod target;
use crate::{
addr::AddrSpace,
api::{WasmType, WasmValue},
};
use anyhow::Result;
use clap::Parser;
use futures::{FutureExt, select};
use gdbstub::{
common::{Signal, Tid},
conn::Connection,
stub::{
MultiThreadStopReason,
state_machine::{GdbStubStateMachine, GdbStubStateMachineInner, state::Running},
},
target::ext::breakpoints::WatchKind,
};
use gdbstub_arch::wasm::addr::WasmAddr;
use log::trace;
use wstd::{
io::{AsyncRead, AsyncWrite},
iter::AsyncIterator,
net::{TcpListener, TcpStream},
};
/// Command-line options.
#[derive(Parser)]
struct Options {
/// The TCP address to listen on, in `<addr>:<port>` format.
///
/// Port 0 instructs the stub server to choose any free port (which
/// will be printed to stderr at startup).
tcp_address: String,
/// Verbose logging.
#[clap(short = 'v')]
verbose: bool,
}
struct Component;
api::export!(Component with_types_in api);
impl api::exports::bytecodealliance::wasmtime::debugger::Guest for Component {
fn debug(d: &api::Debuggee, args: Vec<String>) {
let options = Options::parse_from(args);
if options.verbose {
env_logger::Builder::new()
.filter_level(log::LevelFilter::Trace)
.init();
}
let mut debugger = Debugger {
debuggee: d,
tid: Tid::new(1).unwrap(),
options,
running: None,
current_pc: WasmAddr::from_raw(0).unwrap(),
interrupt: false,
single_stepping: false,
frame_cache: vec![],
addr_space: AddrSpace::new(),
watchpoints: vec![],
pending_watch: None,
};
wstd::runtime::block_on(async {
if let Err(e) = debugger.run().await {
trace!("debugger exited with error: {e}");
}
});
}
}
struct Debugger<'a> {
debuggee: &'a api::Debuggee,
tid: Tid,
options: Options,
running: Option<api::Resumption>,
addr_space: AddrSpace,
interrupt: bool,
single_stepping: bool,
current_pc: WasmAddr,
frame_cache: Vec<api::Frame>,
/// Active write watchpoints, as requested by the client, without
/// duplicates. They may overlap; see `target.rs` for how these are
/// kept in sync with the debuggee's per-byte watches.
watchpoints: Vec<Watchpoint>,
/// A watchpoint was hit and we are stepping over the write before
/// reporting it, holding the address to report.
pending_watch: Option<WasmAddr>,
}
/// One write watchpoint requested by the client.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct Watchpoint {
/// Start of the watched range; always a memory address.
addr: WasmAddr,
/// Length of the watched range, in bytes.
len: u32,
}
impl Watchpoint {
/// Whether this watchpoint covers any byte in `[start, end)` of
/// the memory with the given address-space index.
fn overlaps(&self, memory_index: u32, start: u64, end: u64) -> bool {
let w_start = u64::from(self.addr.offset());
let w_end = w_start + u64::from(self.len);
self.addr.module_index() == memory_index && w_start < end && start < w_end
}
}
impl<'a> Debugger<'a> {
async fn run(&mut self) -> Result<()> {
// Load module info from the debuggee. Modules are
// pre-registered on the debuggee store before the Debuggee is
// created, so they are visible here without needing to
// execute any Wasm.
self.update_on_stop();
let listener = TcpListener::bind(&self.options.tcp_address)
.await
.expect("Could not bind to TCP port");
// Print the actually-bound address rather than the requested
// one, so that binding to port 0 reports the chosen port.
let local_addr = listener
.local_addr()
.expect("Could not get bound TCP address");
api::print_debugger_info(&format!("Debugger listening on {local_addr}"));
api::print_debugger_info(&format!(
"In LLDB, attach with: process connect --plugin wasm connect://{local_addr}",
));
// Only accept one connection for the run; once the debugger
// disconnects, we'll just continue.
let Some(connection) = listener.incoming().next().await else {
return Ok(());
};
let gdbconn = Conn::new(connection?);
let mut stub = gdbstub::stub::GdbStub::new(gdbconn).run_state_machine(&mut *self)?;
// Main loop.
'mainloop: loop {
match stub {
GdbStubStateMachine::Idle(mut inner) => {
if inner.borrow_conn().flush().await.is_err() {
// Connection closed or other outbound error.
break 'mainloop;
}
// Wait for an inbound network byte.
let Some(byte) = inner.borrow_conn().read_byte().await? else {
inner.borrow_conn().flush().await?;
log::info!("Connection closed; debugger detached.");
break 'mainloop;
};
stub = inner.incoming_data(self, byte)?;
}
GdbStubStateMachine::Running(mut inner) => {
if inner.borrow_conn().flush().await.is_err() {
// Connection closed or other outbound error.
break 'mainloop;
}
// Wait for either a resumption or a byte from the
// connection.
let resumption = self
.running
.as_mut()
.expect("In Running state, we must have a resumption future");
select! {
_ = resumption.wait().fuse() => {
let resumption = self.running.take().unwrap();
let event = resumption.result(self.debuggee)?;
stub = self.handle_event(event, inner).await?;
}
byte = inner.borrow_conn().read_byte().fuse() => {
let Some(byte) = byte? else {
// Eat any connection-closed errors on
// the outbound flush.
let _ = inner.borrow_conn().flush().await;
// Connection closed.
log::info!("Connection closed; debugger detached.");
break 'mainloop;
};
stub = inner.incoming_data(&mut *self, byte)?;
}
}
}
GdbStubStateMachine::CtrlCInterrupt(mut inner) => {
if inner.borrow_conn().flush().await.is_err() {
// Connection error: break.
break 'mainloop;
}
// Ask the debuggee to stop; its `interrupted` event is
// then reported as the stop (see `handle_event`).
trace!("Ctrl-C: interrupting debuggee");
self.debuggee.interrupt();
self.interrupt = true;
stub = inner.interrupt_handled(self, None::<MultiThreadStopReason<u64>>)?;
}
GdbStubStateMachine::Disconnected(mut inner) => {
// Eat any connection-closed errors -- we are
// already in Disconnected state.
let _ = inner.borrow_conn().flush().await;
break 'mainloop;
}
}
}
Ok(())
}
fn start_continue(&mut self, resumption: api::ResumptionValue) {
assert!(self.running.is_none());
trace!("continuing");
self.single_stepping = false;
self.running = Some(api::Resumption::continue_(self.debuggee, resumption));
}
fn start_single_step(&mut self, resumption: api::ResumptionValue) {
assert!(self.running.is_none());
trace!("single-stepping");
self.single_stepping = true;
self.running = Some(api::Resumption::single_step(self.debuggee, resumption));
}
fn update_on_stop(&mut self) {
// Any stop satisfies a pending interrupt request.
self.interrupt = false;
self.addr_space.update(self.debuggee).unwrap();
// Cache all frame handles for the duration of this stop.
// The Wasm trait methods take `&self` and need access to
// frames by depth, so we eagerly walk the full stack here.
self.frame_cache.clear();
let mut next = self.debuggee.exit_frames().into_iter().next();
while let Some(f) = next {
next = f.parent_frame(self.debuggee).unwrap();
self.frame_cache.push(f);
}
if let Some(f) = self.frame_cache.first() {
self.current_pc = self.addr_space.frame_to_pc(f, self.debuggee);
} else {
self.current_pc = WasmAddr::from_raw(0).unwrap();
}
}
/// The address to report to the client for a watchpoint hit: the
/// first byte of the write that a client watchpoint covers, so
/// that the client can match it to one of its watchpoints even if
/// the write starts below the watched range.
fn watch_hit_addr(&mut self, hit: &api::WatchpointHit) -> WasmAddr {
let start = hit.address;
let end = hit.address.saturating_add(hit.len);
let base = self.addr_space.memory_addr(&hit.memory, 0);
let memory_index = base.module_index();
let first_watched = self
.watchpoints
.iter()
.filter(|w| w.overlaps(memory_index, start, end))
.map(|w| start.max(u64::from(w.addr.offset())))
.min()
.unwrap_or(start);
let offset = u32::try_from(first_watched).unwrap_or(u32::MAX);
self.addr_space.memory_addr(&hit.memory, offset)
}
async fn handle_event<'b>(
&mut self,
event: api::Event,
inner: GdbStubStateMachineInner<'b, Running, Self, Conn>,
) -> Result<GdbStubStateMachine<'b, Self, Conn>> {
match event {
api::Event::Watchpoint(hit) => {
// The debuggee pauses *before* the write, but gdb and
// LLDB expect watchpoints on this target to trigger
// after the write (they then compare the old and new
// values). So first single-step over the write, then
// report the watchpoint when that step completes.
let addr = self.watch_hit_addr(&hit);
trace!(
"Event::Watchpoint: address {:#x} len {} -> reporting {:#x}",
hit.address,
hit.len,
addr.as_raw()
);
let single_stepping = self.single_stepping;
self.pending_watch = Some(addr);
self.start_single_step(api::ResumptionValue::Normal);
// Keep the client's resume mode so that any event
// other than the step's completion is handled as it
// would have been.
self.single_stepping = single_stepping;
Ok(GdbStubStateMachine::Running(inner))
}
api::Event::Breakpoint if self.pending_watch.is_some() => {
let addr = self.pending_watch.take().unwrap();
trace!("stepped over watched write; reporting watchpoint");
self.update_on_stop();
let pc_bytes = self.current_pc.as_raw().to_le_bytes();
let mut regs = core::iter::once((
gdbstub_arch::wasm::reg::id::WasmRegId::Pc,
pc_bytes.as_slice(),
));
Ok(inner.report_stop_with_regs(
self,
MultiThreadStopReason::Watch {
tid: self.tid,
kind: WatchKind::Write,
addr: addr.as_raw(),
},
&mut regs,
)?)
}
api::Event::Complete => {
trace!("Event::Complete");
self.pending_watch = None;
let pc_bytes = self.current_pc.as_raw().to_le_bytes();
let mut regs = core::iter::once((
gdbstub_arch::wasm::reg::id::WasmRegId::Pc,
pc_bytes.as_slice(),
));
Ok(inner.report_stop_with_regs(
self,
MultiThreadStopReason::Exited(0),
&mut regs,
)?)
}
api::Event::Breakpoint => {
trace!(
"Event::Breakpoint; single_stepping = {}",
self.single_stepping
);
self.update_on_stop();
let stop_reason = if self.single_stepping {
MultiThreadStopReason::SignalWithThread {
tid: self.tid,
signal: Signal::SIGTRAP,
}
} else {
MultiThreadStopReason::SwBreak(self.tid)
};
let pc_bytes = self.current_pc.as_raw().to_le_bytes();
let mut regs = core::iter::once((
gdbstub_arch::wasm::reg::id::WasmRegId::Pc,
pc_bytes.as_slice(),
));
Ok(inner.report_stop_with_regs(self, stop_reason, &mut regs)?)
}
api::Event::Trap => {
trace!("Event::Trap");
self.pending_watch = None;
self.update_on_stop();
let pc_bytes = self.current_pc.as_raw().to_le_bytes();
let mut regs = core::iter::once((
gdbstub_arch::wasm::reg::id::WasmRegId::Pc,
pc_bytes.as_slice(),
));
Ok(inner.report_stop_with_regs(
self,
// We report all traps as SIGSEGV for now.
MultiThreadStopReason::SignalWithThread {
tid: self.tid,
signal: Signal::SIGSEGV,
},
&mut regs,
)?)
}
_ => {
trace!("other event: {event:?}");
if self.interrupt {
self.interrupt = false;
self.pending_watch = None;
self.update_on_stop();
let pc_bytes = self.current_pc.as_raw().to_le_bytes();
let mut regs = core::iter::once((
gdbstub_arch::wasm::reg::id::WasmRegId::Pc,
pc_bytes.as_slice(),
));
Ok(inner.report_stop_with_regs(
self,
MultiThreadStopReason::Signal(Signal::SIGINT),
&mut regs,
)?)
} else {
if self.pending_watch.is_some() {
// Still stepping over a watched write.
let single_stepping = self.single_stepping;
self.start_single_step(api::ResumptionValue::Normal);
self.single_stepping = single_stepping;
} else if self.single_stepping {
self.start_single_step(api::ResumptionValue::Normal);
} else {
self.start_continue(api::ResumptionValue::Normal);
}
Ok(GdbStubStateMachine::Running(inner))
}
}
}
}
fn value_to_bytes(&self, value: WasmValue) -> Vec<u8> {
match value.get_type() {
WasmType::WasmI32 => value.unwrap_i32().to_le_bytes().to_vec(),
WasmType::WasmI64 => value.unwrap_i64().to_le_bytes().to_vec(),
WasmType::WasmF32 => value.unwrap_f32().to_le_bytes().to_vec(),
WasmType::WasmF64 => value.unwrap_f64().to_le_bytes().to_vec(),
WasmType::WasmV128 => value.unwrap_v128(),
WasmType::WasmFuncref => 0u32.to_le_bytes().to_vec(),
WasmType::WasmExnref => 0u32.to_le_bytes().to_vec(),
}
}
}
struct Conn {
buf: Vec<u8>,
conn: TcpStream,
}
impl Conn {
fn new(conn: TcpStream) -> Self {
Conn { buf: vec![], conn }
}
async fn flush(&mut self) -> anyhow::Result<()> {
self.conn.write_all(&self.buf).await?;
self.buf.clear();
Ok(())
}
async fn read_byte(&mut self) -> Result<Option<u8>> {
let mut buf = [0u8];
let len = self.conn.read(&mut buf).await?;
if len == 1 { Ok(Some(buf[0])) } else { Ok(None) }
}
}
impl Drop for Conn {
fn drop(&mut self) {
assert!(
self.buf.is_empty(),
"failed to async-flush before dropping connection write buffer"
);
}
}
impl Connection for Conn {
type Error = anyhow::Error;
fn write(&mut self, byte: u8) -> std::result::Result<(), Self::Error> {
self.buf.push(byte);
Ok(())
}
fn flush(&mut self) -> std::result::Result<(), Self::Error> {
// We cannot flush synchronously; we leave this to the `async
// fn flush` method called within the main loop. Fortunately
// the gdbstub cannot wait for a response before returning to
// the main loop, so we cannot introduce any deadlocks by
// failing to flush synchronously here.
Ok(())
}
}