A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
Debugging: add a debugger callback mechanism to handle debug events. (#11895)
Chris Falline4190de85377
diff --git a/crates/wasmtime/Cargo.toml b/crates/wasmtime/Cargo.tomlindex 671981eb65..cf0057cb1c 100644--- a/crates/wasmtime/Cargo.toml+++ b/crates/wasmtime/Cargo.toml@@ -415,5 +415,8 @@ component-model-async-bytes = []# Enables support for guest debugging.-debug = ['runtime']+debug = [+ 'runtime',+ 'async'+]diff --git a/crates/wasmtime/src/runtime/debug.rs b/crates/wasmtime/src/runtime/debug.rsindex 695de775d3..70bcef9526 100644--- a/crates/wasmtime/src/runtime/debug.rs+++ b/crates/wasmtime/src/runtime/debug.rs@@ -1,8 +1,8 @@//! Debugging API.use crate::{- AnyRef, AsContext, AsContextMut, ExnRef, ExternRef, Func, Instance, Module, StoreContext,- StoreContextMut, Val,+ AnyRef, AsContext, AsContextMut, ExnRef, ExternRef, Func, Instance, Module, OwnedRooted,+ StoreContext, StoreContextMut, Val,store::{AutoAssertNoGc, StoreOpaque},vm::{CurrentActivationBacktrace, VMContext},};@@ -13,7 +13,7 @@ use core::{ffi::c_void, ptr::NonNull};use wasmtime_environ::FrameTable;use wasmtime_environ::{DefinedFuncIndex, FrameInstPos, FrameStackShape, FrameStateSlot, FrameStateSlotOffset,- FrameTableDescriptorIndex, FrameValType, FuncKey,+ FrameTableDescriptorIndex, FrameValType, FuncKey, Trap,};use wasmtime_unwinder::Frame;@@ -445,3 +445,75 @@ impl<'a, T: 'static> AsContextMut for DebugFrameCursor<'a, T> {StoreContextMut(self.iter.store.0)}}++/// One debug event that occurs when running Wasm code on a store with+/// a debug handler attached.+#[derive(Debug)]+pub enum DebugEvent<'a> {+ /// An `anyhow::Error` was raised by a hostcall.+ HostcallError(&'a anyhow::Error),+ /// An exception is thrown and caught by Wasm. The current state+ /// is at the throw-point.+ CaughtExceptionThrown(OwnedRooted<ExnRef>),+ /// An exception was not caught and is escaping to the host.+ UncaughtExceptionThrown(OwnedRooted<ExnRef>),+ /// A Wasm trap occurred.+ Trap(Trap),+}++/// A handler for debug events.+///+/// This is an async callback that is invoked directly within the+/// context of a debug event that occurs, i.e., with the Wasm code+/// still on the stack. The callback can thus observe that stack, up+/// to the most recent entry to Wasm.[^1]+///+/// Because this callback receives a `StoreContextMut`, it has full+/// access to any state that any other hostcall has, including the+/// `T`. In that way, it is like an epoch-deadline callback or a+/// call-hook callback. It also "freezes" the entire store for the+/// duration of the debugger callback future.+///+/// In the future, we expect to provide an "externally async" API on+/// the `Store` that allows receiving a stream of debug events and+/// accessing the store mutably while frozen; that will need to+/// integrate with [`Store::run_concurrent`] to properly timeslice and+/// scope the mutable access to the store, and has not been built+/// yet. In the meantime, it should be possible to build a fully+/// functional debugger with this async-callback API by channeling+/// debug events out, and requests to read the store back in, over+/// message-passing channels between the callback and an external+/// debugger main loop.+///+/// Note that the `handle` hook may use its mutable store access to+/// invoke another Wasm. Debug events will also be caught and will+/// cause further `handle` invocations during this recursive+/// invocation. It is up to the debugger to handle any implications of+/// this reentrancy (e.g., implications on a duplex channel protocol+/// with an event/continue handshake) if it does so.+///+/// Note also that this trait has `Clone` as a supertrait, and the+/// handler is cloned at every invocation as an artifact of the+/// internal ownership structure of Wasmtime: the handler itself is+/// owned by the store, but also receives a mutable borrow to the+/// whole store, so we need to clone it out to invoke it. It is+/// recommended that this trait be implemented by a type that is cheap+/// to clone: for example, a single `Arc` handle to debugger state.+///+/// [^1]: Providing visibility further than the most recent entry to+/// Wasm is not directly possible because it could see into+/// another async stack, and the stack that polls the future+/// running a particular Wasm invocation could change after each+/// suspend point in the handler.+pub trait DebugHandler: Clone + Send + Sync + 'static {+ /// The data expected on the store that this handler is attached+ /// to.+ type Data;++ /// Handle a debug event.+ fn handle(+ &self,+ store: StoreContextMut<'_, Self::Data>,+ event: DebugEvent<'_>,+ ) -> impl Future<Output = ()> + Send;+}diff --git a/crates/wasmtime/src/runtime/store.rs b/crates/wasmtime/src/runtime/store.rsindex 4bde59d5b2..b38e4f806d 100644--- a/crates/wasmtime/src/runtime/store.rs+++ b/crates/wasmtime/src/runtime/store.rs@@ -76,6 +76,10 @@//! contents of `StoreOpaque`. This is an invariant that we, as the authors of//! `wasmtime`, must uphold for the public interface to be safe.+#[cfg(feature = "debug")]+use crate::DebugHandler;+#[cfg(all(feature = "gc", feature = "debug"))]+use crate::OwnedRooted;use crate::RootSet;#[cfg(feature = "gc")]use crate::ThrownException;@@ -259,6 +263,50 @@ pub struct StoreInner<T: 'static> {////// For comments about `ManuallyDrop`, see `Store::into_data`.data_no_provenance: ManuallyDrop<T>,++ /// The user's debug handler, if any. See [`crate::DebugHandler`]+ /// for more documentation.+ ///+ /// We need this to be an `Arc` because the handler itself takes+ /// `&self` and also the whole Store mutably (via+ /// `StoreContextMut`); so we need to hold a separate reference to+ /// it while invoking it.+ #[cfg(feature = "debug")]+ debug_handler: Option<Box<dyn StoreDebugHandler<T>>>,+}++/// Adapter around `DebugHandler` that gets monomorphized into an+/// object-safe dyn trait to place in `store.debug_handler`.+#[cfg(feature = "debug")]+trait StoreDebugHandler<T: 'static>: Send + Sync {+ fn handle<'a>(+ self: Box<Self>,+ store: StoreContextMut<'a, T>,+ event: crate::DebugEvent<'a>,+ ) -> Box<dyn Future<Output = ()> + Send + 'a>;+}++#[cfg(feature = "debug")]+impl<D> StoreDebugHandler<D::Data> for D+where+ D: DebugHandler,+ D::Data: Send,+{+ fn handle<'a>(+ self: Box<Self>,+ store: StoreContextMut<'a, D::Data>,+ event: crate::DebugEvent<'a>,+ ) -> Box<dyn Future<Output = ()> + Send + 'a> {+ // Clone the underlying `DebugHandler` (the trait requires+ // Clone as a supertrait), not the Box. The clone happens here+ // rather than at the callsite because `Clone::clone` is not+ // object-safe so needs to be in a monomorphized context.+ let handler: D = (*self).clone();+ // Since we temporarily took `self` off the store at the+ // callsite, put it back now that we've cloned it.+ store.0.debug_handler = Some(self);+ Box::new(async move { handler.handle(store, event).await })+ }}enum ResourceLimiterInner<T> {@@ -716,6 +764,8 @@ impl<T> Store<T> {#[cfg(target_has_atomic = "64")]epoch_deadline_behavior: None,data_no_provenance: ManuallyDrop::new(data),+ #[cfg(feature = "debug")]+ debug_handler: None,});let store_data =@@ -1188,14 +1238,10 @@ impl<T> Store<T> {/// VM-level values (locals and operand stack), when debugging is/// enabled.///- /// This object views all activations for the current store that- /// are on the stack. An activation is a contiguous sequence of- /// Wasm frames (called functions) that were called from host code- /// and called back out to host code. If there are activations- /// from multiple stores on the stack, for example if Wasm code in- /// one store calls out to host code which invokes another Wasm- /// function in another store, then the other stores are "opaque"- /// to our view here in the same way that host code is.+ /// This object views the frames from the most recent Wasm entry+ /// onward (up to the exit that allows this host code to run). Any+ /// Wasm stack frames upward from the most recent entry to Wasm+ /// are not visible to this cursor.////// Returns `None` if debug instrumentation is not enabled for/// the engine containing this store.@@ -1203,6 +1249,50 @@ impl<T> Store<T> {pub fn debug_frames(&mut self) -> Option<crate::DebugFrameCursor<'_, T>> {self.as_context_mut().debug_frames()}++ /// Set the debug callback on this store.+ ///+ /// See [`crate::DebugHandler`] for more documentation.+ ///+ /// # Panics+ ///+ /// - Will panic if this store is not configured for async+ /// support.+ /// - Will panic if guest-debug support was not enabled via+ /// [`crate::Config::guest_debug`].+ #[cfg(feature = "debug")]+ pub fn set_debug_handler(&mut self, handler: impl DebugHandler<Data = T>)+ where+ // We require `Send` here because the debug handler becomes+ // referenced from a future: when `DebugHandler::handle` is+ // invoked, its `self` references the `handler` with the+ // user's state. Note that we are careful to keep this bound+ // constrained to debug-handler-related code only and not+ // propagate it outward to the store in general. The presence+ // of the trait implementation serves as a witness that `T:+ // Send`. This is required in particular because we will have+ // a `&mut dyn VMStore` on the stack when we pause a fiber+ // with `block_on` to run a debugger hook; that `VMStore` must+ // be a `Store<T> where T: Send`.+ T: Send,+ {+ assert!(+ self.inner.async_support(),+ "debug hooks rely on async support"+ );+ assert!(+ self.engine().tunables().debug_guest,+ "debug hooks require guest debugging to be enabled"+ );+ self.inner.debug_handler = Some(Box::new(handler));+ }++ /// Clear the debug handler on this store. If any existed, it will+ /// be dropped.+ #[cfg(feature = "debug")]+ pub fn clear_debug_handler(&mut self) {+ self.inner.debug_handler = None;+ }}impl<'a, T> StoreContext<'a, T> {@@ -1320,7 +1410,6 @@ impl<'a, T> StoreContextMut<'a, T> {/// Tests whether there is a pending exception.///- ////// See [`Store::has_pending_exception`] for more details.#[cfg(feature = "gc")]pub fn has_pending_exception(&self) -> bool {@@ -2543,6 +2632,12 @@ at https://bytecodealliance.org/security.self.pending_exception.take()}+ /// Tests whether there is a pending exception.+ #[cfg(feature = "gc")]+ pub fn has_pending_exception(&self) -> bool {+ self.pending_exception.is_some()+ }+#[cfg(feature = "gc")]fn take_pending_exception_rooted(&mut self) -> Option<Rooted<ExnRef>> {let vmexnref = self.take_pending_exception()?;@@ -2550,6 +2645,18 @@ at https://bytecodealliance.org/security.Some(Rooted::new(&mut nogc, vmexnref.into()))}+ /// Get an owned rooted reference to the pending exception,+ /// without taking it off the store.+ #[cfg(all(feature = "gc", feature = "debug"))]+ pub(crate) fn pending_exception_owned_rooted(&mut self) -> Option<OwnedRooted<ExnRef>> {+ let mut nogc = AutoAssertNoGc::new(self);+ nogc.pending_exception.take().map(|vmexnref| {+ let cloned = nogc.clone_gc_ref(vmexnref.as_gc_ref());+ nogc.pending_exception = Some(cloned.into_exnref_unchecked());+ OwnedRooted::new(&mut nogc, vmexnref.into())+ })+ }+#[cfg(feature = "gc")]fn throw_impl(&mut self, exception: Rooted<ExnRef>) {let mut nogc = AutoAssertNoGc::new(self);@@ -2645,6 +2752,18 @@ unsafe impl<T> VMStore for StoreInner<T> {fn component_calls(&mut self) -> &mut vm::component::CallContexts {&mut self.component_calls}++ #[cfg(feature = "debug")]+ fn block_on_debug_handler(&mut self, event: crate::DebugEvent<'_>) -> anyhow::Result<()> {+ if let Some(handler) = self.debug_handler.take() {+ log::trace!("about to raise debug event {event:?}");+ StoreContextMut(self).with_blocking(|store, cx| {+ cx.block_on(Pin::from(handler.handle(store, event)).as_mut())+ })+ } else {+ Ok(())+ }+ }}impl<T> StoreInner<T> {diff --git a/crates/wasmtime/src/runtime/vm.rs b/crates/wasmtime/src/runtime/vm.rsindex 7823b515b6..247cea7ac1 100644--- a/crates/wasmtime/src/runtime/vm.rs+++ b/crates/wasmtime/src/runtime/vm.rs@@ -228,6 +228,10 @@ pub unsafe trait VMStore: 'static {fn component_async_store(&mut self,) -> &mut dyn crate::runtime::component::VMComponentAsyncStore;++ /// Invoke a debug handler, if present, at a debug event.+ #[cfg(feature = "debug")]+ fn block_on_debug_handler(&mut self, event: crate::DebugEvent) -> anyhow::Result<()>;}impl Deref for dyn VMStore + '_ {diff --git a/crates/wasmtime/src/runtime/vm/traphandlers.rs b/crates/wasmtime/src/runtime/vm/traphandlers.rsindex 939c2784d6..353f8e6083 100644--- a/crates/wasmtime/src/runtime/vm/traphandlers.rs+++ b/crates/wasmtime/src/runtime/vm/traphandlers.rs@@ -21,6 +21,8 @@ use crate::runtime::module::lookup_code;use crate::runtime::store::{ExecutorRef, StoreOpaque};use crate::runtime::vm::sys::traphandlers;use crate::runtime::vm::{InterpreterRef, VMContext, VMStore, VMStoreContext, f32x4, f64x2, i8x16};+#[cfg(feature = "debug")]+use crate::store::AsStoreOpaque;use crate::{EntryStoreContext, prelude::*};use crate::{StoreContextMut, WasmBacktrace};use core::cell::Cell;@@ -822,7 +824,76 @@ impl CallThreadState {/// skip all Rust destructors on the stack, if there are any, for native/// executors as `Handler::resume` will be used.unsafe fn unwind(&self, store: &mut dyn VMStore) {- let unwind = self.unwind.replace(UnwindState::None);+ #[allow(unused_mut, reason = "only mutated in `debug` configuration")]+ let mut unwind = self.unwind.replace(UnwindState::None);++ #[cfg(feature = "debug")]+ {+ let result = match &unwind {+ UnwindState::UnwindToWasm(_) => {+ assert!(store.as_store_opaque().has_pending_exception());+ let exn = store+ .as_store_opaque()+ .pending_exception_owned_rooted()+ .expect("exception should be set when we are throwing");+ store.block_on_debug_handler(crate::DebugEvent::CaughtExceptionThrown(exn))+ }++ UnwindState::UnwindToHost {+ reason: UnwindReason::Trap(TrapReason::Exception),+ ..+ } => {+ use crate::store::AsStoreOpaque;+ let exn = store+ .as_store_opaque()+ .pending_exception_owned_rooted()+ .expect("exception should be set when we are throwing");+ store.block_on_debug_handler(crate::DebugEvent::UncaughtExceptionThrown(+ exn.clone(),+ ))+ }+ UnwindState::UnwindToHost {+ reason: UnwindReason::Trap(TrapReason::Wasm(trap)),+ ..+ } => store.block_on_debug_handler(crate::DebugEvent::Trap(*trap)),+ UnwindState::UnwindToHost {+ reason: UnwindReason::Trap(TrapReason::User(err)),+ ..+ } => store.block_on_debug_handler(crate::DebugEvent::HostcallError(err)),++ UnwindState::UnwindToHost {+ reason: UnwindReason::Trap(TrapReason::Jit { .. }),+ ..+ } => {+ // JIT traps not handled yet.+ Ok(())+ }+ #[cfg(all(feature = "std", panic = "unwind"))]+ UnwindState::UnwindToHost {+ reason: UnwindReason::Panic(_),+ ..+ } => {+ // We don't invoke any debugger hook when we're+ // unwinding due to a Rust (host-side) panic.+ Ok(())+ }++ UnwindState::None => unreachable!(),+ };++ // If the debugger invocation itself resulted in an `Err`+ // (which can only come from the `block_on` hitting a+ // failure mode), we need to override our unwind as-if+ // were handling a host error.+ if let Err(err) = result {+ unwind = UnwindState::UnwindToHost {+ reason: UnwindReason::Trap(TrapReason::User(err)),+ backtrace: None,+ coredump_stack: None,+ };+ }+ }+match unwind {UnwindState::UnwindToHost { .. } => {self.unwind.set(unwind);diff --git a/tests/all/debug.rs b/tests/all/debug.rsindex c4f3e66f0f..904b0b33c6 100644--- a/tests/all/debug.rs+++ b/tests/all/debug.rs@@ -1,6 +1,11 @@//! Tests for instrumentation-based debugging.-use wasmtime::{AsContextMut, Caller, Config, Engine, Extern, Func, Instance, Module, Store};+use std::sync::Arc;+use std::sync::atomic::{AtomicUsize, Ordering};+use wasmtime::{+ AsContextMut, Caller, Config, DebugEvent, DebugHandler, Engine, Extern, Func, Instance, Module,+ Store, StoreContextMut,+};fn get_module_and_store<C: Fn(&mut Config)>(c: C,@@ -200,3 +205,251 @@ fn debug_frames_on_store_with_no_wasm_activation() -> anyhow::Result<()> {assert!(frames.done());Ok(())}++macro_rules! debug_event_checker {+ ($ty:tt,+ $store:tt,+ $(+ { $i:expr ; $pat:pat => $body:tt }+ ),*)+ =>+ {+ #[derive(Clone)]+ struct $ty(Arc<AtomicUsize>);+ impl $ty {+ fn new_and_counter() -> (Self, Arc<AtomicUsize>) {+ let counter = Arc::new(AtomicUsize::new(0));+ let counter_clone = counter.clone();+ ($ty(counter), counter_clone)+ }+ }+ impl DebugHandler for $ty {+ type Data = ();+ fn handle(+ &self,+ #[allow(unused_variables, reason = "macro rules")]+ #[allow(unused_mut, reason = "macro rules")]+ mut $store: StoreContextMut<'_, ()>,+ event: DebugEvent<'_>,+ ) -> impl Future<Output = ()> + Send {+ let step = self.0.fetch_add(1, Ordering::Relaxed);+ async move {+ if false {}+ $(+ else if step == $i {+ match event {+ $pat => {+ $body;+ }+ _ => panic!("Incorrect event"),+ }+ }+ )*+ else {+ panic!("Too many steps");+ }+ }+ }+ }+ }+}++#[tokio::test]+#[cfg_attr(miri, ignore)]+async fn uncaught_exception_events() -> anyhow::Result<()> {+ let _ = env_logger::try_init();++ let (module, mut store) = get_module_and_store(+ |config| {+ config.async_support(true);+ config.wasm_exceptions(true);+ },+ r#"+ (module+ (tag $t (param i32))+ (func (export "main")+ call 1)+ (func+ (local $i i32)+ (local.set $i (i32.const 100))+ (throw $t (i32.const 42))))+ "#,+ )?;++ debug_event_checker!(+ D, store,+ { 0 ;+ wasmtime::DebugEvent::UncaughtExceptionThrown(e) => {+ assert_eq!(e.field(&mut store, 0).unwrap().unwrap_i32(), 42);+ let mut stack = store.debug_frames().expect("frame cursor must be available");+ assert!(!stack.done());+ assert_eq!(stack.num_locals(), 1);+ assert_eq!(stack.local(0).unwrap_i32(), 100);+ stack.move_to_parent();+ assert!(!stack.done());+ stack.move_to_parent();+ assert!(stack.done());+ }+ }+ );++ let (handler, counter) = D::new_and_counter();+ store.set_debug_handler(handler);++ let instance = Instance::new_async(&mut store, &module, &[]).await?;+ let func = instance.get_func(&mut store, "main").unwrap();+ let mut results = [];+ let result = func.call_async(&mut store, &[], &mut results).await;+ assert!(result.is_err()); // Uncaught exception.+ assert_eq!(counter.load(Ordering::Relaxed), 1);++ Ok(())+}++#[tokio::test]+#[cfg_attr(miri, ignore)]+async fn caught_exception_events() -> anyhow::Result<()> {+ let _ = env_logger::try_init();++ let (module, mut store) = get_module_and_store(+ |config| {+ config.async_support(true);+ config.wasm_exceptions(true);+ },+ r#"+ (module+ (tag $t (param i32))+ (func (export "main")+ (block $b (result i32)+ (try_table (catch $t $b)+ call 1)+ i32.const 0)+ drop)+ (func+ (local $i i32)+ (local.set $i (i32.const 100))+ (throw $t (i32.const 42))))+ "#,+ )?;++ debug_event_checker!(+ D, store,+ { 0 ;+ wasmtime::DebugEvent::CaughtExceptionThrown(e) => {+ assert_eq!(e.field(&mut store, 0).unwrap().unwrap_i32(), 42);+ let mut stack = store.debug_frames().expect("frame cursor must be available");+ assert!(!stack.done());+ assert_eq!(stack.num_locals(), 1);+ assert_eq!(stack.local(0).unwrap_i32(), 100);+ stack.move_to_parent();+ assert!(!stack.done());+ stack.move_to_parent();+ assert!(stack.done());+ }+ }+ );++ let (handler, counter) = D::new_and_counter();+ store.set_debug_handler(handler);++ let instance = Instance::new_async(&mut store, &module, &[]).await?;+ let func = instance.get_func(&mut store, "main").unwrap();+ let mut results = [];+ func.call_async(&mut store, &[], &mut results).await?;+ assert_eq!(counter.load(Ordering::Relaxed), 1);++ Ok(())+}++#[tokio::test]+#[cfg_attr(miri, ignore)]+#[cfg(any(+ target_arch = "x86_64",+ target_arch = "aarch64",+ target_arch = "s390x",+ target_arch = "riscv64"+))]+async fn hostcall_trap_events() -> anyhow::Result<()> {+ let _ = env_logger::try_init();++ let (module, mut store) = get_module_and_store(+ |config| {+ config.async_support(true);+ config.wasm_exceptions(true);+ // Force hostcall-based traps.+ config.signals_based_traps(false);+ },+ r#"+ (module+ (func (export "main")+ i32.const 0+ i32.const 0+ i32.div_u+ drop))+ "#,+ )?;++ debug_event_checker!(+ D, store,+ { 0 ;+ wasmtime::DebugEvent::Trap(wasmtime_environ::Trap::IntegerDivisionByZero) => {}+ }+ );++ let (handler, counter) = D::new_and_counter();+ store.set_debug_handler(handler);++ let instance = Instance::new_async(&mut store, &module, &[]).await?;+ let func = instance.get_func(&mut store, "main").unwrap();+ let mut results = [];+ let result = func.call_async(&mut store, &[], &mut results).await;+ assert!(result.is_err()); // Uncaught trap.+ assert_eq!(counter.load(Ordering::Relaxed), 1);++ Ok(())+}++#[tokio::test]+#[cfg_attr(miri, ignore)]+async fn hostcall_error_events() -> anyhow::Result<()> {+ let _ = env_logger::try_init();++ let (module, mut store) = get_module_and_store(+ |config| {+ config.async_support(true);+ config.wasm_exceptions(true);+ },+ r#"+ (module+ (import "" "do_a_trap" (func))+ (func (export "main")+ call 0))+ "#,+ )?;++ debug_event_checker!(+ D, store,+ { 0 ;+ wasmtime::DebugEvent::HostcallError(e) => {+ assert!(format!("{e:?}").contains("secret error message"));+ }+ }+ );++ let (handler, counter) = D::new_and_counter();+ store.set_debug_handler(handler);++ let do_a_trap = Func::wrap(+ &mut store,+ |_caller: Caller<'_, ()>| -> anyhow::Result<()> {+ Err(anyhow::anyhow!("secret error message"))+ },+ );+ let instance = Instance::new_async(&mut store, &module, &[Extern::Func(do_a_trap)]).await?;+ let func = instance.get_func(&mut store, "main").unwrap();+ let mut results = [];+ let result = func.call_async(&mut store, &[], &mut results).await;+ assert!(result.is_err()); // Uncaught trap.+ assert_eq!(counter.load(Ordering::Relaxed), 1);+ Ok(())+}