hyperlight_host/mem/

shared_mem.rs

/*
Copyright 2025  The Hyperlight Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

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

use bytemuck::Pod;
use hyperlight_common::mem::PAGE_SIZE_USIZE;
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,
};
#[cfg(target_os = "windows")]
use crate::HyperlightError::WindowsAPIError;
use crate::{HyperlightError, Result, log_then_return, new_error};

/// 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(new_error!(
                "Cannot read value from offset {} with size {} in memory of size {}",
                $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(target_os = "linux")]
#[derive(Debug)]
struct Mmap {
    base: *mut c_void,
    len: usize,
}

#[cfg(target_os = "linux")]
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!(HyperlightError::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_USIZE));
        // 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!(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!(HyperlightError::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_USIZE
    }

    /// 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_USIZE)
    }

    /// 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_USIZE
    }

    /// 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_USIZE,
            }
        }
    }

    /// 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()))
    }

    /// Zero a shared memory region
    fn zero(&mut self) -> Result<()> {
        self.with_exclusivity(|e| {
            #[allow(unused_mut)] // unused on some platforms, although not others
            let mut do_copy = true;
            // TODO: Compare & add heuristic thresholds: mmap, MADV_DONTNEED, MADV_REMOVE, MADV_FREE (?)
            // TODO: Find a similar lazy zeroing approach that works on MSHV.
            //       (See Note [Keeping mappings in sync between userspace and the guest])
            #[cfg(all(target_os = "linux", 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);
            }
        })
    }
}

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 {
    /// 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 = "linux")]
    #[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,
        };
        #[cfg(not(miri))]
        use libc::{MAP_NORESERVE, PROT_NONE, mprotect};

        if min_size_bytes == 0 {
            return Err(new_error!("Cannot create shared memory with size 0"));
        }

        let total_size = min_size_bytes
            .checked_add(2 * PAGE_SIZE_USIZE) // guard page around the memory
            .ok_or_else(|| new_error!("Memory required for sandbox exceeded usize::MAX"))?;

        if total_size % PAGE_SIZE_USIZE != 0 {
            return Err(new_error!(
                "shared memory must be a multiple of {}",
                PAGE_SIZE_USIZE
            ));
        }

        // usize and isize are guaranteed to be the same size, and
        // isize::MAX should be positive, so this cast should be safe.
        if total_size > isize::MAX as usize {
            return Err(HyperlightError::MemoryRequestTooBig(
                total_size,
                isize::MAX as usize,
            ));
        }

        // 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!(HyperlightError::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_USIZE, PROT_NONE) };
            if res != 0 {
                return Err(HyperlightError::MprotectFailed(
                    Error::last_os_error().raw_os_error(),
                ));
            }
            let res = unsafe {
                mprotect(
                    (mmap.base as *const u8).add(total_size - PAGE_SIZE_USIZE) as *mut c_void,
                    PAGE_SIZE_USIZE,
                    PROT_NONE,
                )
            };
            if res != 0 {
                return Err(HyperlightError::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> {
        if min_size_bytes == 0 {
            return Err(new_error!("Cannot create shared memory with size 0"));
        }

        let total_size = min_size_bytes
            .checked_add(2 * PAGE_SIZE_USIZE)
            .ok_or_else(|| new_error!("Memory required for sandbox exceeded {}", usize::MAX))?;

        if total_size % PAGE_SIZE_USIZE != 0 {
            return Err(new_error!(
                "shared memory must be a multiple of {}",
                PAGE_SIZE_USIZE
            ));
        }

        // usize and isize are guaranteed to be the same size, and
        // isize::MAX should be positive, so this cast should be safe.
        if total_size > isize::MAX as usize {
            return Err(HyperlightError::MemoryRequestTooBig(
                total_size,
                isize::MAX as usize,
            ));
        }

        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!(HyperlightError::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!(HyperlightError::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_USIZE,
                PAGE_NOACCESS,
                &mut unused_out_old_prot_flags,
            )
        } {
            log_then_return!(WindowsAPIError(e.clone()));
        }

        let last_guard_page_start = unsafe { view.addr.add(total_size - PAGE_SIZE_USIZE) };
        if let Err(e) = unsafe {
            VirtualProtect(
                last_guard_page_start,
                PAGE_SIZE_USIZE,
                PAGE_NOACCESS,
                &mut unused_out_old_prot_flags,
            )
        } {
            log_then_return!(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()
            .map_err(|e| new_error!("Error locking at {}:{}: {}", file!(), line!(), e))?;
        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()
            .map_err(|e| new_error!("Error locking at {}:{}: {}", file!(), line!(), e))?;

        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()
            .map_err(|e| new_error!("Error locking at {}:{}: {}", file!(), line!(), e))?;

        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()
            .map_err(|e| new_error!("Error locking at {}:{}: {}", file!(), line!(), e))?;

        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;
        let buffer_size_u64: u64 = buffer_size.try_into()?;

        if stack_pointer_rel > buffer_size || stack_pointer_rel < 8 {
            return Err(new_error!(
                "Unable to push data to buffer: Stack pointer is out of bounds. Stack pointer: {}, Buffer size: {}",
                stack_pointer_rel,
                buffer_size_u64
            ));
        }

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

        if size_required > size_available {
            return Err(new_error!(
                "Not enough space in buffer to push data. Required: {}, Available: {}",
                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 {
            return Err(new_error!(
                "Unable to pop data from buffer: Stack pointer is out of bounds. Stack pointer: {}, Buffer size: {}",
                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
        {
            return Err(new_error!(
                "Corrupt buffer back-pointer: element offset {} is outside valid range [8, {}].",
                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_else(|| {
                new_error!(
                    "Corrupt buffer size prefix: value {} overflows when adding 4-byte header.",
                    raw_prefix
                )
            })?;
            usize::try_from(total)
        }?;

        if fb_buffer_size > max_element_size {
            return Err(new_error!(
                "Corrupt buffer size prefix: flatbuffer claims {} bytes but the element slot is only {} bytes.",
                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(|_e| {
            new_error!(
                "pop_buffer_into: failed to convert buffer to {}",
                type_name::<T>()
            )
        })?;

        // 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 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()
            .map_err(|e| new_error!("Error locking at {}:{}: {}", file!(), line!(), e))?;
        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.is_multiple_of(PAGE_SIZE_USIZE) {
            return Err(new_error!(
                "guest_mapped_size {} must be a non-zero multiple of PAGE_SIZE",
                guest_mapped_size
            ));
        }
        if guest_mapped_size > contents.len() {
            return Err(new_error!(
                "guest_mapped_size {} exceeds blob length {}",
                guest_mapped_size,
                contents.len()
            ));
        }
        let mut anon = ExclusiveSharedMemory::new(contents.len())?;
        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(|e| new_error!("Failed to read file metadata: {}", e))?
            .len()
            .try_into()
            .map_err(|_| new_error!("File length exceeds usize::MAX"))?;

        if len == 0 {
            return Err(new_error!(
                "Cannot create file-backed shared memory with size 0"
            ));
        }

        if !len.is_multiple_of(PAGE_SIZE_USIZE) {
            return Err(new_error!(
                "file length {} must be a multiple of PAGE_SIZE",
                len
            ));
        }

        if guest_mapped_size == 0
            || guest_mapped_size > len
            || !guest_mapped_size.is_multiple_of(PAGE_SIZE_USIZE)
        {
            return Err(new_error!(
                "guest_mapped_size {} must be a non-zero multiple of PAGE_SIZE no greater than file length {}",
                guest_mapped_size,
                len
            ));
        }

        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(target_os = "linux")]
    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_USIZE).ok_or_else(|| {
            new_error!("Memory required for file-backed mapping exceeded usize::MAX")
        })?;

        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(HyperlightError::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_USIZE) };
        // 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(HyperlightError::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_USIZE).ok_or_else(|| {
            new_error!("Memory required for file-backed mapping exceeded usize::MAX")
        })?;

        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_USIZE, 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!(HyperlightError::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_USIZE,
            },
            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(new_error!(
            "Cannot take exclusive access to a ReadonlySharedMemory"
        ))
    }
    // 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 {
    use hyperlight_common::mem::PAGE_SIZE_USIZE;
    #[cfg(not(miri))]
    use proptest::prelude::*;

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

    #[test]
    fn fill() {
        let mem_size: usize = 4096;
        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, 4096).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 = 4096;
        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 = 4096;
        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_USIZE).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(4096, 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.
        const UNIQUE_SIZE: usize = PAGE_SIZE_USIZE * 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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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 = 4096;
            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(4096).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(4096).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(4096).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 hyperlight_common::mem::PAGE_SIZE_USIZE;
        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_USIZE);
            let mut rsm = ReadonlySharedMemory::from_file(tmp.as_file(), PAGE_SIZE_USIZE)
                .expect("from_file should succeed");
            assert_eq!(rsm.mem_size(), PAGE_SIZE_USIZE);
            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_USIZE);
            let rsm = ReadonlySharedMemory::from_file(tmp.as_file(), PAGE_SIZE_USIZE)
                .expect("from_file should succeed");
            assert_eq!(rsm.mem_size(), 2 * PAGE_SIZE_USIZE);
        }

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

        #[test]
        fn from_file_rejects_unaligned_file_length() {
            let tmp = make_temp_file(PAGE_SIZE_USIZE + 1);
            let err = ReadonlySharedMemory::from_file(tmp.as_file(), PAGE_SIZE_USIZE)
                .expect_err("unaligned file length should be rejected");
            assert!(format!("{}", err).contains("multiple of PAGE_SIZE"));
        }

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

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

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

        /// 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 hyperlight_common::mem::PAGE_SIZE_USIZE;

            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_USIZE);
                let rsm = ReadonlySharedMemory::from_file(tmp.as_file(), PAGE_SIZE_USIZE)
                    .expect("from_file should succeed");
                let guard_ptr = unsafe { rsm.base_ptr().sub(PAGE_SIZE_USIZE) };
                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_USIZE);
                let rsm = ReadonlySharedMemory::from_file(tmp.as_file(), PAGE_SIZE_USIZE)
                    .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 (SIGSEGV on unix, 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;
                status.signal() == Some(libc::SIGSEGV)
            }
            #[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)
            }
        }
    }
}