Skip to main content

hyperlight_host/mem/
mgr.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4use flatbuffers::FlatBufferBuilder;
5use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCall;
6use hyperlight_common::flatbuffer_wrappers::function_types::FunctionCallResult;
7use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
8use hyperlight_common::flatbuffer_wrappers::util::estimate_flatbuffer_capacity;
9use hyperlight_common::log_level::GuestLogFilter;
10use hyperlight_common::transport::{Buf, EncodedMessage, ExternalValues, MailboxValue, MsgKind};
11use hyperlight_common::virtq::ReplyChain;
12use hyperlight_common::vmem::{self, PAGE_TABLE_SIZE};
13#[cfg(crashdump)]
14use hyperlight_common::vmem::{BasicMapping, MappingKind};
15use tracing::{Span, instrument};
16
17use super::layout::SandboxMemoryLayout;
18use super::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, HostSharedMemory, SharedMemory};
19use super::virtq::{self, G2hConsumer, H2gConsumer, VirtqSnapshot};
20use crate::hypervisor::regs::CommonSpecialRegisters;
21use crate::mem::memory_region::MemoryRegion;
22#[cfg(crashdump)]
23use crate::mem::memory_region::{CrashDumpRegion, MemoryRegionFlags, MemoryRegionType};
24use crate::sandbox::snapshot::{NextAction, Snapshot, SnapshotMemoryBacking};
25use crate::{HyperlightError, Result, new_error};
26
27#[cfg(crashdump)]
28fn mapping_kind_to_flags(kind: &MappingKind) -> (MemoryRegionFlags, MemoryRegionType) {
29    match kind {
30        MappingKind::Basic(BasicMapping {
31            readable,
32            writable,
33            executable,
34        }) => {
35            let mut flags = MemoryRegionFlags::empty();
36            if *readable {
37                flags |= MemoryRegionFlags::READ;
38            }
39            if *writable {
40                flags |= MemoryRegionFlags::WRITE;
41            }
42            if *executable {
43                flags |= MemoryRegionFlags::EXECUTE;
44            }
45            (flags, MemoryRegionType::Snapshot)
46        }
47        MappingKind::Cow(cow) => {
48            let mut flags = MemoryRegionFlags::empty();
49            if cow.readable {
50                flags |= MemoryRegionFlags::READ;
51            }
52            if cow.executable {
53                flags |= MemoryRegionFlags::EXECUTE;
54            }
55            (flags, MemoryRegionType::Scratch)
56        }
57        MappingKind::Unmapped => (MemoryRegionFlags::empty(), MemoryRegionType::Snapshot),
58        MappingKind::ZeroInit(bm) => {
59            let mut flags = MemoryRegionFlags::empty();
60            if bm.readable {
61                flags |= MemoryRegionFlags::READ;
62            }
63            if bm.writable {
64                flags |= MemoryRegionFlags::WRITE;
65            }
66            if bm.executable {
67                flags |= MemoryRegionFlags::EXECUTE;
68            }
69            (flags, MemoryRegionType::Snapshot)
70        }
71    }
72}
73
74/// Try to extend the last region in `regions` if the new page is contiguous
75/// in both guest and host address space and has the same flags.
76///
77/// Returns `true` if the region was coalesced, `false` if a new region is needed.
78#[cfg(crashdump)]
79fn try_coalesce_region(
80    regions: &mut [CrashDumpRegion],
81    virt_base: usize,
82    virt_end: usize,
83    host_base: usize,
84    flags: MemoryRegionFlags,
85) -> bool {
86    if let Some(last) = regions.last_mut()
87        && last.guest_region.end == virt_base
88        && last.host_region.end == host_base
89        && last.flags == flags
90    {
91        last.guest_region.end = virt_end;
92        last.host_region.end = host_base + (virt_end - virt_base);
93        return true;
94    }
95    false
96}
97
98#[derive(Clone, Copy, Debug, PartialEq, Eq)]
99pub(crate) enum BackingSource {
100    /// Snapshot layer index.
101    Snapshot(usize),
102    Scratch,
103    /// Dynamic region index.
104    Dynamic(usize),
105}
106
107/// A guest physical range resolved to its backing memory.
108#[derive(Clone, Copy, Debug, PartialEq, Eq)]
109pub(crate) struct GuestBacking {
110    pub(crate) source: BackingSource,
111    pub(crate) offset: usize,
112}
113
114/// Guest physical memory with scratch locked for exclusive access.
115pub(crate) struct GuestPhysicalMemoryView<'a> {
116    snapshot: &'a SnapshotMemoryBacking<HostSharedMemory>,
117    scratch: &'a [u8],
118    dynamic: &'a [MemoryRegion],
119    layout: SandboxMemoryLayout,
120}
121
122impl<'a> GuestPhysicalMemoryView<'a> {
123    /// Runs `f` with a view of `snapshot`, `scratch` and `dynamic`. Scratch
124    /// stays locked until `f` returns.
125    pub(crate) fn with_memory<T>(
126        snapshot: &SnapshotMemoryBacking<HostSharedMemory>,
127        scratch: &HostSharedMemory,
128        dynamic: &[MemoryRegion],
129        layout: SandboxMemoryLayout,
130        f: impl FnOnce(&GuestPhysicalMemoryView<'_>) -> Result<T>,
131    ) -> Result<T> {
132        scratch.with_exclusive_contents(|scratch| {
133            f(&GuestPhysicalMemoryView {
134                snapshot,
135                scratch,
136                dynamic,
137                layout,
138            })
139        })?
140    }
141
142    pub(crate) fn snapshot(&self) -> &'a SnapshotMemoryBacking<HostSharedMemory> {
143        self.snapshot
144    }
145
146    pub(crate) fn resolve(&self, gpa: u64, len: usize) -> Option<GuestBacking> {
147        let end = gpa.checked_add(u64::try_from(len).ok()?)?;
148        let scratch_start =
149            hyperlight_common::layout::scratch_base_gpa(self.layout.get_scratch_size());
150        let scratch_end = scratch_start.checked_add(self.layout.get_scratch_size() as u64)?;
151        if scratch_start <= gpa && end <= scratch_end {
152            return Some(GuestBacking {
153                source: BackingSource::Scratch,
154                offset: usize::try_from(gpa - scratch_start).ok()?,
155            });
156        }
157        if let Some((layer_index, offset)) = self.snapshot.resolve(gpa, len) {
158            return Some(GuestBacking {
159                source: BackingSource::Snapshot(layer_index),
160                offset,
161            });
162        }
163        self.dynamic
164            .iter()
165            .enumerate()
166            .find_map(|(region_index, region)| {
167                let start = u64::try_from(region.guest_region.start).ok()?;
168                let region_end = u64::try_from(region.guest_region.end).ok()?;
169                if start <= gpa && end <= region_end {
170                    Some(GuestBacking {
171                        source: BackingSource::Dynamic(region_index),
172                        offset: usize::try_from(gpa - start).ok()?,
173                    })
174                } else {
175                    None
176                }
177            })
178    }
179
180    pub(crate) fn read(&self, gpa: u64, destination: &mut [u8]) -> Result<GuestBacking> {
181        let backing = self
182            .resolve(gpa, destination.len())
183            .ok_or_else(|| new_error!("GPA range is not backed: {gpa:#x}"))?;
184        self.read_backing(backing, destination)?;
185        Ok(backing)
186    }
187
188    pub(crate) fn read_backing(&self, backing: GuestBacking, destination: &mut [u8]) -> Result<()> {
189        let offset = backing.offset;
190        match backing.source {
191            BackingSource::Snapshot(layer_index) => {
192                self.snapshot
193                    .copy_layer_to_slice(layer_index, destination, offset)?
194            }
195            BackingSource::Scratch => {
196                let source = offset
197                    .checked_add(destination.len())
198                    .and_then(|end| self.scratch.get(offset..end))
199                    .ok_or_else(|| new_error!("scratch read range is out of bounds"))?;
200                destination.copy_from_slice(source);
201            }
202            BackingSource::Dynamic(region_index) => {
203                let region = &self.dynamic[region_index];
204                #[allow(clippy::useless_conversion)]
205                let host_start: usize = region.host_region.start.into();
206                #[allow(clippy::useless_conversion)]
207                let host_end: usize = region.host_region.end.into();
208                let source_end = offset
209                    .checked_add(destination.len())
210                    .ok_or_else(|| new_error!("dynamic memory read range overflows"))?;
211                let host_len = host_end
212                    .checked_sub(host_start)
213                    .ok_or_else(|| new_error!("dynamic memory host range is invalid"))?;
214                if source_end > host_len {
215                    return Err(new_error!("dynamic memory read range is out of bounds"));
216                }
217                let source_start = host_start
218                    .checked_add(offset)
219                    .ok_or_else(|| new_error!("dynamic memory host address overflows"))?;
220                // SAFETY: Dynamic regions come from `Sandbox::map_region`, whose
221                // contract keeps them valid and unmodified for the sandbox's
222                // lifetime. The checks above bound this read.
223                unsafe {
224                    std::ptr::copy(
225                        source_start as *const u8,
226                        destination.as_mut_ptr(),
227                        destination.len(),
228                    )
229                };
230            }
231        }
232        Ok(())
233    }
234
235    #[cfg(crashdump)]
236    fn host_range(&self, gpa: u64, len: usize) -> Result<std::ops::Range<usize>> {
237        let backing = self
238            .resolve(gpa, len)
239            .ok_or_else(|| new_error!("GPA range is not backed: {gpa:#x}"))?;
240        let offset = backing.offset;
241        let (base, backing_len) = match backing.source {
242            BackingSource::Snapshot(layer_index) => self.snapshot.host_range(layer_index)?,
243            BackingSource::Scratch => (self.scratch.as_ptr() as usize, self.scratch.len()),
244            BackingSource::Dynamic(region_index) => {
245                let region = &self.dynamic[region_index];
246                #[allow(clippy::useless_conversion)]
247                let start: usize = region.host_region.start.into();
248                #[allow(clippy::useless_conversion)]
249                let end: usize = region.host_region.end.into();
250                (start, end - start)
251            }
252        };
253        let end_offset = offset
254            .checked_add(len)
255            .filter(|end| *end <= backing_len)
256            .ok_or_else(|| new_error!("resolved GPA range is out of bounds"))?;
257        let start = base
258            .checked_add(offset)
259            .ok_or_else(|| new_error!("resolved host address overflows"))?;
260        let end = base
261            .checked_add(end_offset)
262            .ok_or_else(|| new_error!("resolved host address overflows"))?;
263        Ok(start..end)
264    }
265}
266#[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
267pub(crate) struct GuestVirtualMemoryReader<'a> {
268    memory: &'a GuestPhysicalMemoryView<'a>,
269    root_pt: u64,
270    cached_page: Option<(u64, u64)>,
271}
272
273#[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
274impl<'a> GuestVirtualMemoryReader<'a> {
275    fn new(memory: &'a GuestPhysicalMemoryView<'a>, root_pt: u64) -> Self {
276        Self {
277            memory,
278            root_pt,
279            cached_page: None,
280        }
281    }
282
283    fn translate_page(&mut self, page_gva: u64) -> Result<u64> {
284        if let Some((cached_gva, cached_gpa)) = self.cached_page
285            && cached_gva == page_gva
286        {
287            return Ok(cached_gpa);
288        }
289
290        use crate::sandbox::snapshot::PageTableReader;
291
292        let pt_buf = PageTableReader::new(self.memory, self.root_pt);
293        // SAFETY: The vCPU is stopped for this outb, so its page tables cannot
294        // change during the walk.
295        let mapping = unsafe {
296            hyperlight_common::vmem::virt_to_phys(
297                &pt_buf,
298                page_gva,
299                hyperlight_common::vmem::PAGE_SIZE as u64,
300            )
301        }
302        .next();
303        // A suppressed read leaves a not-present entry behind, so ask before
304        // blaming the guest for an unmapped page.
305        pt_buf.finish()?;
306        let mapping = mapping.ok_or_else(|| new_error!("GVA page is not mapped: {page_gva:#x}"))?;
307        let mapping_offset = page_gva
308            .checked_sub(mapping.virt_base)
309            .ok_or_else(|| new_error!("page-table mapping starts after requested GVA"))?;
310        if mapping
311            .len
312            .checked_sub(mapping_offset)
313            .is_none_or(|len| len < hyperlight_common::vmem::PAGE_SIZE as u64)
314        {
315            return Err(new_error!(
316                "page-table mapping does not cover requested GVA page"
317            ));
318        }
319        let page_gpa = mapping
320            .phys_base
321            .checked_add(mapping_offset)
322            .ok_or_else(|| new_error!("guest physical address overflows"))?;
323        self.cached_page = Some((page_gva, page_gpa));
324        Ok(page_gpa)
325    }
326
327    pub(crate) fn read_exact(&mut self, gva: u64, destination: &mut [u8]) -> Result<()> {
328        gva.checked_add(u64::try_from(destination.len())?)
329            .ok_or_else(|| new_error!("guest virtual address overflows"))?;
330        let mut copied = 0usize;
331        while copied < destination.len() {
332            let current_gva = gva
333                .checked_add(u64::try_from(copied)?)
334                .ok_or_else(|| new_error!("guest virtual address overflows"))?;
335            let page_gva = current_gva / hyperlight_common::vmem::PAGE_SIZE as u64
336                * hyperlight_common::vmem::PAGE_SIZE as u64;
337            let page_offset = usize::try_from(current_gva - page_gva)?;
338            let chunk_len =
339                (destination.len() - copied).min(hyperlight_common::vmem::PAGE_SIZE - page_offset);
340            let gpa = self
341                .translate_page(page_gva)?
342                .checked_add(u64::try_from(page_offset)?)
343                .ok_or_else(|| new_error!("guest physical address overflows"))?;
344            self.memory
345                .read(gpa, &mut destination[copied..copied + chunk_len])?;
346            copied += chunk_len;
347        }
348        Ok(())
349    }
350}
351
352/// Guest operations the host accepts during a VM entry.
353#[derive(Debug, Clone, Copy, PartialEq, Eq)]
354pub(crate) enum ExecutionMode {
355    /// Guest initialization and guest function calls.
356    Unrestricted,
357    /// Snapshot checkpoint preparation. Host function calls are rejected.
358    Restricted,
359}
360
361/// Scratch-top slots the host writes and the guest applies and clears on its
362/// next entry.
363const GUEST_REQUEST_OFFSETS: [u64; 2] = [
364    hyperlight_common::layout::SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
365    hyperlight_common::layout::SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
366];
367
368/// A struct that is responsible for laying out and managing the memory
369/// for a given `Sandbox`.
370pub(crate) struct SandboxMemoryManager<S: SharedMemory> {
371    /// Shared memory for the Sandbox
372    pub(crate) shared_mem: SnapshotMemoryBacking<S>,
373    /// Scratch memory for the Sandbox
374    pub(crate) scratch_mem: S,
375    /// The memory layout of the underlying shared memory
376    pub(crate) layout: SandboxMemoryLayout,
377    /// The next action to perform when this sandbox resumes:
378    /// `Initialise` before the guest has run, `Call` afterwards.
379    pub(crate) next_action: NextAction,
380    /// Guest virtual address of the guest binary's ELF entry point,
381    /// preserved across the `Initialise` -> `Call` transition so it
382    /// can fill `AT_ENTRY` in guest core dumps. 0 if unknown.
383    pub(crate) original_entrypoint: u64,
384    /// Buffer for accumulating guest abort messages
385    pub(crate) abort_buffer: Vec<u8>,
386    /// Guest operations the host accepts during the current VM entry.
387    pub(crate) execution_mode: ExecutionMode,
388    /// Generation counter: how many snapshots have been taken from
389    /// this sandbox's execution path from init to here. Incremented
390    /// on each `snapshot` call; on `restore_snapshot` we inherit the
391    /// restored snapshot's own generation number so the guest-visible
392    /// counter tracks which snapshot the sandbox is a clone of.
393    pub(crate) snapshot_count: u64,
394    /// G2H consumer bound to the current scratch mapping.
395    pub(crate) g2h_consumer: Option<G2hConsumer>,
396    /// H2G consumer bound to the current scratch mapping.
397    pub(crate) h2g_consumer: Option<H2gConsumer>,
398    /// Correlation ID sequence survives consumer replacement and manager cloning.
399    next_guest_cid: u32,
400}
401
402impl<S: Clone + SharedMemory> Clone for SandboxMemoryManager<S> {
403    fn clone(&self) -> Self {
404        Self {
405            shared_mem: self.shared_mem.clone(),
406            scratch_mem: self.scratch_mem.clone(),
407            layout: self.layout,
408            next_action: self.next_action,
409            original_entrypoint: self.original_entrypoint,
410            abort_buffer: self.abort_buffer.clone(),
411            execution_mode: self.execution_mode,
412            snapshot_count: self.snapshot_count,
413            g2h_consumer: None,
414            h2g_consumer: None,
415            next_guest_cid: self.next_guest_cid,
416        }
417    }
418}
419
420/// Buffer for building guest page tables during snapshot creation.
421/// `TableAddr` is an absolute GPA (u64) so the same address space is
422/// used regardless of entry size.
423pub(crate) struct GuestPageTableBuffer {
424    buffer: std::cell::RefCell<Vec<u8>>,
425    phys_base: usize,
426    /// Absolute GPA of the currently-active root table. For
427    /// multi-root guests, `set_root` switches which root subsequent
428    /// `vmem::map` / `vmem::space_aware_map` calls target — typically
429    /// to an address previously returned by `alloc_table`.
430    root: std::cell::Cell<u64>,
431}
432
433impl vmem::TableReadOps for GuestPageTableBuffer {
434    type TableAddr = u64;
435
436    fn entry_addr(addr: u64, offset: u64) -> u64 {
437        addr + offset
438    }
439
440    unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
441        let buffer = self.buffer.borrow();
442        let byte_offset = addr as usize - self.phys_base;
443        let pte_size = core::mem::size_of::<vmem::PageTableEntry>();
444        let Some(bytes) = buffer.get(byte_offset..byte_offset + pte_size) else {
445            return 0;
446        };
447        let mut buf = [0u8; 8];
448        buf[..pte_size].copy_from_slice(bytes);
449        vmem::PageTableEntry::from_le_bytes(buf[..pte_size].try_into().unwrap_or_default())
450    }
451
452    fn to_phys(addr: u64) -> vmem::PhysAddr {
453        addr as vmem::PhysAddr
454    }
455
456    fn from_phys(addr: vmem::PhysAddr) -> u64 {
457        #[allow(clippy::unnecessary_cast)]
458        {
459            addr as u64
460        }
461    }
462
463    fn root_table(&self) -> u64 {
464        self.root.get()
465    }
466}
467
468impl vmem::TableOps for GuestPageTableBuffer {
469    type TableMovability = vmem::MayNotMoveTable;
470
471    unsafe fn alloc_table(&self) -> u64 {
472        let mut b = self.buffer.borrow_mut();
473        let offset = b.len();
474        b.resize(offset + PAGE_TABLE_SIZE, 0);
475        (self.phys_base + offset) as u64
476    }
477
478    unsafe fn write_entry(&self, addr: u64, entry: vmem::PageTableEntry) -> Option<vmem::Void> {
479        let mut b = self.buffer.borrow_mut();
480        let byte_offset = addr as usize - self.phys_base;
481        let pte_size = core::mem::size_of::<vmem::PageTableEntry>();
482        if let Some(slice) = b.get_mut(byte_offset..byte_offset + pte_size) {
483            slice.copy_from_slice(&entry.to_le_bytes()[..pte_size]);
484        }
485        None
486    }
487
488    unsafe fn update_root(&self, impossible: vmem::Void) {
489        match impossible {}
490    }
491}
492
493impl core::convert::AsRef<GuestPageTableBuffer> for GuestPageTableBuffer {
494    fn as_ref(&self) -> &Self {
495        self
496    }
497}
498
499impl GuestPageTableBuffer {
500    /// Create a new buffer with an initial zeroed root table at
501    /// `phys_base`. The returned buffer's current root is `phys_base`;
502    /// additional roots can be obtained by calling `alloc_table`.
503    pub(crate) fn new(phys_base: usize) -> Self {
504        GuestPageTableBuffer {
505            buffer: std::cell::RefCell::new(vec![0u8; PAGE_TABLE_SIZE]),
506            phys_base,
507            root: std::cell::Cell::new(phys_base as u64),
508        }
509    }
510
511    /// Switch the active root. `addr` must have been obtained either
512    /// as the initial root GPA (`phys_base`) or via `alloc_table`.
513    pub(crate) fn set_root(&self, addr: u64) {
514        self.root.set(addr);
515    }
516
517    /// GPA of the initial root allocated by `new`.
518    pub(crate) fn initial_root(&self) -> u64 {
519        self.phys_base as u64
520    }
521
522    #[cfg(test)]
523    #[allow(dead_code)]
524    pub(crate) fn size(&self) -> usize {
525        self.buffer.borrow().len()
526    }
527
528    pub(crate) fn into_bytes(self) -> Box<[u8]> {
529        self.buffer.into_inner().into_boxed_slice()
530    }
531}
532
533impl<S> SandboxMemoryManager<S>
534where
535    S: SharedMemory,
536{
537    /// First GPA available to the guest scratch allocator.
538    pub(crate) fn first_free_scratch_gpa(&self) -> u64 {
539        self.layout.get_pt_base_gpa() + self.shared_mem.page_table_len() as u64
540    }
541
542    /// Create a new `SandboxMemoryManager` with the given parameters
543    #[instrument(skip_all, parent = Span::current(), level= "Trace")]
544    pub(crate) fn new(
545        layout: SandboxMemoryLayout,
546        shared_mem: SnapshotMemoryBacking<S>,
547        scratch_mem: S,
548        next_action: NextAction,
549    ) -> Self {
550        Self {
551            layout,
552            shared_mem,
553            scratch_mem,
554            next_action,
555            original_entrypoint: 0,
556            abort_buffer: Vec::new(),
557            execution_mode: ExecutionMode::Unrestricted,
558            snapshot_count: 0,
559            g2h_consumer: None,
560            h2g_consumer: None,
561            next_guest_cid: 1,
562        }
563    }
564
565    /// Get mutable access to the abort buffer
566    pub(crate) fn get_abort_buffer_mut(&mut self) -> &mut Vec<u8> {
567        &mut self.abort_buffer
568    }
569}
570
571impl SandboxMemoryManager<ExclusiveSharedMemory> {
572    pub(crate) fn from_snapshot(s: &Snapshot) -> Result<Self> {
573        let layout = *s.layout();
574        let shared_mem = SnapshotMemoryBacking::from_snapshot(s.snapshot_memory().clone())?;
575        let scratch_mem = ExclusiveSharedMemory::new(s.layout().get_scratch_size())?;
576        let next_action = s.next_action();
577        let mut mgr = Self::new(layout, shared_mem, scratch_mem, next_action);
578        mgr.original_entrypoint = s.original_entrypoint();
579        // Inherit the snapshot's generation number for the same
580        // reason `restore_snapshot` does: the guest-visible counter
581        // reflects "which snapshot is the sandbox currently a clone
582        // of", not "how many snapshots this partition has taken".
583        mgr.snapshot_count = s.snapshot_generation();
584        Ok(mgr)
585    }
586
587    /// Wraps ExclusiveSharedMemory::build
588    // Morally, this should not have to be a Result: this operation is
589    // infallible. The source of the Result is
590    // update_scratch_bookkeeping(), which calls functions that can
591    // fail due to bounds checks (which are statically known to be ok
592    // in this situation) or due to failing to take the scratch shared
593    // memory lock, but the scratch shared memory is built in this
594    // function, its lock does not escape before the end of the
595    // function, and the lock is taken by no other code path, so we
596    // know it is not contended.
597    pub fn build(
598        self,
599    ) -> Result<(
600        SandboxMemoryManager<HostSharedMemory>,
601        SandboxMemoryManager<GuestSharedMemory>,
602    )> {
603        let (hshm, gshm) = self.shared_mem.build();
604        let (hscratch, gscratch) = self.scratch_mem.build();
605        let mut host_mgr = SandboxMemoryManager {
606            shared_mem: hshm,
607            scratch_mem: hscratch,
608            layout: self.layout,
609            next_action: self.next_action,
610            original_entrypoint: self.original_entrypoint,
611            abort_buffer: self.abort_buffer,
612            execution_mode: self.execution_mode,
613            snapshot_count: self.snapshot_count,
614            g2h_consumer: None,
615            h2g_consumer: None,
616            next_guest_cid: self.next_guest_cid,
617        };
618        let guest_mgr = SandboxMemoryManager {
619            shared_mem: gshm,
620            scratch_mem: gscratch,
621            layout: self.layout,
622            next_action: self.next_action,
623            original_entrypoint: self.original_entrypoint,
624            abort_buffer: Vec::new(), // Guest doesn't need abort buffer
625            execution_mode: self.execution_mode,
626            snapshot_count: self.snapshot_count,
627            g2h_consumer: None,
628            h2g_consumer: None,
629            next_guest_cid: self.next_guest_cid,
630        };
631        host_mgr.update_scratch_bookkeeping()?;
632
633        if matches!(host_mgr.next_action, NextAction::Initialise(_)) {
634            let cp = MailboxValue::CheckpointPending.as_bytes();
635            let mbx = host_mgr.layout.mbx_scratch_offset();
636
637            host_mgr.scratch_mem.copy_from_slice(cp, mbx)?;
638            host_mgr.create_virtq_consumers()?;
639        }
640
641        Ok((host_mgr, guest_mgr))
642    }
643}
644
645impl SandboxMemoryManager<HostSharedMemory> {
646    /// Runs `f` with a view of guest physical memory, including `dynamic`.
647    pub(crate) fn with_guest_memory<T>(
648        &self,
649        dynamic: &[MemoryRegion],
650        f: impl FnOnce(&GuestPhysicalMemoryView<'_>) -> Result<T>,
651    ) -> Result<T> {
652        GuestPhysicalMemoryView::with_memory(
653            &self.shared_mem,
654            &self.scratch_mem,
655            dynamic,
656            self.layout,
657            f,
658        )
659    }
660
661    #[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
662    pub(crate) fn with_guest_virtual_memory_reader<T>(
663        &self,
664        root_pt: u64,
665        f: impl FnOnce(&mut GuestVirtualMemoryReader<'_>) -> Result<T>,
666    ) -> Result<T> {
667        self.with_guest_memory(&[], |memory| {
668            f(&mut GuestVirtualMemoryReader::new(memory, root_pt))
669        })
670    }
671
672    /// Create a snapshot with the given mapped regions.
673    #[allow(clippy::too_many_arguments)]
674    pub(crate) fn snapshot(
675        &mut self,
676        mapped_regions: Vec<MemoryRegion>,
677        root_pt_gpas: &[u64],
678        rsp_gva: u64,
679        sregs: CommonSpecialRegisters,
680        #[cfg(target_arch = "x86_64")] msrs: Vec<crate::hypervisor::regs::MsrEntry>,
681        next_action: NextAction,
682        host_functions: HostFunctionDetails,
683        scratch_size: usize,
684    ) -> Result<Snapshot> {
685        let virtq = match (&self.g2h_consumer, &self.h2g_consumer) {
686            (Some(_), Some(_)) => Some(VirtqSnapshot::capture(&self.layout, &self.scratch_mem)?),
687            (None, None) => None,
688            _ => return Err(new_error!("virtqueue consumer ownership is incomplete")),
689        };
690
691        let layout = self.layout;
692        let original_entrypoint = self.original_entrypoint;
693        let snapshot_generation = self.snapshot_count + 1;
694        let snapshot = self.with_guest_memory(&mapped_regions, |memory| {
695            Snapshot::new(
696                memory,
697                layout,
698                crate::mem::exe::LoadInfo::dummy(),
699                root_pt_gpas,
700                rsp_gva,
701                sregs,
702                #[cfg(target_arch = "x86_64")]
703                msrs,
704                next_action,
705                original_entrypoint,
706                snapshot_generation,
707                host_functions,
708                virtq,
709                scratch_size,
710            )
711        })?;
712        self.snapshot_count = snapshot.snapshot_generation();
713        Ok(snapshot)
714    }
715
716    /// Create host consumers before the guest initializes the transport.
717    ///
718    /// The consumers begin at cursor zero and observe descriptors published
719    /// during the first guest entry.
720    fn create_virtq_consumers(&mut self) -> Result<()> {
721        if self.g2h_consumer.is_some() || self.h2g_consumer.is_some() {
722            return Err(new_error!("virtqueue consumers already exist"));
723        }
724
725        let (g2h, h2g) = virtq::create_consumers(&self.layout, &self.scratch_mem)?;
726        self.g2h_consumer = Some(g2h);
727        self.h2g_consumer = Some(h2g);
728        Ok(())
729    }
730
731    /// Restore admitted ring images into this scratch mapping.
732    pub(crate) fn restore_virtq(&mut self, snapshot: &VirtqSnapshot) -> Result<()> {
733        if self.g2h_consumer.is_some() || self.h2g_consumer.is_some() {
734            return Err(new_error!("virtqueue consumers are already attached"));
735        }
736
737        let (g2h, h2g) = snapshot.restore(&self.layout, &self.scratch_mem)?;
738        self.g2h_consumer = Some(g2h);
739        self.h2g_consumer = Some(h2g);
740        Ok(())
741    }
742
743    /// Write a guest function call into the H2G virtqueue.
744    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
745    pub(crate) fn write_guest_function_call(&mut self, call: &FunctionCall) -> Result<u32> {
746        let cid = self.next_guest_cid;
747        let params = call.parameters.as_deref().unwrap_or_default();
748        let cap = estimate_flatbuffer_capacity(&call.function_name, params);
749
750        let mut builder = FlatBufferBuilder::with_capacity(cap);
751        let mut externals = ExternalValues::new();
752
753        let control = call.encode(&mut builder, &mut externals)?;
754
755        let Some(msg) = EncodedMessage::new(MsgKind::Request, cid, control, externals) else {
756            return Err(new_error!("H2G request exceeds the wire payload limit"));
757        };
758
759        self.write_h2g_message(&msg)?;
760
761        self.next_guest_cid = cid.wrapping_add(1);
762        if self.next_guest_cid == 0 {
763            self.next_guest_cid = 1;
764        }
765
766        Ok(cid)
767    }
768
769    fn write_h2g_message(&mut self, message: &EncodedMessage<'_>) -> Result<()> {
770        let consumer = self.h2g_consumer.as_mut().ok_or_else(|| {
771            HyperlightError::TransportError("H2G consumer is not attached".into())
772        })?;
773
774        let buffer_size = self.layout.get_h2g_buffer_size();
775        let buffer_count = message.total_len().div_ceil(buffer_size);
776
777        // Keep a buffer for a control call that releases retained external bytes.
778        let control_reserve = usize::from(message.external_len() != 0);
779
780        // H2G receive buffers are writable-only, so any readable payload is malformed.
781        let maybe_buffers = consumer
782            .poll_batch(buffer_count, control_reserve, 0)
783            .map_err(|error| {
784                HyperlightError::TransportError(format!("H2G poll failed: {error}"))
785            })?;
786
787        let Some(buffers) = maybe_buffers else {
788            return Err(new_error!(
789                "H2G capacity cannot provide {buffer_count} buffers with {control_reserve} spare"
790            ));
791        };
792
793        // The message is a contiguous sequence of bytes, but the buffers are a chain of possibly
794        // non contiguous slices. Write the message into the buffers in order, advancing the message
795        // cursor as we go.
796        let mut message = message.as_buf();
797
798        for (recv, reply) in buffers {
799            let ReplyChain::Writable(mut buffer) = reply else {
800                return Err(HyperlightError::TransportError(
801                    "H2G receive buffer is not writable".into(),
802                ));
803            };
804
805            if buffer.desc_count() != 1 || buffer.capacity() != buffer_size {
806                return Err(HyperlightError::TransportError(
807                    "H2G receive buffer has an invalid shape".into(),
808                ));
809            }
810
811            while message.has_remaining() && buffer.remaining() != 0 {
812                let written = buffer.write(message.chunk()).map_err(|err| {
813                    HyperlightError::TransportError(format!("H2G write failed: {err}"))
814                })?;
815
816                message.advance(written);
817            }
818
819            consumer.complete(recv, buffer).map_err(|err| {
820                HyperlightError::TransportError(format!("H2G completion failed: {err}"))
821            })?;
822        }
823
824        debug_assert!(!message.has_remaining());
825        Ok(())
826    }
827
828    /// Read a guest function result from the G2H virtqueue.
829    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
830    pub(crate) fn read_h2g_result_from_g2h(&mut self, cid: u32) -> Result<FunctionCallResult> {
831        let max_recv_len = self.layout.get_g2h_queue_dims().pool_len();
832
833        let Some(consumer) = self.g2h_consumer.as_mut() else {
834            return Err(HyperlightError::TransportError(
835                "G2H consumer is not attached".into(),
836            ));
837        };
838
839        loop {
840            let maybe_next = consumer.poll(max_recv_len).map_err(|err| {
841                HyperlightError::TransportError(format!("G2H poll failed: {err}"))
842            })?;
843
844            let Some((mut recv, reply)) = maybe_next else {
845                return Err(HyperlightError::TransportError(
846                    "G2H has no guest function result after halt".into(),
847                ));
848            };
849
850            let header = virtq::read_message_header(&mut recv).map_err(|err| {
851                HyperlightError::TransportError(format!("Failed to read G2H result header: {err}"))
852            })?;
853
854            if !matches!(&reply, ReplyChain::Ack(_)) {
855                return Err(HyperlightError::TransportError(
856                    "G2H result entry has writable buffers".into(),
857                ));
858            }
859
860            match header.kind {
861                MsgKind::Log => {
862                    if header.cid != 0 {
863                        return Err(HyperlightError::TransportError(
864                            "G2H log has a correlation ID".into(),
865                        ));
866                    }
867
868                    let log = virtq::read_guest_log_data(&mut recv).map_err(|err| {
869                        HyperlightError::TransportError(format!("Failed to read G2H log: {err}"))
870                    })?;
871
872                    consumer.complete(recv, reply).map_err(|err| {
873                        HyperlightError::TransportError(format!(
874                            "Failed to complete G2H log: {err}"
875                        ))
876                    })?;
877
878                    crate::sandbox::outb::emit_guest_log(&log);
879                }
880                MsgKind::Response => {
881                    if header.cid != cid {
882                        return Err(HyperlightError::TransportError(
883                            "G2H guest function result correlation ID mismatch".into(),
884                        ));
885                    }
886
887                    let result = virtq::read_guest_function_call_result(&mut recv);
888                    consumer.complete(recv, reply).map_err(|err| {
889                        HyperlightError::TransportError(format!(
890                            "Failed to complete G2H guest function result: {err}"
891                        ))
892                    })?;
893
894                    return result.map_err(|err| {
895                        HyperlightError::TransportError(format!(
896                            "Failed to decode G2H guest function result: {err}"
897                        ))
898                    });
899                }
900                kind => {
901                    return Err(HyperlightError::TransportError(format!(
902                        "Expected G2H guest function result, got {kind:?}"
903                    )));
904                }
905            }
906        }
907    }
908
909    /// Publish an internal request for guest-side snapshot canonicalization.
910    ///
911    /// The pending marker distinguishes a completed checkpoint from an early halt.
912    pub(crate) fn begin_snapshot_checkpoint(&mut self) -> Result<()> {
913        let offset = self.layout.mbx_scratch_offset();
914        let cp = MailboxValue::CheckpointPending.as_bytes();
915        self.scratch_mem.copy_from_slice(cp, offset)?;
916
917        let message = EncodedMessage::new_snapshot_cp();
918        self.write_h2g_message(&message)
919    }
920
921    /// Reset consumers and require the guest's completion status.
922    pub(crate) fn finish_snapshot_checkpoint(&mut self) -> Result<()> {
923        let Some(g2h) = self.g2h_consumer.as_mut() else {
924            return Err(new_error!("G2H consumer is not attached"));
925        };
926
927        let Some(h2g) = self.h2g_consumer.as_mut() else {
928            return Err(new_error!("H2G consumer is not attached"));
929        };
930
931        g2h.reset()?;
932        h2g.reset()?;
933
934        let status = self
935            .scratch_mem
936            .read::<u64>(self.layout.mbx_scratch_offset())
937            .map_err(|error| HyperlightError::TransportError(error.to_string()))?;
938
939        match MailboxValue::try_from(status) {
940            Ok(MailboxValue::CheckpointComplete) => Ok(()),
941            Ok(MailboxValue::CheckpointPending) => Err(HyperlightError::TransportError(
942                "Guest did not publish snapshot checkpoint status".into(),
943            )),
944            Err(_) => Err(HyperlightError::TransportError(format!(
945                "Guest published invalid snapshot checkpoint status {status:#x}"
946            ))),
947        }
948    }
949
950    fn replace_snapshot_memory(
951        &mut self,
952        snapshot: &Snapshot,
953    ) -> Result<SnapshotMemoryBacking<GuestSharedMemory>> {
954        let new_snapshot_mem =
955            SnapshotMemoryBacking::from_snapshot(snapshot.snapshot_memory().clone())?;
956        let (hsnapshot, gsnapshot) = new_snapshot_mem.build();
957        self.shared_mem = hsnapshot;
958        Ok(gsnapshot)
959    }
960
961    fn apply_snapshot_metadata(&mut self, snapshot: &Snapshot) {
962        self.layout = *snapshot.layout();
963        // Inherit the snapshot's own generation number — the
964        // guest-visible counter reflects "which snapshot is the
965        // sandbox currently a clone of", not "how many restores have
966        // happened into this (possibly-reused) partition".
967        self.snapshot_count = snapshot.snapshot_generation();
968        // Carry the guest ELF entry point across restore so crashdumps
969        // report the restored image's entry.
970        self.original_entrypoint = snapshot.original_entrypoint();
971    }
972
973    /// Installs memory produced by a capture without restoring runtime state.
974    ///
975    /// A capture with another scratch size moves the scratch base and page
976    /// tables. It gets new scratch, which the caller maps.
977    pub(crate) fn install_captured_snapshot(
978        &mut self,
979        snapshot: &Snapshot,
980    ) -> Result<(
981        SnapshotMemoryBacking<GuestSharedMemory>,
982        Option<GuestSharedMemory>,
983    )> {
984        if snapshot.layout().get_scratch_size() != self.scratch_mem.mem_size() {
985            let requests = self.guest_requests()?;
986            let memory = self.restore_snapshot(snapshot)?;
987            self.set_guest_requests(requests)?;
988            return Ok(memory);
989        }
990        let used_scratch_end = self.used_scratch_end_gpa()?;
991        let gsnapshot = self.replace_snapshot_memory(snapshot)?;
992        self.apply_snapshot_metadata(snapshot);
993        self.update_snapshot_scratch_bookkeeping()?;
994        self.zero_freed_scratch(used_scratch_end)?;
995        Ok((gsnapshot, None))
996    }
997
998    /// The end of the scratch the guest has allocated: its allocator's next
999    /// free page. The guest controls that value, so it is held to the
1000    /// transport arena, where the guest's allocator stops.
1001    fn used_scratch_end_gpa(&self) -> Result<u64> {
1002        let offset = self.scratch_mem.mem_size()
1003            - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
1004        let end = self.scratch_mem.read::<u64>(offset)?;
1005        Ok(end.min(self.layout.get_transport_arena().base_addr()))
1006    }
1007
1008    /// Bytes of scratch the guest has allocated since the allocator was
1009    /// last reset, at build, restore or snapshot.
1010    pub(crate) fn scratch_allocated_bytes(&self) -> Result<u64> {
1011        Ok(self
1012            .used_scratch_end_gpa()?
1013            .saturating_sub(self.first_free_scratch_gpa()))
1014    }
1015
1016    /// Zeroes the scratch pages freed by resetting the allocator, up to
1017    /// `end`, the allocator's end as `used_scratch_end_gpa` read it.
1018    fn zero_freed_scratch(&mut self, end: u64) -> Result<()> {
1019        let scratch_base = hyperlight_common::layout::scratch_base_gpa(self.scratch_mem.mem_size());
1020        let start = self.first_free_scratch_gpa();
1021        if end <= start {
1022            return Ok(());
1023        }
1024        let start = usize::try_from(start - scratch_base)?;
1025        let end = usize::try_from(end - scratch_base)?;
1026        self.scratch_mem
1027            .with_exclusivity(|scratch| scratch.as_mut_slice()[start..end].fill(0))?;
1028        Ok(())
1029    }
1030
1031    /// Restore base memory after the caller checks snapshot compatibility.
1032    pub(crate) fn restore_snapshot(
1033        &mut self,
1034        snapshot: &Snapshot,
1035    ) -> Result<(
1036        SnapshotMemoryBacking<GuestSharedMemory>,
1037        Option<GuestSharedMemory>,
1038    )> {
1039        let virtq = snapshot.virtq();
1040
1041        if virtq.is_none() && matches!(snapshot.next_action(), NextAction::Call(_)) {
1042            return Err(new_error!(
1043                "running snapshot has no canonical transport state"
1044            ));
1045        }
1046
1047        self.g2h_consumer = None;
1048        self.h2g_consumer = None;
1049        self.execution_mode = ExecutionMode::Unrestricted;
1050
1051        // A panic during restricted dispatch can skip the mode reset.
1052        self.execution_mode = ExecutionMode::Unrestricted;
1053
1054        let gsnapshot = self.replace_snapshot_memory(snapshot)?;
1055        let new_scratch_size = snapshot.layout().get_scratch_size();
1056        let gscratch = if new_scratch_size == self.scratch_mem.mem_size() {
1057            // zero_or_replace picks the fastest zeroing strategy for
1058            // the current platform (see SharedMemory::zero_or_replace).
1059            self.scratch_mem.zero_or_replace()?
1060        } else {
1061            let new_scratch_mem = ExclusiveSharedMemory::new(new_scratch_size)?;
1062            let (hscratch, gscratch) = new_scratch_mem.build();
1063            // Even though this destroys the reference to the host
1064            // side of the old scratch mapping, the VM should still
1065            // own the reference to the guest side of the old scratch
1066            // mapping, so it won't actually be deallocated until it
1067            // has been unmapped from the VM.
1068            self.scratch_mem = hscratch;
1069            Some(gscratch)
1070        };
1071        self.apply_snapshot_metadata(snapshot);
1072        self.update_scratch_bookkeeping()?;
1073        if let Some(virtq) = virtq {
1074            self.restore_virtq(virtq)?;
1075        } else if matches!(snapshot.next_action(), NextAction::Initialise(_)) {
1076            self.scratch_mem.copy_from_slice(
1077                MailboxValue::CheckpointPending.as_bytes(),
1078                self.layout.mbx_scratch_offset(),
1079            )?;
1080            self.create_virtq_consumers()?;
1081        }
1082        Ok((gsnapshot, gscratch))
1083    }
1084
1085    #[inline]
1086    fn update_scratch_bookkeeping_item(&mut self, offset: u64, value: u64) -> Result<()> {
1087        let scratch_size = self.scratch_mem.mem_size();
1088        let base_offset = scratch_size - offset as usize;
1089        self.scratch_mem
1090            .write::<u64>(base_offset, value)
1091            .map_err(From::from)
1092    }
1093
1094    fn guest_requests(&self) -> Result<[u64; 2]> {
1095        let scratch_size = self.scratch_mem.mem_size();
1096        let mut values = [0; 2];
1097        for (value, offset) in values.iter_mut().zip(GUEST_REQUEST_OFFSETS) {
1098            *value = self
1099                .scratch_mem
1100                .read::<u64>(scratch_size - offset as usize)?;
1101        }
1102        Ok(values)
1103    }
1104
1105    fn set_guest_requests(&mut self, values: [u64; 2]) -> Result<()> {
1106        for (value, offset) in values.into_iter().zip(GUEST_REQUEST_OFFSETS) {
1107            self.update_scratch_bookkeeping_item(offset, value)?;
1108        }
1109        Ok(())
1110    }
1111
1112    pub(crate) fn request_libc_rng_reseed(&mut self, seed: u32) -> Result<()> {
1113        // Zero means no request. The upper half marks a pending request, and
1114        // the lower half contains the complete u32 seed.
1115        self.update_scratch_bookkeeping_item(
1116            hyperlight_common::layout::SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
1117            (1_u64 << 32) | u64::from(seed),
1118        )
1119    }
1120
1121    pub(crate) fn request_guest_log_level_update(
1122        &mut self,
1123        log_level: tracing_core::LevelFilter,
1124    ) -> Result<()> {
1125        self.update_scratch_bookkeeping_item(
1126            hyperlight_common::layout::SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
1127            (hyperlight_common::log_level::GUEST_LOG_FILTER_UPDATE_PENDING)
1128                | u64::from(GuestLogFilter::from(log_level)),
1129        )
1130    }
1131
1132    fn update_scratch_bookkeeping(&mut self) -> Result<()> {
1133        use hyperlight_common::layout::*;
1134        let scratch_size = self.scratch_mem.mem_size();
1135        self.update_scratch_bookkeeping_item(SCRATCH_TOP_SIZE_OFFSET, scratch_size as u64)?;
1136        self.update_snapshot_scratch_bookkeeping()?;
1137
1138        Ok(())
1139    }
1140
1141    fn update_snapshot_scratch_bookkeeping(&mut self) -> Result<()> {
1142        use hyperlight_common::layout::*;
1143        self.update_scratch_bookkeeping_item(
1144            SCRATCH_TOP_ALLOCATOR_OFFSET,
1145            self.first_free_scratch_gpa(),
1146        )?;
1147        // Record the GPA of the snapshot's copy of the page tables.
1148        // The copy lives at the tail of the snapshot blob; we copy it
1149        // into scratch below so the guest walker can run against
1150        // mutable, TLB-fresh tables. The guest reads this GPA during
1151        // CoW fault-in to follow the original PTs on the first write
1152        // — until the HV can execute directly out of the
1153        // snapshot-resident PTs, at which point the whole split goes
1154        // away.
1155        self.update_scratch_bookkeeping_item(
1156            SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET,
1157            self.layout.get_pt_base_gpa(),
1158        )?;
1159        self.update_scratch_bookkeeping_item(
1160            SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET,
1161            self.snapshot_count,
1162        )?;
1163        self.update_scratch_bookkeeping_item(
1164            SCRATCH_TOP_HEAP_EXECUTABLE_OFFSET,
1165            cfg!(feature = "executable_heap") as u64,
1166        )?;
1167        // Record the G2H and H2G queue sizes, pool page counts, and buffer sizes.
1168        self.update_scratch_bookkeeping_item(
1169            SCRATCH_TOP_G2H_QUEUE_SIZE_OFFSET,
1170            u64::try_from(self.layout.get_g2h_queue_size())?,
1171        )?;
1172        self.update_scratch_bookkeeping_item(
1173            SCRATCH_TOP_G2H_POOL_PAGES_OFFSET,
1174            u64::try_from(self.layout.get_g2h_pool_pages())?,
1175        )?;
1176        self.update_scratch_bookkeeping_item(
1177            SCRATCH_TOP_G2H_BUFFER_SIZE_OFFSET,
1178            u64::try_from(self.layout.get_g2h_buffer_size())?,
1179        )?;
1180        self.update_scratch_bookkeeping_item(
1181            SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET,
1182            u64::try_from(self.layout.get_h2g_queue_size())?,
1183        )?;
1184        self.update_scratch_bookkeeping_item(
1185            SCRATCH_TOP_H2G_POOL_PAGES_OFFSET,
1186            u64::try_from(self.layout.get_h2g_pool_pages())?,
1187        )?;
1188        self.update_scratch_bookkeeping_item(
1189            SCRATCH_TOP_H2G_BUFFER_SIZE_OFFSET,
1190            u64::try_from(self.layout.get_h2g_buffer_size())?,
1191        )?;
1192
1193        let transport_arena = self.layout.get_transport_arena();
1194        self.update_scratch_bookkeeping_item(
1195            SCRATCH_TOP_TRANSPORT_ARENA_GPA_OFFSET,
1196            transport_arena.base_addr(),
1197        )?;
1198
1199        // Copy page tables from `shared_mem` into scratch. PT bytes
1200        // are appended to the snapshot blob at build time and live
1201        // just past the end of the guest-visible KVM slot (see
1202        // `Snapshot::new`). Keeping them outside the KVM slot avoids
1203        // overlapping with `map_file_cow` regions installed
1204        // immediately after the snapshot in the guest PA space.
1205        let page_tables = self.shared_mem.page_table_bytes();
1206        let offset = self.layout.get_pt_base_scratch_offset();
1207        self.scratch_mem
1208            .with_exclusivity(|scratch| scratch.copy_from_slice(page_tables, offset))??;
1209
1210        Ok(())
1211    }
1212
1213    /// Build the list of guest memory regions for a crash dump.
1214    ///
1215    /// By default, walks the guest page tables to discover
1216    /// GVA→GPA mappings and translates them to host-backed regions.
1217    #[cfg(crashdump)]
1218    pub(crate) fn get_guest_memory_regions(
1219        &mut self,
1220        root_pt: u64,
1221        mmap_regions: &[MemoryRegion],
1222    ) -> Result<Vec<CrashDumpRegion>> {
1223        use crate::sandbox::snapshot::PageTableReader;
1224
1225        let len = hyperlight_common::layout::SCRATCH_TOP_GVA;
1226        self.with_guest_memory(mmap_regions, |memory| {
1227            let pt_buf = PageTableReader::new(memory, root_pt);
1228            let mut regions: Vec<CrashDumpRegion> = Vec::new();
1229            let mut saw_mapping = false;
1230            // SAFETY: Crash handling runs with the vCPU stopped, so its page tables
1231            // cannot change during the walk.
1232            for mapping in unsafe { hyperlight_common::vmem::virt_to_phys(&pt_buf, 0, len as u64) }
1233            {
1234                saw_mapping = true;
1235                let (flags, region_type) = mapping_kind_to_flags(&mapping.kind);
1236                let mut mapped = 0usize;
1237                let mapping_len = usize::try_from(mapping.len)?;
1238                while mapped < mapping_len {
1239                    let chunk_len = (mapping_len - mapped).min(hyperlight_common::vmem::PAGE_SIZE);
1240                    let gpa = mapping
1241                        .phys_base
1242                        .checked_add(u64::try_from(mapped)?)
1243                        .ok_or_else(|| new_error!("crash-dump GPA overflows"))?;
1244                    let Some(host_region) = memory.host_range(gpa, chunk_len).ok() else {
1245                        mapped += chunk_len;
1246                        continue;
1247                    };
1248                    let virt_base = usize::try_from(mapping.virt_base)?
1249                        .checked_add(mapped)
1250                        .ok_or_else(|| new_error!("crash-dump GVA overflows"))?;
1251                    let virt_end = virt_base
1252                        .checked_add(chunk_len)
1253                        .ok_or_else(|| new_error!("crash-dump GVA range overflows"))?;
1254
1255                    if !try_coalesce_region(
1256                        &mut regions,
1257                        virt_base,
1258                        virt_end,
1259                        host_region.start,
1260                        flags,
1261                    ) {
1262                        regions.push(CrashDumpRegion {
1263                            guest_region: virt_base..virt_end,
1264                            host_region,
1265                            flags,
1266                            region_type,
1267                        });
1268                    }
1269                    mapped += chunk_len;
1270                }
1271            }
1272            if !saw_mapping {
1273                return Err(new_error!("No page table mappings found (len {len})",));
1274            }
1275
1276            Ok(regions)
1277        })
1278    }
1279
1280    /// Read guest memory at a Guest Virtual Address (GVA) by walking the
1281    /// page tables to translate GVA → GPA, then reading from the correct
1282    /// backing memory (shared_mem or scratch_mem).
1283    ///
1284    /// This is necessary because with Copy-on-Write (CoW) the guest's
1285    /// virtual pages are backed by physical pages in the scratch
1286    /// region rather than being identity-mapped.
1287    ///
1288    /// # Arguments
1289    /// * `gva` - The Guest Virtual Address to read from
1290    /// * `len` - The number of bytes to read
1291    /// * `root_pt` - The root page table physical address (CR3)
1292    #[cfg(feature = "trace_guest")]
1293    pub(crate) fn read_guest_memory_by_gva(
1294        &self,
1295        gva: u64,
1296        len: usize,
1297        root_pt: u64,
1298    ) -> Result<Vec<u8>> {
1299        let mut result = vec![0; len];
1300        self.with_guest_virtual_memory_reader(root_pt, |reader| {
1301            reader.read_exact(gva, &mut result)
1302        })?;
1303        Ok(result)
1304    }
1305}
1306
1307#[cfg(test)]
1308mod tests {
1309    use std::sync::Arc;
1310
1311    use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCallType;
1312    use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterValue, ReturnType};
1313    use hyperlight_common::transport::{
1314        MsgHeader, SIZE_PREFIX_LEN, size_prefix_payload_len, size_prefixed_len,
1315    };
1316    use hyperlight_common::virtq::DescFlags;
1317    use hyperlight_common::vmem::{self, BasicMapping, Mapping, MappingKind, PAGE_SIZE};
1318    #[cfg(target_arch = "x86_64")]
1319    use hyperlight_testing::sandbox_sizes::{
1320        LARGE_SCRATCH_SIZE, MEDIUM_SCRATCH_SIZE, SMALL_SCRATCH_SIZE,
1321    };
1322    #[cfg(target_arch = "x86_64")]
1323    use hyperlight_testing::simple_guest_as_pathbuf;
1324
1325    use super::*;
1326    #[cfg(target_arch = "x86_64")]
1327    use crate::GuestBinary;
1328    use crate::mem::layout::SandboxMemoryLayout;
1329    use crate::mem::memory_region::MemoryRegionType;
1330    use crate::mem::shared_mem::{ExclusiveSharedMemory, ReadonlySharedMemory};
1331    use crate::mem::virtq::tests::{H2G_BUFFER_SIZE, SCRATCH_SIZE, TestCase, memory_layout};
1332    use crate::sandbox::SandboxConfiguration;
1333    #[cfg(target_arch = "x86_64")]
1334    use crate::sandbox::snapshot::Snapshot;
1335    use crate::sandbox::snapshot::memory::tests::flat_memory;
1336    use crate::sandbox::snapshot::{SnapshotBlob, SnapshotMemory};
1337
1338    fn manager(case: &TestCase) -> SandboxMemoryManager<HostSharedMemory> {
1339        let host_page_size = page_size::get();
1340        let layout = memory_layout();
1341        let snapshot = Arc::new(flat_memory(
1342            &vec![0; host_page_size],
1343            &[0; PAGE_SIZE],
1344            SandboxMemoryLayout::BASE_ADDRESS as u64,
1345            hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
1346        ));
1347
1348        let mut mgr = SandboxMemoryManager::new(
1349            layout,
1350            SnapshotMemoryBacking::from_snapshot(snapshot)
1351                .unwrap()
1352                .build()
1353                .0,
1354            case.scratch.clone(),
1355            NextAction::None,
1356        );
1357
1358        mgr.h2g_consumer = Some(case.h2g_consumer());
1359        mgr
1360    }
1361
1362    fn h2g_call(bytes: usize) -> FunctionCall {
1363        let params = (bytes != 0).then(|| vec![ParameterValue::VecBytes(vec![0xa5; bytes])]);
1364        FunctionCall::new(
1365            "call".to_string(),
1366            params,
1367            FunctionCallType::Guest,
1368            ReturnType::Void,
1369        )
1370    }
1371
1372    #[test]
1373    fn rejects_invalid_h2g_descriptors() {
1374        for (len, expected) in [
1375            (H2G_BUFFER_SIZE as u32, "Payload data too large"),
1376            (0, "not writable"),
1377        ] {
1378            let case = TestCase::new();
1379            let mut mgr = manager(&case);
1380            let mut desc = case.h2g_desc(0);
1381
1382            desc.flags &= !DescFlags::WRITE.bits();
1383            desc.len = len;
1384            case.set_h2g_desc(0, desc);
1385
1386            let error = mgr.write_guest_function_call(&h2g_call(0)).unwrap_err();
1387
1388            assert!(error.to_string().contains(expected), "{error:#}");
1389            assert!(error.is_poison_error());
1390            assert!(matches!(error, HyperlightError::TransportError(_)));
1391        }
1392    }
1393
1394    #[test]
1395    fn partial_h2g_write_is_fatal() {
1396        let case = TestCase::new();
1397        let mut mgr = manager(&case);
1398        let mut desc = case.h2g_desc(1);
1399
1400        desc.addr = hyperlight_common::layout::scratch_base_gva(SCRATCH_SIZE) + SCRATCH_SIZE as u64;
1401        case.set_h2g_desc(1, desc);
1402
1403        let error = mgr
1404            .write_guest_function_call(&h2g_call(H2G_BUFFER_SIZE + 1024))
1405            .unwrap_err();
1406
1407        assert!(error.to_string().contains("Memory write"), "{error:#}");
1408        assert!(error.is_poison_error());
1409        assert!(matches!(error, HyperlightError::TransportError(_)));
1410        assert_eq!(mgr.h2g_consumer.as_ref().unwrap().used_cursor().head(), 1);
1411    }
1412
1413    #[test]
1414    fn insufficient_h2g_capacity_rolls_back() {
1415        let case = TestCase::new();
1416        let mut mgr = manager(&case);
1417        let cursor = mgr.h2g_consumer.as_ref().unwrap().avail_cursor();
1418
1419        let error = mgr
1420            .write_guest_function_call(&h2g_call(H2G_BUFFER_SIZE * 4))
1421            .unwrap_err();
1422
1423        assert!(error.to_string().contains("H2G capacity"), "{error:#}");
1424        assert!(!error.is_poison_error());
1425        assert_eq!(mgr.h2g_consumer.as_ref().unwrap().avail_cursor(), cursor);
1426        assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
1427    }
1428
1429    #[test]
1430    fn missing_g2h_result_is_fatal() {
1431        let case = TestCase::new();
1432        let mut mgr = manager(&case);
1433        mgr.g2h_consumer = Some(case.g2h_consumer());
1434
1435        let Err(error) = mgr.read_h2g_result_from_g2h(1) else {
1436            panic!("expected missing G2H result");
1437        };
1438
1439        assert!(
1440            error
1441                .to_string()
1442                .contains("G2H has no guest function result")
1443        );
1444        assert!(error.is_poison_error());
1445        assert!(matches!(error, HyperlightError::TransportError(_)));
1446    }
1447
1448    #[test]
1449    fn writes_dense_h2g_request_and_reserves_control_buffer() {
1450        let case = TestCase::new();
1451        let mut mgr = manager(&case);
1452        let external_len = H2G_BUFFER_SIZE * 2;
1453        let buffers: Vec<_> = (0..4).map(|index| case.h2g_desc(index).addr).collect();
1454
1455        let cid = mgr
1456            .write_guest_function_call(&h2g_call(external_len))
1457            .unwrap();
1458
1459        let used = mgr.h2g_consumer.as_ref().unwrap().avail_cursor().head();
1460        let wire: Vec<u8> = (0..used)
1461            .flat_map(|index| case.h2g_buffer(index, buffers[index as usize]))
1462            .collect();
1463
1464        let header = MsgHeader::from_bytes(&wire[..MsgHeader::SIZE]).unwrap();
1465        assert_eq!(header.kind, MsgKind::Request);
1466        assert_eq!(header.cid, cid);
1467        assert_eq!(header.payload_len as usize, wire.len() - MsgHeader::SIZE);
1468
1469        let control =
1470            size_prefix_payload_len(&wire[MsgHeader::SIZE..MsgHeader::SIZE + SIZE_PREFIX_LEN])
1471                .unwrap();
1472
1473        let control_len = size_prefixed_len(control).unwrap();
1474        let external = &wire[MsgHeader::SIZE + control_len..];
1475        assert_eq!(external, vec![0xa5; external_len]);
1476
1477        let cursor = mgr.h2g_consumer.as_ref().unwrap().avail_cursor();
1478        let error = mgr.write_guest_function_call(&h2g_call(1)).unwrap_err();
1479
1480        assert!(error.to_string().contains("H2G capacity"), "{error:#}");
1481        assert_eq!(mgr.h2g_consumer.as_ref().unwrap().avail_cursor(), cursor);
1482        assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 2);
1483    }
1484
1485    #[test]
1486    fn writes_header_only_snapshot_checkpoint() {
1487        let case = TestCase::new();
1488        let mut mgr = manager(&case);
1489        let buffer = case.h2g_desc(0).addr;
1490
1491        let mbx = mgr.layout.mbx_scratch_offset();
1492        let cp = MailboxValue::CheckpointComplete.as_bytes();
1493
1494        mgr.scratch_mem.copy_from_slice(cp, mbx).unwrap();
1495        mgr.begin_snapshot_checkpoint().unwrap();
1496
1497        let wire = case.h2g_buffer(0, buffer);
1498        let header = MsgHeader::from_bytes(&wire).unwrap();
1499
1500        assert_eq!(wire.len(), MsgHeader::SIZE);
1501        assert_eq!(header.kind, MsgKind::SnapshotCheckpoint);
1502        assert_eq!(header.cid, 0);
1503        assert_eq!(header.payload_len, 0);
1504        assert_eq!(mgr.next_guest_cid, 1);
1505
1506        assert_eq!(
1507            MailboxValue::try_from(mgr.scratch_mem.read::<u64>(mbx).unwrap()).unwrap(),
1508            MailboxValue::CheckpointPending
1509        );
1510    }
1511
1512    #[test]
1513    fn incomplete_snapshot_checkpoint_is_fatal() {
1514        let case = TestCase::new();
1515        let mut mgr = manager(&case);
1516        mgr.g2h_consumer = Some(case.g2h_consumer());
1517        mgr.begin_snapshot_checkpoint().unwrap();
1518
1519        let error = mgr.finish_snapshot_checkpoint().unwrap_err();
1520
1521        assert!(matches!(error, HyperlightError::TransportError(_)));
1522        assert!(error.is_poison_error());
1523    }
1524
1525    #[test]
1526    fn reads_completed_snapshot_checkpoint_status() {
1527        let case = TestCase::new();
1528        let mut mgr = manager(&case);
1529        mgr.g2h_consumer = Some(case.g2h_consumer());
1530        mgr.begin_snapshot_checkpoint().unwrap();
1531        let mbx = mgr.layout.mbx_scratch_offset();
1532        mgr.scratch_mem
1533            .copy_from_slice(MailboxValue::CheckpointComplete.as_bytes(), mbx)
1534            .unwrap();
1535
1536        mgr.finish_snapshot_checkpoint().unwrap();
1537        let consumer = mgr.h2g_consumer.as_ref().unwrap();
1538        assert_eq!(consumer.avail_cursor().head(), 0);
1539        assert_eq!(consumer.used_cursor().head(), 0);
1540    }
1541
1542    #[test]
1543    fn invalid_checkpoint_status_is_fatal() {
1544        for status in [2, 3, 0xa000, u64::MAX - 1, u64::MAX] {
1545            let queue = TestCase::new();
1546            let mut mgr = manager(&queue);
1547            mgr.g2h_consumer = Some(queue.g2h_consumer());
1548            let mbx = mgr.layout.mbx_scratch_offset();
1549            mgr.scratch_mem.write::<u64>(mbx, status).unwrap();
1550            let error = mgr.finish_snapshot_checkpoint().unwrap_err();
1551
1552            assert!(matches!(error, HyperlightError::TransportError(_)));
1553            assert!(error.is_poison_error(), "{error}");
1554        }
1555    }
1556
1557    #[test]
1558    fn guest_cid_wraps_without_zero() {
1559        let case = TestCase::new();
1560        let mut mgr = manager(&case);
1561        mgr.next_guest_cid = u32::MAX;
1562
1563        assert_eq!(
1564            mgr.write_guest_function_call(&h2g_call(0)).unwrap(),
1565            u32::MAX
1566        );
1567        assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
1568    }
1569
1570    #[test]
1571    fn cloning_preserves_guest_cids_without_consumers() {
1572        let case = TestCase::new();
1573        let mut mgr = manager(&case);
1574        mgr.g2h_consumer = Some(case.g2h_consumer());
1575        mgr.write_guest_function_call(&h2g_call(0)).unwrap();
1576
1577        let cloned = mgr.clone();
1578
1579        assert!(cloned.g2h_consumer.is_none());
1580        assert!(cloned.h2g_consumer.is_none());
1581        assert_eq!(cloned.next_guest_cid, 2);
1582        assert!(mgr.g2h_consumer.is_some());
1583        assert!(mgr.h2g_consumer.is_some());
1584    }
1585
1586    #[test]
1587    fn restoring_transport_preserves_guest_cids() {
1588        let case = TestCase::new();
1589        let mut mgr = manager(&case);
1590        mgr.g2h_consumer = Some(case.g2h_consumer());
1591        let captured = VirtqSnapshot::capture(&mgr.layout, &mgr.scratch_mem).unwrap();
1592        assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
1593
1594        mgr.g2h_consumer = None;
1595        mgr.h2g_consumer = None;
1596        mgr.restore_virtq(&captured).unwrap();
1597
1598        assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 2);
1599    }
1600
1601    /// Build a snapshot for the given configuration and verify the
1602    /// NULL page is not mapped in its page tables.
1603    #[cfg(target_arch = "x86_64")]
1604    fn verify_page_tables(name: &str, config: SandboxConfiguration) {
1605        let path = simple_guest_as_pathbuf();
1606        let snapshot = Snapshot::from_env(GuestBinary::FilePath(path), config)
1607            .unwrap_or_else(|e| panic!("{}: failed to create snapshot: {}", name, e));
1608
1609        // Verify NULL page (0x0) is NOT mapped
1610        assert!(
1611            unsafe { hyperlight_common::vmem::virt_to_phys(&snapshot, 0, 1) }
1612                .next()
1613                .is_none(),
1614            "{}: NULL page (0x0) should NOT be mapped",
1615            name
1616        );
1617    }
1618
1619    #[test]
1620    #[cfg(target_arch = "x86_64")]
1621    fn test_page_tables_for_various_configurations() {
1622        let test_cases: [(&str, SandboxConfiguration); 4] = [
1623            ("default", { SandboxConfiguration::default() }),
1624            ("small (8MiB scratch)", {
1625                let mut cfg = SandboxConfiguration::default();
1626                cfg.set_scratch_size(SMALL_SCRATCH_SIZE);
1627                cfg
1628            }),
1629            ("medium (64MiB scratch)", {
1630                let mut cfg = SandboxConfiguration::default();
1631                cfg.set_scratch_size(MEDIUM_SCRATCH_SIZE);
1632                cfg
1633            }),
1634            ("large (256MiB scratch)", {
1635                let mut cfg = SandboxConfiguration::default();
1636                cfg.set_scratch_size(LARGE_SCRATCH_SIZE);
1637                cfg
1638            }),
1639        ];
1640
1641        for (name, config) in test_cases {
1642            verify_page_tables(name, config);
1643        }
1644    }
1645
1646    #[test]
1647    #[cfg(target_arch = "x86_64")]
1648    fn build_creates_virtq_consumers_before_initialization() {
1649        let path = simple_guest_as_pathbuf();
1650        let bin = GuestBinary::FilePath(path);
1651        let config = SandboxConfiguration::default();
1652
1653        let snapshot = Snapshot::from_env(bin, config).unwrap();
1654
1655        let mgr = SandboxMemoryManager::from_snapshot(&snapshot).unwrap();
1656        let (mgr, _) = mgr.build().unwrap();
1657
1658        assert!(mgr.g2h_consumer.is_some());
1659        assert!(mgr.h2g_consumer.is_some());
1660    }
1661
1662    #[test]
1663    fn snapshot_memory_backing_reads_across_layers() {
1664        let host_page_size = page_size::get();
1665        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1666        let scratch = base + (4 * host_page_size) as u64;
1667        let layer = |gpa_start: u64, value: u8| {
1668            let data_len = host_page_size;
1669            let mut storage = ExclusiveSharedMemory::new(data_len).unwrap();
1670            storage
1671                .copy_from_slice(&vec![value; host_page_size], 0)
1672                .unwrap();
1673            let storage = storage.freeze(data_len).unwrap();
1674            Arc::new(SnapshotBlob::new(storage, gpa_start, 0, scratch).unwrap())
1675        };
1676        let first = layer(base, 0x11);
1677        let second = layer(base + host_page_size as u64, 0x22);
1678        let memory = Arc::new(
1679            SnapshotMemory::new(
1680                Box::new([first, second]),
1681                crate::sandbox::snapshot::memory::tests::stub_page_tables(),
1682            )
1683            .unwrap(),
1684        );
1685        let (snapshot, _) = SnapshotMemoryBacking::from_snapshot(memory)
1686            .unwrap()
1687            .build();
1688        let mut bytes = [0; 2];
1689
1690        snapshot
1691            .read_snapshot_gpa(base + host_page_size as u64 - 1, &mut bytes)
1692            .unwrap();
1693
1694        assert_eq!(bytes, [0x11, 0x22]);
1695        assert!(
1696            snapshot
1697                .read_snapshot_gpa(base + 2 * host_page_size as u64 - 1, &mut bytes)
1698                .is_err()
1699        );
1700    }
1701
1702    fn virtual_reader_manager() -> (SandboxMemoryManager<HostSharedMemory>, u64, u64) {
1703        let cfg = SandboxConfiguration::default();
1704        let layout = SandboxMemoryLayout::new(cfg, PAGE_SIZE, 0, None).unwrap();
1705        let host_page_size = page_size::get();
1706        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1707        let second_gpa = base + host_page_size as u64;
1708        let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
1709        let scratch_gpa = scratch_base + layout.get_scratch_size() as u64 - 0x10000;
1710        let pt_base = layout.get_pt_base_gpa();
1711        let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1712        let kind = MappingKind::Basic(BasicMapping {
1713            readable: true,
1714            writable: false,
1715            executable: false,
1716        });
1717        // SAFETY: The local page-table buffer has no concurrent writers.
1718        unsafe {
1719            vmem::map(
1720                &pt_buf,
1721                Mapping {
1722                    phys_base: base,
1723                    virt_base: base,
1724                    len: PAGE_SIZE as u64,
1725                    kind,
1726                },
1727            );
1728            vmem::map(
1729                &pt_buf,
1730                Mapping {
1731                    phys_base: second_gpa,
1732                    virt_base: base + PAGE_SIZE as u64,
1733                    len: PAGE_SIZE as u64,
1734                    kind,
1735                },
1736            );
1737            vmem::map(
1738                &pt_buf,
1739                Mapping {
1740                    phys_base: scratch_gpa,
1741                    virt_base: base + 2 * PAGE_SIZE as u64,
1742                    len: PAGE_SIZE as u64,
1743                    kind,
1744                },
1745            );
1746        }
1747        let page_tables = pt_buf.into_bytes();
1748        layout.ensure_page_tables_fit(page_tables.len()).unwrap();
1749
1750        let first_storage =
1751            ReadonlySharedMemory::from_bytes(&vec![0x11; host_page_size], host_page_size).unwrap();
1752        let first = Arc::new(SnapshotBlob::new(first_storage, base, 0, scratch_base).unwrap());
1753
1754        let second_storage =
1755            ReadonlySharedMemory::from_bytes(&vec![0x22; host_page_size], host_page_size).unwrap();
1756        let second =
1757            Arc::new(SnapshotBlob::new(second_storage, second_gpa, 0, scratch_base).unwrap());
1758        let memory = Arc::new(
1759            SnapshotMemory::new(
1760                Box::new([first, second]),
1761                crate::sandbox::snapshot::memory::tests::page_tables_from_bytes(&page_tables),
1762            )
1763            .unwrap(),
1764        );
1765        let manager = SandboxMemoryManager::new(
1766            layout,
1767            SnapshotMemoryBacking::from_snapshot(memory).unwrap(),
1768            ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap(),
1769            NextAction::None,
1770        );
1771        let (manager, _) = manager.build().unwrap();
1772        manager
1773            .scratch_mem
1774            .copy_from_slice(
1775                &vec![0x33; PAGE_SIZE],
1776                (scratch_gpa - scratch_base) as usize,
1777            )
1778            .unwrap();
1779        (manager, pt_base, base)
1780    }
1781
1782    #[test]
1783    fn virtual_reader_reads_across_snapshot_layers() {
1784        let (manager, pt_base, base) = virtual_reader_manager();
1785        let mut bytes = [0u8; 2];
1786
1787        manager
1788            .with_guest_virtual_memory_reader(pt_base, |reader| {
1789                reader.read_exact(base + PAGE_SIZE as u64 - 1, &mut bytes)
1790            })
1791            .unwrap();
1792
1793        assert_eq!(bytes, [0x11, 0x22]);
1794    }
1795
1796    #[test]
1797    fn virtual_reader_reads_snapshot_and_cow_scratch_across_pages() {
1798        let (manager, root, base) = virtual_reader_manager();
1799        let mut bytes = [0; 2];
1800        manager
1801            .with_guest_virtual_memory_reader(root, |reader| {
1802                reader.read_exact(base + 2 * PAGE_SIZE as u64 - 1, &mut bytes)
1803            })
1804            .unwrap();
1805        assert_eq!(bytes, [0x22, 0x33]);
1806    }
1807
1808    #[test]
1809    fn virtual_reader_rejects_unmapped_and_overflowing_ranges() {
1810        let (manager, root, base) = virtual_reader_manager();
1811        manager
1812            .with_guest_virtual_memory_reader(root, |reader| {
1813                assert!(
1814                    reader
1815                        .read_exact(base + 3 * PAGE_SIZE as u64, &mut [0])
1816                        .is_err()
1817                );
1818                assert!(reader.read_exact(u64::MAX, &mut [0; 2]).is_err());
1819                assert!(reader.read_exact(u64::MAX, &mut []).is_ok());
1820                Ok(())
1821            })
1822            .unwrap();
1823    }
1824
1825    #[test]
1826    fn virtual_reader_reports_invalid_page_tables() {
1827        let (manager, _, base) = virtual_reader_manager();
1828        let error = manager
1829            .with_guest_virtual_memory_reader(u64::MAX, |reader| reader.read_exact(base, &mut [0]))
1830            .unwrap_err();
1831        assert!(error.to_string().contains("unbacked"));
1832    }
1833
1834    #[test]
1835    fn guest_physical_memory_view_resolves_scratch_and_dynamic_edges() {
1836        let host_page_size = page_size::get();
1837        let layout =
1838            SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
1839        let scratch_start = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
1840        let snapshot = Arc::new(flat_memory(
1841            &[0u8; PAGE_SIZE],
1842            &[0; PAGE_SIZE],
1843            SandboxMemoryLayout::BASE_ADDRESS as u64,
1844            scratch_start,
1845        ));
1846        let (snapshot, _) = SnapshotMemoryBacking::from_snapshot(snapshot)
1847            .unwrap()
1848            .build();
1849
1850        let mut scratch = ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap();
1851        scratch.copy_from_slice(&[0x11], 0).unwrap();
1852        scratch
1853            .copy_from_slice(&[0x22], layout.get_scratch_size() - 1)
1854            .unwrap();
1855        let (scratch, _) = scratch.build();
1856
1857        let dynamic_gpa = SandboxMemoryLayout::BASE_ADDRESS as u64 + host_page_size as u64;
1858        let mut dynamic = ExclusiveSharedMemory::new(host_page_size).unwrap();
1859        dynamic.copy_from_slice(&[0x33], 0).unwrap();
1860        dynamic
1861            .copy_from_slice(&[0x44], host_page_size - 1)
1862            .unwrap();
1863        let (dynamic, dynamic_guest) = dynamic.build();
1864        let dynamic_region = dynamic_guest.mapping_at(dynamic_gpa, MemoryRegionType::Scratch);
1865        let dynamic_regions = [dynamic_region];
1866        GuestPhysicalMemoryView::with_memory(
1867            &snapshot,
1868            &scratch,
1869            &dynamic_regions,
1870            layout,
1871            |view| {
1872                let mut byte = [0u8; 1];
1873
1874                assert_eq!(
1875                    view.read(scratch_start, &mut byte).unwrap(),
1876                    GuestBacking {
1877                        source: BackingSource::Scratch,
1878                        offset: 0,
1879                    }
1880                );
1881                assert_eq!(byte, [0x11]);
1882                assert_eq!(
1883                    view.read(
1884                        scratch_start + layout.get_scratch_size() as u64 - 1,
1885                        &mut byte,
1886                    )
1887                    .unwrap(),
1888                    GuestBacking {
1889                        source: BackingSource::Scratch,
1890                        offset: layout.get_scratch_size() - 1,
1891                    }
1892                );
1893                assert_eq!(byte, [0x22]);
1894                assert_eq!(
1895                    view.read(dynamic_gpa, &mut byte).unwrap(),
1896                    GuestBacking {
1897                        source: BackingSource::Dynamic(0),
1898                        offset: 0,
1899                    }
1900                );
1901                assert_eq!(byte, [0x33]);
1902                assert_eq!(
1903                    view.read(dynamic_gpa + host_page_size as u64 - 1, &mut byte)
1904                        .unwrap(),
1905                    GuestBacking {
1906                        source: BackingSource::Dynamic(0),
1907                        offset: host_page_size - 1,
1908                    }
1909                );
1910                assert_eq!(byte, [0x44]);
1911                assert!(
1912                    view.resolve(dynamic_gpa + host_page_size as u64 - 1, 2)
1913                        .is_none()
1914                );
1915                assert!(
1916                    view.resolve(scratch_start + layout.get_scratch_size() as u64 - 1, 2,)
1917                        .is_none()
1918                );
1919                Ok(())
1920            },
1921        )
1922        .unwrap();
1923
1924        drop(dynamic);
1925        drop(dynamic_guest);
1926    }
1927}