feat: add LinearMemory implementation

This implementation of linear memory is capable of being shared between
multiple, concurrently running interpreter instances. All access to the
actual data goes through raw pointers, derived from `UnsafeCell`s. While
this allows race-conditions, it avoids the other kinds of UB that may
be caused by code that violates the guarantees attached to shared and
mutable references.

Signed-off-by: wucke13 <wucke13+github@gmail.com>

Author: wucke13

src/execution/linear_memory.rs

@@ -0,0 +1,318 @@
+use core::{cell::UnsafeCell, mem};
+
+use alloc::vec::Vec;
+
+use crate::{core::little_endian::LittleEndianBytes, spinlock::RwSpinLock, RuntimeError};
+
+/// Implementation of the linear memory suitable for concurrent access
+///
+/// This linear memory implementation internally relies on a `Vec<UnsafeCell<u8>>`. Thus, the atomic unit of information for it is a byte (`u8`). All access to the linear memory internally occurs through pointers, avoiding the creation of shared and mut refs to the internal data completely. This avoids undefined behavior, except for the race-condition inherent to concurrent writes. Because of this, the [`LinearMemory::store`] function does not require `&mut self` -- `&self` suffices.
+///
+/// # Notes on locking
+///
+/// The internal data vector of the [`LinearMemory`] is wrapped in a [`RwLock`]. Despite the
+/// name, writes to the linear memory do not require an acquisition of a write lock. Writes are
+/// implemented through a shared ref to the internal vector, with an `UnsafeCell` to achieve
+/// interior mutability.
+///
+/// However, linear memory can grow. As the linear memory is implemented via a [`Vec`], a grow can
+/// result in the vector's internal data buffer to be copied over to a bigger, fresh allocation.
+/// The old buffer is then freed. Combined with concurrent mutable access, this can cause
+/// use-after-free. To avoid this, a grow operation of the linear memory acquires a write lock,
+/// blocking all read/write to the linear memory inbetween.
+///
+/// # Unsafe Note
+///
+/// Raw pointer access it required, because concurent mutation of the linear memory might happen
+/// (consider the threading proposal for WASM, where mutliple WASM threads access the same linear
+/// memory at the same time). The inherent race condition results in UB w/r/t the state of the `u8`s
+/// in the inner data. However, this is tolerable, e.g. avoiding race conditions on the state of the
+/// linear memory can not be the task of the interpreter, but has to be fulfilled by the interpreted
+/// bytecode itself.
+// TODO if a memmap like operation is available, the linear memory implementation can be optimized brutally. Out-of-bound access can be mapped to userspace handled page-faults, e.g. the MMU takes over that responsibility of catching out of bounds. Grow can happen without copying of data, by mapping new pages consecutively after the current final page of the linear memory.
+pub struct LinearMemory<const PAGE_SIZE: usize = { 1 << 16 }> {
+    inner_data: RwSpinLock<Vec<UnsafeCell<u8>>>,
+}
+
+impl<const PAGE_SIZE: usize> LinearMemory<PAGE_SIZE> {
+    const PAGE_SIZE: usize = PAGE_SIZE;
+
+    /// Create a new, empty [`LinearMemory`]
+    pub fn new() -> Self {
+        Self {
+            inner_data: RwSpinLock::new(Vec::new()),
+        }
+    }
+
+    /// Create a new, empty [`LinearMemory`]
+    pub fn new_with_capacity(pages: u16) -> Self {
+        let size_bytes = Self::PAGE_SIZE * pages as usize;
+        let mut data = Vec::with_capacity(size_bytes);
+        data.resize_with(size_bytes, || UnsafeCell::new(0));
+
+        Self {
+            inner_data: RwSpinLock::new(data),
+        }
+    }
+
+    /// Grow the [`LinearMemory`] by a number of pages
+    pub fn grow(&self, pages_to_add: i16) {
+        let mut lock_guard = self.inner_data.write();
+        let prior_length_bytes = lock_guard.len();
+        let new_length_bytes = prior_length_bytes + Self::PAGE_SIZE * pages_to_add as usize;
+        lock_guard.resize_with(new_length_bytes, || UnsafeCell::new(0));
+    }
+
+    /// Get the number of pages currently allocated to this [`LinearMemory`]
+    pub fn pages(&self) -> u16 {
+        u16::try_from(self.inner_data.read().len() / PAGE_SIZE).unwrap()
+    }
+
+    /// At a given index, store a datum in the [`LinearMemory`]
+    pub fn store<const N: usize, T: LittleEndianBytes<N>>(
+        &self,
+        index: i32,
+        value: T,
+    ) -> Result<(), RuntimeError> {
+        let value_size = mem::size_of::<T>();
+
+        let lock_guard = self.inner_data.read();
+        let ptr = lock_guard.get(index as usize).unwrap().get();
+        let bytes = value.to_le_bytes(); //
+
+        // A value must fit into the linear memory
+        assert!(
+            value_size <= lock_guard.len(),
+            "value does not fit into linear memory"
+        );
+
+        // The following statement must be true
+        // `index + value_size <= lock_guard.len()`
+        // This check verifies it, while avoiding the possible overflow. The subtraction can not
+        // underflow because of the previous assert.
+        assert!(
+            (index as usize) <= lock_guard.len() - value_size,
+            "value write would extend beyond the end of the linear_memory"
+        );
+
+        // Safety argument:
+        //
+        // - nonoverlapping is guaranteed, because `src` is a pointer to a stack allocated array,
+        //   while the destination is heap allocated Vec
+        // - the first assert above guarantee that `src` fits into the destination
+        // - the second assert above guarantees that even with the offset in `index`, `src` does not
+        //   extend beyond the destinations last `UnsafeCell<u8>`
+        // - the use of `UnsafeCell` avoids any `&` or `&mut` to ever be created on any of the `u8`s
+        //   contained in the `UnsafeCell`s, so no UB is created through the existence of unsound
+        //   references
+        unsafe { ptr.copy_from_nonoverlapping(bytes.as_ref().as_ptr(), value_size) }
+
+        Ok(())
+    }
+
+    /// From a given index, load a datum in the [`LinearMemory`]
+    pub fn load<const N: usize, T: LittleEndianBytes<N>>(
+        &self,
+        index: i32,
+    ) -> Result<T, RuntimeError> {
+        let value_size = mem::size_of::<T>();
+        assert_eq!(value_size, N, "value size must match const generic N");
+
+        let lock_guard = self.inner_data.read();
+        let ptr = lock_guard.get(index as usize).unwrap().get();
+        let mut bytes = [0; N];
+
+        // A value must fit into the linear memory
+        assert!(
+            value_size <= lock_guard.len(),
+            "value does not fit into linear memory"
+        );
+
+        // The following statement must be true
+        // `index + value_size <= lock_guard.len()`
+        // This check verifies it, while avoiding the possible overflow. The subtraction can not
+        // underflow because of the previous assert.
+        assert!(
+            (index as usize) <= lock_guard.len() - value_size,
+            "value read would extend beyond the end of the linear_memory"
+        );
+
+        // Safety argument:
+        //
+        // - nonoverlapping is guaranteed, because `dest` is a pointer to a stack allocated array,
+        //   while the source is heap allocated Vec
+        // - the first assert above guarantee that source is bigger than `dest`
+        // - the second assert above guarantees that even with the offset in `index`, `dest` does
+        //   not extend beyond the destinations last `UnsafeCell<u8>` in source
+        // - the use of `UnsafeCell` avoids any `&` or `&mut` to ever be created on any of the `u8`s
+        //   contained in the `UnsafeCell`s, so no UB is created through the existence of unsound
+        //   references
+        unsafe { ptr.copy_to_nonoverlapping(bytes.as_mut_ptr(), bytes.len()) };
+        Ok(T::from_le_bytes(bytes))
+    }
+}
+
+impl<const PAGE_SIZE: usize> core::fmt::Debug for LinearMemory<PAGE_SIZE> {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        write!(f, "LinearMemory {{ inner_data: [ ")?;
+        let lock_guard = self.inner_data.read();
+        let mut iter = lock_guard.iter();
+
+        if let Some(first_byte_uc) = iter.next() {
+            write!(f, "{}", unsafe { *first_byte_uc.get() })?;
+        }
+
+        for uc in iter {
+            // Safety argument:
+            //
+            // TODO
+            let byte = unsafe { *uc.get() };
+
+            write!(f, ", {byte}")?;
+        }
+        write!(f, " ] }}")
+    }
+}
+
+impl<const PAGE_SIZE: usize> Default for LinearMemory<PAGE_SIZE> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use alloc::format;
+
+    use super::*;
+
+    const PAGE_SIZE: usize = 1 << 8;
+    const PAGES: u16 = 2;
+
+    #[test]
+    fn new_constructor() {
+        let lin_mem = LinearMemory::<PAGE_SIZE>::new();
+        assert_eq!(lin_mem.pages(), 0);
+    }
+
+    #[test]
+    fn new_grow() {
+        let lin_mem = LinearMemory::<PAGE_SIZE>::new();
+        lin_mem.grow(1);
+        assert_eq!(lin_mem.pages(), 1);
+    }
+
+    #[test]
+    fn debug_print() {
+        let lin_mem = LinearMemory::<PAGE_SIZE>::new_with_capacity(1);
+        assert_eq!(lin_mem.pages(), 1);
+
+        let expected_length = "LinearMemory { inner_data: [  ] }".len() + PAGE_SIZE * "0, ".len();
+        let tol = 2;
+
+        let debug_repr = format!("{lin_mem:?}");
+        let lower_bound = expected_length - tol;
+        let upper_bound = expected_length + tol;
+        assert!((lower_bound..upper_bound).contains(&debug_repr.len()));
+    }
+
+    #[test]
+    fn roundtrip_normal_range_i8_neg127() {
+        let x: i8 = -127;
+        let highest_legal_offset = PAGE_SIZE - mem::size_of::<i8>();
+        for offset in 0..i32::try_from(highest_legal_offset).unwrap() {
+            let lin_mem = LinearMemory::<PAGE_SIZE>::new_with_capacity(PAGES);
+
+            lin_mem.store(offset, x).unwrap();
+
+            assert_eq!(
+                lin_mem
+                    .load::<{ core::mem::size_of::<i8>() }, i8>(offset)
+                    .unwrap(),
+                x,
+                "load store roundtrip for {x:?} failed!"
+            );
+        }
+    }
+
+    #[test]
+    fn roundtrip_normal_range_f32_13() {
+        let x: f32 = 13.0;
+        let highest_legal_offset = PAGE_SIZE - mem::size_of::<f32>();
+        for offset in 0..i32::try_from(highest_legal_offset).unwrap() {
+            let lin_mem = LinearMemory::<PAGE_SIZE>::new_with_capacity(PAGES);
+
+            lin_mem.store(offset, x).unwrap();
+
+            assert_eq!(
+                lin_mem
+                    .load::<{ core::mem::size_of::<f32>() }, f32>(offset)
+                    .unwrap(),
+                x,
+                "load store roundtrip for {x:?} failed!"
+            );
+        }
+    }
+
+    #[test]
+    fn roundtrip_normal_range_f64_min() {
+        let x: f64 = f64::MIN;
+        let highest_legal_offset = PAGE_SIZE - mem::size_of::<f64>();
+        for offset in 0..i32::try_from(highest_legal_offset).unwrap() {
+            let lin_mem = LinearMemory::<PAGE_SIZE>::new_with_capacity(PAGES);
+
+            lin_mem.store(offset, x).unwrap();
+
+            assert_eq!(
+                lin_mem
+                    .load::<{ core::mem::size_of::<f64>() }, f64>(offset)
+                    .unwrap(),
+                x,
+                "load store roundtrip for {x:?} failed!"
+            );
+        }
+    }
+
+    #[test]
+    fn roundtrip_normal_range_f64_nan() {
+        let x: f64 = f64::NAN;
+        let highest_legal_offset = PAGE_SIZE - mem::size_of::<f64>();
+        for offset in 0..i32::try_from(highest_legal_offset).unwrap() {
+            let lin_mem = LinearMemory::<PAGE_SIZE>::new_with_capacity(PAGES);
+
+            lin_mem.store(offset, x).unwrap();
+
+            assert!(
+                lin_mem
+                    .load::<{ core::mem::size_of::<f64>() }, f64>(offset)
+                    .unwrap()
+                    .is_nan(),
+                "load store roundtrip for {x:?} failed!"
+            );
+        }
+    }
+
+    #[test]
+    #[should_panic(expected = "value write would extend beyond the end of the linear_memory")]
+    fn store_out_of_range_u128_max() {
+        let x: u128 = u128::MAX;
+        let pages = 1;
+        let lowest_illegal_offset = PAGE_SIZE - mem::size_of::<u128>() + 1;
+        let lowest_illegal_offset = i32::try_from(lowest_illegal_offset).unwrap();
+        let lin_mem = LinearMemory::<PAGE_SIZE>::new_with_capacity(pages);
+
+        lin_mem.store(lowest_illegal_offset, x).unwrap();
+    }
+
+    #[test]
+    #[should_panic(expected = "called `Option::unwrap()` on a `None` value")]
+    fn store_empty_lineaer_memory_u8() {
+        let x: u8 = u8::MAX;
+        let pages = 0;
+        let lowest_illegal_offset = PAGE_SIZE - mem::size_of::<u8>() + 1;
+        let lowest_illegal_offset = i32::try_from(lowest_illegal_offset).unwrap();
+        let lin_mem = LinearMemory::<PAGE_SIZE>::new_with_capacity(pages);
+
+        lin_mem.store(lowest_illegal_offset, x).unwrap();
+    }
+}

src/execution/mod.rs

@@ -33,6 +33,7 @@ pub(crate) mod execution_info;
 pub mod function_ref;
 pub mod hooks;
 mod interpreter_loop;
+pub(crate) mod linear_memory;
 pub(crate) mod locals;
 pub(crate) mod lut;
 pub(crate) mod store;