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