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 /// When the `component-model` feature is enabled this trap represents a 51 /// function that was `canon lift`'d, then `canon lower`'d, then called. 52 /// This combination of creation of a function in the component model 53 /// generates a function that always traps and, when called, produces this 54 /// flavor of trap. 55 WASMTIME_TRAP_CODE_ALWAYS_TRAP_ADAPTER, 56 /// Execution has run out of the configured fuel amount. 57 WASMTIME_TRAP_CODE_OUT_OF_FUEL, 58 /// Used to indicate that a trap was raised by atomic wait operations on non 59 /// shared memory. 60 WASMTIME_TRAP_CODE_ATOMIC_WAIT_NON_SHARED_MEMORY, 61 /// Call to a null reference. 62 WASMTIME_TRAP_CODE_NULL_REFERENCE, 63 /// Attempt to access beyond the bounds of an array. 64 WASMTIME_TRAP_CODE_ARRAY_OUT_OF_BOUNDS, 65 /// Attempted an allocation that was too large to succeed. 66 WASMTIME_TRAP_CODE_ALLOCATION_TOO_LARGE, 67 /// Attempted to cast a reference to a type that it is not an instance of. 68 WASMTIME_TRAP_CODE_CAST_FAILURE, 69 /// When the `component-model` feature is enabled this trap represents a 70 /// scenario where one component tried to call another component but it 71 /// would have violated the reentrance rules of the component model, 72 /// triggering a trap instead. 73 WASMTIME_TRAP_CODE_CANNOT_ENTER_COMPONENT, 74 /// Async-lifted export failed to produce a result by calling `task.return` 75 /// before returning `STATUS_DONE` and/or after all host tasks completed. 76 WASMTIME_TRAP_CODE_NO_ASYNC_RESULT, 77 /// A Pulley opcode was executed at runtime when the opcode was disabled at 78 /// compile time. 79 WASMTIME_TRAP_CODE_DISABLED_OPCODE, 80 }; 81 82 /** 83 * \brief Creates a new trap with the given message. 84 * 85 * \param msg the message to associate with this trap 86 * \param msg_len the byte length of `msg` 87 * 88 * The #wasm_trap_t returned is owned by the caller. 89 */ 90 WASM_API_EXTERN wasm_trap_t *wasmtime_trap_new(const char *msg, size_t msg_len); 91 92 /** 93 * \brief Creates a new trap from the given trap code. 94 * 95 * \param code the trap code to associate with this trap 96 * 97 * The #wasm_trap_t returned is owned by the caller. 98 */ 99 WASM_API_EXTERN wasm_trap_t *wasmtime_trap_new_code(wasmtime_trap_code_t code); 100 101 /** 102 * \brief Attempts to extract the trap code from this trap. 103 * 104 * Returns `true` if the trap is an instruction trap triggered while 105 * executing Wasm. If `true` is returned then the trap code is returned 106 * through the `code` pointer. If `false` is returned then this is not 107 * an instruction trap -- traps can also be created using wasm_trap_new, 108 * or occur with WASI modules exiting with a certain exit code. 109 */ 110 WASM_API_EXTERN bool wasmtime_trap_code(const wasm_trap_t *, 111 wasmtime_trap_code_t *code); 112 113 /** 114 * \brief Returns a human-readable name for this frame's function. 115 * 116 * This function will attempt to load a human-readable name for function this 117 * frame points to. This function may return `NULL`. 118 * 119 * The lifetime of the returned name is the same as the #wasm_frame_t itself. 120 */ 121 WASM_API_EXTERN const wasm_name_t * 122 wasmtime_frame_func_name(const wasm_frame_t *); 123 124 /** 125 * \brief Returns a human-readable name for this frame's module. 126 * 127 * This function will attempt to load a human-readable name for module this 128 * frame points to. This function may return `NULL`. 129 * 130 * The lifetime of the returned name is the same as the #wasm_frame_t itself. 131 */ 132 WASM_API_EXTERN const wasm_name_t * 133 wasmtime_frame_module_name(const wasm_frame_t *); 134 135 #ifdef __cplusplus 136 } // extern "C" 137 #endif 138 139 #endif // WASMTIME_TRAP_H 140