The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /* |
| 2 | * Copyright 2018 WebAssembly Community Group participants |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | #ifndef WASM_RT_H_ |
| 18 | #define WASM_RT_H_ |
| 19 | |
| 20 | #include <setjmp.h> |
| 21 | #include <stdbool.h> |
| 22 | #include <stdint.h> |
| 23 | #include <stdlib.h> |
| 24 | #include <string.h> |
| 25 | |
| 26 | #ifdef __cplusplus |
| 27 | extern "C" { |
| 28 | #endif |
| 29 | |
| 30 | #ifndef __has_builtin |
| 31 | #define __has_builtin(x) 0 /** Compatibility with non-clang compilers. */ |
| 32 | #endif |
| 33 | |
| 34 | #if __has_builtin(__builtin_expect) |
| 35 | #define UNLIKELY(x) __builtin_expect(!!(x), 0) |
| 36 | #define LIKELY(x) __builtin_expect(!!(x), 1) |
| 37 | #else |
| 38 | #define UNLIKELY(x) (x) |
| 39 | #define LIKELY(x) (x) |
| 40 | #endif |
| 41 | |
| 42 | #if __has_builtin(__builtin_memcpy) |
| 43 | #define wasm_rt_memcpy __builtin_memcpy |
| 44 | #else |
| 45 | #define wasm_rt_memcpy memcpy |
| 46 | #endif |
| 47 | |
| 48 | #if __has_builtin(__builtin_unreachable) |
| 49 | #define wasm_rt_unreachable __builtin_unreachable |
| 50 | #else |
| 51 | #define wasm_rt_unreachable abort |
| 52 | #endif |
| 53 | |
| 54 | #ifdef __STDC_VERSION__ |
| 55 | #if __STDC_VERSION__ >= 201112L |
| 56 | #define WASM_RT_C11_AVAILABLE |
| 57 | #endif |
| 58 | #endif |
| 59 | |
| 60 | /** |
| 61 | * Many devices don't implement the C11 threads.h. We use CriticalSection APIs |
| 62 | * for Windows and pthreads on other platforms where threads are not available. |
| 63 | */ |
| 64 | #ifdef WASM_RT_C11_AVAILABLE |
| 65 | |
| 66 | #if defined(_WIN32) |
| 67 | #include <windows.h> |
| 68 | #define WASM_RT_MUTEX CRITICAL_SECTION |
| 69 | #define WASM_RT_USE_CRITICALSECTION 1 |
| 70 | #else |
| 71 | #include <pthread.h> |
| 72 | #define WASM_RT_MUTEX pthread_mutex_t |
| 73 | #define WASM_RT_USE_PTHREADS 1 |
| 74 | #endif |
| 75 | |
| 76 | #endif |
| 77 | |
| 78 | #ifdef WASM_RT_C11_AVAILABLE |
| 79 | #define WASM_RT_THREAD_LOCAL _Thread_local |
| 80 | #elif defined(_MSC_VER) |
| 81 | #define WASM_RT_THREAD_LOCAL __declspec(thread) |
| 82 | #elif (defined(__GNUC__) || defined(__clang__)) && !defined(__APPLE__) |
| 83 | // Disabled on Apple systems due to sporadic test failures. |
| 84 | #define WASM_RT_THREAD_LOCAL __thread |
| 85 | #else |
| 86 | #define WASM_RT_THREAD_LOCAL |
| 87 | #endif |
| 88 | |
| 89 | /** |
| 90 | * If enabled, perform additional sanity checks in the generated wasm2c code and |
| 91 | * wasm2c runtime. This is useful to enable on debug builds. |
| 92 | */ |
| 93 | #ifndef WASM_RT_SANITY_CHECKS |
| 94 | #define WASM_RT_SANITY_CHECKS 0 |
| 95 | #endif |
| 96 | |
| 97 | /** |
| 98 | * Backward compatibility: Convert the previously exposed |
| 99 | * WASM_RT_MEMCHECK_SIGNAL_HANDLER macro to the ALLOCATION and CHECK macros that |
| 100 | * are now used. |
| 101 | */ |
| 102 | #if defined(WASM_RT_MEMCHECK_SIGNAL_HANDLER) |
| 103 | |
| 104 | #if WASM_RT_MEMCHECK_SIGNAL_HANDLER |
| 105 | #define WASM_RT_USE_MMAP 1 |
| 106 | #define WASM_RT_MEMCHECK_GUARD_PAGES 1 |
| 107 | #else |
| 108 | #define WASM_RT_USE_MMAP 0 |
| 109 | #define WASM_RT_MEMCHECK_BOUNDS_CHECK 1 |
| 110 | #endif |
| 111 | |
| 112 | #warning \ |
| 113 | "WASM_RT_MEMCHECK_SIGNAL_HANDLER has been deprecated in favor of WASM_RT_USE_MMAP and WASM_RT_MEMORY_CHECK_* macros" |
| 114 | #endif |
| 115 | |
| 116 | /** |
| 117 | * Specify if we use OR mmap/mprotect (+ Windows equivalents) OR malloc/realloc |
| 118 | * for the Wasm memory allocation and growth. mmap/mprotect guarantees memory |
| 119 | * will grow without being moved, while malloc ensures the virtual memory is |
| 120 | * consumed only as needed, but may relocate the memory to handle memory |
| 121 | * fragmentation. |
| 122 | * |
| 123 | * This defaults to malloc on 32-bit platforms or if memory64 support is needed. |
| 124 | * It defaults to mmap on 64-bit platforms assuming memory64 support is not |
| 125 | * needed (so we can use the guard based range checks below). |
| 126 | */ |
| 127 | #ifndef WASM_RT_USE_MMAP |
| 128 | #if UINTPTR_MAX > 0xffffffff |
| 129 | #define WASM_RT_USE_MMAP 1 |
| 130 | #else |
| 131 | #define WASM_RT_USE_MMAP 0 |
| 132 | #endif |
| 133 | #endif |
| 134 | |
| 135 | /** |
| 136 | * This macro, if defined, allows the embedder to permit elimination of unused |
| 137 | * memory loads. Note, this a non conformant configuration, i.e., this does not |
| 138 | * respect Wasm's specification, as Wasm requires all loads (even the eliminated |
| 139 | * loads to trap), whereas this configuration could eliminate an out-of-bound |
| 140 | * load, and thus allow the Wasm module to not trap. Use with caution. |
| 141 | */ |
| 142 | #ifndef WASM_RT_NONCONFORMING_ALLOW_OOB_READ_ELIMINATION |
| 143 | #define WASM_RT_NONCONFORMING_ALLOW_OOB_READ_ELIMINATION 0 |
| 144 | #endif |
| 145 | |
| 146 | /** |
| 147 | * Set the range checking strategy for Wasm memories. |
| 148 | * |
| 149 | * GUARD_PAGES: memory accesses rely on unmapped pages/guard pages to trap |
| 150 | * out-of-bound accesses. |
| 151 | * |
| 152 | * BOUNDS_CHECK: memory accesses are checked with explicit bounds checks. |
| 153 | * |
| 154 | * This defaults to GUARD_PAGES as this is the fastest option, iff the |
| 155 | * requirements of GUARD_PAGES --- 64-bit platforms, MMAP allocation strategy, |
| 156 | * no 64-bit memories, and platforms with a supported FORCE_READ_STRATEGY |
| 157 | * described below --- are met. This falls back to BOUNDS otherwise. |
| 158 | * |
| 159 | * FORCE_READ_STRATEGY --- either the compiler should be a gcc/clang-like |
| 160 | * compiler or the embedder must permit a non-conforming setting (allow dead |
| 161 | * read elimination from linear memory) |
| 162 | */ |
| 163 | #if UINTPTR_MAX > 0xffffffff && WASM_RT_USE_MMAP && \ |
| 164 | (WASM_RT_NONCONFORMING_ALLOW_OOB_READ_ELIMINATION || defined(__GNUC__)) |
| 165 | #define WASM_RT_GUARD_PAGES_SUPPORTED 1 |
| 166 | #else |
| 167 | #define WASM_RT_GUARD_PAGES_SUPPORTED 0 |
| 168 | #endif |
| 169 | |
| 170 | /** Specify defaults for memory checks if unspecified */ |
| 171 | #if !defined(WASM_RT_MEMCHECK_GUARD_PAGES) && \ |
| 172 | !defined(WASM_RT_MEMCHECK_BOUNDS_CHECK) |
| 173 | #if WASM_RT_GUARD_PAGES_SUPPORTED |
| 174 | #define WASM_RT_MEMCHECK_GUARD_PAGES 1 |
| 175 | #else |
| 176 | #define WASM_RT_MEMCHECK_BOUNDS_CHECK 1 |
| 177 | #endif |
| 178 | #endif |
| 179 | |
| 180 | /** Ensure the macros are defined */ |
| 181 | #ifndef WASM_RT_MEMCHECK_GUARD_PAGES |
| 182 | #define WASM_RT_MEMCHECK_GUARD_PAGES 0 |
| 183 | #endif |
| 184 | #ifndef WASM_RT_MEMCHECK_BOUNDS_CHECK |
| 185 | #define WASM_RT_MEMCHECK_BOUNDS_CHECK 0 |
| 186 | #endif |
| 187 | |
| 188 | /** Sanity check the use of guard pages */ |
| 189 | #if WASM_RT_MEMCHECK_GUARD_PAGES && !WASM_RT_GUARD_PAGES_SUPPORTED |
| 190 | #error \ |
| 191 | "WASM_RT_MEMCHECK_GUARD_PAGES not supported on this platform/configuration" |
| 192 | #endif |
| 193 | |
| 194 | #if WASM_RT_MEMCHECK_GUARD_PAGES && WASM_RT_MEMCHECK_BOUNDS_CHECK |
| 195 | #error \ |
| 196 | "Cannot use both WASM_RT_MEMCHECK_GUARD_PAGES and WASM_RT_MEMCHECK_BOUNDS_CHECK" |
| 197 | |
| 198 | #elif !WASM_RT_MEMCHECK_GUARD_PAGES && !WASM_RT_MEMCHECK_BOUNDS_CHECK |
| 199 | #error \ |
| 200 | "Must choose at least one from WASM_RT_MEMCHECK_GUARD_PAGES and WASM_RT_MEMCHECK_BOUNDS_CHECK" |
| 201 | #endif |
| 202 | |
| 203 | /** |
| 204 | * Some configurations above require the Wasm runtime to install a signal |
| 205 | * handler. However, this can be explicitly disallowed by the host using |
| 206 | * WASM_RT_SKIP_SIGNAL_RECOVERY. In this case, when the wasm code encounters an |
| 207 | * OOB access, it may either trap or abort. |
| 208 | */ |
| 209 | #ifndef WASM_RT_SKIP_SIGNAL_RECOVERY |
| 210 | #define WASM_RT_SKIP_SIGNAL_RECOVERY 0 |
| 211 | #endif |
| 212 | |
| 213 | #if WASM_RT_MEMCHECK_GUARD_PAGES && !WASM_RT_SKIP_SIGNAL_RECOVERY |
| 214 | #define WASM_RT_INSTALL_SIGNAL_HANDLER 1 |
| 215 | #else |
| 216 | #define WASM_RT_INSTALL_SIGNAL_HANDLER 0 |
| 217 | #endif |
| 218 | |
| 219 | /** |
| 220 | * This macro, if defined to 1 (i.e., allows the "segue" optimization), allows |
| 221 | * Wasm2c to use segment registers to speedup access to the linear heap. Note |
| 222 | * that even if allowed in this way, the segment registers would only be used if |
| 223 | * Wasm2c output is compiled for a suitable architecture and OS and the produces |
| 224 | * C file is compiled by supported compilers. The extact restrictions are listed |
| 225 | * in detail in src/template/wasm2c.declarations.c |
| 226 | */ |
| 227 | #ifndef WASM_RT_ALLOW_SEGUE |
| 228 | #define WASM_RT_ALLOW_SEGUE 0 |
| 229 | #endif |
| 230 | |
| 231 | /** |
| 232 | * The segue optimization restores x86 segments to their old values when exiting |
| 233 | * wasm2c code. If WASM_RT_SEGUE_FREE_SEGMENT is defined, wasm2c assumes it has |
| 234 | * exclusive use of the segment and optimizes performance in two ways. First, it |
| 235 | * does not restore the "old" value of the segment during exits. Second, wasm2c |
| 236 | * only sets the segment register if the value has changed since the last time |
| 237 | * it was set. |
| 238 | */ |
| 239 | #ifndef WASM_RT_SEGUE_FREE_SEGMENT |
| 240 | #define WASM_RT_SEGUE_FREE_SEGMENT 0 |
| 241 | #endif |
| 242 | |
| 243 | #ifndef WASM_RT_USE_SEGUE |
| 244 | // Memory functions can use the segue optimization if allowed. The segue |
| 245 | // optimization uses x86 segments to point to a linear memory. We use this |
| 246 | // optimization when: |
| 247 | // |
| 248 | // (1) Segue is allowed using WASM_RT_ALLOW_SEGUE |
| 249 | // (2) on x86_64 without WABT_BIG_ENDIAN enabled |
| 250 | // (3) the compiler supports: intrinsics for (rd|wr)gsbase, "address namespaces" |
| 251 | // for accessing pointers, and supports memcpy on pointers with custom |
| 252 | // "address namespaces". GCC does not support the memcpy requirement, so |
| 253 | // this leaves only clang (version 9 or later) for now. |
| 254 | // (4) The OS provides a way to query if (rd|wr)gsbase is allowed by the kernel |
| 255 | // or the implementation has to use a syscall for this. |
| 256 | // (5) The OS doesn't replace the segment register on context switch which |
| 257 | // eliminates windows for now |
| 258 | // |
| 259 | // While more OS can be supported in the future, we only support linux for now |
| 260 | #if WASM_RT_ALLOW_SEGUE && !WABT_BIG_ENDIAN && \ |
| 261 | (defined(__x86_64__) || defined(_M_X64)) && __clang__ && \ |
| 262 | (__clang_major__ >= 9) && __has_builtin(__builtin_ia32_wrgsbase64) && \ |
| 263 | !defined(_WIN32) && !defined(__ANDROID__) && \ |
| 264 | (defined(__linux__) || defined(__FreeBSD__)) |
| 265 | #define WASM_RT_USE_SEGUE 1 |
| 266 | #else |
| 267 | #define WASM_RT_USE_SEGUE 0 |
| 268 | #endif |
| 269 | #endif |
| 270 | |
| 271 | /** |
| 272 | * This macro, if defined, allows the embedder to disable all stack exhaustion |
| 273 | * checks. This a non conformant configuration, i.e., this does not respect |
| 274 | * Wasm's specification, and may compromise security. Use with caution. |
| 275 | */ |
| 276 | #ifndef WASM_RT_NONCONFORMING_UNCHECKED_STACK_EXHAUSTION |
| 277 | #define WASM_RT_NONCONFORMING_UNCHECKED_STACK_EXHAUSTION 0 |
| 278 | #endif |
| 279 | |
| 280 | /** |
| 281 | * We need to detect and trap stack overflows. If we use a signal handler on |
| 282 | * POSIX systems, this can detect call stack overflows. On windows, or platforms |
| 283 | * without a signal handler, we use stack depth counting. The s390x big endian |
| 284 | * platform additionally seems to have issues with stack guard pages, so we play |
| 285 | * it safe and use stack counting on big endian platforms. |
| 286 | */ |
| 287 | #if !defined(WASM_RT_STACK_DEPTH_COUNT) && \ |
| 288 | !defined(WASM_RT_STACK_EXHAUSTION_HANDLER) && \ |
| 289 | !WASM_RT_NONCONFORMING_UNCHECKED_STACK_EXHAUSTION |
| 290 | |
| 291 | #if WASM_RT_INSTALL_SIGNAL_HANDLER && !defined(_WIN32) && !WABT_BIG_ENDIAN |
| 292 | #define WASM_RT_STACK_EXHAUSTION_HANDLER 1 |
| 293 | #else |
| 294 | #define WASM_RT_STACK_DEPTH_COUNT 1 |
| 295 | #endif |
| 296 | |
| 297 | #endif |
| 298 | |
| 299 | /** Ensure the stack macros are defined */ |
| 300 | #ifndef WASM_RT_STACK_DEPTH_COUNT |
| 301 | #define WASM_RT_STACK_DEPTH_COUNT 0 |
| 302 | #endif |
| 303 | #ifndef WASM_RT_STACK_EXHAUSTION_HANDLER |
| 304 | #define WASM_RT_STACK_EXHAUSTION_HANDLER 0 |
| 305 | #endif |
| 306 | |
| 307 | #if WASM_RT_NONCONFORMING_UNCHECKED_STACK_EXHAUSTION |
| 308 | |
| 309 | #if (WASM_RT_STACK_EXHAUSTION_HANDLER + WASM_RT_STACK_DEPTH_COUNT) != 0 |
| 310 | #error \ |
| 311 | "Cannot specify WASM_RT_NONCONFORMING_UNCHECKED_STACK_EXHAUSTION along with WASM_RT_STACK_EXHAUSTION_HANDLER or WASM_RT_STACK_DEPTH_COUNT" |
| 312 | #endif |
| 313 | |
| 314 | #else |
| 315 | |
| 316 | #if (WASM_RT_STACK_EXHAUSTION_HANDLER + WASM_RT_STACK_DEPTH_COUNT) > 1 |
| 317 | #error \ |
| 318 | "Cannot specify multiple options from WASM_RT_STACK_EXHAUSTION_HANDLER , WASM_RT_STACK_DEPTH_COUNT" |
| 319 | #elif (WASM_RT_STACK_EXHAUSTION_HANDLER + WASM_RT_STACK_DEPTH_COUNT) == 0 |
| 320 | #error \ |
| 321 | "Must specify one of WASM_RT_STACK_EXHAUSTION_HANDLER , WASM_RT_STACK_DEPTH_COUNT" |
| 322 | #endif |
| 323 | |
| 324 | #endif |
| 325 | |
| 326 | #if WASM_RT_STACK_EXHAUSTION_HANDLER && !WASM_RT_INSTALL_SIGNAL_HANDLER |
| 327 | #error \ |
| 328 | "WASM_RT_STACK_EXHAUSTION_HANDLER can only be used if WASM_RT_INSTALL_SIGNAL_HANDLER is enabled" |
| 329 | #endif |
| 330 | |
| 331 | #if WASM_RT_STACK_DEPTH_COUNT |
| 332 | /** |
| 333 | * When the signal handler cannot be used to detect stack overflows, stack depth |
| 334 | * is limited explicitly. The maximum stack depth before trapping can be |
| 335 | * configured by defining this symbol before including wasm-rt when building the |
| 336 | * generated c files, for example: |
| 337 | * |
| 338 | * ``` |
| 339 | * cc -c -DWASM_RT_MAX_CALL_STACK_DEPTH=100 my_module.c -o my_module.o |
| 340 | * ``` |
| 341 | */ |
| 342 | #ifndef WASM_RT_MAX_CALL_STACK_DEPTH |
| 343 | #define WASM_RT_MAX_CALL_STACK_DEPTH 500 |
| 344 | #endif |
| 345 | |
| 346 | /** Current call stack depth. */ |
| 347 | extern WASM_RT_THREAD_LOCAL uint32_t wasm_rt_call_stack_depth; |
| 348 | |
| 349 | #endif |
| 350 | |
| 351 | #if WASM_RT_USE_SEGUE |
| 352 | /** |
| 353 | * The segue optimization uses x86 segments to point to a linear memory. If |
| 354 | * used, the runtime must query whether it can use the fast userspace wrgsbase |
| 355 | * instructions or whether it must invoke syscalls to set the segment base, |
| 356 | * depending on the supported CPU features. The result of this query is saved in |
| 357 | * this variable. |
| 358 | */ |
| 359 | extern bool wasm_rt_fsgsbase_inst_supported; |
| 360 | /** |
| 361 | * If fast userspace wrgsbase instructions don't exist, the runtime most provide |
| 362 | * a function that invokes the OS' underlying syscall to set the segment base. |
| 363 | */ |
| 364 | void wasm_rt_syscall_set_segue_base(void* base); |
| 365 | /** |
| 366 | * If fast userspace rdgsbase instructions don't exist, the runtime most provide |
| 367 | * a function that invokes the OS' underlying syscall to get the segment base. |
| 368 | */ |
| 369 | void* wasm_rt_syscall_get_segue_base(); |
| 370 | /** |
| 371 | * If WASM_RT_SEGUE_FREE_SEGMENT is defined, we must only set the segment |
| 372 | * register if it was changed since the last time it was set. The last value set |
| 373 | * on the segment register is stored in this variable. |
| 374 | */ |
| 375 | #if WASM_RT_SEGUE_FREE_SEGMENT |
| 376 | extern WASM_RT_THREAD_LOCAL void* wasm_rt_last_segment_val; |
| 377 | #endif |
| 378 | #endif |
| 379 | |
| 380 | #if defined(_MSC_VER) |
| 381 | #define WASM_RT_NO_RETURN __declspec(noreturn) |
| 382 | #else |
| 383 | #define WASM_RT_NO_RETURN __attribute__((noreturn)) |
| 384 | #endif |
| 385 | |
| 386 | #if defined(__APPLE__) && WASM_RT_STACK_EXHAUSTION_HANDLER |
| 387 | #define WASM_RT_MERGED_OOB_AND_EXHAUSTION_TRAPS 1 |
| 388 | #else |
| 389 | #define WASM_RT_MERGED_OOB_AND_EXHAUSTION_TRAPS 0 |
| 390 | #endif |
| 391 | |
| 392 | /** Reason a trap occurred. Provide this to `wasm_rt_trap`. */ |
| 393 | typedef enum { |
| 394 | WASM_RT_TRAP_NONE, /** No error. */ |
| 395 | WASM_RT_TRAP_OOB, /** Out-of-bounds access in linear memory or a table. */ |
| 396 | WASM_RT_TRAP_INT_OVERFLOW, /** Integer overflow on divide or truncation. */ |
| 397 | WASM_RT_TRAP_DIV_BY_ZERO, /** Integer divide by zero. */ |
| 398 | WASM_RT_TRAP_INVALID_CONVERSION, /** Conversion from NaN to integer. */ |
| 399 | WASM_RT_TRAP_UNREACHABLE, /** Unreachable instruction executed. */ |
| 400 | WASM_RT_TRAP_CALL_INDIRECT, /** Invalid call_indirect, for any reason. */ |
| 401 | WASM_RT_TRAP_NULL_REF, /** Null reference. */ |
| 402 | WASM_RT_TRAP_UNCAUGHT_EXCEPTION, /** Exception thrown and not caught. */ |
| 403 | WASM_RT_TRAP_UNALIGNED, /** Unaligned atomic instruction executed. */ |
| 404 | #if WASM_RT_MERGED_OOB_AND_EXHAUSTION_TRAPS |
| 405 | WASM_RT_TRAP_EXHAUSTION = WASM_RT_TRAP_OOB, |
| 406 | #else |
| 407 | WASM_RT_TRAP_EXHAUSTION, /** Call stack exhausted. */ |
| 408 | #endif |
| 409 | } wasm_rt_trap_t; |
| 410 | |
| 411 | /** Value types. Used to define function signatures. */ |
| 412 | typedef enum { |
| 413 | WASM_RT_I32, |
| 414 | WASM_RT_I64, |
| 415 | WASM_RT_F32, |
| 416 | WASM_RT_F64, |
| 417 | WASM_RT_V128, |
| 418 | WASM_RT_FUNCREF, |
| 419 | WASM_RT_EXTERNREF, |
| 420 | WASM_RT_EXNREF, |
| 421 | } wasm_rt_type_t; |
| 422 | |
| 423 | /** |
| 424 | * A generic function pointer type, both for Wasm functions (`code`) |
| 425 | * and host functions (`hostcode`). All function pointers are stored |
| 426 | * in this canonical form, but must be cast to their proper signature |
| 427 | * to call. |
| 428 | */ |
| 429 | typedef void (*wasm_rt_function_ptr_t)(void); |
| 430 | |
| 431 | /** |
| 432 | * A pointer to a "tail-callee" function, called by a tail-call |
| 433 | * trampoline or by another tail-callee function. (The definition uses a |
| 434 | * single-member struct to allow a recursive definition.) |
| 435 | */ |
| 436 | typedef struct wasm_rt_tailcallee_t { |
| 437 | void (*fn)(void** instance_ptr, |
| 438 | void* tail_call_stack, |
| 439 | struct wasm_rt_tailcallee_t* next); |
| 440 | } wasm_rt_tailcallee_t; |
| 441 | |
| 442 | /** |
| 443 | * The type of a function (an arbitrary number of param and result types). |
| 444 | * This is represented as an opaque 256-bit ID. |
| 445 | */ |
| 446 | typedef const char* wasm_rt_func_type_t; |
| 447 | |
| 448 | /** |
| 449 | * A function instance (the runtime representation of a function). |
| 450 | * These can be stored in tables of type funcref, or used as values. |
| 451 | */ |
| 452 | typedef struct { |
| 453 | /** The function's type. */ |
| 454 | wasm_rt_func_type_t func_type; |
| 455 | /** |
| 456 | * The function. The embedder must know the actual C signature of the function |
| 457 | * and cast to it before calling. |
| 458 | */ |
| 459 | wasm_rt_function_ptr_t func; |
| 460 | /** An alternate version of the function to be used when tail-called. */ |
| 461 | wasm_rt_tailcallee_t func_tailcallee; |
| 462 | /** |
| 463 | * A function instance is a closure of the function over an instance |
| 464 | * of the originating module. The module_instance element will be passed into |
| 465 | * the function at runtime. |
| 466 | */ |
| 467 | void* module_instance; |
| 468 | } wasm_rt_funcref_t; |
| 469 | |
| 470 | /** Default (null) value of a funcref */ |
| 471 | #define wasm_rt_funcref_null_value \ |
| 472 | ((wasm_rt_funcref_t){NULL, NULL, {NULL}, NULL}) |
| 473 | |
| 474 | /** The type of an external reference (opaque to WebAssembly). */ |
| 475 | typedef void* wasm_rt_externref_t; |
| 476 | |
| 477 | /** Default (null) value of an externref */ |
| 478 | #define wasm_rt_externref_null_value ((wasm_rt_externref_t){NULL}) |
| 479 | |
| 480 | /** A Memory object. */ |
| 481 | typedef struct { |
| 482 | /** The linear memory data, with a byte length of `size`. */ |
| 483 | uint8_t* data; |
| 484 | /** The location after the the reserved space for the linear memory data. */ |
| 485 | uint8_t* data_end; |
| 486 | /** The page size for this Memory object |
| 487 | (always 64 KiB without the custom-page-sizes feature) */ |
| 488 | uint32_t page_size; |
| 489 | /** The current page count for this Memory object. */ |
| 490 | uint64_t pages; |
| 491 | /** The maximum page count for this Memory object. */ |
| 492 | uint64_t max_pages; |
| 493 | /** The current size of the linear memory, in bytes. */ |
| 494 | uint64_t size; |
| 495 | /** Is this memory indexed by u64 (as opposed to default u32) */ |
| 496 | bool is64; |
| 497 | } wasm_rt_memory_t; |
| 498 | |
| 499 | #ifdef WASM_RT_C11_AVAILABLE |
| 500 | /** A shared Memory object. */ |
| 501 | typedef struct { |
| 502 | /** |
| 503 | * The linear memory data, with a byte length of `size`. The memory is marked |
| 504 | * atomic as it is shared and may have to be accessed with different memory |
| 505 | * orders --- sequential when being accessed atomically, relaxed otherwise. |
| 506 | * Unfortunately, the C standard does not state what happens if there are |
| 507 | * overlaps in two memory accesses which have a memory order, e.g., an |
| 508 | * atomic32 being read from the same location an atomic64 is read. One way to |
| 509 | * prevent optimizations from assuming non-overlapping behavior as typically |
| 510 | * done in C is to mark the memory as volatile. Thus the memory is atomic and |
| 511 | * volatile. |
| 512 | */ |
| 513 | _Atomic volatile uint8_t* data; |
| 514 | /** The location one byte after the reserved space for the linear memory data. |
| 515 | * This includes any reserved pages that are not yet allocated. */ |
| 516 | _Atomic volatile uint8_t* data_end; |
| 517 | /** The page size for this Memory object |
| 518 | (always 64 KiB without the custom-page-sizes feature) */ |
| 519 | uint32_t page_size; |
| 520 | /** The current page count for this Memory object. */ |
| 521 | uint64_t pages; |
| 522 | /* The maximum page count for this Memory object. */ |
| 523 | uint64_t max_pages; |
| 524 | /** The current size of the linear memory, in bytes. */ |
| 525 | uint64_t size; |
| 526 | /** Is this memory indexed by u64 (as opposed to default u32) */ |
| 527 | bool is64; |
| 528 | /** Lock used to ensure operations such as memory grow are threadsafe */ |
| 529 | WASM_RT_MUTEX mem_lock; |
| 530 | } wasm_rt_shared_memory_t; |
| 531 | #endif |
| 532 | |
| 533 | /** A Table of type funcref. */ |
| 534 | typedef struct { |
| 535 | /** The table element data, with an element count of `size`. */ |
| 536 | wasm_rt_funcref_t* data; |
| 537 | /** |
| 538 | * The maximum element count of this Table object. If there is no maximum, |
| 539 | * `max_size` is 0xffffffffu (i.e. UINT32_MAX). |
| 540 | */ |
| 541 | uint32_t max_size; |
| 542 | /** The current element count of the table. */ |
| 543 | uint32_t size; |
| 544 | } wasm_rt_funcref_table_t; |
| 545 | |
| 546 | /** A Table of type externref. */ |
| 547 | typedef struct { |
| 548 | /** The table element data, with an element count of `size`. */ |
| 549 | wasm_rt_externref_t* data; |
| 550 | /** |
| 551 | * The maximum element count of this Table object. If there is no maximum, |
| 552 | * `max_size` is 0xffffffffu (i.e. UINT32_MAX). |
| 553 | */ |
| 554 | uint32_t max_size; |
| 555 | /** The current element count of the table. */ |
| 556 | uint32_t size; |
| 557 | } wasm_rt_externref_table_t; |
| 558 | |
| 559 | /** Initialize the runtime. */ |
| 560 | void wasm_rt_init(void); |
| 561 | |
| 562 | /** Is the runtime initialized? */ |
| 563 | bool wasm_rt_is_initialized(void); |
| 564 | |
| 565 | /** Free the runtime's state. */ |
| 566 | void wasm_rt_free(void); |
| 567 | |
| 568 | /* |
| 569 | * Initialize the multithreaded runtime for a given thread. Must be |
| 570 | * called by each thread (other than the one that called wasm_rt_init) |
| 571 | * before initializing a Wasm module or calling an exported |
| 572 | * function. |
| 573 | */ |
| 574 | void wasm_rt_init_thread(void); |
| 575 | |
| 576 | /* |
| 577 | * Free the individual thread's state. |
| 578 | */ |
| 579 | void wasm_rt_free_thread(void); |
| 580 | |
| 581 | /** A hardened jmp_buf that allows checking for initialization before use */ |
| 582 | typedef struct { |
| 583 | /** Is the jmp buf intialized? */ |
| 584 | bool initialized; |
| 585 | /** jmp_buf contents */ |
| 586 | jmp_buf buffer; |
| 587 | } wasm_rt_jmp_buf; |
| 588 | |
| 589 | #ifndef _WIN32 |
| 590 | #define WASM_RT_SETJMP_TRAP_SETBUF(buf) sigsetjmp(buf, 1) |
| 591 | |
| 592 | /** |
| 593 | * On macOS XNU, there is a bug where nested `sigsetjmp` and `siglongjmp` |
| 594 | * across threads that have an allocated alternate signal stack (`SS_ONSTACK`) |
| 595 | * will erroneously cause the kernel to preserve the `SS_ONSTACK` flag in the |
| 596 | * thread state |
| 597 | * |
| 598 | * See: https://github.com/WebAssembly/wabt/issues/2654 |
| 599 | * See: https://github.com/golang/go/issues/44501 |
| 600 | */ |
| 601 | #define WASM_RT_SETJMP_EXN_SETBUF(buf) sigsetjmp(buf, 0) |
| 602 | #else |
| 603 | #define WASM_RT_SETJMP_TRAP_SETBUF(buf) setjmp(buf) |
| 604 | #define WASM_RT_SETJMP_EXN_SETBUF(buf) setjmp(buf) |
| 605 | #endif |
| 606 | |
| 607 | #define WASM_RT_SETJMP(buf) \ |
| 608 | ((buf).initialized = true, WASM_RT_SETJMP_TRAP_SETBUF((buf).buffer)) |
| 609 | #define WASM_RT_SETJMP_EXN(buf) \ |
| 610 | ((buf).initialized = true, WASM_RT_SETJMP_EXN_SETBUF((buf).buffer)) |
| 611 | |
| 612 | #ifndef _WIN32 |
| 613 | #define WASM_RT_LONGJMP_UNCHECKED(buf, val) siglongjmp(buf, val) |
| 614 | #else |
| 615 | #define WASM_RT_LONGJMP_UNCHECKED(buf, val) longjmp(buf, val) |
| 616 | #endif |
| 617 | |
| 618 | #define WASM_RT_LONGJMP(buf, val) \ |
| 619 | /** Abort on failure as this may be called in the trap handler */ \ |
| 620 | if (!((buf).initialized)) \ |
| 621 | abort(); \ |
| 622 | (buf).initialized = false; \ |
| 623 | WASM_RT_LONGJMP_UNCHECKED((buf).buffer, val) |
| 624 | |
| 625 | /** |
| 626 | * Stop execution immediately and jump back to the call to `wasm_rt_impl_try`. |
| 627 | * The result of `wasm_rt_impl_try` will be the provided trap reason. |
| 628 | * |
| 629 | * This is typically called by the generated code, and not the embedder. |
| 630 | */ |
| 631 | WASM_RT_NO_RETURN void wasm_rt_trap(wasm_rt_trap_t); |
| 632 | |
| 633 | /** Return a human readable error string based on a trap type. */ |
| 634 | const char* wasm_rt_strerror(wasm_rt_trap_t trap); |
| 635 | |
| 636 | #define wasm_rt_try(target) WASM_RT_SETJMP_EXN(target) |
| 637 | |
| 638 | /** WebAssembly's default page size (64 KiB) */ |
| 639 | #define WASM_DEFAULT_PAGE_SIZE 65536 |
| 640 | |
| 641 | /** |
| 642 | * Initialize a Memory object with an initial page size of `initial_pages` and |
| 643 | * a maximum page size of `max_pages`, indexed with an i32 or i64. |
| 644 | * |
| 645 | * ``` |
| 646 | * wasm_rt_memory_t my_memory; |
| 647 | * // 1 initial page (65536 bytes), and a maximum of 2 pages, |
| 648 | * // indexed with an i32 |
| 649 | * wasm_rt_allocate_memory(&my_memory, 1, 2, false, WASM_DEFAULT_PAGE_SIZE); |
| 650 | * ``` |
| 651 | */ |
| 652 | void wasm_rt_allocate_memory(wasm_rt_memory_t*, |
| 653 | uint64_t initial_pages, |
| 654 | uint64_t max_pages, |
| 655 | bool is64, |
| 656 | uint32_t page_size); |
| 657 | |
| 658 | /** |
| 659 | * Grow a Memory object by `pages`, and return the previous page count. If |
| 660 | * this new page count is greater than the maximum page count, the grow fails |
| 661 | * and 0xffffffffu (UINT32_MAX) is returned instead. |
| 662 | * |
| 663 | * ``` |
| 664 | * wasm_rt_memory_t my_memory; |
| 665 | * ... |
| 666 | * // Grow memory by 10 pages. |
| 667 | * uint32_t old_page_size = wasm_rt_grow_memory(&my_memory, 10); |
| 668 | * if (old_page_size == UINT32_MAX) { |
| 669 | * // Failed to grow memory. |
| 670 | * } |
| 671 | * ``` |
| 672 | */ |
| 673 | uint64_t wasm_rt_grow_memory(wasm_rt_memory_t*, uint64_t pages); |
| 674 | |
| 675 | /** Free a Memory object. */ |
| 676 | void wasm_rt_free_memory(wasm_rt_memory_t*); |
| 677 | |
| 678 | #ifdef WASM_RT_C11_AVAILABLE |
| 679 | /** Shared memory version of wasm_rt_allocate_memory */ |
| 680 | void wasm_rt_allocate_memory_shared(wasm_rt_shared_memory_t*, |
| 681 | uint64_t initial_pages, |
| 682 | uint64_t max_pages, |
| 683 | bool is64, |
| 684 | uint32_t page_size); |
| 685 | |
| 686 | /** Shared memory version of wasm_rt_grow_memory */ |
| 687 | uint64_t wasm_rt_grow_memory_shared(wasm_rt_shared_memory_t*, uint64_t pages); |
| 688 | |
| 689 | /** Shared memory version of wasm_rt_free_memory */ |
| 690 | void wasm_rt_free_memory_shared(wasm_rt_shared_memory_t*); |
| 691 | #endif |
| 692 | |
| 693 | /** |
| 694 | * Initialize a funcref Table object with an element count of `elements` and a |
| 695 | * maximum size of `max_elements`. |
| 696 | * |
| 697 | * ``` |
| 698 | * wasm_rt_funcref_table_t my_table; |
| 699 | * // 5 elements and a maximum of 10 elements. |
| 700 | * wasm_rt_allocate_funcref_table(&my_table, 5, 10); |
| 701 | * ``` |
| 702 | */ |
| 703 | void wasm_rt_allocate_funcref_table(wasm_rt_funcref_table_t*, |
| 704 | uint32_t elements, |
| 705 | uint32_t max_elements); |
| 706 | |
| 707 | /** Free a funcref Table object. */ |
| 708 | void wasm_rt_free_funcref_table(wasm_rt_funcref_table_t*); |
| 709 | |
| 710 | /** |
| 711 | * Initialize an externref Table object with an element count |
| 712 | * of `elements` and a maximum size of `max_elements`. |
| 713 | * Usage as per wasm_rt_allocate_funcref_table. |
| 714 | */ |
| 715 | void wasm_rt_allocate_externref_table(wasm_rt_externref_table_t*, |
| 716 | uint32_t elements, |
| 717 | uint32_t max_elements); |
| 718 | |
| 719 | /** Free an externref Table object. */ |
| 720 | void wasm_rt_free_externref_table(wasm_rt_externref_table_t*); |
| 721 | |
| 722 | /** |
| 723 | * Grow a Table object by `delta` elements (giving the new elements the value |
| 724 | * `init`), and return the previous element count. If this new element count is |
| 725 | * greater than the maximum element count, the grow fails and 0xffffffffu |
| 726 | * (UINT32_MAX) is returned instead. |
| 727 | */ |
| 728 | uint32_t wasm_rt_grow_funcref_table(wasm_rt_funcref_table_t*, |
| 729 | uint32_t delta, |
| 730 | wasm_rt_funcref_t init); |
| 731 | uint32_t wasm_rt_grow_externref_table(wasm_rt_externref_table_t*, |
| 732 | uint32_t delta, |
| 733 | wasm_rt_externref_t init); |
| 734 | |
| 735 | #ifdef __cplusplus |
| 736 | } |
| 737 | #endif |
| 738 | |
| 739 | #endif /* WASM_RT_H_ */ |