A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
use std::borrow::Cow;
use std::cell::UnsafeCell;
use std::fmt;
use std::mem;
use std::ops::Range;
use std::str;
use wasmtime_environ::error::{Result, bail};
pub use wiggle_macro::from_witx;
pub use wasmtime_environ::error;
pub use wiggle_macro::wasmtime_integration;
pub use bitflags;
#[cfg(feature = "wiggle_metadata")]
pub use witx;
mod guest_error;
mod guest_type;
mod region;
pub use tracing;
pub use guest_error::GuestError;
pub use guest_type::{GuestErrorType, GuestType, GuestTypeTransparent};
pub use region::Region;
#[cfg(feature = "wasmtime")]
pub mod wasmtime_crate {
pub use wasmtime::*;
}
/// Representation of guest memory for `wiggle`-generated trait methods.
///
/// Guest memory is represented as an array of bytes. Memories are either
/// "unshared" or "shared". Unshared means that the host has exclusive access to
/// the entire array of memory. This allows safe borrows into wasm linear
/// memory. Shared memories can be modified at any time and are represented as
/// an array of `UnsafeCell<u8>`.
///
/// This is generated by the `wiggle` bindings macros.
pub enum GuestMemory<'a> {
Unshared(&'a mut [u8]),
Shared(&'a [UnsafeCell<u8>]),
/// An unshared Wasmtime memory accessed by range, so that only the ranges
/// written are considered modified (see
/// `wasmtime::Memory::data_ranges_and_store_data_mut`).
#[cfg(feature = "wasmtime")]
Ranges(wasmtime::MemoryRanges<'a>),
}
// manual impls are needed because of the `UnsafeCell` in the `Shared` branch
// but this otherwise upholds send/sync invariants.
unsafe impl Send for GuestMemory<'_> {}
unsafe impl Sync for GuestMemory<'_> {}
impl<'a> GuestMemory<'a> {
/// Read a value from the provided pointer.
///
/// This method will delegate to `T`'s implementation of `read` which will
/// read a value from the `ptr` provided.
///
/// # Errors
///
/// An error is returned if `ptr` is out of bounds, misaligned, or otherwise
/// not valid to read from.
pub fn read<T>(&self, ptr: GuestPtr<T>) -> Result<T, GuestError>
where
T: GuestType,
{
T::read(self, ptr)
}
/// Writes the `val` provided to the `ptr` provided.
///
/// This commit will write a `val` into a guest's linear memory. This will
/// delegate to `T`'s implementation of `write`.
///
/// # Errors
///
/// An error is returned if `ptr` is out of bounds, misaligned, or otherwise
/// not valid to read from.
pub fn write<T>(&mut self, ptr: GuestPtr<T>, val: T) -> Result<(), GuestError>
where
T: GuestType,
{
T::write(self, ptr, val)
}
/// Acquires a slice or owned copy of the memory pointed to by `ptr`.
///
/// This method will attempt to borrow `ptr` directly from linear memory. If
/// memory is shared and cannot be borrowed directly then an owned copy is
/// returned instead.
///
/// # Errors
///
/// An error is returned if `ptr` is out of bounds, misaligned, or otherwise
/// not valid to read from.
pub fn as_cow(&self, ptr: GuestPtr<[u8]>) -> Result<Cow<'_, [u8]>, GuestError> {
match self {
GuestMemory::Shared(_) => Ok(Cow::Owned(self.to_vec(ptr)?)),
_ => match self.as_slice(ptr)? {
Some(slice) => Ok(Cow::Borrowed(slice)),
None => unreachable!(),
},
}
}
/// Same as [`GuestMemory::as_cow`] but for strings.
///
/// # Errors
///
/// An error is returned if `ptr` is out of bounds, misaligned, or otherwise
/// not valid to read from.
pub fn as_cow_str(&self, ptr: GuestPtr<str>) -> Result<Cow<'_, str>, GuestError> {
match self.as_cow(ptr.cast::<[u8]>())? {
Cow::Owned(bytes) => Ok(Cow::Owned(
String::from_utf8(bytes).map_err(|e| e.utf8_error())?,
)),
Cow::Borrowed(bytes) => Ok(Cow::Borrowed(std::str::from_utf8(bytes)?)),
}
}
/// Attempts to borrow a raw guest slice of memory pointed to by `ptr`.
///
/// This method will attempt to return a raw pointer into guest memory. This
/// can only be done for `Unshared` memories. A `Shared` memory will return
/// `Ok(None)` here.
///
/// # Errors
///
/// An error is returned if `ptr` is out of bounds, misaligned, or otherwise
/// not valid to read from.
pub fn as_slice(&self, ptr: GuestPtr<[u8]>) -> Result<Option<&[u8]>, GuestError> {
let range = self.validate_range::<u8>(ptr.pointer.0, ptr.pointer.1)?;
match self {
GuestMemory::Unshared(slice) => Ok(Some(&slice[range])),
GuestMemory::Shared(_) => Ok(None),
#[cfg(feature = "wasmtime")]
GuestMemory::Ranges(memory) => Ok(Some(&memory.data()[range])),
}
}
/// Same as [`GuestMemory::as_slice`] but for strings.
pub fn as_str(&self, ptr: GuestPtr<str>) -> Result<Option<&str>, GuestError> {
match self.as_slice(ptr.cast())? {
Some(bytes) => Ok(Some(std::str::from_utf8(bytes)?)),
None => Ok(None),
}
}
/// Attempts return `ptr` as a raw slice of mutable bytes in wasm linear
/// memory.
///
/// Like [`GuestMemory::as_slice`] this only works for `Unshared` memories
/// and will not work for `Shared` memories.
pub fn as_slice_mut(&mut self, ptr: GuestPtr<[u8]>) -> Result<Option<&mut [u8]>, GuestError> {
let range = self.validate_range::<u8>(ptr.pointer.0, ptr.pointer.1)?;
match self {
GuestMemory::Unshared(slice) => Ok(Some(&mut slice[range])),
GuestMemory::Shared(_) => Ok(None),
#[cfg(feature = "wasmtime")]
GuestMemory::Ranges(memory) => Ok(Some(
memory.data_range_mut(range).expect("range was validated"),
)),
}
}
/// Copies the data in the guest region into a [`Vec`].
///
/// This is useful when one cannot use [`GuestMemory::as_slice`], e.g., when
/// pointing to a region of WebAssembly shared memory.
pub fn to_vec<T>(&self, ptr: GuestPtr<[T]>) -> Result<Vec<T>, GuestError>
where
T: GuestTypeTransparent + Copy,
{
let guest = self.validate_size_align::<T>(ptr.pointer.0, ptr.pointer.1)?;
let mut host = Vec::with_capacity(guest.len());
// SAFETY: The `guest_slice` variable is already a valid pointer into
// the guest's memory, and it may or may not be a pointer into shared
// memory. We can't naively use `.to_vec(..)` which could introduce data
// races but all that needs to happen is to copy data into our local
// `vec` as all the data is `Copy` and transparent anyway. For this
// purpose the `ptr::copy` function should be sufficient for copying
// over all the data.
//
// TODO: audit that this use of `std::ptr::copy` is safe with shared
// memory (https://github.com/bytecodealliance/wasmtime/issues/4203)
unsafe {
std::ptr::copy(guest.as_ptr().cast(), host.as_mut_ptr(), guest.len());
host.set_len(guest.len());
}
Ok(host)
}
/// Copies the data pointed to by `slice` into this guest region.
///
/// This method is a *safe* method to copy data from the host to the guest.
/// This requires that `self` and `slice` have the same length. The pointee
/// type `T` requires the [`GuestTypeTransparent`] trait which is an
/// assertion that the representation on the host and on the guest is the
/// same.
///
/// # Errors
///
/// Returns an error if this guest pointer is out of bounds or if the length
/// of this guest pointer is not equal to the length of the slice provided.
pub fn copy_from_slice<T>(&mut self, slice: &[T], ptr: GuestPtr<[T]>) -> Result<(), GuestError>
where
T: GuestTypeTransparent + Copy,
{
if usize::try_from(ptr.len())? != slice.len() {
return Err(GuestError::SliceLengthsDiffer);
}
if slice.is_empty() {
return Ok(());
}
let guest = self.validate_size_align_mut::<T>(ptr.pointer.0, ptr.pointer.1)?;
// SAFETY: in the shared memory case, we copy and accept that
// the guest data may be concurrently modified. TODO: audit that
// this use of `std::ptr::copy` is safe with shared memory
// (https://github.com/bytecodealliance/wasmtime/issues/4203)
//
// Also note that the validity of `guest_slice` has already been
// determined by the `as_unsafe_slice_mut` call above.
assert_eq!(guest.len(), slice.len());
unsafe {
let guest: &[UnsafeCell<T>] = guest;
let guest: *const UnsafeCell<T> = guest.as_ptr();
let guest = guest.cast_mut().cast::<T>();
std::ptr::copy(slice.as_ptr(), guest, slice.len());
}
Ok(())
}
/// Validates a guest-relative pointer given various attributes, and returns
/// the corresponding host pointer.
///
/// * `mem` - this is the guest memory being accessed.
/// * `offset` - this is the guest-relative pointer, an offset from the
/// base.
/// * `len` - this is the number of length, in units of `T`, to return
/// in the resulting slice.
///
/// If the parameters are valid then this function will return a slice into
/// `mem` for units of `T`, assuming everything is in-bounds and properly
/// aligned. Additionally the byte-based `Region` is returned, used for borrows
/// later on.
fn validate_size_align<T>(&self, offset: u32, len: u32) -> Result<&[UnsafeCell<T>], GuestError>
where
T: GuestTypeTransparent,
{
let range = self.validate_range::<T>(offset, len)?;
let cells = match self {
GuestMemory::Unshared(s) => {
let s: &[u8] = s;
unsafe { &*(s as *const [u8] as *const [UnsafeCell<u8>]) }
}
GuestMemory::Shared(s) => s,
#[cfg(feature = "wasmtime")]
GuestMemory::Ranges(memory) => {
let s = memory.data();
unsafe { &*(s as *const [u8] as *const [UnsafeCell<u8>]) }
}
};
Self::align_cells(&cells[range.clone()], range)
}
/// Like `validate_size_align`, for writing: with
/// `GuestMemory::Ranges`, only the validated range is borrowed for
/// modification.
pub(crate) fn validate_size_align_mut<T>(
&mut self,
offset: u32,
len: u32,
) -> Result<&[UnsafeCell<T>], GuestError>
where
T: GuestTypeTransparent,
{
match self {
#[cfg(feature = "wasmtime")]
GuestMemory::Ranges(memory) => {
let range = {
let len = len
.checked_mul(T::guest_size())
.ok_or(GuestError::PtrOverflow)?;
let region = Region { start: offset, len };
let start = usize::try_from(offset)?;
let end = start
.checked_add(usize::try_from(len)?)
.ok_or(GuestError::PtrOverflow)?;
if end > memory.len() {
return Err(GuestError::PtrOutOfBounds(region));
}
start..end
};
let s: &mut [u8] = memory
.data_range_mut(range.clone())
.expect("range was validated");
let cells = unsafe { &*(s as *const [u8] as *const [UnsafeCell<u8>]) };
Self::align_cells(cells, range)
}
_ => self.validate_size_align(offset, len),
}
}
/// Reinterprets `memory`, which holds `range` of guest memory, as `T`s,
/// failing if it is misaligned.
fn align_cells<T>(
memory: &[UnsafeCell<u8>],
range: Range<usize>,
) -> Result<&[UnsafeCell<T>], GuestError>
where
T: GuestTypeTransparent,
{
// ... and then align it to `T`, failing if either the head or tail slices
// are nonzero in length. This `unsafe` here is from the standard library
// and should be ok since the input slice is `UnsafeCell<u8>` and the output
// slice is `UnsafeCell<T>`, meaning the only guarantee of the output is
// that it's valid addressable memory, still unsafe to actually access.
assert!(mem::align_of::<T>() <= T::guest_align());
let (start, mid, end) = unsafe { memory.align_to() };
if start.len() > 0 || end.len() > 0 {
let region = Region {
start: range.start as u32,
len: range.len() as u32,
};
return Err(GuestError::PtrNotAligned(region, T::guest_align() as u32));
}
Ok(mid)
}
fn validate_range<T>(&self, offset: u32, len: u32) -> Result<Range<usize>, GuestError>
where
T: GuestTypeTransparent,
{
let byte_len = len
.checked_mul(T::guest_size())
.ok_or(GuestError::PtrOverflow)?;
let region = Region {
start: offset,
len: byte_len,
};
let offset = usize::try_from(offset)?;
let byte_len = usize::try_from(byte_len)?;
let range = offset..offset + byte_len;
let oob = match self {
GuestMemory::Unshared(b) => b.get(range.clone()).is_none(),
GuestMemory::Shared(b) => b.get(range.clone()).is_none(),
#[cfg(feature = "wasmtime")]
GuestMemory::Ranges(memory) => range.end > memory.len(),
};
if oob {
Err(GuestError::PtrOutOfBounds(region))
} else {
Ok(range)
}
}
/// Returns whether this is a shared memory or not.
pub fn is_shared_memory(&self) -> bool {
matches!(self, GuestMemory::Shared(_))
}
}
/// A *guest* pointer.
///
/// This type represents a pointer from the guest that points into host memory.
/// Internally a `GuestPtr` the offset into the memory that the pointer is
/// pointing at. At this time this is always a 32-bit offset so this is not
/// suitable for bindings where wasm has 64-bit addresses.
///
/// Presence of a [`GuestPtr`] does not imply any form of validity. Pointers can
/// be out-of-bounds, misaligned, etc. It is safe to construct a `GuestPtr` with
/// any offset at any time. Consider a `GuestPtr<T>` roughly equivalent to `*mut
/// T`.
///
/// ## Slices and Strings
///
/// Note that the type parameter does not need to implement the `Sized` trait,
/// so you can implement types such as this:
///
/// * `GuestPtr<str>` - a pointer to a guest string.
/// * `GuestPtr<[T]>` - a pointer to a guest array.
///
/// Note that generated bindings won't use these types so you'll have to
/// otherwise construct the types with `.cast()` or `.as_array()`. Unsized types
/// track both the pointer and length in guest memory.
///
/// ## Type parameter and pointee
///
/// The `T` type parameter is largely intended for more static safety in Rust as
/// well as having a better handle on what we're pointing to. A `GuestPtr<T>`,
/// however, does not necessarily literally imply a guest pointer pointing to
/// type `T`. Instead the [`GuestType`] trait is a layer of abstraction where
/// `GuestPtr<T>` may actually be a pointer to `U` in guest memory, but you can
/// construct a `T` from a `U`.
///
/// For example `GuestPtr<GuestPtr<T>>` is a valid type, but this is actually
/// more equivalent to `GuestPtr<u32>` because guest pointers are always
/// 32-bits. That being said you can create a `GuestPtr<T>` from a `u32`.
///
/// Additionally `GuestPtr<MyEnum>` will actually delegate, typically, to and
/// implementation which loads the underlying data as `GuestPtr<u8>` (or
/// similar) and then the bytes loaded are validated to fit within the
/// definition of `MyEnum` before `MyEnum` is returned.
///
/// For more information see the [`GuestMemory::read`] and
/// [`GuestMemory::write`] methods. In general though be extremely careful about
/// writing `unsafe` code when working with a `GuestPtr` if you're not using one
/// of the already-attached helper methods.
#[repr(transparent)]
pub struct GuestPtr<T: ?Sized + Pointee> {
pointer: T::Pointer,
}
impl<T: ?Sized + Pointee> GuestPtr<T> {
/// Creates a new `GuestPtr` from the given `mem` and `pointer` values.
///
/// Note that for sized types like `u32`, `GuestPtr<T>`, etc, the `pointer`
/// value is a `u32` offset into guest memory. For slices and strings,
/// `pointer` is a `(u32, u32)` offset/length pair.
pub fn new(pointer: T::Pointer) -> GuestPtr<T> {
GuestPtr { pointer }
}
/// Returns the offset of this pointer in guest memory.
///
/// Note that for sized types this returns a `u32`, but for slices and
/// strings it returns a `(u32, u32)` pointer/length pair.
pub fn offset(&self) -> T::Pointer {
self.pointer
}
/// Casts this `GuestPtr` type to a different type.
///
/// This is a safe method which is useful for simply reinterpreting the type
/// parameter on this `GuestPtr`. Note that this is a safe method, where
/// again there's no guarantees about alignment, validity, in-bounds-ness,
/// etc of the returned pointer.
pub fn cast<U>(&self) -> GuestPtr<U>
where
U: Pointee<Pointer = T::Pointer> + ?Sized,
{
GuestPtr::new(self.pointer)
}
/// Performs pointer arithmetic on this pointer, moving the pointer forward
/// `amt` slots.
///
/// This will either return the resulting pointer or `Err` if the pointer
/// arithmetic calculation would overflow around the end of the address
/// space.
pub fn add(&self, amt: u32) -> Result<GuestPtr<T>, GuestError>
where
T: GuestType + Pointee<Pointer = u32>,
{
let offset = amt
.checked_mul(T::guest_size())
.and_then(|o| self.pointer.checked_add(o));
let offset = match offset {
Some(o) => o,
None => return Err(GuestError::PtrOverflow),
};
Ok(GuestPtr::new(offset))
}
/// Returns a `GuestPtr` for an array of `T`s using this pointer as the
/// base.
pub fn as_array(&self, elems: u32) -> GuestPtr<[T]>
where
T: GuestType + Pointee<Pointer = u32>,
{
GuestPtr::new((self.pointer, elems))
}
}
impl<T> GuestPtr<[T]> {
/// For slices, specifically returns the relative pointer to the base of the
/// array.
///
/// This is similar to `<[T]>::as_ptr()`
pub fn offset_base(&self) -> u32 {
self.pointer.0
}
/// For slices, returns the length of the slice, in elements.
pub fn len(&self) -> u32 {
self.pointer.1
}
/// Returns an iterator over interior pointers.
///
/// Each item is a `Result` indicating whether it overflowed past the end of
/// the address space or not.
pub fn iter(&self) -> impl ExactSizeIterator<Item = Result<GuestPtr<T>, GuestError>> + '_
where
T: GuestType,
{
let base = self.as_ptr();
(0..self.len()).map(move |i| base.add(i))
}
/// Returns a `GuestPtr` pointing to the base of the array for the interior
/// type `T`.
pub fn as_ptr(&self) -> GuestPtr<T> {
GuestPtr::new(self.offset_base())
}
pub fn get(&self, index: u32) -> Option<GuestPtr<T>>
where
T: GuestType,
{
if index < self.len() {
Some(
self.as_ptr()
.add(index)
.expect("just performed bounds check"),
)
} else {
None
}
}
pub fn get_range(&self, r: std::ops::Range<u32>) -> Option<GuestPtr<[T]>>
where
T: GuestType,
{
if r.end < r.start {
return None;
}
let range_length = r.end - r.start;
if r.start <= self.len() && r.end <= self.len() {
Some(
self.as_ptr()
.add(r.start)
.expect("just performed bounds check")
.as_array(range_length),
)
} else {
None
}
}
}
impl GuestPtr<str> {
/// For strings, returns the relative pointer to the base of the string
/// allocation.
pub fn offset_base(&self) -> u32 {
self.pointer.0
}
/// Returns the length, in bytes, of the string.
pub fn len(&self) -> u32 {
self.pointer.1
}
/// Returns a raw pointer for the underlying slice of bytes that this
/// pointer points to.
pub fn as_bytes(&self) -> GuestPtr<[u8]> {
GuestPtr::new(self.pointer)
}
}
impl<T: ?Sized + Pointee> Clone for GuestPtr<T> {
fn clone(&self) -> Self {
*self
}
}
impl<T: ?Sized + Pointee> Copy for GuestPtr<T> {}
impl<T: ?Sized + Pointee> fmt::Debug for GuestPtr<T> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
T::debug(self.pointer, f)
}
}
impl<T: ?Sized + Pointee> PartialEq for GuestPtr<T> {
fn eq(&self, other: &Self) -> bool {
self.pointer == other.pointer
}
}
mod private {
pub trait Sealed {}
impl<T> Sealed for T {}
impl<T> Sealed for [T] {}
impl Sealed for str {}
}
/// Types that can be pointed to by `GuestPtr<T>`.
///
/// In essence everything can, and the only special-case is unsized types like
/// `str` and `[T]` which have special implementations.
pub trait Pointee: private::Sealed {
#[doc(hidden)]
type Pointer: Copy + PartialEq;
#[doc(hidden)]
fn debug(pointer: Self::Pointer, f: &mut fmt::Formatter) -> fmt::Result;
}
impl<T> Pointee for T {
type Pointer = u32;
fn debug(pointer: Self::Pointer, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "*guest {pointer:#x}")
}
}
impl<T> Pointee for [T] {
type Pointer = (u32, u32);
fn debug(pointer: Self::Pointer, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "*guest {:#x}/{}", pointer.0, pointer.1)
}
}
impl Pointee for str {
type Pointer = (u32, u32);
fn debug(pointer: Self::Pointer, f: &mut fmt::Formatter) -> fmt::Result {
<[u8]>::debug(pointer, f)
}
}
pub fn run_in_dummy_executor<F: std::future::Future>(future: F) -> Result<F::Output> {
use std::pin::Pin;
use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
let mut f = Pin::from(Box::new(future));
let waker = dummy_waker();
let mut cx = Context::from_waker(&waker);
match f.as_mut().poll(&mut cx) {
Poll::Ready(val) => return Ok(val),
Poll::Pending => bail!(
"Cannot wait on pending future: must enable wiggle \"async\" future and execute on an async Store"
),
}
fn dummy_waker() -> Waker {
return unsafe { Waker::from_raw(clone(5 as *const _)) };
unsafe fn clone(ptr: *const ()) -> RawWaker {
assert_eq!(ptr as usize, 5);
const VTABLE: RawWakerVTable = RawWakerVTable::new(clone, wake, wake_by_ref, drop);
RawWaker::new(ptr, &VTABLE)
}
unsafe fn wake(ptr: *const ()) {
assert_eq!(ptr as usize, 5);
}
unsafe fn wake_by_ref(ptr: *const ()) {
assert_eq!(ptr as usize, 5);
}
unsafe fn drop(ptr: *const ()) {
assert_eq!(ptr as usize, 5);
}
}
}