wasmtime/runtime/trap.rs
1#[cfg(feature = "coredump")]
2use super::coredump::WasmCoreDump;
3use crate::prelude::*;
4use crate::store::StoreOpaque;
5use crate::{AsContext, Module};
6use core::fmt;
7use wasmtime_environ::{demangle_function_name, demangle_function_name_or_index, FilePos};
8
9/// Representation of a WebAssembly trap and what caused it to occur.
10///
11/// WebAssembly traps happen explicitly for instructions such as `unreachable`
12/// but can also happen as side effects of other instructions such as `i32.load`
13/// loading an out-of-bounds address. Traps halt the execution of WebAssembly
14/// and cause an error to be returned to the host. This enumeration is a list of
15/// all possible traps that can happen in wasm, in addition to some
16/// Wasmtime-specific trap codes listed here as well.
17///
18/// # Errors in Wasmtime
19///
20/// Error-handling in Wasmtime is primarily done through the
21/// [`anyhow`][mod@anyhow] crate where most results are a
22/// [`Result<T>`](anyhow::Result) which is an alias for [`Result<T,
23/// anyhow::Error>`](std::result::Result). Errors in Wasmtime are represented
24/// with [`anyhow::Error`] which acts as a container for any type of error in
25/// addition to optional context for this error. The "base" error or
26/// [`anyhow::Error::root_cause`] is a [`Trap`] whenever WebAssembly hits a
27/// trap, or otherwise it's whatever the host created the error with when
28/// returning an error for a host call.
29///
30/// Any error which happens while WebAssembly is executing will also, by
31/// default, capture a backtrace of the wasm frames while executing. This
32/// backtrace is represented with a [`WasmBacktrace`] instance and is attached
33/// to the [`anyhow::Error`] return value as a
34/// [`context`](anyhow::Error::context). Inspecting a [`WasmBacktrace`] can be
35/// done with the [`downcast_ref`](anyhow::Error::downcast_ref) function. For
36/// information on this see the [`WasmBacktrace`] documentation.
37///
38/// # Examples
39///
40/// ```
41/// # use wasmtime::*;
42/// # fn main() -> Result<()> {
43/// let engine = Engine::default();
44/// let module = Module::new(
45/// &engine,
46/// r#"
47/// (module
48/// (func (export "trap")
49/// unreachable)
50/// (func $overflow (export "overflow")
51/// call $overflow)
52/// )
53/// "#,
54/// )?;
55/// let mut store = Store::new(&engine, ());
56/// let instance = Instance::new(&mut store, &module, &[])?;
57///
58/// let trap = instance.get_typed_func::<(), ()>(&mut store, "trap")?;
59/// let error = trap.call(&mut store, ()).unwrap_err();
60/// assert_eq!(*error.downcast_ref::<Trap>().unwrap(), Trap::UnreachableCodeReached);
61/// assert!(error.root_cause().is::<Trap>());
62///
63/// let overflow = instance.get_typed_func::<(), ()>(&mut store, "overflow")?;
64/// let error = overflow.call(&mut store, ()).unwrap_err();
65/// assert_eq!(*error.downcast_ref::<Trap>().unwrap(), Trap::StackOverflow);
66/// # Ok(())
67/// # }
68/// ```
69pub use wasmtime_environ::Trap;
70
71#[cold] // traps are exceptional, this helps move handling off the main path
72pub(crate) fn from_runtime_box(
73 store: &mut StoreOpaque,
74 runtime_trap: Box<crate::runtime::vm::Trap>,
75) -> Error {
76 let crate::runtime::vm::Trap {
77 reason,
78 backtrace,
79 coredumpstack,
80 } = *runtime_trap;
81 let (mut error, pc) = match reason {
82 // For user-defined errors they're already an `anyhow::Error` so no
83 // conversion is really necessary here, but a `backtrace` may have
84 // been captured so it's attempted to get inserted here.
85 //
86 // If the error is actually a `Trap` then the backtrace is inserted
87 // directly into the `Trap` since there's storage there for it.
88 // Otherwise though this represents a host-defined error which isn't
89 // using a `Trap` but instead some other condition that was fatal to
90 // wasm itself. In that situation the backtrace is inserted as
91 // contextual information on error using `error.context(...)` to
92 // provide useful information to debug with for the embedder/caller,
93 // otherwise the information about what the wasm was doing when the
94 // error was generated would be lost.
95 crate::runtime::vm::TrapReason::User(error) => (error, None),
96 crate::runtime::vm::TrapReason::Jit {
97 pc,
98 faulting_addr,
99 trap,
100 } => {
101 let mut err: Error = trap.into();
102
103 // If a fault address was present, for example with segfaults,
104 // then simultaneously assert that it's within a known linear memory
105 // and additionally translate it to a wasm-local address to be added
106 // as context to the error.
107 if let Some(fault) = faulting_addr.and_then(|addr| store.wasm_fault(pc, addr)) {
108 err = err.context(fault);
109 }
110 (err, Some(pc))
111 }
112 crate::runtime::vm::TrapReason::Wasm(trap_code) => (trap_code.into(), None),
113 };
114
115 if let Some(bt) = backtrace {
116 let bt = WasmBacktrace::from_captured(store, bt, pc);
117 if !bt.wasm_trace.is_empty() {
118 error = error.context(bt);
119 }
120 }
121
122 let _ = &coredumpstack;
123 #[cfg(feature = "coredump")]
124 if let Some(coredump) = coredumpstack {
125 let bt = WasmBacktrace::from_captured(store, coredump.bt, pc);
126 let cd = WasmCoreDump::new(store, bt);
127 error = error.context(cd);
128 }
129
130 error
131}
132
133/// Representation of a backtrace of function frames in a WebAssembly module for
134/// where an error happened.
135///
136/// This structure is attached to the [`anyhow::Error`] returned from many
137/// Wasmtime functions that execute WebAssembly such as [`Instance::new`] or
138/// [`Func::call`]. This can be acquired with the [`anyhow::Error::downcast`]
139/// family of methods to programmatically inspect the backtrace. Otherwise since
140/// it's part of the error returned this will get printed along with the rest of
141/// the error when the error is logged.
142///
143/// Capturing of wasm backtraces can be configured through the
144/// [`Config::wasm_backtrace`](crate::Config::wasm_backtrace) method.
145///
146/// For more information about errors in wasmtime see the documentation of the
147/// [`Trap`] type.
148///
149/// [`Func::call`]: crate::Func::call
150/// [`Instance::new`]: crate::Instance::new
151///
152/// # Examples
153///
154/// ```
155/// # use wasmtime::*;
156/// # fn main() -> Result<()> {
157/// let engine = Engine::default();
158/// let module = Module::new(
159/// &engine,
160/// r#"
161/// (module
162/// (func $start (export "run")
163/// call $trap)
164/// (func $trap
165/// unreachable)
166/// )
167/// "#,
168/// )?;
169/// let mut store = Store::new(&engine, ());
170/// let instance = Instance::new(&mut store, &module, &[])?;
171/// let func = instance.get_typed_func::<(), ()>(&mut store, "run")?;
172/// let error = func.call(&mut store, ()).unwrap_err();
173/// let bt = error.downcast_ref::<WasmBacktrace>().unwrap();
174/// let frames = bt.frames();
175/// assert_eq!(frames.len(), 2);
176/// assert_eq!(frames[0].func_name(), Some("trap"));
177/// assert_eq!(frames[1].func_name(), Some("start"));
178/// # Ok(())
179/// # }
180/// ```
181#[derive(Debug)]
182pub struct WasmBacktrace {
183 wasm_trace: Vec<FrameInfo>,
184 hint_wasm_backtrace_details_env: bool,
185 // This is currently only present for the `Debug` implementation for extra
186 // context.
187 #[allow(dead_code)]
188 runtime_trace: crate::runtime::vm::Backtrace,
189}
190
191impl WasmBacktrace {
192 /// Captures a trace of the WebAssembly frames on the stack for the
193 /// provided store.
194 ///
195 /// This will return a [`WasmBacktrace`] which holds captured
196 /// [`FrameInfo`]s for each frame of WebAssembly on the call stack of the
197 /// current thread. If no WebAssembly is on the stack then the returned
198 /// backtrace will have no frames in it.
199 ///
200 /// Note that this function will respect the [`Config::wasm_backtrace`]
201 /// configuration option and will return an empty backtrace if that is
202 /// disabled. To always capture a backtrace use the
203 /// [`WasmBacktrace::force_capture`] method.
204 ///
205 /// Also note that this function will only capture frames from the
206 /// specified `store` on the stack, ignoring frames from other stores if
207 /// present.
208 ///
209 /// [`Config::wasm_backtrace`]: crate::Config::wasm_backtrace
210 ///
211 /// # Example
212 ///
213 /// ```
214 /// # use wasmtime::*;
215 /// # fn main() -> Result<()> {
216 /// let engine = Engine::default();
217 /// let module = Module::new(
218 /// &engine,
219 /// r#"
220 /// (module
221 /// (import "" "" (func $host))
222 /// (func $foo (export "f") call $bar)
223 /// (func $bar call $host)
224 /// )
225 /// "#,
226 /// )?;
227 ///
228 /// let mut store = Store::new(&engine, ());
229 /// let func = Func::wrap(&mut store, |cx: Caller<'_, ()>| {
230 /// let trace = WasmBacktrace::capture(&cx);
231 /// println!("{trace:?}");
232 /// });
233 /// let instance = Instance::new(&mut store, &module, &[func.into()])?;
234 /// let func = instance.get_typed_func::<(), ()>(&mut store, "f")?;
235 /// func.call(&mut store, ())?;
236 /// # Ok(())
237 /// # }
238 /// ```
239 pub fn capture(store: impl AsContext) -> WasmBacktrace {
240 let store = store.as_context();
241 if store.engine().config().wasm_backtrace {
242 Self::force_capture(store)
243 } else {
244 WasmBacktrace {
245 wasm_trace: Vec::new(),
246 hint_wasm_backtrace_details_env: false,
247 runtime_trace: crate::runtime::vm::Backtrace::empty(),
248 }
249 }
250 }
251
252 /// Unconditionally captures a trace of the WebAssembly frames on the stack
253 /// for the provided store.
254 ///
255 /// Same as [`WasmBacktrace::capture`] except that it disregards the
256 /// [`Config::wasm_backtrace`](crate::Config::wasm_backtrace) setting and
257 /// always captures a backtrace.
258 pub fn force_capture(store: impl AsContext) -> WasmBacktrace {
259 let store = store.as_context();
260 Self::from_captured(store.0, crate::runtime::vm::Backtrace::new(store.0), None)
261 }
262
263 fn from_captured(
264 store: &StoreOpaque,
265 runtime_trace: crate::runtime::vm::Backtrace,
266 trap_pc: Option<usize>,
267 ) -> Self {
268 let mut wasm_trace = Vec::<FrameInfo>::with_capacity(runtime_trace.frames().len());
269 let mut hint_wasm_backtrace_details_env = false;
270 let wasm_backtrace_details_env_used =
271 store.engine().config().wasm_backtrace_details_env_used;
272
273 for frame in runtime_trace.frames() {
274 debug_assert!(frame.pc() != 0);
275
276 // Note that we need to be careful about the pc we pass in
277 // here to lookup frame information. This program counter is
278 // used to translate back to an original source location in
279 // the origin wasm module. If this pc is the exact pc that
280 // the trap happened at, then we look up that pc precisely.
281 // Otherwise backtrace information typically points at the
282 // pc *after* the call instruction (because otherwise it's
283 // likely a call instruction on the stack). In that case we
284 // want to lookup information for the previous instruction
285 // (the call instruction) so we subtract one as the lookup.
286 let pc_to_lookup = if Some(frame.pc()) == trap_pc {
287 frame.pc()
288 } else {
289 frame.pc() - 1
290 };
291
292 // NB: The PC we are looking up _must_ be a Wasm PC since
293 // `crate::runtime::vm::Backtrace` only contains Wasm frames.
294 //
295 // However, consider the case where we have multiple, nested calls
296 // across stores (with host code in between, by necessity, since
297 // only things in the same store can be linked directly together):
298 //
299 // | ... |
300 // | Host | |
301 // +-----------------+ | stack
302 // | Wasm in store A | | grows
303 // +-----------------+ | down
304 // | Host | |
305 // +-----------------+ |
306 // | Wasm in store B | V
307 // +-----------------+
308 //
309 // In this scenario, the `crate::runtime::vm::Backtrace` will
310 // contain two frames: Wasm in store B followed by Wasm in store
311 // A. But `store.modules()` will only have the module information
312 // for modules instantiated within this store. Therefore, we use `if
313 // let Some(..)` instead of the `unwrap` you might otherwise expect
314 // and we ignore frames from modules that were not registered in
315 // this store's module registry.
316 if let Some((info, module)) = store.modules().lookup_frame_info(pc_to_lookup) {
317 wasm_trace.push(info);
318
319 // If this frame has unparsed debug information and the
320 // store's configuration indicates that we were
321 // respecting the environment variable of whether to
322 // do this then we will print out a helpful note in
323 // `Display` to indicate that more detailed information
324 // in a trap may be available.
325 let has_unparsed_debuginfo = module.compiled_module().has_unparsed_debuginfo();
326 if has_unparsed_debuginfo
327 && wasm_backtrace_details_env_used
328 && cfg!(feature = "addr2line")
329 {
330 hint_wasm_backtrace_details_env = true;
331 }
332 }
333 }
334
335 Self {
336 wasm_trace,
337 runtime_trace,
338 hint_wasm_backtrace_details_env,
339 }
340 }
341
342 /// Returns a list of function frames in WebAssembly this backtrace
343 /// represents.
344 pub fn frames(&self) -> &[FrameInfo] {
345 self.wasm_trace.as_slice()
346 }
347}
348
349impl fmt::Display for WasmBacktrace {
350 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
351 writeln!(f, "error while executing at wasm backtrace:")?;
352
353 let mut needs_newline = false;
354 for (i, frame) in self.wasm_trace.iter().enumerate() {
355 // Avoid putting a trailing newline on the output
356 if needs_newline {
357 writeln!(f, "")?;
358 } else {
359 needs_newline = true;
360 }
361 let name = frame.module().name().unwrap_or("<unknown>");
362 write!(f, " {i:>3}: ")?;
363
364 if let Some(offset) = frame.module_offset() {
365 write!(f, "{offset:#8x} - ")?;
366 }
367
368 let write_raw_func_name = |f: &mut fmt::Formatter<'_>| {
369 demangle_function_name_or_index(f, frame.func_name(), frame.func_index() as usize)
370 };
371 if frame.symbols().is_empty() {
372 write!(f, "{name}!")?;
373 write_raw_func_name(f)?;
374 } else {
375 for (i, symbol) in frame.symbols().iter().enumerate() {
376 if i > 0 {
377 if needs_newline {
378 writeln!(f, "")?;
379 } else {
380 needs_newline = true;
381 }
382 write!(f, " - ")?;
383 } else {
384 // ...
385 }
386 match symbol.name() {
387 Some(name) => demangle_function_name(f, name)?,
388 None if i == 0 => write_raw_func_name(f)?,
389 None => write!(f, "<inlined function>")?,
390 }
391 if let Some(file) = symbol.file() {
392 writeln!(f, "")?;
393 write!(f, " at {file}")?;
394 if let Some(line) = symbol.line() {
395 write!(f, ":{line}")?;
396 if let Some(col) = symbol.column() {
397 write!(f, ":{col}")?;
398 }
399 }
400 }
401 }
402 }
403 }
404 if self.hint_wasm_backtrace_details_env {
405 write!(
406 f,
407 "\nnote: using the `WASMTIME_BACKTRACE_DETAILS=1` \
408 environment variable may show more debugging information"
409 )?;
410 }
411 Ok(())
412 }
413}
414
415/// Description of a frame in a backtrace for a [`WasmBacktrace`].
416///
417/// Whenever an error happens while WebAssembly is executing a
418/// [`WasmBacktrace`] will be attached to the error returned which can be used
419/// to acquire this `FrameInfo`. For more information see [`WasmBacktrace`].
420#[derive(Debug)]
421pub struct FrameInfo {
422 module: Module,
423 func_index: u32,
424 func_name: Option<String>,
425 func_start: FilePos,
426 instr: Option<FilePos>,
427 symbols: Vec<FrameSymbol>,
428}
429
430impl FrameInfo {
431 /// Fetches frame information about a program counter in a backtrace.
432 ///
433 /// Returns an object if this `pc` is known to this module, or returns `None`
434 /// if no information can be found.
435 pub(crate) fn new(module: Module, text_offset: usize) -> Option<FrameInfo> {
436 let compiled_module = module.compiled_module();
437 let (index, _func_offset) = compiled_module.func_by_text_offset(text_offset)?;
438 let func_start = compiled_module.func_start_srcloc(index);
439 let instr = wasmtime_environ::lookup_file_pos(
440 compiled_module.code_memory().address_map_data(),
441 text_offset,
442 );
443 let index = compiled_module.module().func_index(index);
444 let func_index = index.as_u32();
445 let func_name = compiled_module.func_name(index).map(|s| s.to_string());
446
447 // In debug mode for now assert that we found a mapping for `pc` within
448 // the function, because otherwise something is buggy along the way and
449 // not accounting for all the instructions. This isn't super critical
450 // though so we can omit this check in release mode.
451 //
452 // Note that if the module doesn't even have an address map due to
453 // compilation settings then it's expected that `instr` is `None`.
454 debug_assert!(
455 instr.is_some() || !compiled_module.has_address_map(),
456 "failed to find instruction for {text_offset:#x}"
457 );
458
459 // Use our wasm-relative pc to symbolize this frame. If there's a
460 // symbolication context (dwarf debug info) available then we can try to
461 // look this up there.
462 //
463 // Note that dwarf pcs are code-section-relative, hence the subtraction
464 // from the location of `instr`. Also note that all errors are ignored
465 // here for now since technically wasm modules can always have any
466 // custom section contents.
467 let mut symbols = Vec::new();
468
469 let _ = &mut symbols;
470 #[cfg(feature = "addr2line")]
471 if let Some(s) = &compiled_module.symbolize_context().ok().and_then(|c| c) {
472 if let Some(offset) = instr.and_then(|i| i.file_offset()) {
473 let to_lookup = u64::from(offset) - s.code_section_offset();
474 if let Ok(mut frames) = s.addr2line().find_frames(to_lookup).skip_all_loads() {
475 while let Ok(Some(frame)) = frames.next() {
476 symbols.push(FrameSymbol {
477 name: frame
478 .function
479 .as_ref()
480 .and_then(|l| l.raw_name().ok())
481 .map(|s| s.to_string()),
482 file: frame
483 .location
484 .as_ref()
485 .and_then(|l| l.file)
486 .map(|s| s.to_string()),
487 line: frame.location.as_ref().and_then(|l| l.line),
488 column: frame.location.as_ref().and_then(|l| l.column),
489 });
490 }
491 }
492 }
493 }
494
495 Some(FrameInfo {
496 module,
497 func_index,
498 func_name,
499 instr,
500 func_start,
501 symbols,
502 })
503 }
504
505 /// Returns the WebAssembly function index for this frame.
506 ///
507 /// This function index is the index in the function index space of the
508 /// WebAssembly module that this frame comes from.
509 pub fn func_index(&self) -> u32 {
510 self.func_index
511 }
512
513 /// Returns the module for this frame.
514 ///
515 /// This is the module who's code was being run in this frame.
516 pub fn module(&self) -> &Module {
517 &self.module
518 }
519
520 /// Returns a descriptive name of the function for this frame, if one is
521 /// available.
522 ///
523 /// The name of this function may come from the `name` section of the
524 /// WebAssembly binary, or wasmtime may try to infer a better name for it if
525 /// not available, for example the name of the export if it's exported.
526 ///
527 /// This return value is primarily used for debugging and human-readable
528 /// purposes for things like traps. Note that the exact return value may be
529 /// tweaked over time here and isn't guaranteed to be something in
530 /// particular about a wasm module due to its primary purpose of assisting
531 /// in debugging.
532 ///
533 /// This function returns `None` when no name could be inferred.
534 pub fn func_name(&self) -> Option<&str> {
535 self.func_name.as_deref()
536 }
537
538 /// Returns the offset within the original wasm module this frame's program
539 /// counter was at.
540 ///
541 /// The offset here is the offset from the beginning of the original wasm
542 /// module to the instruction that this frame points to.
543 ///
544 /// Note that `None` may be returned if the original module was not
545 /// compiled with mapping information to yield this information. This is
546 /// controlled by the
547 /// [`Config::generate_address_map`](crate::Config::generate_address_map)
548 /// configuration option.
549 pub fn module_offset(&self) -> Option<usize> {
550 Some(self.instr?.file_offset()? as usize)
551 }
552
553 /// Returns the offset from the original wasm module's function to this
554 /// frame's program counter.
555 ///
556 /// The offset here is the offset from the beginning of the defining
557 /// function of this frame (within the wasm module) to the instruction this
558 /// frame points to.
559 ///
560 /// Note that `None` may be returned if the original module was not
561 /// compiled with mapping information to yield this information. This is
562 /// controlled by the
563 /// [`Config::generate_address_map`](crate::Config::generate_address_map)
564 /// configuration option.
565 pub fn func_offset(&self) -> Option<usize> {
566 let instr_offset = self.instr?.file_offset()?;
567 Some((instr_offset - self.func_start.file_offset()?) as usize)
568 }
569
570 /// Returns the debug symbols found, if any, for this function frame.
571 ///
572 /// When a wasm program is compiled with DWARF debug information then this
573 /// function may be populated to return symbols which contain extra debug
574 /// information about a frame including the filename and line number. If no
575 /// debug information was found or if it was malformed then this will return
576 /// an empty array.
577 pub fn symbols(&self) -> &[FrameSymbol] {
578 &self.symbols
579 }
580}
581
582/// Debug information for a symbol that is attached to a [`FrameInfo`].
583///
584/// When DWARF debug information is present in a wasm file then this structure
585/// can be found on a [`FrameInfo`] and can be used to learn about filenames,
586/// line numbers, etc, which are the origin of a function in a stack trace.
587#[derive(Debug)]
588pub struct FrameSymbol {
589 name: Option<String>,
590 file: Option<String>,
591 line: Option<u32>,
592 column: Option<u32>,
593}
594
595impl FrameSymbol {
596 /// Returns the function name associated with this symbol.
597 ///
598 /// Note that this may not be present with malformed debug information, or
599 /// the debug information may not include it. Also note that the symbol is
600 /// frequently mangled, so you might need to run some form of demangling
601 /// over it.
602 pub fn name(&self) -> Option<&str> {
603 self.name.as_deref()
604 }
605
606 /// Returns the source code filename this symbol was defined in.
607 ///
608 /// Note that this may not be present with malformed debug information, or
609 /// the debug information may not include it.
610 pub fn file(&self) -> Option<&str> {
611 self.file.as_deref()
612 }
613
614 /// Returns the 1-indexed source code line number this symbol was defined
615 /// on.
616 ///
617 /// Note that this may not be present with malformed debug information, or
618 /// the debug information may not include it.
619 pub fn line(&self) -> Option<u32> {
620 self.line
621 }
622
623 /// Returns the 1-indexed source code column number this symbol was defined
624 /// on.
625 ///
626 /// Note that this may not be present with malformed debug information, or
627 /// the debug information may not include it.
628 pub fn column(&self) -> Option<u32> {
629 self.column
630 }
631}