A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! no_std implementation of fibers.
//!
//! This is a very stripped-down version of the Unix platform support,
//! but without mmap or guard pages, because on no_std systems we do
//! not assume that virtual memory exists.
//!
//! The stack layout is nevertheless the same (modulo the guard page)
//! as on Unix because we share its low-level implementations:
//!
//! ```text
//! 0xB000 +-----------------------+ <- top of stack
//! | &Cell<RunResult> | <- where to store results
//! 0xAff8 +-----------------------+
//! | *const u8 | <- last sp to resume from
//! 0xAff0 +-----------------------+ <- 16-byte aligned
//! | |
//! ~ ... ~ <- actual native stack space to use
//! | |
//! 0x0000 +-----------------------+
//! ```
//!
//! Here `0xAff8` is filled in temporarily while `resume` is running. The fiber
//! started with 0xB000 as a parameter so it knows how to find this.
//! Additionally `resumes` stores state at 0xAff0 to restart execution, and
//! `suspend`, which has 0xB000 so it can find this, will read that and write
//! its own resumption information into this slot as well.
use crate::stackswitch::*;
/// Raw fibers use this crate's stack-switching routines.
pub(crate) use crate::stackswitch::raw;
use crate::{Result, RunResult, RuntimeFiberStack};
use alloc::boxed::Box;
use core::cell::Cell;
use core::ops::Range;
use wasmtime_environ::prelude::*;
// The no_std implementation is infallible in practice, but we use
// `wasmtime_environ::error::Error` here absent any better alternative.
pub use wasmtime_environ::error::Error;
pub struct FiberStack {
base: BasePtr,
len: usize,
storage: FiberStackStorage,
}
#[expect(
dead_code,
reason = "fields are held to own the backing storage until drop"
)]
enum FiberStackStorage {
/// Backing storage, if owned. Allocated once at startup and then
/// not reallocated afterward.
Owned(TryVec<Align16>),
Unmanaged,
Custom(Box<dyn RuntimeFiberStack>),
}
#[repr(align(16))]
struct Align16 {
_contents: u128,
}
struct BasePtr(*mut u8);
unsafe impl Send for BasePtr {}
unsafe impl Sync for BasePtr {}
impl FiberStack {
pub fn new(size: usize, zeroed: bool) -> Result<Self> {
// Round up the size to at least one page.
let size = core::cmp::max(4096, size);
let mut storage = TryVec::new();
let size_rounded_up = size
.checked_next_multiple_of(16)
.ok_or_else(|| format_err!("stack size too large to round up to 16 bytes"))?;
let size_in_16byte_units = size_rounded_up / 16;
storage.reserve_exact(size_in_16byte_units)?;
if zeroed {
storage.resize_with(size_in_16byte_units, || Align16 { _contents: 0 })?;
}
Ok(FiberStack {
base: BasePtr(storage.as_mut_ptr().cast()),
len: storage.capacity() * 16,
storage: FiberStackStorage::Owned(storage),
})
}
pub unsafe fn from_raw_parts(base: *mut u8, guard_size: usize, len: usize) -> Result<Self> {
Ok(FiberStack {
storage: FiberStackStorage::Unmanaged,
base: BasePtr(unsafe { base.offset(isize::try_from(guard_size).unwrap()) }),
len,
})
}
pub fn is_from_raw_parts(&self) -> bool {
matches!(self.storage, FiberStackStorage::Unmanaged)
}
pub fn from_custom(custom: Box<dyn RuntimeFiberStack>) -> Result<Self> {
let range = custom.range();
let start_ptr = range.start as *mut u8;
Ok(FiberStack {
base: BasePtr(start_ptr),
len: range.len(),
storage: FiberStackStorage::Custom(custom),
})
}
pub fn top(&self) -> Option<*mut u8> {
Some(self.base.0.wrapping_byte_add(self.len))
}
pub fn range(&self) -> Option<Range<usize>> {
let base = self.base.0 as usize;
Some(base..base + self.len)
}
pub fn guard_range(&self) -> Option<Range<*mut u8>> {
None
}
}
pub struct Fiber;
pub struct Suspend {
top_of_stack: *mut u8,
}
extern "C" fn fiber_start<F, A, B, C>(arg0: *mut u8, top_of_stack: *mut u8) -> *mut u8
where
F: FnOnce(A, &mut super::Suspend<A, B, C>) -> C,
{
unsafe {
let inner = Suspend { top_of_stack };
let initial = inner.take_resume::<A, B, C>();
let inner =
super::Suspend::<A, B, C>::execute(inner, initial, Box::from_raw(arg0.cast::<F>()));
inner.top_of_stack
}
}
impl Fiber {
pub fn new<F, A, B, C>(stack: &FiberStack, func: F) -> Result<Self>
where
F: FnOnce(A, &mut super::Suspend<A, B, C>) -> C,
{
// On unsupported platforms `wasmtime_fiber_init` is a panicking shim so
// return an error saying the host architecture isn't supported instead.
if !SUPPORTED_ARCH {
bail!("fibers unsupported on this host architecture");
}
unsafe {
let data = Box::into_raw(try_new::<Box<_>>(func)?).cast();
wasmtime_fiber_init(stack.top().unwrap(), fiber_start::<F, A, B, C>, data);
}
Ok(Self)
}
pub(crate) fn resume<A, B, C>(&self, stack: &FiberStack, result: &Cell<RunResult<A, B, C>>) {
unsafe {
// Store where our result is going at the very tip-top of the
// stack, otherwise known as our reserved slot for this information.
//
// In the diagram above this is updating address 0xAff8
let addr = stack.top().unwrap().cast::<usize>().offset(-1);
addr.write(result as *const _ as usize);
assert!(SUPPORTED_ARCH);
wasmtime_fiber_switch(stack.top().unwrap());
// null this out to help catch use-after-free
addr.write(0);
}
}
pub(crate) unsafe fn drop<A, B, C>(&mut self) {}
}
impl Suspend {
pub(crate) fn switch<A, B, C>(&mut self, result: RunResult<A, B, C>) -> A {
unsafe {
// Calculate 0xAff8 and then write to it
(*self.result_location::<A, B, C>()).set(result);
wasmtime_fiber_switch(self.top_of_stack);
self.take_resume::<A, B, C>()
}
}
pub(crate) fn start_exit<A, B, C>(&mut self, result: RunResult<A, B, C>) {
unsafe {
(*self.result_location::<A, B, C>()).set(result);
}
}
unsafe fn take_resume<A, B, C>(&self) -> A {
unsafe {
match (*self.result_location::<A, B, C>()).replace(RunResult::Executing) {
RunResult::Resuming(val) => val,
_ => panic!("not in resuming state"),
}
}
}
unsafe fn result_location<A, B, C>(&self) -> *const Cell<RunResult<A, B, C>> {
unsafe {
let ret = self.top_of_stack.cast::<*const u8>().offset(-1).read();
assert!(!ret.is_null());
ret.cast()
}
}
}