hyperlight_host/mem/

shared_mem.rs

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025 The Hyperlight Authors.

use std::any::type_name;
use std::ffi::c_void;
use std::io::Error;
use std::mem::{align_of, size_of};
#[cfg(unix)]
use std::ptr::null_mut;
use std::sync::{Arc, RwLock};

use bytemuck::Pod;
use thiserror::Error;
use tracing::{Span, instrument};
#[cfg(target_os = "windows")]
use windows::Win32::Foundation::{CloseHandle, HANDLE, INVALID_HANDLE_VALUE};
#[cfg(target_os = "windows")]
use windows::Win32::System::Memory::PAGE_READWRITE;
#[cfg(target_os = "windows")]
use windows::Win32::System::Memory::{
    CreateFileMappingA, FILE_MAP_ALL_ACCESS, MEM_PRESERVE_PLACEHOLDER, MEM_RELEASE,
    MEM_REPLACE_PLACEHOLDER, MEM_RESERVE, MEM_RESERVE_PLACEHOLDER, MEMORY_MAPPED_VIEW_ADDRESS,
    MapViewOfFile, MapViewOfFile3, PAGE_NOACCESS, PAGE_PROTECTION_FLAGS, PAGE_READONLY,
    UnmapViewOfFile, VIRTUAL_ALLOCATION_TYPE, VIRTUAL_FREE_TYPE, VirtualAlloc2, VirtualFree,
    VirtualProtect,
};
#[cfg(target_os = "windows")]
use windows::core::PCSTR;

use super::memory_region::{
    HostGuestMemoryRegion, MemoryRegion, MemoryRegionFlags, MemoryRegionKind, MemoryRegionType,
};
use crate::log_then_return;

type Result<T> = core::result::Result<T, SharedMemoryError>;

/// Whether a [`StackError`] was encountered whilst pushing or popping
/// from the guest stack
#[derive(Debug)]
pub enum StackOp {
    /// The error was encountered while pushing to the guest stack
    Push,
    /// The error was encountered while popping from the guest stack
    Pop,
}
/// An error related to the stack discipline of guest I/O
#[derive(Error, Debug)]
pub enum StackError {
    /// The stack pointer for a stack entry was out-of-bounds for the
    /// stack
    #[error(
        "Unable to {0:?} data from buffer: Stack pointer is out of bounds. Stack pointer: {1}, Buffer size: {2}"
    )]
    SpOob(StackOp, usize, usize),

    /// The back pointer for a stack entry was corrupt
    #[error("Corrupt buffer back-pointer: element offset {0} is outside valid range [8, {1}].")]
    CorruptBackPointer(usize, usize),

    /// A stack entry size prefix was too large for necessary
    /// operations on it to remain in the range of a u32
    #[error("Corrupt buffer size prefix: value {0} overflows when adding 4-byte header.")]
    OverflowingPrefix(u32),

    /// It was not possible to convert a stack entry size prefix into
    /// a usize. This should be impossible on all currently supported
    /// architectures, since usize is 64 bits on all of them.
    #[error("Prefix too large: {0}")]
    PrefixTooLarge(std::num::TryFromIntError),

    /// A stack entry size prefix is larger than its
    /// logically-enclosing element
    #[error(
        "Corrupt buffer size prefix: flatbuffer claims {0} bytes but the element slot is only {1} bytes."
    )]
    CorruptPrefix(usize, usize),

    /// An error was encountered during a routine error conversion
    /// that should have been infallible
    #[error("pop_buffer_into: failed to convert buffer to {0}")]
    ConvertError(String),

    /// There was not enough free space available on the stack for an
    /// element to be pushed
    #[error("Not enough space in buffer to push data. Required: {0}, Available: {1}")]
    BufferFullError(usize, usize),
}
/// This is just an alias for std::backtrace::Backtrace that we
/// introduce to stop thiserror from using its backtrace
/// functionality, which depends on nightly APIs.
type ThisErrorHackBacktrace = std::backtrace::Backtrace;

/// An error encountered while setting up or manipulating a shared memory region
#[derive(Error, Debug)]
pub enum SharedMemoryError {
    /// Some operation on the shared memory attempted to read or write
    /// out of bounds
    #[error("Cannot access a value with size {0} at offset {1} in memory of size {2}")]
    Bounds(usize, usize, usize),

    /// When creating a memory with contents from a file, metadata for
    /// that file could not be read
    #[error("Could not access metadata for file: {0}")]
    FileMetadata(std::io::Error),

    /// When creating a memory with contents from a file, that file
    /// was logically larger than the range of a usize.
    #[error("File size exceeded usize: {0}")]
    FileTooLarge(std::num::TryFromIntError),

    /// The locking discipline used to enforce temporary exclusive
    /// access by the host to a shared memory failed in some way
    #[error("Could not acquire memory lock: {0} at {1}")]
    LockError(String, ThisErrorHackBacktrace),

    /// A request to allocate a shared memory could not be fulfilled
    /// by the host operating system
    #[error("Memory Allocation Failed with OS Error {0:?}.")]
    MemoryAllocationFailed(Option<i32>),

    /// A ruqest to allocate a shared shared memory had an invalid
    /// size, due either to bounds or alignment.
    #[error(
        "Memory request does not satisfy constraints: 0x{1:x} < 0x{0:x} <= 0x{2:x} && 0x{0:x} % 0x{3:x} = 0"
    )]
    MemoryRequest(usize, usize, usize, usize),

    /// An request to mmap a file or create an anonymous memory could
    /// not be fulfilled by the host operating system
    #[error("mmap failed with os error {0:?}")]
    MmapFailed(Option<i32>),

    /// A request to change the host-side permissions on the guard
    /// pages of a shared memory region could not be fulfilled by the
    /// host operating system
    #[error("mprotect failed with os error {0:?}")]
    MprotectFailed(Option<i32>),

    /// A Windows virtual memory API call failed
    #[cfg(target_os = "windows")]
    #[error("Windows API Error Result {0:?}")]
    WindowsAPIError(#[from] windows_result::Error),

    /// Calling code attempted to take exclusive (write) access to a
    /// [`ReadonlySharedMemory`].
    #[error("Cannot take exclusive access to a ReadonlySharedMemory")]
    ReadonlySharedMemoryExclusiveRequest,

    /// The stack discipline of guest I/O was violated in some way
    #[error("{0}")]
    Stack(#[from] StackError),

    /// An error was encountered when trying to convert a slice of raw
    /// bytes into some logical data
    #[error("Error reading slice {0}")]
    TryFromSlice(#[from] std::array::TryFromSliceError),

    /// An error was encountered during a routine error conversion
    /// that should have been infallible
    #[error("Error reading int: {0}")]
    TryFromInt(#[from] std::num::TryFromIntError),
}
impl<T> From<std::sync::TryLockError<T>> for SharedMemoryError {
    fn from(e: std::sync::TryLockError<T>) -> SharedMemoryError {
        SharedMemoryError::LockError(format!("{:?}", e), std::backtrace::Backtrace::capture())
    }
}

/// Makes sure that the given `offset` and `size` are within the bounds of the memory with size `mem_size`.
macro_rules! bounds_check {
    ($offset:expr, $size:expr, $mem_size:expr) => {
        if $offset.checked_add($size).is_none_or(|end| end > $mem_size) {
            return Err(SharedMemoryError::Bounds($offset, $size, $mem_size));
        }
    };
}

/// generates a reader function for the given type
macro_rules! generate_reader {
    ($fname:ident, $ty:ty) => {
        /// Read a value of type `$ty` from the memory at the given offset.
        #[allow(dead_code)]
        #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
        pub(crate) fn $fname(&self, offset: usize) -> Result<$ty> {
            let data = self.as_slice();
            bounds_check!(offset, std::mem::size_of::<$ty>(), data.len());
            Ok(<$ty>::from_le_bytes(
                data[offset..offset + std::mem::size_of::<$ty>()].try_into()?,
            ))
        }
    };
}

/// generates a writer function for the given type
macro_rules! generate_writer {
    ($fname:ident, $ty:ty) => {
        /// Write a value of type `$ty` to the memory at the given offset.
        #[allow(dead_code)]
        pub(crate) fn $fname(&mut self, offset: usize, value: $ty) -> Result<()> {
            let data = self.as_mut_slice();
            bounds_check!(offset, std::mem::size_of::<$ty>(), data.len());
            data[offset..offset + std::mem::size_of::<$ty>()].copy_from_slice(&value.to_le_bytes());
            Ok(())
        }
    };
}

/// A representation of a host mapping of a shared memory region,
/// which will be released when this structure is Drop'd. This is not
/// individually Clone (since it holds ownership of the mapping), or
/// Send or Sync, since it doesn't ensure any particular synchronization.
#[derive(Debug)]
pub struct HostMapping {
    #[cfg(not(target_os = "windows"))]
    mmap: Mmap,
    #[cfg(target_os = "windows")]
    mapping: WindowsMapping,
}

/// Windows-side flavors of a [`HostMapping`].
#[cfg(target_os = "windows")]
#[derive(Debug)]
enum WindowsMapping {
    /// `[guard][blob][guard]` carved from a single anonymous file
    /// mapping created via `CreateFileMappingA(INVALID_HANDLE_VALUE)`
    /// and mapped with `MapViewOfFile`.
    ///
    /// ```text
    /// |<------------------ view ------------------>|
    /// [   guard   ][         blob         ][   guard   ]
    /// ```
    Anonymous {
        view: MappedView,
        file_mapping: FileMapping,
    },
    /// File-backed: a `VirtualAlloc2` placeholder is split in three.
    /// The middle slot is replaced by a `MapViewOfFile3` view of the
    /// file. The flanking placeholder slots remain unmapped and act
    /// as the guard pages.
    ///
    /// ```text
    /// [ leading ][         view         ][ trailing ]
    /// ```
    FileBacked {
        leading: Placeholder,
        view: MappedView,
        trailing: Placeholder,
        file_mapping: FileMapping,
    },
}

impl HostMapping {
    /// Base address of the host mapping, including the surrounding guard pages.
    pub(crate) fn ptr(&self) -> *mut u8 {
        #[cfg(not(target_os = "windows"))]
        {
            self.mmap.base as *mut u8
        }
        #[cfg(target_os = "windows")]
        match &self.mapping {
            WindowsMapping::Anonymous { view, .. } => view.addr as *mut u8,
            WindowsMapping::FileBacked { leading, .. } => leading.addr as *mut u8,
        }
    }

    /// Total size of the host mapping, including the surrounding guard pages.
    pub(crate) fn size(&self) -> usize {
        #[cfg(not(target_os = "windows"))]
        {
            self.mmap.len
        }
        #[cfg(target_os = "windows")]
        match &self.mapping {
            WindowsMapping::Anonymous { view, .. } => view.len,
            WindowsMapping::FileBacked {
                leading,
                view,
                trailing,
                ..
            } => leading.size + view.len + trailing.size,
        }
    }

    /// Win32 file-mapping handle backing this mapping.
    #[cfg(target_os = "windows")]
    pub(crate) fn file_mapping_handle(&self) -> HANDLE {
        match &self.mapping {
            WindowsMapping::Anonymous { file_mapping, .. }
            | WindowsMapping::FileBacked { file_mapping, .. } => file_mapping.0,
        }
    }
}

/// RAII guard for an `mmap` reservation. Calls `munmap` on drop.
#[cfg(unix)]
#[derive(Debug)]
struct Mmap {
    base: *mut c_void,
    len: usize,
}

#[cfg(unix)]
impl Drop for Mmap {
    fn drop(&mut self) {
        // SAFETY: `self.base` and `self.len` are exactly what was
        // returned by the `mmap` that produced this `Mmap`, and that
        // mapping has not been unmapped (we own it).
        unsafe {
            if libc::munmap(self.base, self.len) != 0 {
                tracing::error!(
                    "Mmap::drop: munmap failed: {:?}",
                    std::io::Error::last_os_error()
                );
            }
        }
    }
}

/// RAII guard for a Win32 mapped view. Calls `UnmapViewOfFile` on drop.
#[cfg(target_os = "windows")]
#[derive(Debug)]
struct MappedView {
    addr: *mut c_void,
    len: usize,
}

#[cfg(target_os = "windows")]
impl Drop for MappedView {
    fn drop(&mut self) {
        let view = MEMORY_MAPPED_VIEW_ADDRESS { Value: self.addr };
        // Plain `UnmapViewOfFile` fully releases the address range.
        // `UnmapViewOfFile2(MEM_PRESERVE_PLACEHOLDER)` would convert
        // it back into a placeholder for remapping, which is not
        // what we want: the surrounding guard `Placeholder`s release
        // their slots independently on drop.
        // SAFETY: `self.addr` is the base address returned by the
        // `MapViewOfFile` call that produced this `MappedView`, and
        // the view has not been unmapped (we own it).
        if let Err(e) = unsafe { UnmapViewOfFile(view) } {
            tracing::error!(
                "MappedView::drop(addr={:?}, len={}) UnmapViewOfFile failed: {:?}",
                self.addr,
                self.len,
                e
            );
        }
    }
}

/// Owns a Win32 file-mapping `HANDLE`. Calls `CloseHandle` on drop.
#[cfg(target_os = "windows")]
#[derive(Debug)]
struct FileMapping(HANDLE);

#[cfg(target_os = "windows")]
impl Drop for FileMapping {
    fn drop(&mut self) {
        // SAFETY: `self.0` is a valid HANDLE returned by
        // `CreateFileMappingA` that has not been closed (we own it).
        unsafe {
            if let Err(e) = CloseHandle(self.0) {
                tracing::error!(
                    "FileMapping::drop(handle={:?}) CloseHandle failed: {:?}",
                    self.0,
                    e
                );
            }
        }
    }
}

/// RAII guard for a `VirtualAlloc2` placeholder reservation. Owns
/// the `[addr, addr + size)` range until split into smaller
/// placeholders, replaced by a mapped view, or dropped (which calls
/// `VirtualFree(MEM_RELEASE)`).
#[cfg(target_os = "windows")]
#[derive(Debug)]
pub(crate) struct Placeholder {
    addr: *mut c_void,
    size: usize,
}

#[cfg(target_os = "windows")]
impl Placeholder {
    fn reserve(size: usize) -> Result<Self> {
        // SAFETY: `VirtualAlloc2` with `MEM_RESERVE |
        // MEM_RESERVE_PLACEHOLDER` and `PAGE_NOACCESS` only reserves
        // address space. No pages are committed and no access is
        // granted, so the call has no preconditions and the returned
        // reservation cannot be misused from safe code.
        let addr = unsafe {
            VirtualAlloc2(
                None,
                None,
                size,
                VIRTUAL_ALLOCATION_TYPE(MEM_RESERVE.0 | MEM_RESERVE_PLACEHOLDER.0),
                PAGE_NOACCESS.0,
                None,
            )
        };
        if addr.is_null() {
            log_then_return!(SharedMemoryError::MemoryAllocationFailed(
                Error::last_os_error().raw_os_error()
            ));
        }
        Ok(Placeholder { addr, size })
    }

    fn split_front(self, front_size: usize) -> Result<(Placeholder, Placeholder)> {
        debug_assert!(front_size > 0 && front_size < self.size);
        debug_assert!(front_size.is_multiple_of(page_size::get()));
        // SAFETY: `self` owns the placeholder reservation at
        // `[self.addr, self.addr + self.size)`. `MEM_RELEASE |
        // MEM_PRESERVE_PLACEHOLDER` is the Win32 idiom for splitting
        // a placeholder in two: no memory is released, the
        // reservation is just carved at `front_size`.
        if let Err(e) = unsafe {
            VirtualFree(
                self.addr,
                front_size,
                VIRTUAL_FREE_TYPE(MEM_RELEASE.0 | MEM_PRESERVE_PLACEHOLDER.0),
            )
        } {
            // `self` drops here, releasing the unsplit reservation.
            log_then_return!(SharedMemoryError::WindowsAPIError(e.clone()));
        }
        let addr = self.addr;
        let total = self.size;
        // Forget the parent so its `Drop` does not release the two
        // child slots as one.
        std::mem::forget(self);
        let front = Placeholder {
            addr,
            size: front_size,
        };
        let back = Placeholder {
            // SAFETY: `front_size < total`, so `addr + front_size`
            // is in-bounds of the original reservation.
            addr: unsafe { (addr as *mut u8).add(front_size) as *mut c_void },
            size: total - front_size,
        };
        Ok((front, back))
    }

    fn split_into_three(
        self,
        front_size: usize,
        middle_size: usize,
    ) -> Result<(Placeholder, Placeholder, Placeholder)> {
        let (front, rest) = self.split_front(front_size)?;
        let (middle, back) = rest.split_front(middle_size)?;
        Ok((front, middle, back))
    }

    fn map_file_view(self, file_mapping: HANDLE) -> Result<MappedView> {
        // SAFETY: `self` owns the placeholder slot at
        // `[self.addr, self.addr + self.size)`.
        // `MEM_REPLACE_PLACEHOLDER` requires the target range to be
        // an existing placeholder of exactly that size, which the
        // type system guarantees here. On success, ownership of the
        // range transfers to the returned `MappedView`; the caller
        // releases the file mapping handle via `FileMapping`.
        let mapped = unsafe {
            MapViewOfFile3(
                file_mapping,
                None,
                Some(self.addr),
                0,
                self.size,
                MEM_REPLACE_PLACEHOLDER,
                PAGE_READONLY.0,
                None,
            )
        };
        if mapped.Value.is_null() {
            // `self` drops here, releasing the placeholder.
            log_then_return!(SharedMemoryError::MemoryAllocationFailed(
                Error::last_os_error().raw_os_error()
            ));
        }
        let addr = self.addr;
        let len = self.size;
        std::mem::forget(self);
        Ok(MappedView { addr, len })
    }
}

#[cfg(target_os = "windows")]
impl Drop for Placeholder {
    fn drop(&mut self) {
        // SAFETY: `self.addr` is the base of a placeholder
        // reservation we own. `MEM_RELEASE` with size 0 releases the
        // entire reservation.
        if let Err(e) = unsafe { VirtualFree(self.addr, 0, VIRTUAL_FREE_TYPE(MEM_RELEASE.0)) } {
            tracing::error!(
                "Placeholder::drop(addr={:?}, size={}) VirtualFree failed: {:?}",
                self.addr,
                self.size,
                e
            );
        }
    }
}

/// A trait that abstracts over the particular kind of SharedMemory,
/// used when invoking operations from Rust that absolutely must have
/// exclusive control over the shared memory for correctness +
/// performance, like snapshotting.
pub trait SharedMemory {
    /// Return a readonly reference to the host mapping backing this SharedMemory
    fn region(&self) -> &HostMapping;

    /// Return the base address of the host mapping of this
    /// region. Following the general Rust philosophy, this does not
    /// need to be marked as `unsafe` because doing anything with this
    /// pointer itself requires `unsafe`.
    fn base_addr(&self) -> usize {
        self.region().ptr() as usize + page_size::get()
    }

    /// Return the base address of the host mapping of this region as
    /// a pointer. Following the general Rust philosophy, this does
    /// not need to be marked as `unsafe` because doing anything with
    /// this pointer itself requires `unsafe`.
    fn base_ptr(&self) -> *mut u8 {
        self.region().ptr().wrapping_add(page_size::get())
    }

    /// Return the length of usable memory contained in `self`.
    /// The returned size does not include the size of the surrounding
    /// guard pages.
    fn mem_size(&self) -> usize {
        self.region().size() - 2 * page_size::get()
    }

    /// Return the raw base address of the host mapping, including the
    /// guard pages.
    fn raw_ptr(&self) -> *mut u8 {
        self.region().ptr()
    }

    /// Return the raw size of the host mapping, including the guard
    /// pages.
    fn raw_mem_size(&self) -> usize {
        self.region().size()
    }

    /// Extract a base address that can be mapped into a VM for this
    /// SharedMemory.
    ///
    /// On Linux this returns a raw `usize` pointer. On Windows it
    /// returns a [`HostRegionBase`](super::memory_region::HostRegionBase)
    /// that carries the file-mapping handle metadata needed by WHP.
    fn host_region_base(&self) -> <HostGuestMemoryRegion as MemoryRegionKind>::HostBaseType {
        #[cfg(not(windows))]
        {
            self.base_addr()
        }
        #[cfg(windows)]
        {
            super::memory_region::HostRegionBase {
                from_handle: self.region().file_mapping_handle().into(),
                handle_base: self.region().ptr() as usize,
                handle_size: self.region().size(),
                offset: page_size::get(),
            }
        }
    }

    /// Return the end address of the host region (base + usable size).
    fn host_region_end(&self) -> <HostGuestMemoryRegion as MemoryRegionKind>::HostBaseType {
        <HostGuestMemoryRegion as MemoryRegionKind>::add(self.host_region_base(), self.mem_size())
    }

    /// Run some code with exclusive access to the SharedMemory
    /// underlying this.  If the SharedMemory is not an
    /// ExclusiveSharedMemory, any concurrent accesses to the relevant
    /// HostSharedMemory/GuestSharedMemory may make this fail, or be
    /// made to fail by this, and should be avoided.
    fn with_exclusivity<T, F: FnOnce(&mut ExclusiveSharedMemory) -> T>(
        &mut self,
        f: F,
    ) -> Result<T>;

    /// Run some code that is allowed to access the contents of the
    /// SharedMemory as if it is a normal slice.  By default, this is
    /// implemented via [`SharedMemory::with_exclusivity`], which is
    /// the correct implementation for a memory that can be mutated,
    /// but a [`ReadonlySharedMemory`], can support this.
    fn with_contents<T, F: FnOnce(&[u8]) -> T>(&mut self, f: F) -> Result<T> {
        self.with_exclusivity(|m| f(m.as_slice()))
    }
}

fn mapping_at(
    s: &impl SharedMemory,
    gpa: u64,
    size: usize,
    region_type: MemoryRegionType,
    flags: MemoryRegionFlags,
) -> MemoryRegion {
    let guest_base = gpa as usize;

    MemoryRegion {
        guest_region: guest_base..(guest_base + size),
        host_region: s.host_region_base()
            ..<HostGuestMemoryRegion as MemoryRegionKind>::add(s.host_region_base(), size),
        region_type,
        flags,
    }
}

/// These three structures represent various phases of the lifecycle of
/// a memory buffer that is shared with the guest. An
/// ExclusiveSharedMemory is used for certain operations that
/// unrestrictedly write to the shared memory, including setting it up
/// and taking snapshots.
#[derive(Debug)]
pub struct ExclusiveSharedMemory {
    region: Arc<HostMapping>,
}
unsafe impl Send for ExclusiveSharedMemory {}

impl ExclusiveSharedMemory {
    /// Helper function used to abstract common checks from Windows
    /// and Linux implementations of [`ExclusiveSharedMemory::new()`]
    fn total_size(min_size_bytes: usize) -> Result<usize> {
        if min_size_bytes > 0 &&
            // guard page around the memory
            let Some(total_size) = min_size_bytes.checked_add(2 * page_size::get()) &&
            total_size % page_size::get() == 0 &&
            // usize and isize are guaranteed to be the same size, and
            // isize::MAX should be positive, so this cast should be
            // safe.
            total_size <= isize::MAX as usize
        {
            Ok(total_size)
        } else {
            Err(SharedMemoryError::MemoryRequest(
                min_size_bytes,
                2,
                isize::MAX as usize - 2 * page_size::get(),
                page_size::get(),
            ))
        }
    }

    /// Create a new region of shared memory with the given minimum
    /// size in bytes. The region will be surrounded by guard pages.
    ///
    /// Return `Err` if shared memory could not be allocated.
    #[cfg(unix)]
    #[instrument(skip_all, parent = Span::current(), level= "Trace")]
    pub fn new(min_size_bytes: usize) -> Result<Self> {
        use libc::{
            MAP_ANONYMOUS, MAP_FAILED, MAP_PRIVATE, PROT_READ, PROT_WRITE, c_int, mmap, off_t,
            size_t,
        };

        let total_size = Self::total_size(min_size_bytes)?;

        #[cfg(not(miri))]
        use libc::{MAP_NORESERVE, PROT_NONE, mprotect};

        // allocate the memory
        #[cfg(not(miri))]
        let flags = MAP_ANONYMOUS | MAP_PRIVATE | MAP_NORESERVE;
        #[cfg(miri)]
        let flags = MAP_ANONYMOUS | MAP_PRIVATE;

        let addr = unsafe {
            mmap(
                null_mut(),
                total_size as size_t,
                PROT_READ | PROT_WRITE,
                flags,
                -1 as c_int,
                0 as off_t,
            )
        };
        if addr == MAP_FAILED {
            log_then_return!(SharedMemoryError::MmapFailed(
                Error::last_os_error().raw_os_error()
            ));
        }
        let mmap = Mmap {
            base: addr,
            len: total_size,
        };

        // protect the guard pages
        #[cfg(not(miri))]
        {
            let res = unsafe { mprotect(mmap.base, page_size::get(), PROT_NONE) };
            if res != 0 {
                return Err(SharedMemoryError::MprotectFailed(
                    Error::last_os_error().raw_os_error(),
                ));
            }
            let res = unsafe {
                mprotect(
                    (mmap.base as *const u8).add(total_size - page_size::get()) as *mut c_void,
                    page_size::get(),
                    PROT_NONE,
                )
            };
            if res != 0 {
                return Err(SharedMemoryError::MprotectFailed(
                    Error::last_os_error().raw_os_error(),
                ));
            }
        }

        Ok(Self {
            // HostMapping is only non-Send/Sync because raw pointers
            // are not ("as a lint", as the Rust docs say). We don't
            // want to mark HostMapping Send/Sync immediately, because
            // that could socially imply that it's "safe" to use
            // unsafe accesses from multiple threads at once. Instead, we
            // directly impl Send and Sync on this type. Since this
            // type does have Send and Sync manually impl'd, the Arc
            // is not pointless as the lint suggests.
            #[allow(clippy::arc_with_non_send_sync)]
            region: Arc::new(HostMapping { mmap }),
        })
    }

    /// Create a new region of shared memory with the given minimum
    /// size in bytes. The region will be surrounded by guard pages.
    ///
    /// Return `Err` if shared memory could not be allocated.
    #[cfg(target_os = "windows")]
    #[instrument(skip_all, parent = Span::current(), level= "Trace")]
    pub fn new(min_size_bytes: usize) -> Result<Self> {
        let total_size = Self::total_size(min_size_bytes)?;

        let mut dwmaximumsizehigh = 0;
        let mut dwmaximumsizelow = 0;

        if std::mem::size_of::<usize>() == 8 {
            dwmaximumsizehigh = (total_size >> 32) as u32;
            dwmaximumsizelow = (total_size & 0xFFFFFFFF) as u32;
        }

        // Allocate the memory use CreateFileMapping instead of VirtualAlloc
        // This allows us to map the memory into the surrogate process using MapViewOfFile2

        let flags = PAGE_READWRITE;

        let handle = unsafe {
            CreateFileMappingA(
                INVALID_HANDLE_VALUE,
                None,
                flags,
                dwmaximumsizehigh,
                dwmaximumsizelow,
                PCSTR::null(),
            )?
        };

        if handle.is_invalid() {
            log_then_return!(SharedMemoryError::MemoryAllocationFailed(
                Error::last_os_error().raw_os_error()
            ));
        }
        let file_mapping = FileMapping(handle);

        let file_map = FILE_MAP_ALL_ACCESS;
        let addr = unsafe { MapViewOfFile(file_mapping.0, file_map, 0, 0, 0) };

        if addr.Value.is_null() {
            log_then_return!(SharedMemoryError::MemoryAllocationFailed(
                Error::last_os_error().raw_os_error()
            ));
        }
        let view = MappedView {
            addr: addr.Value,
            len: total_size,
        };

        // Set the first and last pages to be guard pages

        let mut unused_out_old_prot_flags = PAGE_PROTECTION_FLAGS(0);

        // If the following calls to VirtualProtect are changed make sure to update the calls to VirtualProtectEx in surrogate_process_manager.rs

        let first_guard_page_start = view.addr;
        if let Err(e) = unsafe {
            VirtualProtect(
                first_guard_page_start,
                page_size::get(),
                PAGE_NOACCESS,
                &mut unused_out_old_prot_flags,
            )
        } {
            log_then_return!(SharedMemoryError::WindowsAPIError(e.clone()));
        }

        let last_guard_page_start = unsafe { view.addr.add(total_size - page_size::get()) };
        if let Err(e) = unsafe {
            VirtualProtect(
                last_guard_page_start,
                page_size::get(),
                PAGE_NOACCESS,
                &mut unused_out_old_prot_flags,
            )
        } {
            log_then_return!(SharedMemoryError::WindowsAPIError(e.clone()));
        }

        Ok(Self {
            // HostMapping is only non-Send/Sync because raw pointers
            // are not ("as a lint", as the Rust docs say). We don't
            // want to mark HostMapping Send/Sync immediately, because
            // that could socially imply that it's "safe" to use
            // unsafe accesses from multiple threads at once. Instead, we
            // directly impl Send and Sync on this type. Since this
            // type does have Send and Sync manually impl'd, the Arc
            // is not pointless as the lint suggests.
            #[allow(clippy::arc_with_non_send_sync)]
            region: Arc::new(HostMapping {
                mapping: WindowsMapping::Anonymous { view, file_mapping },
            }),
        })
    }

    /// Internal helper method to get the backing memory as a mutable slice.
    ///
    /// # Safety
    /// As per std::slice::from_raw_parts_mut:
    /// - self.base_addr() must be valid for both reads and writes for
    ///   self.mem_size() * mem::size_of::<u8>() many bytes, and it
    ///   must be properly aligned.
    ///
    ///   The rules on validity are still somewhat unspecified, but we
    ///   assume that the result of our calls to mmap/CreateFileMappings may
    ///   be considered a single "allocated object". The use of
    ///   non-atomic accesses is alright from a Safe Rust standpoint,
    ///   because SharedMemoryBuilder is  not Sync.
    /// - self.base_addr() must point to self.mem_size() consecutive
    ///   properly initialized values of type u8
    ///
    ///   Again, the exact provenance restrictions on what is
    ///   considered to be initialized values are unclear, but we make
    ///   sure to use mmap(MAP_ANONYMOUS) and
    ///   CreateFileMapping(SEC_COMMIT), so the pages in question are
    ///   zero-initialized, which we hope counts for u8.
    /// - The memory referenced by the returned slice must not be
    ///   accessed through any other pointer (not derived from the
    ///   return value) for the duration of the lifetime 'a. Both read
    ///   and write accesses are forbidden.
    ///
    ///   Accesses from Safe Rust necessarily follow this rule,
    ///   because the returned slice's lifetime is the same as that of
    ///   a mutable borrow of self.
    /// - The total size self.mem_size() * mem::size_of::<u8>() of the
    ///   slice must be no larger than isize::MAX, and adding that
    ///   size to data must not "wrap around" the address space. See
    ///   the safety documentation of pointer::offset.
    ///
    ///   This is ensured by a check in ::new()
    pub(super) fn as_mut_slice(&mut self) -> &mut [u8] {
        unsafe { std::slice::from_raw_parts_mut(self.base_ptr(), self.mem_size()) }
    }

    /// Internal helper method to get the backing memory as a slice.
    ///
    /// # Safety
    /// See the discussion on as_mut_slice, with the third point
    /// replaced by:
    /// - The memory referenced by the returned slice must not be
    ///   mutated for the duration of lifetime 'a, except inside an
    ///   UnsafeCell.
    ///
    ///   Host accesses from Safe Rust necessarily follow this rule,
    ///   because the returned slice's lifetime is the same as that of
    ///   a borrow of self, preventing mutations via other methods.
    #[instrument(skip_all, parent = Span::current(), level= "Trace")]
    pub fn as_slice<'a>(&'a self) -> &'a [u8] {
        unsafe { std::slice::from_raw_parts(self.base_ptr(), self.mem_size()) }
    }

    /// Copy the entire contents of `self` into a `Vec<u8>`, then return it
    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
    #[cfg(test)]
    pub(crate) fn copy_all_to_vec(&self) -> Result<Vec<u8>> {
        let data = self.as_slice();
        Ok(data.to_vec())
    }

    /// Copies all bytes from `src` to `self` starting at offset
    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
    pub fn copy_from_slice(&mut self, src: &[u8], offset: usize) -> Result<()> {
        let data = self.as_mut_slice();
        bounds_check!(offset, src.len(), data.len());
        data[offset..offset + src.len()].copy_from_slice(src);
        Ok(())
    }

    generate_reader!(read_u8, u8);
    generate_reader!(read_i8, i8);
    generate_reader!(read_u16, u16);
    generate_reader!(read_i16, i16);
    generate_reader!(read_u32, u32);
    generate_reader!(read_i32, i32);
    generate_reader!(read_u64, u64);
    generate_reader!(read_i64, i64);
    generate_reader!(read_usize, usize);
    generate_reader!(read_isize, isize);

    generate_writer!(write_u8, u8);
    generate_writer!(write_i8, i8);
    generate_writer!(write_u16, u16);
    generate_writer!(write_i16, i16);
    generate_writer!(write_u32, u32);
    generate_writer!(write_i32, i32);
    generate_writer!(write_u64, u64);
    generate_writer!(write_i64, i64);
    generate_writer!(write_usize, usize);
    generate_writer!(write_isize, isize);

    /// Convert the ExclusiveSharedMemory, which may be freely
    /// modified, into a GuestSharedMemory, which may be somewhat
    /// freely modified (mostly by the guest), and a HostSharedMemory,
    /// which may only make certain kinds of accesses that do not race
    /// in the presence of malicious code inside the guest mutating
    /// the GuestSharedMemory.
    pub fn build(self) -> (HostSharedMemory, GuestSharedMemory) {
        let lock = Arc::new(RwLock::new(()));
        let hshm = HostSharedMemory {
            region: self.region.clone(),
            lock: lock.clone(),
        };
        (
            hshm,
            GuestSharedMemory {
                region: self.region.clone(),
                lock,
            },
        )
    }

    /// Gets the file handle of the shared memory region for this Sandbox
    #[cfg(target_os = "windows")]
    pub fn get_mmap_file_handle(&self) -> HANDLE {
        self.region.file_mapping_handle()
    }
}

impl SharedMemory for ExclusiveSharedMemory {
    fn region(&self) -> &HostMapping {
        &self.region
    }
    fn with_exclusivity<T, F: FnOnce(&mut ExclusiveSharedMemory) -> T>(
        &mut self,
        f: F,
    ) -> Result<T> {
        Ok(f(self))
    }
}

/// A GuestSharedMemory is used to represent
/// the reference to all-of-memory that is taken by the virtual cpu.
/// Because of the memory model limitations that affect
/// HostSharedMemory, it is likely fairly important (to ensure that
/// our UB remains limited to interaction with an external compilation
/// unit that likely can't be discovered by the compiler) that _rust_
/// users do not perform racy accesses to the guest communication
/// buffers that are also accessed by HostSharedMemory.
#[derive(Debug)]
pub struct GuestSharedMemory {
    region: Arc<HostMapping>,
    /// The lock that indicates this shared memory is being used by non-Rust code
    ///
    /// This lock _must_ be held whenever the guest is executing,
    /// because it prevents the host from converting its
    /// HostSharedMemory to an ExclusiveSharedMemory. Since the guest
    /// may arbitrarily mutate the shared memory, only synchronized
    /// accesses from Rust should be allowed!
    ///
    /// We cannot enforce this in the type system, because the memory
    /// is mapped in to the VM at VM creation time.
    pub lock: Arc<RwLock<()>>,
}
unsafe impl Send for GuestSharedMemory {}

impl GuestSharedMemory {
    /// Create a [`super::memory_region::MemoryRegion`] structure
    /// suitable for mapping this region into a VM
    pub(crate) fn mapping_at(
        &self,
        guest_base: u64,
        region_type: MemoryRegionType,
    ) -> MemoryRegion {
        let flags = match region_type {
            MemoryRegionType::Scratch => {
                MemoryRegionFlags::READ | MemoryRegionFlags::WRITE | MemoryRegionFlags::EXECUTE
            }
            #[cfg(unshared_snapshot_mem)]
            MemoryRegionType::Snapshot => {
                MemoryRegionFlags::READ | MemoryRegionFlags::WRITE | MemoryRegionFlags::EXECUTE
            }
            #[allow(clippy::panic)]
            // This will not ever actually panic: the only places this
            // is called are HyperlightVm::update_snapshot_mapping and
            // HyperlightVm::update_scratch_mapping. The latter
            // statically uses the Scratch region type, and the former
            // does not use this at all when the unshared_snapshot_mem
            // feature is not set, since in that case the scratch
            // mapping type is ReadonlySharedMemory, not
            // GuestSharedMemory.
            _ => panic!(
                "GuestSharedMemory::mapping_at should only be used for Scratch or Snapshot regions"
            ),
        };
        mapping_at(self, guest_base, self.mem_size(), region_type, flags)
    }
}

impl SharedMemory for GuestSharedMemory {
    fn region(&self) -> &HostMapping {
        &self.region
    }
    fn with_exclusivity<T, F: FnOnce(&mut ExclusiveSharedMemory) -> T>(
        &mut self,
        f: F,
    ) -> Result<T> {
        let guard = self.lock.try_write()?;
        let mut excl = ExclusiveSharedMemory {
            region: self.region.clone(),
        };
        let ret = f(&mut excl);
        drop(excl);
        drop(guard);
        Ok(ret)
    }
}

/// A HostSharedMemory allows synchronized accesses to guest
/// communication buffers, allowing it to be used concurrently with a
/// GuestSharedMemory.
///
/// # Concurrency model
///
/// Given future requirements for asynchronous I/O with a minimum
/// amount of copying (e.g. WASIp3 streams), we would like it to be
/// possible to safely access these buffers concurrently with the
/// guest, ensuring that (1) data is read appropriately if the guest
/// is well-behaved; and (2) the host's behaviour is defined
/// regardless of whether or not the guest is well-behaved.
///
/// The ideal (future) flow for a guest->host message is something like
///   - Guest writes (unordered) bytes describing a work item into a buffer
///   - Guest reveals buffer via a release-store of a pointer into an
///     MMIO ring-buffer
///   - Host acquire-loads the buffer pointer from the "MMIO" ring
///     buffer
///   - Host (unordered) reads the bytes from the buffer
///   - Host performs validation of those bytes and uses them
///
/// Unfortunately, there appears to be no way to do this with defined
/// behaviour in present Rust (see
/// e.g. <https://github.com/rust-lang/unsafe-code-guidelines/issues/152>).
/// Rust does not yet have its own defined memory model, but in the
/// interim, it is widely treated as inheriting the current C/C++
/// memory models.  The most immediate problem is that regardless of
/// anything else, under those memory models \[1, p. 17-18; 2, p. 88\],
///
///   > The execution of a program contains a _data race_ if it
///   > contains two [C++23: "potentially concurrent"] conflicting
///   > actions [C23: "in different threads"], at least one of which
///   > is not atomic, and neither happens before the other [C++23: ",
///   > except for the special case for signal handlers described
///   > below"].  Any such data race results in undefined behavior.
///
/// Consequently, if a misbehaving guest fails to correctly
/// synchronize its stores with the host, the host's innocent loads
/// will trigger undefined behaviour for the entire program, including
/// the host.  Note that this also applies if the guest makes an
/// unsynchronized read of a location that the host is writing!
///
/// Despite Rust's de jure inheritance of the C memory model at the
/// present time, the compiler in many cases de facto adheres to LLVM
/// semantics, so it is worthwhile to consider what LLVM does in this
/// case as well.  According to the the LangRef \[3\] memory model,
/// loads which are involved in a race that includes at least one
/// non-atomic access (whether the load or a store) return `undef`,
/// making them roughly equivalent to reading uninitialized
/// memory. While this is much better, it is still bad.
///
/// Considering a different direction, recent C++ papers have seemed
/// to lean towards using `volatile` for similar use cases. For
/// example, in P1152R0 \[4\], JF Bastien notes that
///
///   > We’ve shown that volatile is purposely defined to denote
///   > external modifications. This happens for:
///   >   - Shared memory with untrusted code, where volatile is the
///   >     right way to avoid time-of-check time-of-use (ToCToU)
///   >     races which lead to security bugs such as \[PWN2OWN\] and
///   >     \[XENXSA155\].
///
/// Unfortunately, although this paper was adopted for C++20 (and,
/// sadly, mostly un-adopted for C++23, although that does not concern
/// us), the paper did not actually redefine volatile accesses or data
/// races to prevent volatile accesses from racing with other accesses
/// and causing undefined behaviour.  P1382R1 \[5\] would have amended
/// the wording of the data race definition to specifically exclude
/// volatile, but, unfortunately, despite receiving a
/// generally-positive reception at its first WG21 meeting more than
/// five years ago, it has not progressed.
///
/// Separately from the data race issue, there is also a concern that
/// according to the various memory models in use, there may be ways
/// in which the guest can semantically obtain uninitialized memory
/// and write it into the shared buffer, which may also result in
/// undefined behaviour on reads.  The degree to which this is a
/// concern is unclear, however, since it is unclear to what degree
/// the Rust abstract machine's conception of uninitialized memory
/// applies to the sandbox.  Returning briefly to the LLVM level,
/// rather than the Rust level, this, combined with the fact that
/// racing loads in LLVM return `undef`, as discussed above, we would
/// ideally `llvm.freeze` the result of any load out of the sandbox.
///
/// It would furthermore be ideal if we could run the flatbuffers
/// parsing code directly on the guest memory, in order to avoid
/// unnecessary copies.  That is unfortunately probably not viable at
/// the present time: because the generated flatbuffers parsing code
/// doesn't use atomic or volatile accesses, it is likely to introduce
/// double-read vulnerabilities.
///
/// In short, none of the Rust-level operations available to us do the
/// right thing, at the Rust spec level or the LLVM spec level. Our
/// major remaining options are therefore:
///   - Choose one of the options that is available to us, and accept
///     that we are doing something unsound according to the spec, but
///     hope that no reasonable compiler could possibly notice.
///   - Use inline assembly per architecture, for which we would only
///     need to worry about the _architecture_'s memory model (which
///     is far less demanding).
///
/// The leading candidate for the first option would seem to be to
/// simply use volatile accesses; there seems to be wide agreement
/// that this _should_ be a valid use case for them (even if it isn't
/// now), and projects like Linux and rust-vmm already use C11
/// `volatile` for this purpose.  It is also worth noting that because
/// we still do need to synchronize with the guest when it _is_ being
/// well-behaved, we would ideally use volatile acquire loads and
/// volatile release stores for interacting with the stack pointer in
/// the guest in this case.  Unfortunately, while those operations are
/// defined in LLVM, they are not presently exposed to Rust. While
/// atomic fences that are not associated with memory accesses
/// ([`std::sync::atomic::fence`]) might at first glance seem to help with
/// this problem, they unfortunately do not \[6\]:
///
///    > A fence ‘A’ which has (at least) Release ordering semantics,
///    > synchronizes with a fence ‘B’ with (at least) Acquire
///    > semantics, if and only if there exist operations X and Y,
///    > both operating on some atomic object ‘M’ such that A is
///    > sequenced before X, Y is sequenced before B and Y observes
///    > the change to M. This provides a happens-before dependence
///    > between A and B.
///
/// Note that the X and Y must be to an _atomic_ object.
///
/// We consequently assume that there has been a strong architectural
/// fence on a vmenter/vmexit between data being read and written.
/// This is unsafe (not guaranteed in the type system)!
///
/// \[1\] N3047 C23 Working Draft. <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf>
/// \[2\] N4950 C++23 Working Draft. <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/n4950.pdf>
/// \[3\] LLVM Language Reference Manual, Memory Model for Concurrent Operations. <https://llvm.org/docs/LangRef.html#memmodel>
/// \[4\] P1152R0: Deprecating `volatile`. JF Bastien. <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1152r0.html>
/// \[5\] P1382R1: `volatile_load<T>` and `volatile_store<T>`. JF Bastien, Paul McKenney, Jeffrey Yasskin, and the indefatigable TBD. <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1382r1.pdf>
/// \[6\] Documentation for std::sync::atomic::fence. <https://doc.rust-lang.org/std/sync/atomic/fn.fence.html>
///
/// # Note \[Keeping mappings in sync between userspace and the guest\]
///
/// When using this structure with mshv on Linux, it is necessary to
/// be a little bit careful: since the hypervisor is not directly
/// integrated with the host kernel virtual memory subsystem, it is
/// easy for the memory region in userspace to get out of sync with
/// the memory region mapped into the guest.  Generally speaking, when
/// the [`SharedMemory`] is mapped into a partition, the MSHV kernel
/// module will call `pin_user_pages(FOLL_PIN|FOLL_WRITE)` on it,
/// which will eagerly do any CoW, etc needing to obtain backing pages
/// pinned in memory, and then map precisely those backing pages into
/// the virtual machine. After that, the backing pages mapped into the
/// VM will not change until the region is unmapped or remapped.  This
/// means that code in this module needs to be very careful to avoid
/// changing the backing pages of the region in the host userspace,
/// since that would result in hyperlight-host's view of the memory
/// becoming completely divorced from the view of the VM.
#[derive(Clone, Debug)]
pub struct HostSharedMemory {
    region: Arc<HostMapping>,
    lock: Arc<RwLock<()>>,
}
unsafe impl Send for HostSharedMemory {}

impl HostSharedMemory {
    /// Read a [`Pod`] value of type `T`, whose representation is the same
    /// between the sandbox and the host.
    pub fn read<T: Pod>(&self, offset: usize) -> Result<T> {
        bounds_check!(offset, std::mem::size_of::<T>(), self.mem_size());
        let mut ret = T::zeroed();
        self.copy_to_slice(bytemuck::bytes_of_mut(&mut ret), offset)?;
        Ok(ret)
    }

    /// Write a [`Pod`] value of type `T`, whose representation is the same
    /// between the sandbox and the host.
    pub fn write<T: Pod>(&self, offset: usize, data: T) -> Result<()> {
        bounds_check!(offset, std::mem::size_of::<T>(), self.mem_size());
        self.copy_from_slice(bytemuck::bytes_of(&data), offset)
    }

    /// Copy the contents of the slice into the sandbox at the
    /// specified offset
    pub fn copy_to_slice(&self, slice: &mut [u8], offset: usize) -> Result<()> {
        bounds_check!(offset, slice.len(), self.mem_size());
        let base = self.base_ptr().wrapping_add(offset);
        let guard = self.lock.try_read()?;

        const CHUNK: usize = size_of::<u128>();
        let len = slice.len();
        let mut i = 0;

        // Handle unaligned head bytes until we reach u128 alignment.
        // Note: align_offset can return usize::MAX if alignment is impossible.
        // In that case, head_len = len via .min(), so we fall back to byte-by-byte
        // operations for the entire slice.
        let align_offset = base.align_offset(align_of::<u128>());
        let head_len = align_offset.min(len);
        while i < head_len {
            unsafe {
                slice[i] = base.add(i).read_volatile();
            }
            i += 1;
        }

        // Read aligned u128 chunks
        // SAFETY: After processing head_len bytes, base.add(i) is u128-aligned.
        // We use write_unaligned for the destination since the slice may not be u128-aligned.
        let dst = slice.as_mut_ptr();
        while i + CHUNK <= len {
            unsafe {
                let value = (base.add(i) as *const u128).read_volatile();
                std::ptr::write_unaligned(dst.add(i) as *mut u128, value);
            }
            i += CHUNK;
        }

        // Handle remaining tail bytes
        while i < len {
            unsafe {
                slice[i] = base.add(i).read_volatile();
            }
            i += 1;
        }

        drop(guard);
        Ok(())
    }

    /// Copy the contents of the sandbox at the specified offset into
    /// the slice
    pub fn copy_from_slice(&self, slice: &[u8], offset: usize) -> Result<()> {
        bounds_check!(offset, slice.len(), self.mem_size());
        let base = self.base_ptr().wrapping_add(offset);
        let guard = self.lock.try_read()?;

        const CHUNK: usize = size_of::<u128>();
        let len = slice.len();
        let mut i = 0;

        // Handle unaligned head bytes until we reach u128 alignment.
        // Note: align_offset can return usize::MAX if alignment is impossible.
        // In that case, head_len = len via .min(), so we fall back to byte-by-byte
        // operations for the entire slice.
        let align_offset = base.align_offset(align_of::<u128>());
        let head_len = align_offset.min(len);
        while i < head_len {
            unsafe {
                base.add(i).write_volatile(slice[i]);
            }
            i += 1;
        }

        // Write aligned u128 chunks
        // SAFETY: After processing head_len bytes, base.add(i) is u128-aligned.
        // We use read_unaligned for the source since the slice may not be u128-aligned.
        let src = slice.as_ptr();
        while i + CHUNK <= len {
            unsafe {
                let value = std::ptr::read_unaligned(src.add(i) as *const u128);
                (base.add(i) as *mut u128).write_volatile(value);
            }
            i += CHUNK;
        }

        // Handle remaining tail bytes
        while i < len {
            unsafe {
                base.add(i).write_volatile(slice[i]);
            }
            i += 1;
        }

        drop(guard);
        Ok(())
    }

    /// Fill the memory in the range `[offset, offset + len)` with `value`
    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
    pub fn fill(&mut self, value: u8, offset: usize, len: usize) -> Result<()> {
        bounds_check!(offset, len, self.mem_size());
        let base = self.base_ptr().wrapping_add(offset);
        let guard = self.lock.try_read()?;

        const CHUNK: usize = size_of::<u128>();
        let value_u128 = u128::from_ne_bytes([value; CHUNK]);
        let mut i = 0;

        // Handle unaligned head bytes until we reach u128 alignment.
        // Note: align_offset can return usize::MAX if alignment is impossible.
        // In that case, head_len = len via .min(), so we fall back to byte-by-byte
        // operations for the entire slice.
        let align_offset = base.align_offset(align_of::<u128>());
        let head_len = align_offset.min(len);
        while i < head_len {
            unsafe {
                base.add(i).write_volatile(value);
            }
            i += 1;
        }

        // Write aligned u128 chunks
        // SAFETY: After processing head_len bytes, base.add(i) is u128-aligned
        while i + CHUNK <= len {
            unsafe {
                (base.add(i) as *mut u128).write_volatile(value_u128);
            }
            i += CHUNK;
        }

        // Handle remaining tail bytes
        while i < len {
            unsafe {
                base.add(i).write_volatile(value);
            }
            i += 1;
        }

        drop(guard);
        Ok(())
    }

    /// Pushes the given data onto shared memory to the buffer at the given offset.
    /// NOTE! buffer_start_offset must point to the beginning of the buffer
    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
    pub fn push_buffer(
        &mut self,
        buffer_start_offset: usize,
        buffer_size: usize,
        data: &[u8],
    ) -> Result<()> {
        let stack_pointer_rel = self.read::<u64>(buffer_start_offset)? as usize;

        if stack_pointer_rel > buffer_size || stack_pointer_rel < 8 {
            Err(StackError::SpOob(
                StackOp::Push,
                stack_pointer_rel,
                buffer_size,
            ))?;
        }

        let size_required = data.len() + 8;
        let size_available = buffer_size - stack_pointer_rel;

        if size_required > size_available {
            Err(StackError::BufferFullError(size_required, size_available))?;
        }

        // get absolute
        let stack_pointer_abs = stack_pointer_rel + buffer_start_offset;

        // write the actual data to the top of stack
        self.copy_from_slice(data, stack_pointer_abs)?;

        // write the offset to the newly written data, to the top of stack.
        // this is used when popping the stack, to know how far back to jump
        self.write::<u64>(stack_pointer_abs + data.len(), stack_pointer_rel as u64)?;

        // update stack pointer to point to the next free address
        self.write::<u64>(
            buffer_start_offset,
            (stack_pointer_rel + data.len() + 8) as u64,
        )?;
        Ok(())
    }

    /// Pops the given given buffer into a `T` and returns it.
    /// NOTE! the data must be a size-prefixed flatbuffer, and
    /// buffer_start_offset must point to the beginning of the buffer
    pub fn try_pop_buffer_into<T>(
        &mut self,
        buffer_start_offset: usize,
        buffer_size: usize,
    ) -> Result<T>
    where
        T: for<'b> TryFrom<&'b [u8]>,
    {
        // get the stackpointer
        let stack_pointer_rel = self.read::<u64>(buffer_start_offset)? as usize;

        if stack_pointer_rel > buffer_size || stack_pointer_rel < 16 {
            Err(StackError::SpOob(
                StackOp::Pop,
                stack_pointer_rel,
                buffer_size,
            ))?;
        }

        // make it absolute
        let last_element_offset_abs = stack_pointer_rel + buffer_start_offset;

        // go back 8 bytes to get offset to element on top of stack
        let last_element_offset_rel: usize =
            self.read::<u64>(last_element_offset_abs - 8)? as usize;

        // Validate element offset (guest-writable): must be in [8, stack_pointer_rel - 16]
        // to leave room for the 8-byte back-pointer plus at least 8 bytes of element data
        // (the minimum for a size-prefixed flatbuffer: 4-byte prefix + 4-byte root offset).
        if last_element_offset_rel > stack_pointer_rel.saturating_sub(16)
            || last_element_offset_rel < 8
        {
            Err(StackError::CorruptBackPointer(
                last_element_offset_rel,
                stack_pointer_rel.saturating_sub(16),
            ))?;
        }

        // make it absolute
        let last_element_offset_abs = last_element_offset_rel + buffer_start_offset;

        // Max bytes the element can span (excluding the 8-byte back-pointer).
        let max_element_size = stack_pointer_rel - last_element_offset_rel - 8;

        // Get the size of the flatbuffer buffer from memory
        let fb_buffer_size = {
            let raw_prefix = self.read::<u32>(last_element_offset_abs)?;
            // flatbuffer byte arrays are prefixed by 4 bytes indicating
            // the remaining size; add 4 for the prefix itself.
            let total = raw_prefix
                .checked_add(4)
                .ok_or(StackError::OverflowingPrefix(raw_prefix))?;
            usize::try_from(total).map_err(StackError::PrefixTooLarge)?
        };

        if fb_buffer_size > max_element_size {
            Err(StackError::CorruptPrefix(fb_buffer_size, max_element_size))?;
        }

        let mut result_buffer = vec![0; fb_buffer_size];

        self.copy_to_slice(&mut result_buffer, last_element_offset_abs)?;
        let to_return = T::try_from(result_buffer.as_slice())
            .map_err(|_| StackError::ConvertError(type_name::<T>().to_string()))?;

        // update the stack pointer to point to the element we just popped off since that is now free
        self.write::<u64>(buffer_start_offset, last_element_offset_rel as u64)?;

        // zero out the memory we just popped off
        let num_bytes_to_zero = stack_pointer_rel - last_element_offset_rel;
        self.fill(0, last_element_offset_abs, num_bytes_to_zero)?;

        Ok(to_return)
    }
}

impl HostSharedMemory {
    /// Reset this memory region to all-zeros, choosing the fastest
    /// strategy for the current platform and hypervisor configuration.
    ///
    /// On Linux/KVM (without mshv3), uses `MADV_DONTNEED` for lazy
    /// zeroing.  On Linux/mshv3, falls through to `fill(0)`.
    ///
    /// On Windows, zeroing via `fill(0)` is prohibitively expensive
    /// for large regions (e.g. 448 MiB scratch).  Instead, the
    /// mapping is replaced with a fresh demand-zero allocation.
    /// Returns `Some(GuestSharedMemory)` when the mapping was
    /// replaced (the caller must update the VM mapping), or `None`
    /// when zeroed in place.
    ///
    // TODO: Find the break-even point between zero-in-place and
    // replace for each hypervisor and use a size-based heuristic
    // instead of a compile-time platform check.
    pub(crate) fn zero_or_replace(&mut self) -> Result<Option<GuestSharedMemory>> {
        #[cfg(target_os = "windows")]
        {
            let new_mem = ExclusiveSharedMemory::new(self.mem_size())?;
            let (hscratch, gscratch) = new_mem.build();
            *self = hscratch;
            Ok(Some(gscratch))
        }
        #[cfg(not(target_os = "windows"))]
        {
            self.with_exclusivity(|e| {
                #[allow(unused_mut)]
                let mut do_copy = true;
                // TODO: Find a similar lazy zeroing approach that works on MSHV.
                //       (See Note [Keeping mappings in sync between userspace and the guest])
                #[cfg(all(feature = "kvm", not(any(feature = "mshv3"))))]
                unsafe {
                    let ret = libc::madvise(
                        e.region.ptr() as *mut libc::c_void,
                        e.region.size(),
                        libc::MADV_DONTNEED,
                    );
                    if ret == 0 {
                        do_copy = false;
                    }
                }
                if do_copy {
                    e.as_mut_slice().fill(0);
                }
            })?;
            Ok(None)
        }
    }
}

impl SharedMemory for HostSharedMemory {
    fn region(&self) -> &HostMapping {
        &self.region
    }
    fn with_exclusivity<T, F: FnOnce(&mut ExclusiveSharedMemory) -> T>(
        &mut self,
        f: F,
    ) -> Result<T> {
        let guard = self.lock.try_write()?;
        let mut excl = ExclusiveSharedMemory {
            region: self.region.clone(),
        };
        let ret = f(&mut excl);
        drop(excl);
        drop(guard);
        Ok(ret)
    }
}

/// A ReadonlySharedMemory is a different kind of shared memory,
/// separate from the exclusive/host/guest lifecycle, used to
/// represent read-only mappings of snapshot pages into the guest
/// efficiently.
#[derive(Clone, Debug)]
pub struct ReadonlySharedMemory {
    region: Arc<HostMapping>,
    /// Number of bytes from the start of the blob that `mapping_at`
    /// exposes to the guest. Production callers pass the size of the
    /// guest-visible prefix of the snapshot blob; the remainder of
    /// the blob is the page-table tail that lives only host-side.
    #[cfg_attr(unshared_snapshot_mem, allow(dead_code))]
    guest_mapped_size: usize,
}
// Safety: HostMapping is only non-Send/Sync (causing
// ReadonlySharedMemory to not be automatically Send/Sync) because raw
// pointers are not ("as a lint", as the Rust docs say). We don't want
// to mark HostMapping Send/Sync immediately, because that could
// socially imply that it's "safe" to use unsafe accesses from
// multiple threads at once in more cases, including ones that don't
// actually ensure immutability/synchronisation. Since
// ReadonlySharedMemory can only be accessed by reading, and reading
// concurrently from multiple threads is not racy,
// ReadonlySharedMemory can be Send and Sync.
unsafe impl Send for ReadonlySharedMemory {}
unsafe impl Sync for ReadonlySharedMemory {}

impl ReadonlySharedMemory {
    pub(crate) fn from_bytes(contents: &[u8], guest_mapped_size: usize) -> Result<Self> {
        if guest_mapped_size == 0
            || guest_mapped_size > contents.len()
            || !guest_mapped_size.is_multiple_of(page_size::get())
        {
            return Err(SharedMemoryError::MemoryRequest(
                guest_mapped_size,
                0,
                contents.len(),
                page_size::get(),
            ));
        }
        let mut anon =
            ExclusiveSharedMemory::new(contents.len().next_multiple_of(page_size::get()))?;
        anon.copy_from_slice(contents, 0)?;
        Ok(ReadonlySharedMemory {
            region: anon.region,
            guest_mapped_size,
        })
    }

    /// The number of bytes that should be mapped into guest PA space.
    #[cfg(not(unshared_snapshot_mem))]
    pub(crate) fn guest_mapped_size(&self) -> usize {
        self.guest_mapped_size
    }

    /// Create a `ReadonlySharedMemory` backed by a file on disk.
    ///
    /// The file's length must be a non-zero multiple of `PAGE_SIZE`.
    /// `guest_mapped_size` must be a non-zero multiple of `PAGE_SIZE`
    /// no greater than the file's length.
    pub(crate) fn from_file(file: &std::fs::File, guest_mapped_size: usize) -> Result<Self> {
        let len: usize = file
            .metadata()
            .map_err(SharedMemoryError::FileMetadata)?
            .len()
            .try_into()
            .map_err(SharedMemoryError::FileTooLarge)?;

        if len == 0 || !len.is_multiple_of(page_size::get()) {
            return Err(SharedMemoryError::MemoryRequest(
                len,
                0,
                usize::MAX,
                page_size::get(),
            ));
        }

        if guest_mapped_size == 0
            || guest_mapped_size > len
            || !guest_mapped_size.is_multiple_of(page_size::get())
        {
            return Err(SharedMemoryError::MemoryRequest(
                guest_mapped_size,
                0,
                len,
                page_size::get(),
            ));
        }

        let region = Self::map_file(file, len)?;
        Ok(ReadonlySharedMemory {
            region,
            guest_mapped_size,
        })
    }

    /// Linux: reserve `[guard][blob][guard]` as one anonymous
    /// `PROT_NONE` mapping, then `MAP_FIXED` the file over the
    /// middle slot.
    #[cfg(unix)]
    fn map_file(file: &std::fs::File, len: usize) -> Result<Arc<HostMapping>> {
        use std::os::unix::io::AsRawFd;

        #[cfg(mshv3)]
        use libc::PROT_WRITE;
        use libc::{
            MAP_ANONYMOUS, MAP_FAILED, MAP_FIXED, MAP_NORESERVE, MAP_PRIVATE, PROT_NONE, PROT_READ,
            mmap, off_t, size_t,
        };

        let total_size =
            len.checked_add(2 * page_size::get())
                .ok_or(SharedMemoryError::MemoryRequest(
                    len,
                    0,
                    usize::MAX - 2 * page_size::get(),
                    1,
                ))?;

        let fd = file.as_raw_fd();

        // 1. Reserve the full `[guard][blob][guard]` address range as
        //    one anonymous `PROT_NONE` mapping. This pins the layout
        //    and gives us a single RAII owner for the whole region.
        // SAFETY: anonymous `mmap` with a null address has no
        // preconditions; the kernel picks the address.
        let base = unsafe {
            mmap(
                null_mut(),
                total_size as size_t,
                PROT_NONE,
                MAP_ANONYMOUS | MAP_PRIVATE | MAP_NORESERVE,
                -1,
                0 as off_t,
            )
        };
        if base == MAP_FAILED {
            return Err(SharedMemoryError::MmapFailed(
                std::io::Error::last_os_error().raw_os_error(),
            ));
        }
        let reservation = Mmap {
            base,
            len: total_size,
        };

        // 2. Overlay the file content on the middle slot with
        //    `MAP_FIXED`. `MAP_PRIVATE` keeps the mapping detached
        //    from the underlying file.
        //
        //    MSHV's map_user_memory requires host-writable pages
        //    (the kernel module calls `pin_user_pages(FOLL_PIN|FOLL_WRITE)`
        //    on the region when it is mapped into the partition).
        //    KVM accepts read-only host pages for read-only guest slots.
        #[cfg(mshv3)]
        let file_prot = PROT_READ | PROT_WRITE;
        #[cfg(not(mshv3))]
        let file_prot = PROT_READ;
        // SAFETY: `total_size = len + 2 * PAGE_SIZE_USIZE`, so
        // `base + PAGE_SIZE_USIZE` is in-bounds of the reservation.
        let usable_ptr = unsafe { (base as *mut u8).add(page_size::get()) };
        // SAFETY: `usable_ptr..usable_ptr + len` lies entirely within
        // the reservation owned by `reservation`. `MAP_FIXED`
        // replaces that sub-range in place; on failure the
        // surrounding anonymous mapping is unaffected and
        // `reservation` releases it on drop.
        let mapped = unsafe {
            mmap(
                usable_ptr as *mut c_void,
                len as size_t,
                file_prot,
                MAP_PRIVATE | MAP_FIXED | MAP_NORESERVE,
                fd,
                0 as off_t,
            )
        };
        if mapped == MAP_FAILED {
            return Err(SharedMemoryError::MmapFailed(
                std::io::Error::last_os_error().raw_os_error(),
            ));
        }

        // 3. The first and last pages keep their `PROT_NONE` from the
        //    anonymous reservation, so no extra `mprotect` is needed.

        #[allow(clippy::arc_with_non_send_sync)]
        Ok(Arc::new(HostMapping { mmap: reservation }))
    }

    /// Windows: reserve `[guard][blob][guard]` as one
    /// `VirtualAlloc2` placeholder, split the middle slot out, and
    /// `MapViewOfFile3` the file over the middle slot.
    #[cfg(target_os = "windows")]
    fn map_file(file: &std::fs::File, len: usize) -> Result<Arc<HostMapping>> {
        use std::os::windows::io::AsRawHandle;

        let total_size =
            len.checked_add(2 * page_size::get())
                .ok_or(SharedMemoryError::MemoryRequest(
                    len,
                    0,
                    usize::MAX - 2 * page_size::get(),
                    1,
                ))?;

        let file_handle = HANDLE(file.as_raw_handle());

        // 1. Reserve the full `[guard][blob][guard]` address range
        //    as one `VirtualAlloc2` placeholder.
        let whole = Placeholder::reserve(total_size)?;

        // 2. Split the placeholder into three adjacent slots. The
        //    leading and trailing slots stay unmapped and act as
        //    guard pages. The middle slot will receive the file view.
        let (leading, middle, trailing) = whole.split_into_three(page_size::get(), len)?;

        // 3. Create a read-only file mapping section over the file.
        // SAFETY: `file_handle` is a valid file HANDLE borrowed from
        // `file` for the duration of this call. `CreateFileMappingA`
        // returns a new handle that we wrap in `FileMapping` below.
        let raw_handle =
            unsafe { CreateFileMappingA(file_handle, None, PAGE_READONLY, 0, 0, PCSTR::null()) }?;
        if raw_handle.is_invalid() {
            log_then_return!(SharedMemoryError::MemoryAllocationFailed(
                Error::last_os_error().raw_os_error()
            ));
        }
        let file_mapping = FileMapping(raw_handle);

        // 4. Replace the middle placeholder slot with a view of the
        //    file mapping via `MapViewOfFile3(MEM_REPLACE_PLACEHOLDER)`.
        let view = middle.map_file_view(raw_handle)?;

        #[allow(clippy::arc_with_non_send_sync)]
        Ok(Arc::new(HostMapping {
            mapping: WindowsMapping::FileBacked {
                leading,
                view,
                trailing,
                file_mapping,
            },
        }))
    }

    pub(crate) fn as_slice(&self) -> &[u8] {
        unsafe { std::slice::from_raw_parts(self.base_ptr(), self.mem_size()) }
    }

    #[cfg(unshared_snapshot_mem)]
    pub(crate) fn copy_to_writable(&self) -> Result<ExclusiveSharedMemory> {
        let mut writable = ExclusiveSharedMemory::new(self.mem_size())?;
        writable.copy_from_slice(self.as_slice(), 0)?;
        Ok(writable)
    }

    #[cfg(not(unshared_snapshot_mem))]
    pub(crate) fn build(self) -> (Self, Self) {
        (self.clone(), self)
    }

    #[cfg(not(unshared_snapshot_mem))]
    pub(crate) fn mapping_at(
        &self,
        guest_base: u64,
        region_type: MemoryRegionType,
    ) -> MemoryRegion {
        #[allow(clippy::panic)]
        // This will not ever actually panic: the only place this is
        // called is HyperlightVm::update_snapshot_mapping, which
        // always calls it with the Snapshot region type.
        if region_type != MemoryRegionType::Snapshot {
            panic!("ReadonlySharedMemory::mapping_at should only be used for Snapshot regions");
        }
        mapping_at(
            self,
            guest_base,
            self.guest_mapped_size(),
            region_type,
            MemoryRegionFlags::READ | MemoryRegionFlags::EXECUTE,
        )
    }
}

impl SharedMemory for ReadonlySharedMemory {
    fn region(&self) -> &HostMapping {
        &self.region
    }
    // Trait defaults work for `base_addr`, `base_ptr`, and
    // `mem_size`: each `ReadonlySharedMemory` has the
    // `[guard][blob][guard]` layout.
    //
    // `host_region_base` differs per Windows mapping flavour:
    //  * `WindowsMapping::Anonymous` (`from_bytes`): file mapping
    //    spans the whole region. Same as the trait default.
    //  * `WindowsMapping::FileBacked` (`from_file`): file mapping
    //    covers only the blob. Expose only the blob to the surrogate.
    #[cfg(windows)]
    fn host_region_base(&self) -> <HostGuestMemoryRegion as MemoryRegionKind>::HostBaseType {
        match &self.region().mapping {
            WindowsMapping::Anonymous { .. } => super::memory_region::HostRegionBase {
                from_handle: self.region().file_mapping_handle().into(),
                handle_base: self.region().ptr() as usize,
                handle_size: self.region().size(),
                offset: page_size::get(),
            },
            WindowsMapping::FileBacked { .. } => super::memory_region::HostRegionBase {
                from_handle: self.region().file_mapping_handle().into(),
                handle_base: self.base_ptr() as usize,
                handle_size: self.mem_size(),
                offset: 0,
            },
        }
    }
    // There's no way to get exclusive (and therefore writable) access
    // to a ReadonlySharedMemory.
    fn with_exclusivity<T, F: FnOnce(&mut ExclusiveSharedMemory) -> T>(
        &mut self,
        _: F,
    ) -> Result<T> {
        Err(SharedMemoryError::ReadonlySharedMemoryExclusiveRequest)
    }
    // However, just access to the contents as a slice is doable
    fn with_contents<T, F: FnOnce(&[u8]) -> T>(&mut self, f: F) -> Result<T> {
        Ok(f(self.as_slice()))
    }
}

impl<S: SharedMemory> PartialEq<S> for ReadonlySharedMemory {
    fn eq(&self, other: &S) -> bool {
        self.raw_ptr() == other.raw_ptr()
    }
}

#[cfg(test)]
mod tests {
    #[cfg(not(miri))]
    use proptest::prelude::*;

    #[cfg(not(miri))]
    use super::HostSharedMemory;
    use super::{ExclusiveSharedMemory, Result, SharedMemory};
    #[cfg(not(miri))]
    use crate::mem::shared_mem_tests::read_write_test_suite;

    #[test]
    fn fill() {
        let mem_size: usize = page_size::get();
        let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
        let (mut hshm, _) = eshm.build();

        hshm.fill(1, 0, 1024).unwrap();
        hshm.fill(2, 1024, 1024).unwrap();
        hshm.fill(3, 2048, 1024).unwrap();
        hshm.fill(4, 3072, 1024).unwrap();

        let vec = hshm
            .with_exclusivity(|e| e.copy_all_to_vec().unwrap())
            .unwrap();

        assert!(vec[0..1024].iter().all(|&x| x == 1));
        assert!(vec[1024..2048].iter().all(|&x| x == 2));
        assert!(vec[2048..3072].iter().all(|&x| x == 3));
        assert!(vec[3072..4096].iter().all(|&x| x == 4));

        hshm.fill(5, 0, mem_size).unwrap();

        let vec2 = hshm
            .with_exclusivity(|e| e.copy_all_to_vec().unwrap())
            .unwrap();
        assert!(vec2.iter().all(|&x| x == 5));

        assert!(hshm.fill(0, 0, mem_size + 1).is_err());
        assert!(hshm.fill(0, mem_size, 1).is_err());
    }

    /// Verify that `bounds_check!` rejects offset + size combinations that
    /// would overflow `usize`.
    #[test]
    fn bounds_check_overflow() {
        let mem_size: usize = page_size::get();
        let mut eshm = ExclusiveSharedMemory::new(mem_size).unwrap();

        // ExclusiveSharedMemory methods
        assert!(eshm.read_i32(usize::MAX).is_err());
        assert!(eshm.write_i32(usize::MAX, 0).is_err());
        assert!(eshm.copy_from_slice(&[0u8; 1], usize::MAX).is_err());

        // HostSharedMemory methods
        let (mut hshm, _) = eshm.build();

        assert!(hshm.read::<u8>(usize::MAX).is_err());
        assert!(hshm.read::<u64>(usize::MAX - 3).is_err());
        assert!(hshm.write::<u8>(usize::MAX, 0).is_err());
        assert!(hshm.write::<u64>(usize::MAX - 3, 0).is_err());

        let mut buf = [0u8; 1];
        assert!(hshm.copy_to_slice(&mut buf, usize::MAX).is_err());
        assert!(hshm.copy_from_slice(&[0u8; 1], usize::MAX).is_err());

        assert!(hshm.fill(0, usize::MAX, 1).is_err());
        assert!(hshm.fill(0, 1, usize::MAX).is_err());
    }

    #[test]
    fn copy_into_from() -> Result<()> {
        let mem_size: usize = page_size::get();
        let vec_len = 10;
        let eshm = ExclusiveSharedMemory::new(mem_size)?;
        let (hshm, _) = eshm.build();
        let vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
        // write the value to the memory at the beginning.
        hshm.copy_from_slice(&vec, 0)?;

        let mut vec2 = vec![0; vec_len];
        // read the value back from the memory at the beginning.
        hshm.copy_to_slice(vec2.as_mut_slice(), 0)?;
        assert_eq!(vec, vec2);

        let offset = mem_size - vec.len();
        // write the value to the memory at the end.
        hshm.copy_from_slice(&vec, offset)?;

        let mut vec3 = vec![0; vec_len];
        // read the value back from the memory at the end.
        hshm.copy_to_slice(&mut vec3, offset)?;
        assert_eq!(vec, vec3);

        let offset = mem_size / 2;
        // write the value to the memory at the middle.
        hshm.copy_from_slice(&vec, offset)?;

        let mut vec4 = vec![0; vec_len];
        // read the value back from the memory at the middle.
        hshm.copy_to_slice(&mut vec4, offset)?;
        assert_eq!(vec, vec4);

        // try and read a value from an offset that is beyond the end of the memory.
        let mut vec5 = vec![0; vec_len];
        assert!(hshm.copy_to_slice(&mut vec5, mem_size).is_err());

        // try and write a value to an offset that is beyond the end of the memory.
        assert!(hshm.copy_from_slice(&vec5, mem_size).is_err());

        // try and read a value from an offset that is too large.
        let mut vec6 = vec![0; vec_len];
        assert!(hshm.copy_to_slice(&mut vec6, mem_size * 2).is_err());

        // try and write a value to an offset that is too large.
        assert!(hshm.copy_from_slice(&vec6, mem_size * 2).is_err());

        // try and read a value that is too large.
        let mut vec7 = vec![0; mem_size * 2];
        assert!(hshm.copy_to_slice(&mut vec7, 0).is_err());

        // try and write a value that is too large.
        assert!(hshm.copy_from_slice(&vec7, 0).is_err());

        Ok(())
    }

    // proptest uses file I/O (getcwd, open) which miri doesn't support
    #[cfg(not(miri))]
    proptest! {
        #[test]
        fn read_write_i32(val in -0x1000_i32..0x1000_i32) {
            read_write_test_suite(
                val,
                ExclusiveSharedMemory::new,
                Box::new(ExclusiveSharedMemory::read_i32),
                Box::new(ExclusiveSharedMemory::write_i32),
            )
            .unwrap();
            read_write_test_suite(
                val,
                |s| {
                    let e = ExclusiveSharedMemory::new(s)?;
                    let (h, _) = e.build();
                    Ok(h)
                },
                Box::new(HostSharedMemory::read::<i32>),
                Box::new(|h, o, v| h.write::<i32>(o, v)),
            )
            .unwrap();
        }
    }

    #[test]
    fn alloc_fail() {
        let gm = ExclusiveSharedMemory::new(0);
        assert!(gm.is_err());
        let gm = ExclusiveSharedMemory::new(usize::MAX);
        assert!(gm.is_err());
    }

    #[test]
    fn clone() {
        let eshm = ExclusiveSharedMemory::new(page_size::get()).unwrap();
        let (hshm1, _) = eshm.build();
        let hshm2 = hshm1.clone();

        // after hshm1 is cloned, hshm1 and hshm2 should have identical
        // memory sizes and pointers.
        assert_eq!(hshm1.mem_size(), hshm2.mem_size());
        assert_eq!(hshm1.base_addr(), hshm2.base_addr());

        // we should be able to copy a byte array into both hshm1 and hshm2,
        // and have both changes be reflected in all clones
        hshm1.copy_from_slice(b"a", 0).unwrap();
        hshm2.copy_from_slice(b"b", 1).unwrap();

        // at this point, both hshm1 and hshm2 should have
        // offset 0 = 'a', offset 1 = 'b'
        for (raw_offset, expected) in &[(0, b'a'), (1, b'b')] {
            assert_eq!(hshm1.read::<u8>(*raw_offset).unwrap(), *expected);
            assert_eq!(hshm2.read::<u8>(*raw_offset).unwrap(), *expected);
        }

        // after we drop hshm1, hshm2 should still exist, be valid,
        // and have all contents from before hshm1 was dropped
        drop(hshm1);

        // at this point, hshm2 should still have offset 0 = 'a', offset 1 = 'b'
        for (raw_offset, expected) in &[(0, b'a'), (1, b'b')] {
            assert_eq!(hshm2.read::<u8>(*raw_offset).unwrap(), *expected);
        }
        hshm2.copy_from_slice(b"c", 2).unwrap();
        assert_eq!(hshm2.read::<u8>(2).unwrap(), b'c');
        drop(hshm2);
    }

    #[test]
    fn copy_all_to_vec() {
        let mut data = vec![b'a', b'b', b'c'];
        data.resize(page_size::get(), 0);
        let mut eshm = ExclusiveSharedMemory::new(data.len()).unwrap();
        eshm.copy_from_slice(data.as_slice(), 0).unwrap();
        let ret_vec = eshm.copy_all_to_vec().unwrap();
        assert_eq!(data, ret_vec);
    }

    /// Test that verifies memory is properly unmapped when all SharedMemory
    /// references are dropped.
    #[test]
    #[cfg(all(target_os = "linux", not(miri)))]
    fn test_drop() {
        use proc_maps::get_process_maps;

        // Use a unique size that no other test uses to avoid false positives
        // from concurrent tests allocating at the same address.
        // The mprotect calls split the mapping into 3 regions (guard, usable, guard),
        // so we check for the usable region which has this exact size.
        //
        // NOTE: If this test fails intermittently, there may be a race condition
        // where another test allocates memory at the same address between our
        // drop and the mapping check. Ensure UNIQUE_SIZE is not used by any
        // other test in the codebase to avoid this.
        let unique_size: usize = page_size::get() * 17;

        let pid = std::process::id();

        let eshm = ExclusiveSharedMemory::new(unique_size).unwrap();
        let (hshm1, gshm) = eshm.build();
        let hshm2 = hshm1.clone();

        // Use the usable memory region (not raw), since mprotect splits the mapping
        let base_ptr = hshm1.base_ptr() as usize;
        let mem_size = hshm1.mem_size();

        // Helper to check if exact mapping exists (matching both address and size)
        let has_exact_mapping = |ptr: usize, size: usize| -> bool {
            get_process_maps(pid.try_into().unwrap())
                .unwrap()
                .iter()
                .any(|m| m.start() == ptr && m.size() == size)
        };

        // Verify mapping exists before drop
        assert!(
            has_exact_mapping(base_ptr, mem_size),
            "shared memory mapping not found at {:#x} with size {}",
            base_ptr,
            mem_size
        );

        // Drop all references
        drop(hshm1);
        drop(hshm2);
        drop(gshm);

        // Verify exact mapping is gone
        assert!(
            !has_exact_mapping(base_ptr, mem_size),
            "shared memory mapping still exists at {:#x} with size {} after drop",
            base_ptr,
            mem_size
        );
    }

    /// Tests for the optimized aligned memory operations.
    /// These tests verify that the u128 chunk optimization works correctly
    /// for various alignment scenarios and buffer sizes.
    mod alignment_tests {
        use super::*;

        const CHUNK_SIZE: usize = size_of::<u128>();

        /// Test copy operations with all possible starting alignment offsets (0-15)
        #[test]
        fn copy_with_various_alignments() {
            // Use a buffer large enough to test all alignment cases
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (hshm, _) = eshm.build();

            // Test all 16 possible alignment offsets (0 through 15)
            for start_offset in 0..CHUNK_SIZE {
                let test_len = 64; // Enough to cover head, aligned chunks, and tail
                let test_data: Vec<u8> = (0..test_len).map(|i| (i + start_offset) as u8).collect();

                // Write data at the given offset
                hshm.copy_from_slice(&test_data, start_offset).unwrap();

                // Read it back
                let mut read_buf = vec![0u8; test_len];
                hshm.copy_to_slice(&mut read_buf, start_offset).unwrap();

                assert_eq!(
                    test_data, read_buf,
                    "Mismatch at alignment offset {}",
                    start_offset
                );
            }
        }

        /// Test copy operations with lengths smaller than chunk size (< 16 bytes)
        #[test]
        fn copy_small_lengths() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (hshm, _) = eshm.build();

            for len in 0..CHUNK_SIZE {
                let test_data: Vec<u8> = (0..len).map(|i| i as u8).collect();

                hshm.copy_from_slice(&test_data, 0).unwrap();

                let mut read_buf = vec![0u8; len];
                hshm.copy_to_slice(&mut read_buf, 0).unwrap();

                assert_eq!(test_data, read_buf, "Mismatch for length {}", len);
            }
        }

        /// Test copy operations with lengths that don't align to chunk boundaries
        #[test]
        fn copy_non_aligned_lengths() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (hshm, _) = eshm.build();

            // Test lengths like 17, 31, 33, 47, 63, 65, etc.
            let test_lengths = [17, 31, 33, 47, 63, 65, 100, 127, 129, 255, 257];

            for &len in &test_lengths {
                let test_data: Vec<u8> = (0..len).map(|i| (i % 256) as u8).collect();

                hshm.copy_from_slice(&test_data, 0).unwrap();

                let mut read_buf = vec![0u8; len];
                hshm.copy_to_slice(&mut read_buf, 0).unwrap();

                assert_eq!(test_data, read_buf, "Mismatch for length {}", len);
            }
        }

        /// Test copy with exactly one chunk (16 bytes)
        #[test]
        fn copy_exact_chunk_size() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (hshm, _) = eshm.build();

            let test_data: Vec<u8> = (0..CHUNK_SIZE).map(|i| i as u8).collect();

            hshm.copy_from_slice(&test_data, 0).unwrap();

            let mut read_buf = vec![0u8; CHUNK_SIZE];
            hshm.copy_to_slice(&mut read_buf, 0).unwrap();

            assert_eq!(test_data, read_buf);
        }

        /// Test fill with various alignment offsets
        #[test]
        fn fill_with_various_alignments() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (mut hshm, _) = eshm.build();

            for start_offset in 0..CHUNK_SIZE {
                let fill_len = 64;
                let fill_value = (start_offset % 256) as u8;

                // Clear memory first
                hshm.fill(0, 0, mem_size).unwrap();

                // Fill at the given offset
                hshm.fill(fill_value, start_offset, fill_len).unwrap();

                // Read it back and verify
                let mut read_buf = vec![0u8; fill_len];
                hshm.copy_to_slice(&mut read_buf, start_offset).unwrap();

                assert!(
                    read_buf.iter().all(|&b| b == fill_value),
                    "Fill mismatch at alignment offset {}",
                    start_offset
                );
            }
        }

        /// Test fill with lengths smaller than chunk size
        #[test]
        fn fill_small_lengths() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (mut hshm, _) = eshm.build();

            for len in 0..CHUNK_SIZE {
                let fill_value = 0xAB;

                hshm.fill(0, 0, mem_size).unwrap(); // Clear
                hshm.fill(fill_value, 0, len).unwrap();

                let mut read_buf = vec![0u8; len];
                hshm.copy_to_slice(&mut read_buf, 0).unwrap();

                assert!(
                    read_buf.iter().all(|&b| b == fill_value),
                    "Fill mismatch for length {}",
                    len
                );
            }
        }

        /// Test fill with non-aligned lengths
        #[test]
        fn fill_non_aligned_lengths() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (mut hshm, _) = eshm.build();

            let test_lengths = [17, 31, 33, 47, 63, 65, 100, 127, 129, 255, 257];

            for &len in &test_lengths {
                let fill_value = 0xCD;

                hshm.fill(0, 0, mem_size).unwrap(); // Clear
                hshm.fill(fill_value, 0, len).unwrap();

                let mut read_buf = vec![0u8; len];
                hshm.copy_to_slice(&mut read_buf, 0).unwrap();

                assert!(
                    read_buf.iter().all(|&b| b == fill_value),
                    "Fill mismatch for length {}",
                    len
                );
            }
        }

        /// Test edge cases: length 0 and length 1
        #[test]
        fn copy_edge_cases() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (hshm, _) = eshm.build();

            // Length 0
            let empty: Vec<u8> = vec![];
            hshm.copy_from_slice(&empty, 0).unwrap();
            let mut read_buf: Vec<u8> = vec![];
            hshm.copy_to_slice(&mut read_buf, 0).unwrap();
            assert!(read_buf.is_empty());

            // Length 1
            let single = vec![0x42u8];
            hshm.copy_from_slice(&single, 0).unwrap();
            let mut read_buf = vec![0u8; 1];
            hshm.copy_to_slice(&mut read_buf, 0).unwrap();
            assert_eq!(single, read_buf);
        }

        /// Test combined: unaligned start + non-aligned length
        #[test]
        fn copy_unaligned_start_and_length() {
            let mem_size: usize = page_size::get();
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (hshm, _) = eshm.build();

            // Start at offset 7 (unaligned), length 37 (not a multiple of 16)
            let start_offset = 7;
            let len = 37;
            let test_data: Vec<u8> = (0..len).map(|i| (i * 3) as u8).collect();

            hshm.copy_from_slice(&test_data, start_offset).unwrap();

            let mut read_buf = vec![0u8; len];
            hshm.copy_to_slice(&mut read_buf, start_offset).unwrap();

            assert_eq!(test_data, read_buf);
        }
    }

    /// Bounds checking for `try_pop_buffer_into` against corrupt guest data.
    mod try_pop_buffer_bounds {
        use super::*;

        #[derive(Debug, PartialEq)]
        struct RawBytes(Vec<u8>);

        impl TryFrom<&[u8]> for RawBytes {
            type Error = String;
            fn try_from(value: &[u8]) -> std::result::Result<Self, Self::Error> {
                Ok(RawBytes(value.to_vec()))
            }
        }

        /// Create a buffer with stack pointer initialized to 8 (empty).
        fn make_buffer(mem_size: usize) -> super::super::HostSharedMemory {
            let eshm = ExclusiveSharedMemory::new(mem_size).unwrap();
            let (hshm, _) = eshm.build();
            hshm.write::<u64>(0, 8u64).unwrap();
            hshm
        }

        #[test]
        fn normal_push_pop_roundtrip() {
            let mem_size = page_size::get();
            let mut hshm = make_buffer(mem_size);

            // Size-prefixed flatbuffer-like payload: [size: u32 LE][payload]
            let payload = b"hello";
            let mut data = Vec::new();
            data.extend_from_slice(&(payload.len() as u32).to_le_bytes());
            data.extend_from_slice(payload);

            hshm.push_buffer(0, mem_size, &data).unwrap();
            let result: RawBytes = hshm.try_pop_buffer_into(0, mem_size).unwrap();
            assert_eq!(result.0, data);
        }

        #[test]
        fn malicious_flatbuffer_size_prefix() {
            let mem_size = page_size::get();
            let mut hshm = make_buffer(mem_size);

            let payload = b"small";
            let mut data = Vec::new();
            data.extend_from_slice(&(payload.len() as u32).to_le_bytes());
            data.extend_from_slice(payload);
            hshm.push_buffer(0, mem_size, &data).unwrap();

            // Corrupt size prefix at element start (offset 8) to near u32::MAX.
            hshm.write::<u32>(8, 0xFFFF_FFFBu32).unwrap(); // +4 = 0xFFFF_FFFF

            let result: Result<RawBytes> = hshm.try_pop_buffer_into(0, mem_size);
            let err_msg = format!("{}", result.unwrap_err());
            assert!(
                err_msg.contains("Corrupt buffer size prefix: flatbuffer claims 4294967295 bytes but the element slot is only 9 bytes"),
                "Unexpected error message: {}",
                err_msg
            );
        }

        #[test]
        fn malicious_element_offset_too_small() {
            let mem_size = page_size::get();
            let mut hshm = make_buffer(mem_size);

            let payload = b"test";
            let mut data = Vec::new();
            data.extend_from_slice(&(payload.len() as u32).to_le_bytes());
            data.extend_from_slice(payload);
            hshm.push_buffer(0, mem_size, &data).unwrap();

            // Corrupt back-pointer (offset 16) to 0 (before valid range).
            hshm.write::<u64>(16, 0u64).unwrap();

            let result: Result<RawBytes> = hshm.try_pop_buffer_into(0, mem_size);
            let err_msg = format!("{}", result.unwrap_err());
            assert!(
                err_msg.contains(
                    "Corrupt buffer back-pointer: element offset 0 is outside valid range [8, 8]"
                ),
                "Unexpected error message: {}",
                err_msg
            );
        }

        #[test]
        fn malicious_element_offset_past_stack_pointer() {
            let mem_size = page_size::get();
            let mut hshm = make_buffer(mem_size);

            let payload = b"test";
            let mut data = Vec::new();
            data.extend_from_slice(&(payload.len() as u32).to_le_bytes());
            data.extend_from_slice(payload);
            hshm.push_buffer(0, mem_size, &data).unwrap();

            // Corrupt back-pointer (offset 16) to 9999 (past stack pointer 24).
            hshm.write::<u64>(16, 9999u64).unwrap();

            let result: Result<RawBytes> = hshm.try_pop_buffer_into(0, mem_size);
            let err_msg = format!("{}", result.unwrap_err());
            assert!(
                err_msg.contains(
                    "Corrupt buffer back-pointer: element offset 9999 is outside valid range [8, 8]"
                ),
                "Unexpected error message: {}",
                err_msg
            );
        }

        #[test]
        fn malicious_flatbuffer_size_off_by_one() {
            let mem_size = page_size::get();
            let mut hshm = make_buffer(mem_size);

            let payload = b"abcd";
            let mut data = Vec::new();
            data.extend_from_slice(&(payload.len() as u32).to_le_bytes());
            data.extend_from_slice(payload);
            hshm.push_buffer(0, mem_size, &data).unwrap();

            // Corrupt size prefix: claim 5 bytes (total 9), exceeding the 8-byte slot.
            hshm.write::<u32>(8, 5u32).unwrap(); // fb_buffer_size = 5 + 4 = 9

            let result: Result<RawBytes> = hshm.try_pop_buffer_into(0, mem_size);
            let err_msg = format!("{}", result.unwrap_err());
            assert!(
                err_msg.contains("Corrupt buffer size prefix: flatbuffer claims 9 bytes but the element slot is only 8 bytes"),
                "Unexpected error message: {}",
                err_msg
            );
        }

        /// Back-pointer just below stack_pointer causes underflow in
        /// `stack_pointer_rel - last_element_offset_rel - 8`.
        #[test]
        fn back_pointer_near_stack_pointer_underflow() {
            let mem_size = page_size::get();
            let mut hshm = make_buffer(mem_size);

            let payload = b"test";
            let mut data = Vec::new();
            data.extend_from_slice(&(payload.len() as u32).to_le_bytes());
            data.extend_from_slice(payload);
            hshm.push_buffer(0, mem_size, &data).unwrap();

            // stack_pointer_rel = 24. Set back-pointer to 23 (> 24 - 16 = 8, so rejected).
            hshm.write::<u64>(16, 23u64).unwrap();

            let result: Result<RawBytes> = hshm.try_pop_buffer_into(0, mem_size);
            let err_msg = format!("{}", result.unwrap_err());
            assert!(
                err_msg.contains(
                    "Corrupt buffer back-pointer: element offset 23 is outside valid range [8, 8]"
                ),
                "Unexpected error message: {}",
                err_msg
            );
        }

        /// Size prefix of 0xFFFF_FFFD causes u32 overflow: 0xFFFF_FFFD + 4 wraps.
        #[test]
        fn size_prefix_u32_overflow() {
            let mem_size = page_size::get();
            let mut hshm = make_buffer(mem_size);

            let payload = b"test";
            let mut data = Vec::new();
            data.extend_from_slice(&(payload.len() as u32).to_le_bytes());
            data.extend_from_slice(payload);
            hshm.push_buffer(0, mem_size, &data).unwrap();

            // Write 0xFFFF_FFFD as size prefix: checked_add(4) returns None.
            hshm.write::<u32>(8, 0xFFFF_FFFDu32).unwrap();

            let result: Result<RawBytes> = hshm.try_pop_buffer_into(0, mem_size);
            let err_msg = format!("{}", result.unwrap_err());
            assert!(
                err_msg.contains("Corrupt buffer size prefix: value 4294967293 overflows when adding 4-byte header"),
                "Unexpected error message: {}",
                err_msg
            );
        }
    }

    #[cfg(target_os = "linux")]
    mod guard_page_crash_test {
        use crate::mem::shared_mem::{ExclusiveSharedMemory, SharedMemory};

        const TEST_EXIT_CODE: u8 = 211; // an uncommon exit code, used for testing purposes

        /// hook sigsegv to exit with status code, to make it testable, rather than have it exit from a signal
        /// NOTE: We CANNOT panic!() in the handler, and make the tests #[should_panic], because
        ///     the test harness process will crash anyway after the test passes
        fn setup_signal_handler() {
            unsafe {
                signal_hook_registry::register_signal_unchecked(libc::SIGSEGV, || {
                    std::process::exit(TEST_EXIT_CODE.into());
                })
                .unwrap();
            }
        }

        #[test]
        #[ignore] // this test is ignored because it will crash the running process
        fn read() {
            setup_signal_handler();

            let eshm = ExclusiveSharedMemory::new(page_size::get()).unwrap();
            let (hshm, _) = eshm.build();
            let guard_page_ptr = hshm.raw_ptr();
            unsafe { std::ptr::read_volatile(guard_page_ptr) };
        }

        #[test]
        #[ignore] // this test is ignored because it will crash the running process
        fn write() {
            setup_signal_handler();

            let eshm = ExclusiveSharedMemory::new(page_size::get()).unwrap();
            let (hshm, _) = eshm.build();
            let guard_page_ptr = hshm.raw_ptr();
            unsafe { std::ptr::write_volatile(guard_page_ptr, 0u8) };
        }

        #[test]
        #[ignore] // this test is ignored because it will crash the running process
        fn exec() {
            setup_signal_handler();

            let eshm = ExclusiveSharedMemory::new(page_size::get()).unwrap();
            let (hshm, _) = eshm.build();
            let guard_page_ptr = hshm.raw_ptr();
            let func: fn() = unsafe { std::mem::transmute(guard_page_ptr) };
            func();
        }

        // provides a way for running the above tests in a separate process since they expect to crash
        #[test]
        #[cfg_attr(miri, ignore)] // miri can't spawn subprocesses
        fn guard_page_testing_shim() {
            let tests = vec!["read", "write", "exec"];
            for test in tests {
                let triple = std::env::var("TARGET_TRIPLE").ok();
                let target_args = if let Some(triple) = triple.filter(|t| !t.is_empty()) {
                    vec!["--target".to_string(), triple.to_string()]
                } else {
                    vec![]
                };
                let output = std::process::Command::new("cargo")
                    .args(["test", "-p", "hyperlight-host", "--lib"])
                    .args(target_args)
                    .args(["--", "--ignored", test])
                    .stdin(std::process::Stdio::null())
                    .output()
                    .expect("Unable to launch tests");
                let exit_code = output.status.code();
                if exit_code != Some(TEST_EXIT_CODE.into()) {
                    eprintln!("=== Guard Page test '{}' failed ===", test);
                    eprintln!("Exit code: {:?} (expected {})", exit_code, TEST_EXIT_CODE);
                    eprintln!("=== STDOUT ===");
                    eprintln!("{}", String::from_utf8_lossy(&output.stdout));
                    eprintln!("=== STDERR ===");
                    eprintln!("{}", String::from_utf8_lossy(&output.stderr));
                    panic!(
                        "Guard Page test failed: {} (exit code {:?}, expected {})",
                        test, exit_code, TEST_EXIT_CODE
                    );
                }
            }
        }
    }

    #[cfg(not(miri))]
    mod from_file_tests {
        use std::io::Write;

        use tempfile::NamedTempFile;

        use crate::mem::shared_mem::{ReadonlySharedMemory, SharedMemory};

        pub(super) fn make_temp_file(len: usize) -> NamedTempFile {
            let mut f = NamedTempFile::new().expect("create temp file");
            if len > 0 {
                let mut buf = vec![0u8; len];
                for (i, b) in buf.iter_mut().enumerate() {
                    *b = (i & 0xff) as u8;
                }
                f.write_all(&buf).expect("write temp file");
                f.flush().expect("flush temp file");
            }
            f
        }

        #[test]
        fn from_file_success_single_page() {
            let tmp = make_temp_file(page_size::get());
            let mut rsm = ReadonlySharedMemory::from_file(tmp.as_file(), page_size::get())
                .expect("from_file should succeed");
            assert_eq!(rsm.mem_size(), page_size::get());
            rsm.with_contents(|slice| {
                for (i, b) in slice.iter().enumerate() {
                    assert_eq!(*b, (i & 0xff) as u8);
                }
            })
            .expect("with_contents should succeed");
        }

        #[test]
        fn from_file_success_smaller_guest_mapped_size() {
            let tmp = make_temp_file(2 * page_size::get());
            let rsm = ReadonlySharedMemory::from_file(tmp.as_file(), page_size::get())
                .expect("from_file should succeed");
            assert_eq!(rsm.mem_size(), 2 * page_size::get());
        }

        #[test]
        fn from_file_rejects_empty_file() {
            let tmp = make_temp_file(0);
            let err = ReadonlySharedMemory::from_file(tmp.as_file(), page_size::get())
                .expect_err("empty file should be rejected");
            assert!(format!("{}", err).contains("0x0 < 0x0"));
        }

        #[test]
        fn from_file_rejects_unaligned_file_length() {
            let tmp = make_temp_file(page_size::get() + 1);
            let err = ReadonlySharedMemory::from_file(tmp.as_file(), page_size::get())
                .expect_err("unaligned file length should be rejected");
            assert!(format!("{}", err).contains(&format!(
                "0x{:x} % 0x{:x} = 0",
                page_size::get() + 1,
                page_size::get()
            )));
        }

        #[test]
        fn from_file_rejects_zero_guest_mapped_size() {
            let tmp = make_temp_file(page_size::get());
            let err = ReadonlySharedMemory::from_file(tmp.as_file(), 0)
                .expect_err("zero guest_mapped_size should be rejected");
            assert!(format!("{}", err).contains("0x0 < 0x0"));
        }

        #[test]
        fn from_file_rejects_unaligned_guest_mapped_size() {
            let tmp = make_temp_file(2 * page_size::get());
            let err = ReadonlySharedMemory::from_file(tmp.as_file(), page_size::get() + 1)
                .expect_err("unaligned guest_mapped_size should be rejected");
            assert!(format!("{}", err).contains(&format!(
                "0x{:x} % 0x{:x} = ",
                page_size::get() + 1,
                page_size::get()
            )));
        }

        #[test]
        fn from_file_rejects_guest_mapped_size_exceeding_file() {
            let tmp = make_temp_file(page_size::get());
            let err = ReadonlySharedMemory::from_file(tmp.as_file(), 2 * page_size::get())
                .expect_err("guest_mapped_size > file length should be rejected");
            assert!(format!("{}", err).contains(&format!(
                "0x{:x} <= 0x{:x}",
                2 * page_size::get(),
                page_size::get()
            )));
        }

        /// Tests in this submodule are `#[ignore]`'d because each one
        /// is expected to die from a memory access violation. They are
        /// not run by a plain `cargo test`. The `from_file_guard_page_shim`
        /// test in the parent module re-executes each one in a subprocess
        /// and asserts the trap occurred.
        mod guard_page_crash_tests {
            use super::make_temp_file;
            use crate::mem::shared_mem::{ReadonlySharedMemory, SharedMemory};

            /// Loads from the byte immediately before the mapping.
            #[test]
            #[ignore]
            pub(super) fn leading_guard_page_traps() {
                let tmp = make_temp_file(page_size::get());
                let rsm = ReadonlySharedMemory::from_file(tmp.as_file(), page_size::get())
                    .expect("from_file should succeed");
                let guard_ptr = unsafe { rsm.base_ptr().sub(page_size::get()) };
                println!("reached_guard");
                let _ = unsafe { std::ptr::read_volatile(guard_ptr) };
                println!("survived_guard");
            }

            /// Loads from the byte immediately after the mapping.
            #[test]
            #[ignore]
            pub(super) fn trailing_guard_page_traps() {
                let tmp = make_temp_file(page_size::get());
                let rsm = ReadonlySharedMemory::from_file(tmp.as_file(), page_size::get())
                    .expect("from_file should succeed");
                let guard_ptr = unsafe { rsm.base_ptr().add(rsm.mem_size()) };
                println!("reached_guard");
                let _ = unsafe { std::ptr::read_volatile(guard_ptr) };
                println!("survived_guard");
            }
        }

        /// Spawn each ignored guard-page test as a subprocess and assert
        /// it terminated by an OS access violation. Re-executes the
        /// current test binary so no rebuild or `cargo` invocation is
        /// needed.
        #[test]
        #[cfg_attr(miri, ignore)] // miri can't spawn subprocesses
        fn from_file_guard_page_shim() {
            use guard_page_crash_tests::{leading_guard_page_traps, trailing_guard_page_traps};
            let ignored_test_paths = [
                test_path(leading_guard_page_traps),
                test_path(trailing_guard_page_traps),
            ];

            let exe = std::env::current_exe().expect("current_exe");
            for path in &ignored_test_paths {
                run_guard_page_subprocess(&exe, path);
            }
        }

        /// Derive a libtest filter path for a test function from its
        /// type name. Strips the leading crate-name segment that
        /// `type_name` includes but libtest does not.
        fn test_path<F: Fn()>(_: F) -> &'static str {
            let full = std::any::type_name::<F>();
            let (_, rest) = full
                .split_once("::")
                .expect("type_name of a function item is always qualified by the crate name");
            rest
        }

        fn run_guard_page_subprocess(exe: &std::path::Path, ignored_test_path: &str) {
            let output = std::process::Command::new(exe)
                .args([
                    "--ignored",
                    "--nocapture",
                    "--exact",
                    "--test-threads=1",
                    ignored_test_path,
                ])
                .stdin(std::process::Stdio::null())
                .output()
                .expect("Unable to launch subprocess test");

            let stdout = String::from_utf8_lossy(&output.stdout);
            let stderr = String::from_utf8_lossy(&output.stderr);

            // libtest with no matching filter exits 0, so verify the
            // test actually ran via the "running 1 test" banner.
            let ran_test = stdout.contains("running 1 test");
            let reached = stdout.contains("reached_guard");
            let survived = stdout.contains("survived_guard");
            let by_access_violation = killed_by_access_violation(&output.status);

            let ok = reached && !survived && by_access_violation && ran_test;
            if !ok {
                eprintln!("=== Guard page shim failed for {} ===", ignored_test_path);
                eprintln!(
                    "status={:?} ran_test={} reached={} survived={} by_access_violation={}",
                    output.status, ran_test, reached, survived, by_access_violation
                );
                eprintln!("=== STDOUT ===\n{}", stdout);
                eprintln!("=== STDERR ===\n{}", stderr);
                let hint = if !ran_test {
                    format!(
                        "\nHINT: ran_test=false (subprocess reported 'running 0 tests'). \
                         Most likely cause is a stale test path in the shim. Verify that \
                         `{}` still exists and matches the path passed via --exact above.",
                        ignored_test_path
                    )
                } else {
                    String::new()
                };
                panic!(
                    "Expected subprocess to run {}, print 'reached_guard', \
                     then die from a memory access fault. ran_test={}, reached={}, \
                     survived={}, by_access_violation={}, status={:?}{}",
                    ignored_test_path,
                    ran_test,
                    reached,
                    survived,
                    by_access_violation,
                    output.status,
                    hint
                );
            }

            println!(
                "guard page trap confirmed for {}: subprocess terminated with {:?}",
                ignored_test_path, output.status
            );
        }

        /// Returns true if `status` indicates the process died from a
        /// memory access fault (SIGBUS on macos, SIGSEGV on linux,
        /// STATUS_ACCESS_VIOLATION (or 0xDEAD) on Windows).
        fn killed_by_access_violation(status: &std::process::ExitStatus) -> bool {
            #[cfg(unix)]
            {
                use std::os::unix::process::ExitStatusExt;
                let expected_signal = if cfg!(target_os = "macos") {
                    libc::SIGBUS
                } else {
                    libc::SIGSEGV
                };
                status.signal() == Some(expected_signal)
            }
            #[cfg(windows)]
            {
                use windows::Win32::Foundation::STATUS_ACCESS_VIOLATION;
                // See https://github.com/hyperlight-dev/hyperlight/issues/1507
                status.code() == Some(STATUS_ACCESS_VIOLATION.0) || status.code() == Some(0xDEAD)
            }
        }
    }
}