1 /**
2  * \file wasmtime/trap.h
3  *
4  * Wasmtime APIs for interacting with traps and extensions to #wasm_trap_t.
5  */
6 
7 #ifndef WASMTIME_TRAP_H
8 #define WASMTIME_TRAP_H
9 
10 #include <wasm.h>
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 /**
17  * \brief Code of an instruction trap.
18  *
19  * See #wasmtime_trap_code_enum for possible values.
20  */
21 typedef uint8_t wasmtime_trap_code_t;
22 
23 /**
24  * \brief Trap codes for instruction traps.
25  */
26 enum wasmtime_trap_code_enum {
27   /// The current stack space was exhausted.
28   WASMTIME_TRAP_CODE_STACK_OVERFLOW,
29   /// An out-of-bounds memory access.
30   WASMTIME_TRAP_CODE_MEMORY_OUT_OF_BOUNDS,
31   /// A wasm atomic operation was presented with a not-naturally-aligned
32   /// linear-memory address.
33   WASMTIME_TRAP_CODE_HEAP_MISALIGNED,
34   /// An out-of-bounds access to a table.
35   WASMTIME_TRAP_CODE_TABLE_OUT_OF_BOUNDS,
36   /// Indirect call to a null table entry.
37   WASMTIME_TRAP_CODE_INDIRECT_CALL_TO_NULL,
38   /// Signature mismatch on indirect call.
39   WASMTIME_TRAP_CODE_BAD_SIGNATURE,
40   /// An integer arithmetic operation caused an overflow.
41   WASMTIME_TRAP_CODE_INTEGER_OVERFLOW,
42   /// An integer division by zero.
43   WASMTIME_TRAP_CODE_INTEGER_DIVISION_BY_ZERO,
44   /// Failed float-to-int conversion.
45   WASMTIME_TRAP_CODE_BAD_CONVERSION_TO_INTEGER,
46   /// Code that was supposed to have been unreachable was reached.
47   WASMTIME_TRAP_CODE_UNREACHABLE_CODE_REACHED,
48   /// Execution has potentially run too long and may be interrupted.
49   WASMTIME_TRAP_CODE_INTERRUPT,
50   /// Execution has run out of the configured fuel amount.
51   WASMTIME_TRAP_CODE_OUT_OF_FUEL,
52 };
53 
54 /**
55  * \brief Creates a new trap.
56  *
57  * \param msg the message to associate with this trap
58  * \param msg_len the byte length of `msg`
59  *
60  * The #wasm_trap_t returned is owned by the caller.
61  */
62 WASM_API_EXTERN wasm_trap_t *wasmtime_trap_new(const char *msg, size_t msg_len);
63 
64 /**
65  * \brief Attempts to extract the trap code from this trap.
66  *
67  * Returns `true` if the trap is an instruction trap triggered while
68  * executing Wasm. If `true` is returned then the trap code is returned
69  * through the `code` pointer. If `false` is returned then this is not
70  * an instruction trap -- traps can also be created using wasm_trap_new,
71  * or occur with WASI modules exiting with a certain exit code.
72  */
73 WASM_API_EXTERN bool wasmtime_trap_code(const wasm_trap_t *,
74                                         wasmtime_trap_code_t *code);
75 
76 /**
77  * \brief Returns a human-readable name for this frame's function.
78  *
79  * This function will attempt to load a human-readable name for function this
80  * frame points to. This function may return `NULL`.
81  *
82  * The lifetime of the returned name is the same as the #wasm_frame_t itself.
83  */
84 WASM_API_EXTERN const wasm_name_t *
85 wasmtime_frame_func_name(const wasm_frame_t *);
86 
87 /**
88  * \brief Returns a human-readable name for this frame's module.
89  *
90  * This function will attempt to load a human-readable name for module this
91  * frame points to. This function may return `NULL`.
92  *
93  * The lifetime of the returned name is the same as the #wasm_frame_t itself.
94  */
95 WASM_API_EXTERN const wasm_name_t *
96 wasmtime_frame_module_name(const wasm_frame_t *);
97 
98 #ifdef __cplusplus
99 } // extern "C"
100 #endif
101 
102 #endif // WASMTIME_TRAP_H
103