Skip to main content

wasmtime/runtime/vm/
vmcontext.rs

1//! This file declares `VMContext` and several related structs which contain
2//! fields that compiled wasm code accesses directly.
3
4mod vm_host_func_context;
5
6pub use self::vm_host_func_context::VMArrayCallHostFuncContext;
7use crate::prelude::*;
8use crate::runtime::vm::{InterpreterRef, VMGcRef, VmPtr, VmSafe, f32x4, f64x2, i8x16};
9use crate::store::StoreOpaque;
10use crate::vm::stack_switching::{VMContinuationStack, VMStackChain, VMStackState};
11use core::cell::UnsafeCell;
12use core::ffi::c_void;
13use core::fmt;
14use core::marker::{self, PhantomPinned};
15use core::mem::{self, ManuallyDrop, MaybeUninit};
16#[cfg(feature = "gc-null")]
17use core::num::NonZeroU32;
18use core::ops::Range;
19use core::ptr::{self, NonNull};
20use core::sync::atomic::{AtomicUsize, Ordering};
21use wasmtime_environ::{
22    BuiltinFunctionIndex, DefinedGlobalIndex, DefinedMemoryIndex, DefinedTableIndex,
23    DefinedTagIndex, NUM_COMPONENT_CONTEXT_SLOTS, VMCONTEXT_MAGIC, VMSharedTypeIndex,
24};
25
26/// A function pointer that exposes the array calling convention.
27///
28/// Regardless of the underlying Wasm function type, all functions using the
29/// array calling convention have the same Rust signature.
30///
31/// Arguments:
32///
33/// * Callee `vmctx` for the function itself.
34///
35/// * Caller's `vmctx` (so that host functions can access the linear memory of
36///   their Wasm callers).
37///
38/// * A pointer to a buffer of `ValRaw`s where both arguments are passed into
39///   this function, and where results are returned from this function.
40///
41/// * The capacity of the `ValRaw` buffer. Must always be at least
42///   `max(len(wasm_params), len(wasm_results))`.
43///
44/// Return value:
45///
46/// * `true` if this call succeeded.
47/// * `false` if this call failed and a trap was recorded in TLS.
48pub type VMArrayCallNative = unsafe extern "C" fn(
49    NonNull<VMOpaqueContext>,
50    NonNull<VMContext>,
51    NonNull<ValRaw>,
52    usize,
53) -> bool;
54
55/// An opaque function pointer which might be `VMArrayCallNative` or it might be
56/// pulley bytecode. Requires external knowledge to determine what kind of
57/// function pointer this is.
58#[repr(transparent)]
59pub struct VMArrayCallFunction(VMFunctionBody);
60
61/// A function pointer that exposes the Wasm calling convention.
62///
63/// In practice, different Wasm function types end up mapping to different Rust
64/// function types, so this isn't simply a type alias the way that
65/// `VMArrayCallFunction` is. However, the exact details of the calling
66/// convention are left to the Wasm compiler (e.g. Cranelift or Winch). Runtime
67/// code never does anything with these function pointers except shuffle them
68/// around and pass them back to Wasm.
69#[repr(transparent)]
70pub struct VMWasmCallFunction(VMFunctionBody);
71
72// SAFETY: `VMFunctionImport` is generated with `#[repr(C)]` and only contains
73// `VmSafe` fields.
74unsafe impl VmSafe for VMFunctionImport {}
75
76impl VMFunctionImport {
77    /// Convert `&VMFunctionImport` into `&VMFuncRef`.
78    pub fn as_func_ref(&self) -> &VMFuncRef {
79        // Safety: `VMFunctionImport` and `VMFuncRef` have the same
80        // representation.
81        unsafe { Self::as_non_null_func_ref(NonNull::from(self)).as_ref() }
82    }
83
84    /// Convert `NonNull<VMFunctionImport>` into `NonNull<VMFuncRef>`.
85    pub fn as_non_null_func_ref(p: NonNull<VMFunctionImport>) -> NonNull<VMFuncRef> {
86        p.cast()
87    }
88
89    /// Convert `*mut VMFunctionImport` into `*mut VMFuncRef`.
90    pub fn as_func_ref_ptr(p: *mut VMFunctionImport) -> *mut VMFuncRef {
91        p.cast()
92    }
93}
94
95#[cfg(test)]
96mod test_vmfunction_import {
97    use super::{VMFuncRef, VMFunctionImport};
98    use core::mem::offset_of;
99    use std::mem::size_of;
100
101    #[test]
102    fn vmfunction_import_and_vmfunc_ref_have_same_layout() {
103        assert_eq!(size_of::<VMFunctionImport>(), size_of::<VMFuncRef>());
104        assert_eq!(
105            offset_of!(VMFunctionImport, array_call),
106            offset_of!(VMFuncRef, array_call),
107        );
108        assert_eq!(
109            offset_of!(VMFunctionImport, wasm_call),
110            offset_of!(VMFuncRef, wasm_call),
111        );
112        assert_eq!(
113            offset_of!(VMFunctionImport, type_index),
114            offset_of!(VMFuncRef, type_index),
115        );
116        assert_eq!(
117            offset_of!(VMFunctionImport, vmctx),
118            offset_of!(VMFuncRef, vmctx),
119        );
120    }
121}
122
123/// A placeholder byte-sized type which is just used to provide some amount of type
124/// safety when dealing with pointers to JIT-compiled function bodies. Note that it's
125/// deliberately not Copy, as we shouldn't be carelessly copying function body bytes
126/// around.
127#[repr(C)]
128pub struct VMFunctionBody(u8);
129
130// SAFETY: this structure is never read and is safe to pass to jit code.
131unsafe impl VmSafe for VMFunctionBody {}
132
133#[cfg(test)]
134mod test_vmfunction_body {
135    use super::VMFunctionBody;
136    use std::mem::size_of;
137
138    #[test]
139    fn check_vmfunction_body_offsets() {
140        assert_eq!(size_of::<VMFunctionBody>(), 1);
141    }
142}
143
144// SAFETY: `VMTableImport` is generated with `#[repr(C)]` and only contains
145// `VmSafe` fields.
146unsafe impl VmSafe for VMTableImport {}
147
148#[cfg(test)]
149mod test_vmtable {
150    use wasmtime_environ::component::{Component, VMComponentOffsets};
151    use wasmtime_environ::{HostPtr, Module, PtrSize, StaticModuleIndex, VMOffsets};
152
153    #[test]
154    fn ensure_sizes_match() {
155        // Because we use `VMTableImport` for recording tables used by components, we
156        // want to make sure that the size calculations between `VMOffsets` and
157        // `VMComponentOffsets` stay the same.
158        let module = Module::new(StaticModuleIndex::from_u32(0));
159        let vm_offsets = VMOffsets::new(HostPtr, &module);
160        let component = Component::default();
161        let vm_component_offsets = VMComponentOffsets::new(HostPtr, &component);
162        assert_eq!(
163            vm_offsets.ptr.vm_table_import().size(),
164            vm_component_offsets.ptr.vm_table_import().size()
165        );
166    }
167}
168
169// SAFETY: `VMMemoryImport` is generated with `#[repr(C)]` and only contains
170// `VmSafe` fields.
171unsafe impl VmSafe for VMMemoryImport {}
172
173// SAFETY: `VMGlobalImport` is generated with `#[repr(C)]` and only contains
174// `VmSafe` fields.
175unsafe impl VmSafe for VMGlobalImport {}
176
177/// The kinds of globals that Wasmtime has.
178#[derive(Debug, Copy, Clone)]
179#[repr(C, u32)]
180pub enum VMGlobalKind {
181    /// Host globals, stored in a `StoreOpaque`.
182    Host(DefinedGlobalIndex),
183    /// Instance globals, stored in `VMContext`s
184    Instance(DefinedGlobalIndex),
185    /// Flags for a component instance, stored in `VMComponentContext`.
186    #[cfg(feature = "component-model")]
187    ComponentFlags(wasmtime_environ::component::RuntimeComponentInstanceIndex),
188}
189
190// SAFETY: the above enum is repr(C) and stores nothing else
191unsafe impl VmSafe for VMGlobalKind {}
192
193// SAFETY: `VMTagImport` is generated with `#[repr(C)]` and only contains
194// `VmSafe` fields.
195unsafe impl VmSafe for VMTagImport {}
196
197/// Define the runtime definitions of the shared `VM*` types.
198#[allow(
199    unused_macro_rules,
200    reason = "the `@test` arms are only expanded inside the `#[cfg(test)]` \
201              layout-test module, and the enum arms go unused whenever no \
202              `VM*` type is an enum"
203)]
204macro_rules! define_vm_types {
205    // Emit the layout test for one `struct` VM type: its size and alignment,
206    // plus each field's offset, checked against the real Rust type.
207    (@test [ $($cfg:tt)* ] $Name:ident $snake:ident [ $($fname:ident)* ]) => {
208        $($cfg)*
209        #[test]
210        fn $snake() {
211            use super::$Name;
212
213            let host = HostPtr;
214            let offsets = host.$snake();
215
216            let expected = usize::from(offsets.size());
217            let actual = size_of::<$Name>();
218            assert_eq!(
219                expected,
220                actual,
221                "size of {} failed: {expected} (expected) != {actual} (actual)",
222                stringify!($Name),
223            );
224
225            let expected = usize::from(offsets.align());
226            let actual = align_of::<$Name>();
227            assert_eq!(
228                expected,
229                actual,
230                "alignment of {} failed: {expected} (expected) != {actual} (actual)",
231                stringify!($Name),
232            );
233
234            $(
235                let expected = usize::from(offsets.$fname());
236                let actual = offset_of!($Name, $fname);
237                assert_eq!(
238                    expected,
239                    actual,
240                    "offset of {}::{} failed: {expected} (expected) != {actual} (actual)",
241                    stringify!($Name),
242                    stringify!($fname),
243                );
244            )*
245        }
246    };
247
248    // Emit the layout test for one `#[repr(C, $tag)]` enum VM type.
249    //
250    // `offset_of!` does not work on enum variants, so instead of measuring a
251    // variant field's offset this checks the generated offsets against the
252    // layout rule `#[repr(C, $tag)]` guarantees, evaluated with each field
253    // type's real `size_of`/`align_of`.
254    (@test_enum [ $($cfg:tt)* ] $Name:ident $snake:ident $tag:ty [
255        $( { $vsnake:ident $Variant:ident [ $( $fname:ident : $fty:ty , )* ] } )*
256    ]) => {
257        $($cfg)*
258        #[test]
259        fn $snake() {
260            use super::$Name;
261
262            let host = HostPtr;
263            let offsets = host.$snake();
264
265            let expected = usize::from(offsets.size());
266            let actual = size_of::<$Name>();
267            assert_eq!(
268                expected,
269                actual,
270                "size of {} failed: {expected} (expected) != {actual} (actual)",
271                stringify!($Name),
272            );
273
274            let expected = usize::from(offsets.align());
275            let actual = align_of::<$Name>();
276            assert_eq!(
277                expected,
278                actual,
279                "alignment of {} failed: {expected} (expected) != {actual} (actual)",
280                stringify!($Name),
281            );
282
283            let expected = usize::from(offsets.tag_size());
284            let actual = size_of::<$tag>();
285            assert_eq!(
286                expected,
287                actual,
288                "tag size of {} failed: {expected} (expected) != {actual} (actual)",
289                stringify!($Name),
290            );
291
292            // The payload of a `#[repr(C, $tag)]` enum starts just past the
293            // tag, rounded up to the enum's alignment.
294            let expected = usize::from(offsets.payload());
295            let actual = align_up(size_of::<$tag>(), align_of::<$Name>());
296            assert_eq!(
297                expected,
298                actual,
299                "payload offset of {} failed: {expected} (expected) != {actual} (actual)",
300                stringify!($Name),
301            );
302
303            $(
304                // A variant with no fields leaves both untouched.
305                #[allow(
306                    unused_assignments,
307                    unused_mut,
308                    unused_variables,
309                    reason = "a variant may have no fields, and the last \
310                              field's size is accumulated but never read"
311                )]
312                {
313                    let variant = offsets.$vsnake();
314                    let mut o = usize::from(offsets.payload());
315                    $(
316                        o = align_up(o, align_of::<$fty>());
317                        let expected = usize::from(variant.$fname());
318                        assert_eq!(
319                            expected,
320                            o,
321                            "offset of {}::{}::{} failed: \
322                             {expected} (expected) != {o} (actual)",
323                            stringify!($Name),
324                            stringify!($Variant),
325                            stringify!($fname),
326                        );
327                        o += size_of::<$fty>();
328                    )*
329                }
330            )*
331        }
332    };
333
334    // Munched one at a time rather than matched as a repetition because a
335    // `struct` and an `enum` do not share a body shape.
336    (@munch { $($defs:tt)* } { $($tests:tt)* }) => {
337        $($defs)*
338
339        #[cfg(test)]
340        #[allow(
341            unused_imports,
342            dead_code,
343            reason = "the glob import and `align_up` are only used by the enum \
344                      tests, and not every `VM*` type is an enum"
345        )]
346        mod test_vm_type_layouts {
347            // The enum tests name variant fields' types, so the module needs
348            // everything the definitions above were written against.
349            use super::*;
350            use core::mem::{align_of, offset_of, size_of};
351            use wasmtime_environ::{HostPtr, PtrSize};
352
353            /// Round `offset` up to a multiple of `align`.
354            fn align_up(offset: usize, align: usize) -> usize {
355                offset.next_multiple_of(align)
356            }
357
358            $($tests)*
359        }
360    };
361
362    (@munch { $($defs:tt)* } { $($tests:tt)* }
363        $(#[doc = $sdoc:literal])*
364        $(#[cfg($($scfg:tt)*)])?
365        $(#[derive($($d:ident),*)])?
366        #[repr(C, $tag:ident)]
367        #[snake_name = $snake:ident]
368        $svis:vis enum $Name:ident {
369            $(
370                $(#[doc = $vdoc:literal])*
371                #[snake_name = $vsnake:ident]
372                $(#[$vattr:meta])*
373                $Variant:ident {
374                    $(
375                        $(#[doc = $fdoc:literal])*
376                        $(#[aggregate])?
377                        $(#[indexed])?
378                        $(#[readonly])?
379                        $(#[can_move])?
380                        $fname:ident : $fty:ty ,
381                    )*
382                } = $disc:literal ,
383            )*
384        }
385        $($rest:tt)*
386    ) => {
387        define_vm_types!(
388            @munch
389            {
390                $($defs)*
391
392                $(#[doc = $sdoc])*
393                $(#[cfg($($scfg)*)])?
394                $(#[derive($($d),*)])?
395                #[repr(C, $tag)]
396                $svis enum $Name {
397                    $(
398                        $(#[doc = $vdoc])*
399                        $(#[$vattr])*
400                        $Variant {
401                            $(
402                                $(#[doc = $fdoc])*
403                                $fname: $fty,
404                            )*
405                        } = $disc,
406                    )*
407                }
408            }
409            {
410                $($tests)*
411
412                define_vm_types!(
413                    @test_enum
414                    [ $(#[cfg($($scfg)*)])? ]
415                    $Name $snake $tag
416                    [ $( { $vsnake $Variant [ $( $fname : $fty , )* ] } )* ]
417                );
418            }
419            $($rest)*
420        );
421    };
422
423    (@munch { $($defs:tt)* } { $($tests:tt)* }
424        $(#[doc = $sdoc:literal])*
425        $(#[cfg($($scfg:tt)*)])?
426        $(#[derive($($d:ident),*)])?
427        #[repr($($repr:tt)*)]
428        #[snake_name = $snake:ident]
429        $svis:vis struct $Name:ident {
430            $(
431                $(#[doc = $fdoc:literal])*
432                $(#[aggregate])?
433                $(#[indexed])?
434                $(#[readonly])?
435                $(#[can_move])?
436                // Unlike the offsets and alias-region consumers, this one only
437                // ever re-emits a field's type verbatim, so it can capture the
438                // whole type as one fragment instead of taking it apart.
439                $fvis:vis $fname:ident : $fty:ty ,
440            )*
441        }
442        $($rest:tt)*
443    ) => {
444        define_vm_types!(
445            @munch
446            {
447                $($defs)*
448
449                $(#[doc = $sdoc])*
450                $(#[cfg($($scfg)*)])?
451                $(#[derive($($d),*)])?
452                #[repr($($repr)*)]
453                $svis struct $Name {
454                    $(
455                        $(#[doc = $fdoc])*
456                        $fvis $fname: $fty,
457                    )*
458                }
459            }
460            {
461                $($tests)*
462
463                define_vm_types!(
464                    @test
465                    [ $(#[cfg($($scfg)*)])? ]
466                    $Name $snake
467                    [ $($fname)* ]
468                );
469            }
470            $($rest)*
471        );
472    };
473
474    ( $($defs:tt)* ) => {
475        define_vm_types!(@munch {} {} $($defs)*);
476    };
477}
478wasmtime_environ::for_each_vm_type!(define_vm_types);
479
480// SAFETY: `VMMemoryDefinition` is generated with `#[repr(C)]` and each field
481// individually implements `VmSafe`, which satisfies the requirements of this
482// trait.
483unsafe impl VmSafe for VMMemoryDefinition {}
484
485impl VMMemoryDefinition {
486    /// Return the current length (in bytes) of the [`VMMemoryDefinition`] by
487    /// performing a relaxed load; do not use this function for situations in
488    /// which a precise length is needed. Owned memories (i.e., non-shared) will
489    /// always return a precise result (since no concurrent modification is
490    /// possible) but shared memories may see an imprecise value--a
491    /// `current_length` potentially smaller than what some other thread
492    /// observes. Since Wasm memory only grows, this under-estimation may be
493    /// acceptable in certain cases.
494    #[inline]
495    pub fn current_length(&self) -> usize {
496        self.current_length.load(Ordering::Relaxed)
497    }
498
499    /// Return a copy of the [`VMMemoryDefinition`] using the relaxed value of
500    /// `current_length`; see [`VMMemoryDefinition::current_length()`].
501    #[inline]
502    pub unsafe fn load(ptr: *mut Self) -> Self {
503        let other = unsafe { &*ptr };
504        VMMemoryDefinition {
505            base: other.base,
506            current_length: other.current_length().into(),
507        }
508    }
509}
510
511// SAFETY: `VMTableDefinition` is generated with `#[repr(C)]` and only contains
512// `VmSafe` fields.
513unsafe impl VmSafe for VMTableDefinition {}
514
515// SAFETY: `VMGlobalDefinition` is `#[repr(C)]` and only contains `VmSafe`
516// fields.
517unsafe impl VmSafe for VMGlobalDefinition {}
518
519#[cfg(test)]
520mod test_vmglobal_definition {
521    use super::VMGlobalDefinition;
522    use std::mem::{align_of, size_of};
523    use wasmtime_environ::{HostPtr, Module, PtrSize, StaticModuleIndex, VMOffsets};
524
525    #[test]
526    fn check_vmglobal_definition_size() {
527        // The compiler lays out globals using this size; see
528        // `vmctx_field_size!` in `wasmtime-environ`.
529        assert_eq!(size_of::<VMGlobalDefinition>(), 16);
530        assert_eq!(
531            size_of::<VMGlobalDefinition>(),
532            usize::from(HostPtr.maximum_value_size())
533        );
534    }
535
536    #[test]
537    fn check_vmglobal_definition_alignment() {
538        assert_eq!(align_of::<VMGlobalDefinition>(), 16);
539        assert!(align_of::<VMGlobalDefinition>() >= align_of::<i32>());
540        assert!(align_of::<VMGlobalDefinition>() >= align_of::<i64>());
541        assert!(align_of::<VMGlobalDefinition>() >= align_of::<f32>());
542        assert!(align_of::<VMGlobalDefinition>() >= align_of::<f64>());
543        assert!(align_of::<VMGlobalDefinition>() >= align_of::<[u8; 16]>());
544        assert!(align_of::<VMGlobalDefinition>() >= align_of::<[f32; 4]>());
545        assert!(align_of::<VMGlobalDefinition>() >= align_of::<[f64; 2]>());
546    }
547
548    #[test]
549    fn check_vmglobal_begins_aligned() {
550        let module = Module::new(StaticModuleIndex::from_u32(0));
551        let offsets = VMOffsets::new(HostPtr, &module);
552        assert_eq!(offsets.globals().begin() % 16, 0);
553    }
554
555    #[test]
556    #[cfg(feature = "gc")]
557    fn check_vmglobal_can_contain_gc_ref() {
558        assert!(size_of::<crate::runtime::vm::VMGcRef>() <= size_of::<VMGlobalDefinition>());
559    }
560}
561
562/// The storage for a WebAssembly global defined within the instance.
563///
564/// Compiled code reads and writes this storage directly, as the field that
565/// matches the global's type. Scalars are stored in native-endian order, except
566/// `v128`, which is little-endian.
567///
568/// TODO: Pack the globals more densely, rather than using the same size for
569/// every type.
570#[repr(C, align(16))]
571pub union VMGlobalDefinition {
572    // These values are all stored in native-endian
573    i32: i32,
574    i64: i64,
575    f32: u32,
576    f64: u64,
577    gc_ref: ManuallyDrop<Option<VMGcRef>>,
578    func_ref: Option<VmPtr<VMFuncRef>>,
579    // This is stored in little-endian
580    v128: [u8; 16],
581}
582
583impl VMGlobalDefinition {
584    /// Construct a `VMGlobalDefinition`.
585    pub fn new() -> Self {
586        Self { v128: [0; 16] }
587    }
588
589    /// Returns the value of this `i32` global.
590    ///
591    /// # Safety
592    ///
593    /// This function requires that the type of this global is `i32`.
594    pub unsafe fn get_i32(&self) -> i32 {
595        unsafe { self.i32 }
596    }
597
598    /// Sets the value of this `i32` global.
599    ///
600    /// # Safety
601    ///
602    /// This function requires that the type of this global is `i32`.
603    pub unsafe fn set_i32(&mut self, val: i32) {
604        self.i32 = val;
605    }
606
607    /// Returns the value of this `i64` global.
608    ///
609    /// # Safety
610    ///
611    /// This function requires that the type of this global is `i64`.
612    pub unsafe fn get_i64(&self) -> i64 {
613        unsafe { self.i64 }
614    }
615
616    /// Sets the value of this `i64` global.
617    ///
618    /// # Safety
619    ///
620    /// This function requires that the type of this global is `i64`.
621    pub unsafe fn set_i64(&mut self, val: i64) {
622        self.i64 = val;
623    }
624
625    /// Returns the bits of this `f32` global.
626    ///
627    /// # Safety
628    ///
629    /// This function requires that the type of this global is `f32`.
630    pub unsafe fn get_f32_bits(&self) -> u32 {
631        unsafe { self.f32 }
632    }
633
634    /// Sets the bits of this `f32` global.
635    ///
636    /// # Safety
637    ///
638    /// This function requires that the type of this global is `f32`.
639    pub unsafe fn set_f32_bits(&mut self, bits: u32) {
640        self.f32 = bits;
641    }
642
643    /// Returns the bits of this `f64` global.
644    ///
645    /// # Safety
646    ///
647    /// This function requires that the type of this global is `f64`.
648    pub unsafe fn get_f64_bits(&self) -> u64 {
649        unsafe { self.f64 }
650    }
651
652    /// Sets the bits of this `f64` global.
653    ///
654    /// # Safety
655    ///
656    /// This function requires that the type of this global is `f64`.
657    pub unsafe fn set_f64_bits(&mut self, bits: u64) {
658        self.f64 = bits;
659    }
660
661    /// Returns the value of this `v128` global.
662    ///
663    /// # Safety
664    ///
665    /// This function requires that the type of this global is `v128`.
666    pub unsafe fn get_u128(&self) -> u128 {
667        u128::from_le_bytes(unsafe { self.v128 })
668    }
669
670    /// Sets the value of this `v128` global.
671    ///
672    /// # Safety
673    ///
674    /// This function requires that the type of this global is `v128`.
675    pub unsafe fn set_u128(&mut self, val: u128) {
676        self.v128 = val.to_le_bytes();
677    }
678
679    /// Returns the value of this GC reference global.
680    ///
681    /// # Safety
682    ///
683    /// This function requires that the type of this global is a GC reference,
684    /// for example `extrenref`, `anyref`, `exnref`, etc.
685    pub unsafe fn as_gc_ref(&self) -> Option<&VMGcRef> {
686        let ret = unsafe { (*self.gc_ref).as_ref() };
687        assert!(cfg!(feature = "gc") || ret.is_none());
688        ret
689    }
690
691    /// Returns the value of this GC reference global, mutably.
692    ///
693    /// # Safety
694    ///
695    /// This function requires that the type of this global is a GC reference,
696    /// for example `extrenref`, `anyref`, `exnref`, etc.
697    pub unsafe fn as_gc_ref_mut(&mut self) -> Option<&mut VMGcRef> {
698        let ret = unsafe { (*self.gc_ref).as_mut() };
699        assert!(cfg!(feature = "gc") || ret.is_none());
700        ret
701    }
702
703    /// Initialize this GC reference global to the given GC reference.
704    ///
705    /// # Safety
706    ///
707    /// This function requires that the type of this global is a GC reference,
708    /// for example `extrenref`, `anyref`, `exnref`, etc.
709    pub unsafe fn init_gc_ref(
710        &mut self,
711        store: &mut StoreOpaque,
712        gc_ref: Option<&VMGcRef>,
713    ) -> Result<()> {
714        // SAFETY: `MaybeUninit<T>` has the same layout as `T`, and this global
715        // is uninitialized, so it must not be read as a `VMGcRef`.
716        let dest = unsafe { &mut *(&raw mut self.gc_ref).cast::<MaybeUninit<Option<VMGcRef>>>() };
717        store.init_gc_ref(dest, gc_ref)
718    }
719
720    /// Write a GC reference into this GC reference global.
721    pub unsafe fn write_gc_ref(
722        &mut self,
723        store: &mut StoreOpaque,
724        gc_ref: Option<&VMGcRef>,
725    ) -> Result<()> {
726        let dest = unsafe { &mut *self.gc_ref };
727        store.write_gc_ref(dest, gc_ref)
728    }
729
730    /// Returns the value of this funcref global.
731    ///
732    /// # Safety
733    ///
734    /// This function requires that the type of this global is a `funcref` or
735    /// a concrete function type.
736    pub unsafe fn get_func_ref(&self) -> Option<NonNull<VMFuncRef>> {
737        unsafe { self.func_ref.map(|p| p.as_non_null()) }
738    }
739
740    /// Sets the value of this funcref global.
741    ///
742    /// # Safety
743    ///
744    /// This function requires that the type of this global is a `funcref` or
745    /// a concrete function type.
746    pub unsafe fn set_func_ref(&mut self, func_ref: Option<NonNull<VMFuncRef>>) {
747        self.func_ref = func_ref.map(VmPtr::from);
748    }
749}
750
751#[cfg(test)]
752mod test_vmshared_type_index {
753    use super::VMSharedTypeIndex;
754    use std::mem::size_of;
755    use wasmtime_environ::{HostPtr, Module, StaticModuleIndex, VMOffsets};
756
757    #[test]
758    fn check_vmshared_type_index() {
759        let module = Module::new(StaticModuleIndex::from_u32(0));
760        let offsets = VMOffsets::new(HostPtr, &module);
761        assert_eq!(
762            size_of::<VMSharedTypeIndex>(),
763            usize::from(offsets.size_of_vmshared_type_index())
764        );
765    }
766}
767
768impl VMTagDefinition {
769    pub fn new(type_index: VMSharedTypeIndex) -> Self {
770        Self { type_index }
771    }
772}
773
774// SAFETY: `VMTagDefinition` is generated with `#[repr(C)]` and only contains
775// `VmSafe` fields.
776unsafe impl VmSafe for VMTagDefinition {}
777
778#[cfg(test)]
779mod test_vmtag_definition {
780    use wasmtime_environ::{HostPtr, Module, StaticModuleIndex, VMOffsets};
781
782    #[test]
783    fn check_vmtag_begins_aligned() {
784        let module = Module::new(StaticModuleIndex::from_u32(0));
785        let offsets = VMOffsets::new(HostPtr, &module);
786        assert_eq!(offsets.tags().begin() % 16, 0);
787    }
788}
789
790// SAFETY: `VMFuncRef` is generated with `#[repr(C)]` and only contains
791// `VmSafe` fields.
792unsafe impl VmSafe for VMFuncRef {}
793
794impl VMFuncRef {
795    /// Invokes the `array_call` field of this `VMFuncRef` with the supplied
796    /// arguments.
797    ///
798    /// This will invoke the function pointer in the `array_call` field with:
799    ///
800    /// * the `callee` vmctx as `self.vmctx`
801    /// * the `caller` as `caller` specified here
802    /// * the args pointer as `args_and_results`
803    /// * the args length as `args_and_results`
804    ///
805    /// The `args_and_results` area must be large enough to both load all
806    /// arguments from and store all results to.
807    ///
808    /// Returns whether a trap was recorded in TLS for raising.
809    ///
810    /// # Unsafety
811    ///
812    /// This method is unsafe because it can be called with any pointers. They
813    /// must all be valid for this wasm function call to proceed. For example
814    /// the `caller` must be valid machine code if `pulley` is `None` or it must
815    /// be valid bytecode if `pulley` is `Some`. Additionally `args_and_results`
816    /// must be large enough to handle all the arguments/results for this call.
817    ///
818    /// Note that the unsafety invariants to maintain here are not currently
819    /// exhaustively documented.
820    #[inline]
821    pub unsafe fn array_call(
822        me: NonNull<VMFuncRef>,
823        pulley: Option<InterpreterRef<'_>>,
824        caller: NonNull<VMContext>,
825        args_and_results: NonNull<[ValRaw]>,
826    ) -> bool {
827        match pulley {
828            Some(vm) => unsafe { Self::array_call_interpreted(me, vm, caller, args_and_results) },
829            None => unsafe { Self::array_call_native(me, caller, args_and_results) },
830        }
831    }
832
833    unsafe fn array_call_interpreted(
834        me: NonNull<VMFuncRef>,
835        vm: InterpreterRef<'_>,
836        caller: NonNull<VMContext>,
837        args_and_results: NonNull<[ValRaw]>,
838    ) -> bool {
839        // If `caller` is actually a `VMArrayCallHostFuncContext` then skip the
840        // interpreter, even though it's available, as `array_call` will be
841        // native code.
842        unsafe {
843            if me.as_ref().vmctx.as_non_null().as_ref().magic
844                == wasmtime_environ::VM_ARRAY_CALL_HOST_FUNC_MAGIC
845            {
846                return Self::array_call_native(me, caller, args_and_results);
847            }
848            vm.call(
849                me.as_ref().array_call.as_non_null().cast(),
850                me.as_ref().vmctx.as_non_null(),
851                caller,
852                args_and_results,
853            )
854        }
855    }
856
857    #[inline]
858    unsafe fn array_call_native(
859        me: NonNull<VMFuncRef>,
860        caller: NonNull<VMContext>,
861        args_and_results: NonNull<[ValRaw]>,
862    ) -> bool {
863        unsafe {
864            union GetNativePointer {
865                native: VMArrayCallNative,
866                ptr: NonNull<VMArrayCallFunction>,
867            }
868            let native = GetNativePointer {
869                ptr: me.as_ref().array_call.as_non_null(),
870            }
871            .native;
872            native(
873                me.as_ref().vmctx.as_non_null(),
874                caller,
875                args_and_results.cast(),
876                args_and_results.len(),
877            )
878        }
879    }
880
881    pub(crate) fn as_vm_function_import(&self) -> Option<&VMFunctionImport> {
882        if self.wasm_call.is_some() {
883            // Safety: `VMFuncRef` and `VMFunctionImport` have the same layout
884            // and `wasm_call` is non-null.
885            Some(unsafe { NonNull::from(self).cast::<VMFunctionImport>().as_ref() })
886        } else {
887            None
888        }
889    }
890}
891
892macro_rules! define_builtin_array {
893    (
894        $(
895            $( #[$attr:meta] )*
896            $name:ident( $( $pname:ident: $param:ident ),* ) $( -> $result:ident )?;
897        )*
898    ) => {
899        /// An array that stores addresses of builtin functions. We translate code
900        /// to use indirect calls. This way, we don't have to patch the code.
901        #[repr(C)]
902        #[allow(improper_ctypes_definitions, reason = "__m128i known not FFI-safe")]
903        pub struct VMBuiltinFunctionsArray {
904            $(
905                $name: unsafe extern "C" fn(
906                    $(define_builtin_array!(@ty $param)),*
907                ) $( -> define_builtin_array!(@ty $result))?,
908            )*
909        }
910
911        impl VMBuiltinFunctionsArray {
912            pub const INIT: VMBuiltinFunctionsArray = VMBuiltinFunctionsArray {
913                $(
914                    $name: crate::runtime::vm::libcalls::raw::$name,
915                )*
916            };
917
918            /// Helper to call `expose_provenance()` on all contained pointers.
919            ///
920            /// This is required to be called at least once before entering wasm
921            /// to inform the compiler that these function pointers may all be
922            /// loaded/stored and used on the "other end" to reacquire
923            /// provenance in Pulley. Pulley models hostcalls with a host
924            /// pointer as the first parameter that's a function pointer under
925            /// the hood, and this call ensures that the use of the function
926            /// pointer is considered valid.
927            pub fn expose_provenance(&self) -> NonNull<Self>{
928                $(
929                    (self.$name as *mut u8).expose_provenance();
930                )*
931                NonNull::from(self)
932            }
933        }
934    };
935
936    (@ty u32) => (u32);
937    (@ty u64) => (u64);
938    (@ty f32) => (f32);
939    (@ty f64) => (f64);
940    (@ty u8) => (u8);
941    (@ty i8x16) => (i8x16);
942    (@ty f32x4) => (f32x4);
943    (@ty f64x2) => (f64x2);
944    (@ty bool) => (bool);
945    (@ty pointer) => (*mut u8);
946    (@ty size) => (usize);
947    (@ty vmctx) => (NonNull<VMContext>);
948}
949
950// SAFETY: the above structure is repr(C) and only contains `VmSafe` fields.
951unsafe impl VmSafe for VMBuiltinFunctionsArray {}
952
953wasmtime_environ::foreach_builtin_function!(define_builtin_array);
954
955const _: () = {
956    assert!(
957        mem::size_of::<VMBuiltinFunctionsArray>()
958            == mem::size_of::<usize>() * (BuiltinFunctionIndex::len() as usize)
959    )
960};
961
962impl VMStoreContext {
963    /// From the current saved trampoline FP, get the FP of the last
964    /// Wasm frame. If the current saved trampoline FP is null, return
965    /// null.
966    ///
967    /// We store only the trampoline FP, because (i) we need the
968    /// trampoline FP, so we know the size (bottom) of the last Wasm
969    /// frame; and (ii) the last Wasm frame, just above the trampoline
970    /// frame, can be recovered via the FP chain.
971    ///
972    /// # Safety
973    ///
974    /// This function requires that the `last_wasm_exit_trampoline_fp`
975    /// field either points to an active trampoline frame or is a null
976    /// pointer.
977    pub(crate) unsafe fn last_wasm_exit_fp(&self) -> usize {
978        // SAFETY: the unsafe cell is safe to load (no other threads
979        // will be writing our store when we have control), and the
980        // helper function's safety condition is the same as ours.
981        unsafe {
982            let trampoline_fp = *self.last_wasm_exit_trampoline_fp.get();
983            Self::wasm_exit_fp_from_trampoline_fp(trampoline_fp)
984        }
985    }
986
987    /// From any saved trampoline FP, get the FP of the last Wasm
988    /// frame. If the given trampoline FP is null, return null.
989    ///
990    /// This differs from `last_wasm_exit_fp()` above in that it
991    /// allows accessing activations further up the stack as well,
992    /// e.g. via `CallThreadState::old_state`.
993    ///
994    /// # Safety
995    ///
996    /// This function requires that the provided FP value is valid,
997    /// and points to an active trampoline frame, or is null.
998    ///
999    /// This function depends on the invariant that on all supported
1000    /// architectures, we store the previous FP value under the
1001    /// current FP. This is a property of our ABI that we control and
1002    /// ensure.
1003    pub(crate) unsafe fn wasm_exit_fp_from_trampoline_fp(trampoline_fp: usize) -> usize {
1004        if trampoline_fp != 0 {
1005            // SAFETY: We require that trampoline_fp points to a valid
1006            // frame, which will (by definition) contain an old FP value
1007            // that we can load.
1008            unsafe { *(trampoline_fp as *const usize) }
1009        } else {
1010            0
1011        }
1012    }
1013
1014    #[cfg(feature = "component-model-async")]
1015    pub(crate) fn component_context_mut(&mut self) -> &mut [u32; NUM_COMPONENT_CONTEXT_SLOTS] {
1016        self.component_context.get_mut()
1017    }
1018}
1019
1020// The `VMStoreContext` type is a pod-type with no destructor, and we don't
1021// access any fields from other threads, so add in these trait impls which are
1022// otherwise not available due to the `fuel_consumed` and `epoch_deadline`
1023// variables in `VMStoreContext`.
1024unsafe impl Send for VMStoreContext {}
1025unsafe impl Sync for VMStoreContext {}
1026
1027// SAFETY: the above structure is repr(C) and only contains `VmSafe` fields.
1028unsafe impl VmSafe for VMStoreContext {}
1029
1030impl Default for VMStoreContext {
1031    fn default() -> VMStoreContext {
1032        VMStoreContext {
1033            fuel_consumed: UnsafeCell::new(0),
1034            epoch_deadline: UnsafeCell::new(0),
1035            stack_limit: UnsafeCell::new(usize::MAX),
1036            gc_heap: UnsafeCell::new(VMMemoryDefinition {
1037                base: NonNull::dangling().into(),
1038                current_length: AtomicUsize::new(0),
1039            }),
1040            last_wasm_exit_trampoline_fp: UnsafeCell::new(0),
1041            last_wasm_exit_pc: UnsafeCell::new(0),
1042            last_wasm_entry_fp: UnsafeCell::new(0),
1043            last_wasm_entry_sp: UnsafeCell::new(0),
1044            last_wasm_entry_trap_handler: UnsafeCell::new(0),
1045            stack_chain: UnsafeCell::new(VMStackChain::Absent),
1046            async_guard_range: ptr::null_mut()..ptr::null_mut(),
1047            store_data: VmPtr::dangling(),
1048            component_context: UnsafeCell::new([0; NUM_COMPONENT_CONTEXT_SLOTS]),
1049            current_thread: UnsafeCell::new(VMLazyThread::none()),
1050            lazy_lenders: VmPtr::dangling(),
1051            lazy_lenders_len: UnsafeCell::new(0),
1052        }
1053    }
1054}
1055
1056#[cfg(test)]
1057mod test_vmstore_context {
1058    use super::{VMMemoryDefinition, VMStoreContext};
1059    use core::mem::offset_of;
1060    use wasmtime_environ::{HostPtr, Module, PtrSize, StaticModuleIndex, VMOffsets};
1061
1062    /// Check the `VMStoreContext` offsets that `for_each_vm_type!` does *not*
1063    /// generate: the offsets reaching into the inlined `gc_heap`.
1064    ///
1065    /// Every field offset, plus the size and alignment of the type, is already
1066    /// checked by the generated `test_vm_type_layouts::vm_store_context`.
1067    #[test]
1068    fn derived_field_offsets() {
1069        let module = Module::new(StaticModuleIndex::from_u32(0));
1070        let offsets = VMOffsets::new(HostPtr, &module);
1071        assert_eq!(
1072            offset_of!(VMStoreContext, gc_heap) + offset_of!(VMMemoryDefinition, base),
1073            usize::from(offsets.ptr.vm_store_context().gc_heap_base())
1074        );
1075        assert_eq!(
1076            offset_of!(VMStoreContext, gc_heap) + offset_of!(VMMemoryDefinition, current_length),
1077            usize::from(offsets.ptr.vm_store_context().gc_heap_current_length())
1078        );
1079    }
1080}
1081
1082#[cfg(test)]
1083mod test_vm_cont_ref {
1084    use wasmtime_environ::PtrSize;
1085
1086    /// Check the one `VMContRef` property that `for_each_vm_type!` does *not*
1087    /// generate an assertion for: that `revision` lands at an eight-aligned
1088    /// offset for every target pointer width, not just the host's.
1089    ///
1090    /// Some 32-bit platforms need it to be 8-byte aligned and some don't, so we
1091    /// make sure that it always is, without padding to get there.
1092    ///
1093    /// Every field offset, plus the size and alignment of the type, is already
1094    /// checked by the generated `test_vm_type_layouts::vm_cont_ref`.
1095    #[test]
1096    fn revision_is_eight_aligned() {
1097        assert_eq!(4u8.vm_cont_ref().revision() % 8, 0);
1098        assert_eq!(8u8.vm_cont_ref().revision() % 8, 0);
1099    }
1100}
1101
1102impl VMLazyThread {
1103    const _ASSERT_SIZE: () = assert!(
1104        core::mem::size_of::<VMLazyThread>() == core::mem::size_of::<*mut VMDeferredThread>()
1105    );
1106    const _ASSERT_ALIGN: () = assert!(
1107        core::mem::align_of::<VMLazyThread>() == core::mem::align_of::<*mut VMDeferredThread>()
1108    );
1109
1110    const FORCED: VmPtr<VMDeferredThread> = VmPtr::<u8>::dangling().cast();
1111
1112    /// There is no current thread.
1113    pub const fn none() -> Self {
1114        Self { thread: None }
1115    }
1116
1117    /// A lazy thread that has already been promoted.
1118    pub const fn forced() -> Self {
1119        Self {
1120            thread: Some(Self::FORCED),
1121        }
1122    }
1123
1124    /// A deferred thread referencing the given on-stack [`VMDeferredThread`].
1125    pub fn deferred(ptr: NonNull<VMDeferredThread>) -> Self {
1126        debug_assert_eq!(ptr.addr().get() & Self::FORCED.addr().get(), 0);
1127        Self {
1128            thread: Some(ptr.into()),
1129        }
1130    }
1131
1132    /// Returns `true` if there is no current thread.
1133    pub fn is_none(self) -> bool {
1134        self.thread.is_none()
1135    }
1136
1137    /// Returns `true` if a deferred thread has been forced/promoted.
1138    pub fn is_forced(self) -> bool {
1139        self.thread.is_some_and(|p| p == Self::FORCED)
1140    }
1141
1142    /// Returns `true` if this is a deferred thread (i.e. neither `None` nor
1143    /// forced).
1144    pub fn is_deferred(self) -> bool {
1145        self.thread.is_some_and(|p| p != Self::FORCED)
1146    }
1147
1148    /// Returns the deferred [`VMDeferredThread`] pointer if this is a deferred
1149    /// thread.
1150    pub fn as_deferred(self) -> Option<VmPtr<VMDeferredThread>> {
1151        self.thread
1152            .and_then(|p| if p == Self::FORCED { None } else { Some(p) })
1153    }
1154}
1155
1156#[cfg(test)]
1157mod test_vmlazy_thread {
1158    use super::*;
1159
1160    #[test]
1161    fn vmlazy_thread_forced() {
1162        assert_eq!(
1163            VMLazyThread::forced().thread.unwrap().addr().get(),
1164            usize::try_from(wasmtime_environ::VM_LAZY_THREAD_FORCED).unwrap()
1165        );
1166    }
1167}
1168
1169/// The VM "context", which is pointed to by the `vmctx` arg in Cranelift.
1170/// This has information about globals, memories, tables, and other runtime
1171/// state associated with the current instance.
1172///
1173/// The struct here is empty, as the sizes of these fields are dynamic, and
1174/// we can't describe them in Rust's type system. Sufficient memory is
1175/// allocated at runtime.
1176#[derive(Debug)]
1177#[repr(C, align(16))] // align 16 since globals are aligned to that and contained inside
1178pub struct VMContext {
1179    _magic: u32,
1180}
1181
1182impl VMContext {
1183    /// Helper function to cast between context types using a debug assertion to
1184    /// protect against some mistakes.
1185    #[inline]
1186    pub unsafe fn from_opaque(opaque: NonNull<VMOpaqueContext>) -> NonNull<VMContext> {
1187        // Note that in general the offset of the "magic" field is stored in
1188        // `VMContext::magic`. Given though that this is a sanity check
1189        // about converting this pointer to another type we ideally don't want
1190        // to read the offset from potentially corrupt memory. Instead it would
1191        // be better to catch errors here as soon as possible.
1192        //
1193        // To accomplish this the `VMContext` structure is laid out with the
1194        // magic field at a statically known offset (here it's 0 for now). This
1195        // static offset is asserted in `VMOffsets::from` and needs to be kept
1196        // in sync with this line for this debug assertion to work.
1197        //
1198        // Also note that this magic is only ever invalid in the presence of
1199        // bugs, meaning we don't actually read the magic and act differently
1200        // at runtime depending what it is, so this is a debug assertion as
1201        // opposed to a regular assertion.
1202        unsafe {
1203            debug_assert_eq!(opaque.as_ref().magic, VMCONTEXT_MAGIC);
1204        }
1205        opaque.cast()
1206    }
1207}
1208
1209/// A "raw" and unsafe representation of a WebAssembly value.
1210///
1211/// This is provided for use with the `Func::new_unchecked` and
1212/// `Func::call_unchecked` APIs. In general it's unlikely you should be using
1213/// this from Rust, rather using APIs like `Func::wrap` and `TypedFunc::call`.
1214///
1215/// This is notably an "unsafe" way to work with `Val` and it's recommended to
1216/// instead use `Val` where possible. An important note about this union is that
1217/// fields are all stored in little-endian format, regardless of the endianness
1218/// of the host system.
1219#[repr(C)]
1220#[derive(Copy, Clone)]
1221pub union ValRaw {
1222    /// A WebAssembly `i32` value.
1223    ///
1224    /// Note that the payload here is a Rust `i32` but the WebAssembly `i32`
1225    /// type does not assign an interpretation of the upper bit as either signed
1226    /// or unsigned. The Rust type `i32` is simply chosen for convenience.
1227    ///
1228    /// This value is always stored in a little-endian format.
1229    i32: i32,
1230
1231    /// A WebAssembly `i64` value.
1232    ///
1233    /// Note that the payload here is a Rust `i64` but the WebAssembly `i64`
1234    /// type does not assign an interpretation of the upper bit as either signed
1235    /// or unsigned. The Rust type `i64` is simply chosen for convenience.
1236    ///
1237    /// This value is always stored in a little-endian format.
1238    i64: i64,
1239
1240    /// A WebAssembly `f32` value.
1241    ///
1242    /// Note that the payload here is a Rust `u32`. This is to allow passing any
1243    /// representation of NaN into WebAssembly without risk of changing NaN
1244    /// payload bits as its gets passed around the system. Otherwise though this
1245    /// `u32` value is the return value of `f32::to_bits` in Rust.
1246    ///
1247    /// This value is always stored in a little-endian format.
1248    f32: u32,
1249
1250    /// A WebAssembly `f64` value.
1251    ///
1252    /// Note that the payload here is a Rust `u64`. This is to allow passing any
1253    /// representation of NaN into WebAssembly without risk of changing NaN
1254    /// payload bits as its gets passed around the system. Otherwise though this
1255    /// `u64` value is the return value of `f64::to_bits` in Rust.
1256    ///
1257    /// This value is always stored in a little-endian format.
1258    f64: u64,
1259
1260    /// A WebAssembly `v128` value.
1261    ///
1262    /// The payload here is a Rust `[u8; 16]` which has the same number of bits
1263    /// but note that `v128` in WebAssembly is often considered a vector type
1264    /// such as `i32x4` or `f64x2`. This means that the actual interpretation
1265    /// of the underlying bits is left up to the instructions which consume
1266    /// this value.
1267    ///
1268    /// This value is always stored in a little-endian format.
1269    v128: [u8; 16],
1270
1271    /// A WebAssembly `funcref` value (or one of its subtypes).
1272    ///
1273    /// The payload here is a pointer which is runtime-defined. This is one of
1274    /// the main points of unsafety about the `ValRaw` type as the validity of
1275    /// the pointer here is not easily verified and must be preserved by
1276    /// carefully calling the correct functions throughout the runtime.
1277    ///
1278    /// This value is always stored in a little-endian format.
1279    funcref: *mut c_void,
1280
1281    /// A WebAssembly `externref` value (or one of its subtypes).
1282    ///
1283    /// The payload here is a compressed pointer value which is
1284    /// runtime-defined. This is one of the main points of unsafety about the
1285    /// `ValRaw` type as the validity of the pointer here is not easily verified
1286    /// and must be preserved by carefully calling the correct functions
1287    /// throughout the runtime.
1288    ///
1289    /// This value is always stored in a little-endian format.
1290    externref: u32,
1291
1292    /// A WebAssembly `anyref` value (or one of its subtypes).
1293    ///
1294    /// The payload here is a compressed pointer value which is
1295    /// runtime-defined. This is one of the main points of unsafety about the
1296    /// `ValRaw` type as the validity of the pointer here is not easily verified
1297    /// and must be preserved by carefully calling the correct functions
1298    /// throughout the runtime.
1299    ///
1300    /// This value is always stored in a little-endian format.
1301    anyref: u32,
1302
1303    /// A WebAssembly `exnref` value (or one of its subtypes).
1304    ///
1305    /// The payload here is a compressed pointer value which is
1306    /// runtime-defined. This is one of the main points of unsafety about the
1307    /// `ValRaw` type as the validity of the pointer here is not easily verified
1308    /// and must be preserved by carefully calling the correct functions
1309    /// throughout the runtime.
1310    ///
1311    /// This value is always stored in a little-endian format.
1312    exnref: u32,
1313}
1314
1315// The `ValRaw` type is matched as `wasmtime_val_raw_t` in the C API so these
1316// are some simple assertions about the shape of the type which are additionally
1317// matched in C.
1318const _: () = {
1319    assert!(mem::size_of::<ValRaw>() == 16);
1320    assert!(mem::align_of::<ValRaw>() == mem::align_of::<u64>());
1321};
1322
1323// This type is just a bag-of-bits so it's up to the caller to figure out how
1324// to safely deal with threading concerns and safely access interior bits.
1325unsafe impl Send for ValRaw {}
1326unsafe impl Sync for ValRaw {}
1327
1328impl fmt::Debug for ValRaw {
1329    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1330        struct Hex<T>(T);
1331        impl<T: fmt::LowerHex> fmt::Debug for Hex<T> {
1332            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1333                let bytes = mem::size_of::<T>();
1334                let hex_digits_per_byte = 2;
1335                let hex_digits = bytes * hex_digits_per_byte;
1336                write!(f, "0x{:0width$x}", self.0, width = hex_digits)
1337            }
1338        }
1339
1340        unsafe {
1341            f.debug_struct("ValRaw")
1342                .field("i32", &Hex(self.i32))
1343                .field("i64", &Hex(self.i64))
1344                .field("f32", &Hex(self.f32))
1345                .field("f64", &Hex(self.f64))
1346                .field("v128", &Hex(u128::from_le_bytes(self.v128)))
1347                .field("funcref", &self.funcref)
1348                .field("externref", &Hex(self.externref))
1349                .field("anyref", &Hex(self.anyref))
1350                .field("exnref", &Hex(self.exnref))
1351                .finish()
1352        }
1353    }
1354}
1355
1356impl ValRaw {
1357    /// Create a null reference that is compatible with any of
1358    /// `{any,extern,func,exn}ref`.
1359    pub fn null() -> ValRaw {
1360        unsafe {
1361            let raw = mem::MaybeUninit::<Self>::zeroed().assume_init();
1362            debug_assert_eq!(raw.get_anyref(), 0);
1363            debug_assert_eq!(raw.get_exnref(), 0);
1364            debug_assert_eq!(raw.get_externref(), 0);
1365            debug_assert_eq!(raw.get_funcref(), ptr::null_mut());
1366            raw
1367        }
1368    }
1369
1370    /// Creates a WebAssembly `i32` value
1371    #[inline]
1372    pub fn i32(i: i32) -> ValRaw {
1373        // Note that this is intentionally not setting the `i32` field, instead
1374        // setting the `i64` field with a zero-extended version of `i`. For more
1375        // information on this see the comments on `Lower for Result` in the
1376        // `wasmtime` crate. Otherwise though all `ValRaw` constructors are
1377        // otherwise constrained to guarantee that the initial 64-bits are
1378        // always initialized.
1379        ValRaw::u64(i.cast_unsigned().into())
1380    }
1381
1382    /// Creates a WebAssembly `i64` value
1383    #[inline]
1384    pub fn i64(i: i64) -> ValRaw {
1385        ValRaw { i64: i.to_le() }
1386    }
1387
1388    /// Creates a WebAssembly `i32` value
1389    #[inline]
1390    pub fn u32(i: u32) -> ValRaw {
1391        // See comments in `ValRaw::i32` for why this is setting the upper
1392        // 32-bits as well.
1393        ValRaw::u64(i.into())
1394    }
1395
1396    /// Creates a WebAssembly `i64` value
1397    #[inline]
1398    pub fn u64(i: u64) -> ValRaw {
1399        ValRaw::i64(i as i64)
1400    }
1401
1402    /// Creates a WebAssembly `f32` value
1403    #[inline]
1404    pub fn f32(i: u32) -> ValRaw {
1405        // See comments in `ValRaw::i32` for why this is setting the upper
1406        // 32-bits as well.
1407        ValRaw::u64(i.into())
1408    }
1409
1410    /// Creates a WebAssembly `f64` value
1411    #[inline]
1412    pub fn f64(i: u64) -> ValRaw {
1413        ValRaw { f64: i.to_le() }
1414    }
1415
1416    /// Creates a WebAssembly `v128` value
1417    #[inline]
1418    pub fn v128(i: u128) -> ValRaw {
1419        ValRaw {
1420            v128: i.to_le_bytes(),
1421        }
1422    }
1423
1424    /// Creates a WebAssembly `funcref` value
1425    #[inline]
1426    pub fn funcref(i: *mut c_void) -> ValRaw {
1427        ValRaw {
1428            funcref: i.map_addr(|i| i.to_le()),
1429        }
1430    }
1431
1432    /// Creates a WebAssembly `externref` value
1433    #[inline]
1434    pub fn externref(e: u32) -> ValRaw {
1435        assert!(cfg!(feature = "gc") || e == 0);
1436        ValRaw {
1437            externref: e.to_le(),
1438        }
1439    }
1440
1441    /// Creates a WebAssembly `anyref` value
1442    #[inline]
1443    pub fn anyref(r: u32) -> ValRaw {
1444        assert!(cfg!(feature = "gc") || r == 0);
1445        ValRaw { anyref: r.to_le() }
1446    }
1447
1448    /// Creates a WebAssembly `exnref` value
1449    #[inline]
1450    pub fn exnref(r: u32) -> ValRaw {
1451        assert!(cfg!(feature = "gc") || r == 0);
1452        ValRaw { exnref: r.to_le() }
1453    }
1454
1455    #[inline]
1456    pub(crate) fn vmgcref(r: Option<VMGcRef>) -> ValRaw {
1457        let raw = r.map_or(0, |r| r.as_raw_u32());
1458
1459        // NB: All `VMGcRef`-based `ValRaw`s are the same.
1460        debug_assert_eq!(raw, ValRaw::anyref(raw).get_exnref());
1461        debug_assert_eq!(raw, ValRaw::exnref(raw).get_externref());
1462        debug_assert_eq!(raw, ValRaw::externref(raw).get_anyref());
1463
1464        ValRaw::anyref(raw)
1465    }
1466
1467    /// Gets the WebAssembly `i32` value
1468    #[inline]
1469    pub fn get_i32(&self) -> i32 {
1470        unsafe { i32::from_le(self.i32) }
1471    }
1472
1473    /// Gets the WebAssembly `i64` value
1474    #[inline]
1475    pub fn get_i64(&self) -> i64 {
1476        unsafe { i64::from_le(self.i64) }
1477    }
1478
1479    /// Gets the WebAssembly `i32` value
1480    #[inline]
1481    pub fn get_u32(&self) -> u32 {
1482        self.get_i32().cast_unsigned()
1483    }
1484
1485    /// Gets the WebAssembly `i64` value
1486    #[inline]
1487    pub fn get_u64(&self) -> u64 {
1488        self.get_i64().cast_unsigned()
1489    }
1490
1491    /// Gets the WebAssembly `f32` value
1492    #[inline]
1493    pub fn get_f32(&self) -> u32 {
1494        unsafe { u32::from_le(self.f32) }
1495    }
1496
1497    /// Gets the WebAssembly `f64` value
1498    #[inline]
1499    pub fn get_f64(&self) -> u64 {
1500        unsafe { u64::from_le(self.f64) }
1501    }
1502
1503    /// Gets the WebAssembly `v128` value
1504    #[inline]
1505    pub fn get_v128(&self) -> u128 {
1506        unsafe { u128::from_le_bytes(self.v128) }
1507    }
1508
1509    /// Gets the WebAssembly `funcref` value
1510    #[inline]
1511    pub fn get_funcref(&self) -> *mut c_void {
1512        let addr = unsafe { usize::from_le(self.funcref.addr()) };
1513        core::ptr::with_exposed_provenance_mut(addr)
1514    }
1515
1516    /// Gets the WebAssembly `externref` value
1517    #[inline]
1518    pub fn get_externref(&self) -> u32 {
1519        let externref = u32::from_le(unsafe { self.externref });
1520        assert!(cfg!(feature = "gc") || externref == 0);
1521        externref
1522    }
1523
1524    /// Gets the WebAssembly `anyref` value
1525    #[inline]
1526    pub fn get_anyref(&self) -> u32 {
1527        let anyref = u32::from_le(unsafe { self.anyref });
1528        assert!(cfg!(feature = "gc") || anyref == 0);
1529        anyref
1530    }
1531
1532    /// Gets the WebAssembly `exnref` value
1533    #[inline]
1534    pub fn get_exnref(&self) -> u32 {
1535        let exnref = u32::from_le(unsafe { self.exnref });
1536        assert!(cfg!(feature = "gc") || exnref == 0);
1537        exnref
1538    }
1539
1540    /// Get the inner `VMGcRef`.
1541    pub(crate) fn get_vmgcref(&self) -> Option<crate::vm::VMGcRef> {
1542        debug_assert_eq!(self.get_anyref(), self.get_exnref());
1543        debug_assert_eq!(self.get_anyref(), self.get_externref());
1544        VMGcRef::from_raw_u32(self.get_anyref())
1545    }
1546}
1547
1548/// An "opaque" version of `VMContext` which must be explicitly casted to a
1549/// target context.
1550///
1551/// This context is used to represent that contexts specified in
1552/// `VMFuncRef` can have any type and don't have an implicit
1553/// structure. Neither wasmtime nor cranelift-generated code can rely on the
1554/// structure of an opaque context in general and only the code which configured
1555/// the context is able to rely on a particular structure. This is because the
1556/// context pointer configured for `VMFuncRef` is guaranteed to be
1557/// the first parameter passed.
1558///
1559/// Note that Wasmtime currently has a layout where all contexts that are casted
1560/// to an opaque context start with a 32-bit "magic" which can be used in debug
1561/// mode to debug-assert that the casts here are correct and have at least a
1562/// little protection against incorrect casts.
1563pub struct VMOpaqueContext {
1564    pub(crate) magic: u32,
1565    _marker: marker::PhantomPinned,
1566}
1567
1568impl VMOpaqueContext {
1569    /// Helper function to clearly indicate that casts are desired.
1570    #[inline]
1571    pub fn from_vmcontext(ptr: NonNull<VMContext>) -> NonNull<VMOpaqueContext> {
1572        ptr.cast()
1573    }
1574
1575    /// Helper function to clearly indicate that casts are desired.
1576    #[inline]
1577    pub fn from_vm_array_call_host_func_context(
1578        ptr: NonNull<VMArrayCallHostFuncContext>,
1579    ) -> NonNull<VMOpaqueContext> {
1580        ptr.cast()
1581    }
1582}