wasmtime_environ/
builtin.rs

1/// Helper macro to iterate over all builtin functions and their signatures.
2#[macro_export]
3macro_rules! foreach_builtin_function {
4    ($mac:ident) => {
5        $mac! {
6            // Returns an index for wasm's `memory.grow` builtin function.
7            memory32_grow(vmctx: vmctx, delta: u64, index: u32) -> pointer;
8            // Returns an index for wasm's `table.copy` when both tables are locally
9            // defined.
10            table_copy(vmctx: vmctx, dst_index: u32, src_index: u32, dst: u64, src: u64, len: u64) -> bool;
11            // Returns an index for wasm's `table.init`.
12            table_init(vmctx: vmctx, table: u32, elem: u32, dst: u64, src: u64, len: u64) -> bool;
13            // Returns an index for wasm's `elem.drop`.
14            elem_drop(vmctx: vmctx, elem: u32);
15            // Returns an index for wasm's `memory.copy`
16            memory_copy(vmctx: vmctx, dst_index: u32, dst: u64, src_index: u32, src: u64, len: u64) -> bool;
17            // Returns an index for wasm's `memory.fill` instruction.
18            memory_fill(vmctx: vmctx, memory: u32, dst: u64, val: u32, len: u64) -> bool;
19            // Returns an index for wasm's `memory.init` instruction.
20            memory_init(vmctx: vmctx, memory: u32, data: u32, dst: u64, src: u32, len: u32) -> bool;
21            // Returns a value for wasm's `ref.func` instruction.
22            ref_func(vmctx: vmctx, func: u32) -> pointer;
23            // Returns an index for wasm's `data.drop` instruction.
24            data_drop(vmctx: vmctx, data: u32);
25            // Returns a table entry after lazily initializing it.
26            table_get_lazy_init_func_ref(vmctx: vmctx, table: u32, index: u64) -> pointer;
27            // Returns an index for Wasm's `table.grow` instruction for `funcref`s.
28            table_grow_func_ref(vmctx: vmctx, table: u32, delta: u64, init: pointer) -> pointer;
29            // Returns an index for Wasm's `table.fill` instruction for `funcref`s.
30            table_fill_func_ref(vmctx: vmctx, table: u32, dst: u64, val: pointer, len: u64) -> bool;
31            // Returns an index for wasm's `memory.atomic.notify` instruction.
32            #[cfg(feature = "threads")]
33            memory_atomic_notify(vmctx: vmctx, memory: u32, addr: u64, count: u32) -> u64;
34            // Returns an index for wasm's `memory.atomic.wait32` instruction.
35            #[cfg(feature = "threads")]
36            memory_atomic_wait32(vmctx: vmctx, memory: u32, addr: u64, expected: u32, timeout: u64) -> u64;
37            // Returns an index for wasm's `memory.atomic.wait64` instruction.
38            #[cfg(feature = "threads")]
39            memory_atomic_wait64(vmctx: vmctx, memory: u32, addr: u64, expected: u64, timeout: u64) -> u64;
40            // Invoked when fuel has run out while executing a function.
41            out_of_gas(vmctx: vmctx) -> bool;
42            // Invoked when we reach a new epoch.
43            #[cfg(target_has_atomic = "64")]
44            new_epoch(vmctx: vmctx) -> u64;
45            // Invoked before malloc returns.
46            #[cfg(feature = "wmemcheck")]
47            check_malloc(vmctx: vmctx, addr: u32, len: u32) -> bool;
48            // Invoked before the free returns.
49            #[cfg(feature = "wmemcheck")]
50            check_free(vmctx: vmctx, addr: u32) -> bool;
51            // Invoked before a load is executed.
52            #[cfg(feature = "wmemcheck")]
53            check_load(vmctx: vmctx, num_bytes: u32, addr: u32, offset: u32) -> bool;
54            // Invoked before a store is executed.
55            #[cfg(feature = "wmemcheck")]
56            check_store(vmctx: vmctx, num_bytes: u32, addr: u32, offset: u32) -> bool;
57            // Invoked after malloc is called.
58            #[cfg(feature = "wmemcheck")]
59            malloc_start(vmctx: vmctx);
60            // Invoked after free is called.
61            #[cfg(feature = "wmemcheck")]
62            free_start(vmctx: vmctx);
63            // Invoked when wasm stack pointer is updated.
64            #[cfg(feature = "wmemcheck")]
65            update_stack_pointer(vmctx: vmctx, value: u32);
66            // Invoked before memory.grow is called.
67            #[cfg(feature = "wmemcheck")]
68            update_mem_size(vmctx: vmctx, num_bytes: u32);
69
70            // Drop a non-stack GC reference (eg an overwritten table entry)
71            // once it will no longer be used again. (Note: `val` is not of type
72            // `reference` because it needn't appear in any stack maps, as it
73            // must not be live after this call.)
74            #[cfg(feature = "gc-drc")]
75            drop_gc_ref(vmctx: vmctx, val: u32);
76
77            // Grow the GC heap by `bytes_needed` bytes.
78            //
79            // Traps if growing the GC heap fails.
80            #[cfg(feature = "gc-null")]
81            grow_gc_heap(vmctx: vmctx, bytes_needed: u64) -> bool;
82
83            // Do a GC, treating the optional `root` as a GC root and returning
84            // the updated `root` (so that, in the case of moving collectors,
85            // callers have a valid version of `root` again).
86            #[cfg(feature = "gc-drc")]
87            gc(vmctx: vmctx, root: u32) -> u64;
88
89            // Allocate a new, uninitialized GC object and return a reference to
90            // it.
91            #[cfg(feature = "gc-drc")]
92            gc_alloc_raw(
93                vmctx: vmctx,
94                kind: u32,
95                module_interned_type_index: u32,
96                size: u32,
97                align: u32
98            ) -> u32;
99
100            // Intern a `funcref` into the GC heap, returning its
101            // `FuncRefTableId`.
102            //
103            // This libcall may not GC.
104            #[cfg(feature = "gc")]
105            intern_func_ref_for_gc_heap(
106                vmctx: vmctx,
107                func_ref: pointer
108            ) -> u64;
109
110            // Get the raw `VMFuncRef` pointer associated with a
111            // `FuncRefTableId` from an earlier `intern_func_ref_for_gc_heap`
112            // call.
113            //
114            // This libcall may not GC.
115            //
116            // Passes in the `ModuleInternedTypeIndex` of the funcref's expected
117            // type, or `ModuleInternedTypeIndex::reserved_value()` if we are
118            // getting the function reference as an untyped `funcref` rather
119            // than a typed `(ref $ty)`.
120            //
121            // TODO: We will want to eventually expose the table directly to
122            // Wasm code, so that it doesn't need to make a libcall to go from
123            // id to `VMFuncRef`. That will be a little tricky: it will also
124            // require updating the pointer to the slab in the `VMContext` (or
125            // `VMStoreContext` or wherever we put it) when the slab is
126            // resized.
127            #[cfg(feature = "gc")]
128            get_interned_func_ref(
129                vmctx: vmctx,
130                func_ref_id: u32,
131                module_interned_type_index: u32
132            ) -> pointer;
133
134            // Builtin implementation of the `array.new_data` instruction.
135            #[cfg(feature = "gc")]
136            array_new_data(
137                vmctx: vmctx,
138                array_interned_type_index: u32,
139                data_index: u32,
140                data_offset: u32,
141                len: u32
142            ) -> u32;
143
144            // Builtin implementation of the `array.new_elem` instruction.
145            #[cfg(feature = "gc")]
146            array_new_elem(
147                vmctx: vmctx,
148                array_interned_type_index: u32,
149                elem_index: u32,
150                elem_offset: u32,
151                len: u32
152            ) -> u32;
153
154            // Builtin implementation of the `array.copy` instruction.
155            #[cfg(feature = "gc")]
156            array_copy(
157                vmctx: vmctx,
158                dst_array: u32,
159                dst_index: u32,
160                src_array: u32,
161                src_index: u32,
162                len: u32
163            ) -> bool;
164
165            // Builtin implementation of the `array.init_data` instruction.
166            #[cfg(feature = "gc")]
167            array_init_data(
168                vmctx: vmctx,
169                array_interned_type_index: u32,
170                array: u32,
171                dst_index: u32,
172                data_index: u32,
173                data_offset: u32,
174                len: u32
175            ) -> bool;
176
177            // Builtin implementation of the `array.init_elem` instruction.
178            #[cfg(feature = "gc")]
179            array_init_elem(
180                vmctx: vmctx,
181                array_interned_type_index: u32,
182                array: u32,
183                dst: u32,
184                elem_index: u32,
185                src: u32,
186                len: u32
187            ) -> bool;
188
189            // Returns whether `actual_engine_type` is a subtype of
190            // `expected_engine_type`.
191            #[cfg(feature = "gc")]
192            is_subtype(
193                vmctx: vmctx,
194                actual_engine_type: u32,
195                expected_engine_type: u32
196            ) -> u32;
197
198            // Returns an index for Wasm's `table.grow` instruction for GC references.
199            #[cfg(feature = "gc")]
200            table_grow_gc_ref(vmctx: vmctx, table: u32, delta: u64, init: u32) -> pointer;
201
202            // Returns an index for Wasm's `table.fill` instruction for GC references.
203            #[cfg(feature = "gc")]
204            table_fill_gc_ref(vmctx: vmctx, table: u32, dst: u64, val: u32, len: u64) -> bool;
205
206            // Wasm floating-point routines for when the CPU instructions aren't available.
207            ceil_f32(vmctx: vmctx, x: f32) -> f32;
208            ceil_f64(vmctx: vmctx, x: f64) -> f64;
209            floor_f32(vmctx: vmctx, x: f32) -> f32;
210            floor_f64(vmctx: vmctx, x: f64) -> f64;
211            trunc_f32(vmctx: vmctx, x: f32) -> f32;
212            trunc_f64(vmctx: vmctx, x: f64) -> f64;
213            nearest_f32(vmctx: vmctx, x: f32) -> f32;
214            nearest_f64(vmctx: vmctx, x: f64) -> f64;
215            i8x16_swizzle(vmctx: vmctx, a: i8x16, b: i8x16) -> i8x16;
216            i8x16_shuffle(vmctx: vmctx, a: i8x16, b: i8x16, c: i8x16) -> i8x16;
217            fma_f32x4(vmctx: vmctx, x: f32x4, y: f32x4, z: f32x4) -> f32x4;
218            fma_f64x2(vmctx: vmctx, x: f64x2, y: f64x2, z: f64x2) -> f64x2;
219
220            // Raises an unconditional trap with the specified code.
221            //
222            // This is used when signals-based-traps are disabled for backends
223            // when an illegal instruction can't be executed for example.
224            trap(vmctx: vmctx, code: u8);
225
226            // Raises an unconditional trap where the trap information must have
227            // been previously filled in.
228            raise(vmctx: vmctx);
229
230            // Creates a new continuation from a funcref.
231            #[cfg(feature = "stack-switching")]
232            cont_new(vmctx: vmctx, r: pointer, param_count: u32, result_count: u32) -> pointer;
233
234            // Returns an index for Wasm's `table.grow` instruction
235            // for `contobj`s.  Note that the initial
236            // Option<VMContObj> (i.e., the value to fill the new
237            // slots with) is split into two arguments: The underlying
238            // continuation reference and the revision count.  To
239            // denote the continuation being `None`, `init_contref`
240            // may be 0.
241            #[cfg(feature = "stack-switching")]
242            table_grow_cont_obj(vmctx: vmctx, table: u32, delta: u64, init_contref: pointer, init_revision: u64) -> pointer;
243
244            // `value_contref` and `value_revision` together encode
245            // the Option<VMContObj>, as in previous libcall.
246            #[cfg(feature = "stack-switching")]
247            table_fill_cont_obj(vmctx: vmctx, table: u32, dst: u64, value_contref: pointer, value_revision: u64, len: u64) -> bool;
248        }
249    };
250}
251
252/// Helper macro to define a builtin type such as `BuiltinFunctionIndex` and
253/// `ComponentBuiltinFunctionIndex` using the iterator macro, e.g.
254/// `foreach_builtin_function`, as the way to generate accessor methods.
255macro_rules! declare_builtin_index {
256    ($index_name:ident, $iter:ident) => {
257        /// An index type for builtin functions.
258        #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
259        pub struct $index_name(u32);
260
261        impl $index_name {
262            /// Create a new builtin from its raw index
263            pub const fn from_u32(i: u32) -> Self {
264                assert!(i < Self::len());
265                Self(i)
266            }
267
268            /// Return the index as an u32 number.
269            pub const fn index(&self) -> u32 {
270                self.0
271            }
272
273            $iter!(declare_builtin_index_constructors);
274        }
275    };
276}
277
278/// Helper macro used by the above macro.
279macro_rules! declare_builtin_index_constructors {
280    (
281        $(
282            $( #[$attr:meta] )*
283            $name:ident( $( $pname:ident: $param:ident ),* ) $( -> $result:ident )?;
284        )*
285    ) => {
286        declare_builtin_index_constructors!(
287            @indices;
288            0;
289            $( $( #[$attr] )* $name; )*
290        );
291
292        /// Returns a symbol name for this builtin.
293        pub fn name(&self) -> &'static str {
294            $(
295                if *self == Self::$name() {
296                    return stringify!($name);
297                }
298            )*
299            unreachable!()
300        }
301    };
302
303    // Base case: no more indices to declare, so define the total number of
304    // function indices.
305    (
306        @indices;
307        $len:expr;
308    ) => {
309        /// Returns the total number of builtin functions.
310        pub const fn len() -> u32 {
311            $len
312        }
313    };
314
315    // Recursive case: declare the next index, and then keep declaring the rest of
316    // the indices.
317    (
318         @indices;
319         $index:expr;
320         $( #[$this_attr:meta] )*
321         $this_name:ident;
322         $(
323             $( #[$rest_attr:meta] )*
324             $rest_name:ident;
325         )*
326    ) => {
327        #[expect(missing_docs, reason = "macro-generated")]
328        pub const fn $this_name() -> Self {
329            Self($index)
330        }
331
332        declare_builtin_index_constructors!(
333            @indices;
334            ($index + 1);
335            $( $( #[$rest_attr] )* $rest_name; )*
336        );
337    }
338}
339
340// Define `struct BuiltinFunctionIndex`
341declare_builtin_index!(BuiltinFunctionIndex, foreach_builtin_function);
342
343/// Return value of [`BuiltinFunctionIndex::trap_sentinel`].
344pub enum TrapSentinel {
345    /// A falsy or zero value indicates a trap.
346    Falsy,
347    /// The value `-2` indicates a trap (used for growth-related builtins).
348    NegativeTwo,
349    /// The value `-1` indicates a trap .
350    NegativeOne,
351    /// Any negative value indicates a trap.
352    Negative,
353}
354
355impl BuiltinFunctionIndex {
356    /// Describes the return value of this builtin and what represents a trap.
357    ///
358    /// Libcalls don't raise traps themselves and instead delegate to compilers
359    /// to do so. This means that some return values of libcalls indicate a trap
360    /// is happening and this is represented with sentinel values. This function
361    /// returns the description of the sentinel value which indicates a trap, if
362    /// any. If `None` is returned from this function then this builtin cannot
363    /// generate a trap.
364    #[allow(unreachable_code, unused_macro_rules, reason = "macro-generated code")]
365    pub fn trap_sentinel(&self) -> Option<TrapSentinel> {
366        macro_rules! trap_sentinel {
367            (
368                $(
369                    $( #[$attr:meta] )*
370                    $name:ident( $( $pname:ident: $param:ident ),* ) $( -> $result:ident )?;
371                )*
372            ) => {{
373                $(
374                    $(#[$attr])*
375                    if *self == BuiltinFunctionIndex::$name() {
376                        let mut _ret = None;
377                        $(_ret = Some(trap_sentinel!(@get $name $result));)?
378                        return _ret;
379                    }
380                )*
381
382                None
383            }};
384
385            // Growth-related functions return -2 as a sentinel.
386            (@get memory32_grow pointer) => (TrapSentinel::NegativeTwo);
387            (@get table_grow_func_ref pointer) => (TrapSentinel::NegativeTwo);
388            (@get table_grow_gc_ref pointer) => (TrapSentinel::NegativeTwo);
389            (@get table_grow_cont_obj pointer) => (TrapSentinel::NegativeTwo);
390
391            // Atomics-related functions return a negative value indicating trap
392            // indicate a trap.
393            (@get memory_atomic_notify u64) => (TrapSentinel::Negative);
394            (@get memory_atomic_wait32 u64) => (TrapSentinel::Negative);
395            (@get memory_atomic_wait64 u64) => (TrapSentinel::Negative);
396
397            // GC returns an optional GC ref, encoded as a `u64` with a negative
398            // value indicating a trap.
399            (@get gc u64) => (TrapSentinel::Negative);
400
401            // GC allocation functions return a u32 which is zero to indicate a
402            // trap.
403            (@get gc_alloc_raw u32) => (TrapSentinel::Falsy);
404            (@get array_new_data u32) => (TrapSentinel::Falsy);
405            (@get array_new_elem u32) => (TrapSentinel::Falsy);
406
407            // The final epoch represents a trap
408            (@get new_epoch u64) => (TrapSentinel::NegativeOne);
409
410            // These libcalls can't trap
411            (@get ref_func pointer) => (return None);
412            (@get table_get_lazy_init_func_ref pointer) => (return None);
413            (@get get_interned_func_ref pointer) => (return None);
414            (@get intern_func_ref_for_gc_heap u64) => (return None);
415            (@get is_subtype u32) => (return None);
416            (@get ceil_f32 f32) => (return None);
417            (@get ceil_f64 f64) => (return None);
418            (@get floor_f32 f32) => (return None);
419            (@get floor_f64 f64) => (return None);
420            (@get trunc_f32 f32) => (return None);
421            (@get trunc_f64 f64) => (return None);
422            (@get nearest_f32 f32) => (return None);
423            (@get nearest_f64 f64) => (return None);
424            (@get i8x16_swizzle i8x16) => (return None);
425            (@get i8x16_shuffle i8x16) => (return None);
426            (@get fma_f32x4 f32x4) => (return None);
427            (@get fma_f64x2 f64x2) => (return None);
428
429            (@get cont_new pointer) => (TrapSentinel::Negative);
430
431            // Bool-returning functions use `false` as an indicator of a trap.
432            (@get $name:ident bool) => (TrapSentinel::Falsy);
433
434            (@get $name:ident $ret:ident) => (
435                compile_error!(concat!("no trap sentinel registered for ", stringify!($name)))
436            )
437        }
438
439        foreach_builtin_function!(trap_sentinel)
440    }
441}