wasmtime_environ/
trap_encoding.rs

1use core::fmt;
2use object::{Bytes, LittleEndian, U32Bytes};
3
4/// Information about trap.
5#[derive(Debug, PartialEq, Eq, Clone)]
6pub struct TrapInformation {
7    /// The offset of the trapping instruction in native code.
8    ///
9    /// This is relative to the beginning of the function.
10    pub code_offset: u32,
11
12    /// Code of the trap.
13    pub trap_code: Trap,
14}
15
16// The code can be accessed from the c-api, where the possible values are
17// translated into enum values defined there:
18//
19// * `wasm_trap_code` in c-api/src/trap.rs, and
20// * `wasmtime_trap_code_enum` in c-api/include/wasmtime/trap.h.
21//
22// These need to be kept in sync.
23#[non_exhaustive]
24#[derive(Clone, Copy, PartialEq, Eq, Debug, Hash)]
25#[expect(missing_docs, reason = "self-describing variants")]
26pub enum Trap {
27    /// The current stack space was exhausted.
28    StackOverflow,
29
30    /// An out-of-bounds memory access.
31    MemoryOutOfBounds,
32
33    /// A wasm atomic operation was presented with a not-naturally-aligned linear-memory address.
34    HeapMisaligned,
35
36    /// An out-of-bounds access to a table.
37    TableOutOfBounds,
38
39    /// Indirect call to a null table entry.
40    IndirectCallToNull,
41
42    /// Signature mismatch on indirect call.
43    BadSignature,
44
45    /// An integer arithmetic operation caused an overflow.
46    IntegerOverflow,
47
48    /// An integer division by zero.
49    IntegerDivisionByZero,
50
51    /// Failed float-to-int conversion.
52    BadConversionToInteger,
53
54    /// Code that was supposed to have been unreachable was reached.
55    UnreachableCodeReached,
56
57    /// Execution has potentially run too long and may be interrupted.
58    Interrupt,
59
60    /// When the `component-model` feature is enabled this trap represents a
61    /// function that was `canon lift`'d, then `canon lower`'d, then called.
62    /// This combination of creation of a function in the component model
63    /// generates a function that always traps and, when called, produces this
64    /// flavor of trap.
65    AlwaysTrapAdapter,
66
67    /// When wasm code is configured to consume fuel and it runs out of fuel
68    /// then this trap will be raised.
69    OutOfFuel,
70
71    /// Used to indicate that a trap was raised by atomic wait operations on non shared memory.
72    AtomicWaitNonSharedMemory,
73
74    /// Call to a null reference.
75    NullReference,
76
77    /// Attempt to access beyond the bounds of an array.
78    ArrayOutOfBounds,
79
80    /// Attempted an allocation that was too large to succeed.
81    AllocationTooLarge,
82
83    /// Attempted to cast a reference to a type that it is not an instance of.
84    CastFailure,
85
86    /// When the `component-model` feature is enabled this trap represents a
87    /// scenario where one component tried to call another component but it
88    /// would have violated the reentrance rules of the component model,
89    /// triggering a trap instead.
90    CannotEnterComponent,
91
92    /// Async-lifted export failed to produce a result by calling `task.return`
93    /// before returning `STATUS_DONE` and/or after all host tasks completed.
94    NoAsyncResult,
95
96    /// We are suspending to a tag for which there is no active handler.
97    UnhandledTag,
98
99    /// Attempt to resume a continuation twice.
100    ContinuationAlreadyConsumed,
101
102    /// A Pulley opcode was executed at runtime when the opcode was disabled at
103    /// compile time.
104    DisabledOpcode,
105
106    /// Async event loop deadlocked; i.e. it cannot make further progress given
107    /// that all host tasks have completed and any/all host-owned stream/future
108    /// handles have been dropped.
109    AsyncDeadlock,
110    // if adding a variant here be sure to update the `check!` macro below
111}
112
113impl Trap {
114    /// Converts a byte back into a `Trap` if its in-bounds
115    pub fn from_u8(byte: u8) -> Option<Trap> {
116        // FIXME: this could use some sort of derive-like thing to avoid having to
117        // deduplicate the names here.
118        //
119        // This simply converts from the a `u8`, to the `Trap` enum.
120        macro_rules! check {
121            ($($name:ident)*) => ($(if byte == Trap::$name as u8 {
122                return Some(Trap::$name);
123            })*);
124        }
125
126        check! {
127            StackOverflow
128            MemoryOutOfBounds
129            HeapMisaligned
130            TableOutOfBounds
131            IndirectCallToNull
132            BadSignature
133            IntegerOverflow
134            IntegerDivisionByZero
135            BadConversionToInteger
136            UnreachableCodeReached
137            Interrupt
138            AlwaysTrapAdapter
139            OutOfFuel
140            AtomicWaitNonSharedMemory
141            NullReference
142            ArrayOutOfBounds
143            AllocationTooLarge
144            CastFailure
145            CannotEnterComponent
146            NoAsyncResult
147            UnhandledTag
148            ContinuationAlreadyConsumed
149            DisabledOpcode
150            AsyncDeadlock
151        }
152
153        None
154    }
155}
156
157impl fmt::Display for Trap {
158    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
159        use Trap::*;
160
161        let desc = match self {
162            StackOverflow => "call stack exhausted",
163            MemoryOutOfBounds => "out of bounds memory access",
164            HeapMisaligned => "unaligned atomic",
165            TableOutOfBounds => "undefined element: out of bounds table access",
166            IndirectCallToNull => "uninitialized element",
167            BadSignature => "indirect call type mismatch",
168            IntegerOverflow => "integer overflow",
169            IntegerDivisionByZero => "integer divide by zero",
170            BadConversionToInteger => "invalid conversion to integer",
171            UnreachableCodeReached => "wasm `unreachable` instruction executed",
172            Interrupt => "interrupt",
173            AlwaysTrapAdapter => "degenerate component adapter called",
174            OutOfFuel => "all fuel consumed by WebAssembly",
175            AtomicWaitNonSharedMemory => "atomic wait on non-shared memory",
176            NullReference => "null reference",
177            ArrayOutOfBounds => "out of bounds array access",
178            AllocationTooLarge => "allocation size too large",
179            CastFailure => "cast failure",
180            CannotEnterComponent => "cannot enter component instance",
181            NoAsyncResult => "async-lifted export failed to produce a result",
182            UnhandledTag => "unhandled tag",
183            ContinuationAlreadyConsumed => "continuation already consumed",
184            DisabledOpcode => "pulley opcode disabled at compile time was executed",
185            AsyncDeadlock => "deadlock detected: event loop cannot make further progress",
186        };
187        write!(f, "wasm trap: {desc}")
188    }
189}
190
191impl core::error::Error for Trap {}
192
193/// Decodes the provided trap information section and attempts to find the trap
194/// code corresponding to the `offset` specified.
195///
196/// The `section` provided is expected to have been built by
197/// `TrapEncodingBuilder` above. Additionally the `offset` should be a relative
198/// offset within the text section of the compilation image.
199pub fn lookup_trap_code(section: &[u8], offset: usize) -> Option<Trap> {
200    let (offsets, traps) = parse(section)?;
201
202    // The `offsets` table is sorted in the trap section so perform a binary
203    // search of the contents of this section to find whether `offset` is an
204    // entry in the section. Note that this is a precise search because trap pcs
205    // should always be precise as well as our metadata about them, which means
206    // we expect an exact match to correspond to a trap opcode.
207    //
208    // Once an index is found within the `offsets` array then that same index is
209    // used to lookup from the `traps` list of bytes to get the trap code byte
210    // corresponding to this offset.
211    let offset = u32::try_from(offset).ok()?;
212    let index = offsets
213        .binary_search_by_key(&offset, |val| val.get(LittleEndian))
214        .ok()?;
215    debug_assert!(index < traps.len());
216    let byte = *traps.get(index)?;
217
218    let trap = Trap::from_u8(byte);
219    debug_assert!(trap.is_some(), "missing mapping for {byte}");
220    trap
221}
222
223fn parse(section: &[u8]) -> Option<(&[U32Bytes<LittleEndian>], &[u8])> {
224    let mut section = Bytes(section);
225    // NB: this matches the encoding written by `append_to` above.
226    let count = section.read::<U32Bytes<LittleEndian>>().ok()?;
227    let count = usize::try_from(count.get(LittleEndian)).ok()?;
228    let (offsets, traps) =
229        object::slice_from_bytes::<U32Bytes<LittleEndian>>(section.0, count).ok()?;
230    debug_assert_eq!(traps.len(), count);
231    Some((offsets, traps))
232}
233
234/// Returns an iterator over all of the traps encoded in `section`, which should
235/// have been produced by `TrapEncodingBuilder`.
236pub fn iterate_traps(section: &[u8]) -> Option<impl Iterator<Item = (u32, Trap)> + '_> {
237    let (offsets, traps) = parse(section)?;
238    Some(
239        offsets
240            .iter()
241            .zip(traps)
242            .map(|(offset, trap)| (offset.get(LittleEndian), Trap::from_u8(*trap).unwrap())),
243    )
244}
wasmtime_environ/trap_encoding.rs

wasmtime_environ/
trap_encoding.rs
