@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
h 739 lines 25 KB
Raw
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_ */