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}