Skip to main content

hyperlight_host/sandbox/snapshot/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4mod file;
5mod file_tests;
6pub(crate) mod memory;
7mod tripwires;
8
9use std::cell::{Cell, RefCell};
10use std::collections::BTreeMap;
11use std::ops::Range;
12use std::sync::Arc;
13
14pub(crate) use file::host_cpu_vendor_golden_tag;
15pub use file::reference::{OciDigest, OciReference, OciTag};
16use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
17use hyperlight_common::layout::{
18    SCRATCH_TOP_GVA, io_page, scratch_base_gpa, scratch_base_gva, scratch_reserved_top_gpa,
19    scratch_reserved_top_gva, scratch_transport_end_gva,
20};
21use hyperlight_common::vmem;
22use hyperlight_common::vmem::{
23    BasicMapping, CowMapping, Mapping, MappingKind, PAGE_SIZE, SpaceAwareMapping, SpaceId, TableOps,
24};
25use tracing::{Span, instrument};
26
27pub(crate) use self::memory::{SnapshotBlob, SnapshotMemory, SnapshotMemoryBacking};
28use crate::Result;
29use crate::hypervisor::regs::CommonSpecialRegisters;
30#[cfg(target_arch = "x86_64")]
31use crate::hypervisor::regs::MsrEntry;
32use crate::mem::exe::{ExeInfo, LoadInfo};
33use crate::mem::layout::SandboxMemoryLayout;
34use crate::mem::memory_region::MemoryRegionFlags;
35use crate::mem::mgr::{BackingSource, GuestBacking, GuestPageTableBuffer, GuestPhysicalMemoryView};
36use crate::mem::shared_mem::ExclusiveSharedMemory;
37use crate::mem::virtq::VirtqSnapshot;
38use crate::sandbox::SandboxConfiguration;
39use crate::sandbox::uninitialized::{GuestBinary, GuestEnvironment};
40
41const PTE_SIZE: usize = size_of::<vmem::PageTableEntry>();
42
43/// Presently, a snapshot can be of a preinitialised sandbox, which
44/// still needs an initialise function called in order to determine
45/// how to call into it, or of an already-properly-initialised sandbox
46/// which can be immediately called into. This keeps track of the
47/// difference.
48///
49/// TODO: this should not necessarily be around in the long term:
50/// ideally we would just preinitialise earlier in the snapshot
51/// creation process and never need this.
52#[derive(Copy, Clone, PartialEq, Eq)]
53pub enum NextAction {
54    /// A sandbox in the preinitialise state still needs to be
55    /// initialised by calling the initialise function
56    Initialise(u64),
57    /// A sandbox in the ready state can immediately be called into,
58    /// using the dispatch function pointer.
59    Call(u64),
60    /// Only when compiling for tests: a sandbox that cannot actually
61    /// be used
62    #[cfg(test)]
63    None,
64}
65
66/// Options for
67/// [`Sandbox::snapshot_with_options`](crate::Sandbox::snapshot_with_options).
68/// The default options take the same snapshot as
69/// [`Sandbox::snapshot`](crate::Sandbox::snapshot).
70#[derive(Clone, Debug, Default)]
71pub struct SnapshotOptions {
72    pub(crate) scratch_size: Option<usize>,
73}
74
75impl SnapshotOptions {
76    /// The snapshot, and the sandbox it is taken from, get a scratch region
77    /// of `scratch_size` bytes. By default the scratch size stays the same.
78    ///
79    /// A sandbox can boot with the scratch its initialisation needs, then
80    /// run guest function calls from a snapshot with only the scratch they
81    /// need, which makes each restore cheaper, or with more scratch than it
82    /// booted with.
83    ///
84    /// A size larger than the maximum memory size (`MemoryRequestTooBig`),
85    /// too small for the transport (`MemoryRequestTooSmall`), or not a
86    /// whole number of host pages is rejected before the guest is entered.
87    /// Room for the page tables depends on the guest's mappings and is
88    /// checked when the snapshot is built, after a pending transport
89    /// checkpoint has run in the guest: a size without it fails then, with
90    /// `MemoryRequestTooSmall`. A larger size whose scratch window would
91    /// cover a guest mapping below the current one fails then too. Both
92    /// failures leave the sandbox usable. Whether guest function calls fit
93    /// is not checked: one that needs more scratch fails in the guest, and
94    /// a later restore recovers the sandbox.
95    #[must_use]
96    pub fn scratch_size(mut self, scratch_size: usize) -> Self {
97        self.scratch_size = Some(scratch_size);
98        self
99    }
100}
101
102/// An immutable snapshot of sandbox state.
103pub struct Snapshot {
104    state: Arc<SnapshotState>,
105    // Stable key order keeps config bytes deterministic.
106    metadata: BTreeMap<String, serde_json::Value>,
107}
108
109/// Immutable sandbox state held by a snapshot.
110struct SnapshotState {
111    /// Layout object for the sandbox. TODO: get rid of this and
112    /// replace with something saner and set up from the guest (early
113    /// on?).
114    layout: crate::mem::layout::SandboxMemoryLayout,
115    /// Memory of the sandbox at the time this snapshot was taken
116    memory: Arc<SnapshotMemory>,
117    /// Extra debug information about the binary in this snapshot,
118    /// from when the binary was first loaded into the snapshot.
119    ///
120    /// This information is provided on a best-effort basis, and there
121    /// is a pretty good chance that it does not exist; generally speaking,
122    /// things like persisting a snapshot and reloading it are likely
123    /// to destroy this information.
124    load_info: LoadInfo,
125    /// The address of the top of the guest stack
126    stack_top_gva: u64,
127
128    /// Special register state captured from the vCPU during snapshot.
129    /// None for snapshots created directly from a binary (before
130    /// guest runs).  Some for snapshots taken from a running sandbox.
131    /// Note: CR3 in this struct is NOT used on restore, since page
132    /// tables are relocated during snapshot.
133    sregs: Option<CommonSpecialRegisters>,
134
135    /// The MSRs saved in this snapshot. None before the guest has run.
136    #[cfg(target_arch = "x86_64")]
137    msrs: Option<Vec<MsrEntry>>,
138
139    /// The next action that should be performed on this snapshot
140    next_action: NextAction,
141
142    /// Guest virtual address of the guest binary's ELF entry point
143    /// (`code GVA + e_entry - base_va`). Unlike `next_action`, which
144    /// transitions to `Call(dispatch_addr)` once the guest has run,
145    /// this preserves the original entry across that transition. Used
146    /// to fill `AT_ENTRY` in guest core dumps so a debugger can
147    /// compute the PIE load bias. 0 if unknown (e.g. an older
148    /// on-disk snapshot that predates this field).
149    original_entrypoint: u64,
150
151    /// The generation number assigned to this snapshot when it was
152    /// taken — i.e. "this is the Nth snapshot taken from the sandbox's
153    /// execution path from init to here". Propagated into the
154    /// restored sandbox's guest-visible counter so the guest can tell
155    /// which snapshot it is currently a clone of.
156    snapshot_generation: u64,
157
158    /// Names and signatures of host functions registered on the
159    /// sandbox at the time this snapshot was taken. Used by
160    /// [`crate::Sandbox::from_snapshot`] to reject a
161    /// `HostFunctions` set that is missing required functions or
162    /// has mismatched signatures.
163    host_functions: HostFunctionDetails,
164
165    /// Validated ring images omitted from ordinary snapshot pages.
166    ///
167    /// Construction and loading validate these images against `layout`.
168    /// Both the images and layout remain immutable afterwards.
169    virtq: Option<VirtqSnapshot>,
170}
171
172impl core::convert::AsRef<Snapshot> for Snapshot {
173    fn as_ref(&self) -> &Self {
174        self
175    }
176}
177impl hyperlight_common::vmem::TableReadOps for Snapshot {
178    type TableAddr = u64;
179    fn entry_addr(addr: u64, offset: u64) -> u64 {
180        addr + offset
181    }
182    unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
183        let mut pte_bytes = [0u8; PTE_SIZE];
184        if self
185            .state
186            .memory
187            .read_page_tables(self.state.layout.get_pt_base_gpa(), addr, &mut pte_bytes)
188            .is_err()
189        {
190            // Attacker-controlled data pointed out-of-bounds. We'll
191            // default to returning 0 in this case, which, for most
192            // architectures (including x86-64 and arm64, the ones we
193            // care about presently) will be a not-present entry.
194            return 0;
195        }
196        vmem::PageTableEntry::from_le_bytes(pte_bytes)
197    }
198    #[allow(clippy::unnecessary_cast)]
199    fn to_phys(addr: u64) -> vmem::PhysAddr {
200        addr as vmem::PhysAddr
201    }
202    #[allow(clippy::unnecessary_cast)]
203    fn from_phys(addr: vmem::PhysAddr) -> u64 {
204        addr as u64
205    }
206    fn root_table(&self) -> u64 {
207        self.root_pt_gpa()
208    }
209}
210
211pub(crate) struct PageTableReader<'a> {
212    memory: &'a GuestPhysicalMemoryView<'a>,
213    root: u64,
214    failure: Cell<Option<&'static str>>,
215    /// Address and copy of the last table page read. A walk reads the
216    /// entries of one table in sequence.
217    cache: RefCell<(u64, [u8; PAGE_SIZE])>,
218}
219impl<'a> PageTableReader<'a> {
220    pub(crate) fn new(memory: &'a GuestPhysicalMemoryView<'a>, root: u64) -> Self {
221        Self {
222            memory,
223            root,
224            failure: Cell::new(None),
225            // An unaligned address never matches a table page.
226            cache: RefCell::new((u64::MAX, [0; PAGE_SIZE])),
227        }
228    }
229
230    /// Returns suppressed page-table read failures.
231    pub(crate) fn finish(&self) -> Result<()> {
232        match self.failure.get() {
233            Some(failure) => Err(crate::new_error!("{}", failure)),
234            None => Ok(()),
235        }
236    }
237
238    fn read_cached(&self, addr: u64) -> Option<vmem::PageTableEntry> {
239        let page = addr & !(PAGE_SIZE as u64 - 1);
240        let offset = usize::try_from(addr - page).ok()?;
241        let mut cache = self.cache.borrow_mut();
242        if cache.0 != page {
243            cache.0 = u64::MAX;
244            self.memory.read(page, &mut cache.1).ok()?;
245            cache.0 = page;
246        }
247        let entry = cache.1.get(offset..offset + PTE_SIZE)?;
248        Some(vmem::PageTableEntry::from_le_bytes(entry.try_into().ok()?))
249    }
250}
251impl<'a> hyperlight_common::vmem::TableReadOps for PageTableReader<'a> {
252    type TableAddr = u64;
253    fn entry_addr(addr: u64, offset: u64) -> u64 {
254        addr + offset
255    }
256    unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
257        if let Some(entry) = self.read_cached(addr) {
258            return entry;
259        }
260        let mut pte_bytes = [0u8; PTE_SIZE];
261        if self.memory.read(addr, &mut pte_bytes).is_err() {
262            // Attacker-controlled data pointed out-of-bounds. We'll
263            // default to returning 0 in this case, which, for most
264            // architectures (including x86-64 and arm64, the ones we
265            // care about presently) will be a not-present entry.
266            // `finish` reports the failure.
267            self.failure
268                .set(Some("snapshot page-table walk accessed unbacked memory"));
269            return 0;
270        }
271        vmem::PageTableEntry::from_le_bytes(pte_bytes)
272    }
273    #[allow(clippy::unnecessary_cast)]
274    fn to_phys(addr: u64) -> vmem::PhysAddr {
275        addr as vmem::PhysAddr
276    }
277    #[allow(clippy::unnecessary_cast)]
278    fn from_phys(addr: vmem::PhysAddr) -> u64 {
279        addr as u64
280    }
281    fn root_table(&self) -> u64 {
282        self.root
283    }
284}
285impl<'a> core::convert::AsRef<PageTableReader<'a>> for PageTableReader<'a> {
286    fn as_ref(&self) -> &Self {
287        self
288    }
289}
290
291/// Return true if `virt_base` is a VA we must not preserve into the
292/// rebuilt snapshot page tables: it is either part of the scratch
293/// region (re-mapped freshly by `map_specials`) or, on amd64, part of
294/// the self-map of the snapshot's own page tables.
295fn skip_virt(virt_base: u64, scratch_gva: u64) -> bool {
296    if virt_base >= scratch_gva {
297        return true;
298    }
299    if virt_base >= hyperlight_common::layout::SNAPSHOT_PT_GVA_MIN as u64
300        && virt_base <= hyperlight_common::layout::SNAPSHOT_PT_GVA_MAX as u64
301    {
302        return true;
303    }
304    false
305}
306
307fn for_each_mapping_page(
308    mapping: &Mapping,
309    mut visitor: impl FnMut(u64, u64, MappingKind) -> Result<()>,
310) -> Result<()> {
311    if !validate_mapping(mapping)? {
312        return Ok(());
313    }
314    let mut offset = 0u64;
315    while offset < mapping.len {
316        let phys = mapping
317            .phys_base
318            .checked_add(offset)
319            .ok_or_else(|| crate::new_error!("guest physical mapping overflows"))?;
320        let virt = mapping
321            .virt_base
322            .checked_add(offset)
323            .ok_or_else(|| crate::new_error!("guest virtual mapping overflows"))?;
324        visitor(phys, virt, mapping.kind)?;
325        offset = offset
326            .checked_add(PAGE_SIZE as u64)
327            .ok_or_else(|| crate::new_error!("guest mapping offset overflows"))?;
328    }
329    Ok(())
330}
331
332fn validate_mapping(mapping: &Mapping) -> Result<bool> {
333    if mapping.kind == MappingKind::Unmapped {
334        return Ok(false);
335    }
336    if mapping.len == 0
337        || !mapping.phys_base.is_multiple_of(PAGE_SIZE as u64)
338        || !mapping.virt_base.is_multiple_of(PAGE_SIZE as u64)
339        || !mapping.len.is_multiple_of(PAGE_SIZE as u64)
340    {
341        return Err(crate::new_error!("guest mapping is not page aligned"));
342    }
343    Ok(true)
344}
345
346fn mapping_has_skipped_pages(mapping: &Mapping, scratch_gva: u64) -> Result<bool> {
347    let last_page = mapping
348        .virt_base
349        .checked_add(mapping.len - PAGE_SIZE as u64)
350        .ok_or_else(|| crate::new_error!("guest virtual mapping overflows"))?;
351    let snapshot_pt_start = hyperlight_common::layout::SNAPSHOT_PT_GVA_MIN as u64;
352    let snapshot_pt_end = hyperlight_common::layout::SNAPSHOT_PT_GVA_MAX as u64;
353    Ok(last_page >= scratch_gva
354        || (mapping.virt_base <= snapshot_pt_end && snapshot_pt_start <= last_page))
355}
356
357#[derive(Clone, Copy)]
358struct NewPage {
359    source_gpa: u64,
360    backing: GuestBacking,
361}
362
363/// Marks reused layers, or queues pages for copying into the new layer.
364fn record_backed_pages(
365    backing: GuestBacking,
366    source_gpa: u64,
367    len: usize,
368    reused_layers: Option<&mut [bool]>,
369    new_pages: &mut Vec<NewPage>,
370) -> Result<()> {
371    if let BackingSource::Snapshot(layer_index) = backing.source
372        && let Some(reused_layers) = reused_layers
373    {
374        *reused_layers
375            .get_mut(layer_index)
376            .ok_or_else(|| crate::new_error!("snapshot layer index is out of bounds"))? = true;
377        return Ok(());
378    }
379
380    for offset in (0..len).step_by(PAGE_SIZE) {
381        new_pages.push(NewPage {
382            source_gpa: source_gpa
383                .checked_add(u64::try_from(offset)?)
384                .ok_or_else(|| crate::new_error!("snapshot source GPA overflows"))?,
385            backing: GuestBacking {
386                offset: backing
387                    .offset
388                    .checked_add(offset)
389                    .ok_or_else(|| crate::new_error!("snapshot source backing offset overflows"))?,
390                ..backing
391            },
392        });
393    }
394    Ok(())
395}
396
397struct NewPageRun {
398    source: Range<u64>,
399    destination_start: u64,
400}
401
402struct NewPageCopy {
403    backing: GuestBacking,
404    destination: Range<usize>,
405}
406
407fn new_page_copies(pages: &[NewPage]) -> Result<Vec<NewPageCopy>> {
408    let mut copies = Vec::<NewPageCopy>::new();
409    for (index, page) in pages.iter().enumerate() {
410        let start = index
411            .checked_mul(PAGE_SIZE)
412            .ok_or_else(|| crate::new_error!("snapshot page offset overflows"))?;
413        let end = start
414            .checked_add(PAGE_SIZE)
415            .ok_or_else(|| crate::new_error!("snapshot page range overflows"))?;
416        if let Some(copy) = copies.last_mut()
417            && copy.backing.source == page.backing.source
418            && copy.backing.offset.checked_add(copy.destination.len()) == Some(page.backing.offset)
419        {
420            copy.destination.end = end;
421        } else {
422            copies.push(NewPageCopy {
423                backing: page.backing,
424                destination: start..end,
425            });
426        }
427    }
428    Ok(copies)
429}
430
431fn new_page_runs(pages: &[NewPage], destination_start: u64) -> Result<Vec<NewPageRun>> {
432    let mut runs = Vec::<NewPageRun>::new();
433    for (index, page) in pages.iter().enumerate() {
434        let source_gpa = page.source_gpa;
435        let destination = destination_start
436            .checked_add(u64::try_from(index.checked_mul(PAGE_SIZE).ok_or_else(
437                || crate::new_error!("snapshot page offset overflows"),
438            )?)?)
439            .ok_or_else(|| crate::new_error!("snapshot page GPA overflows"))?;
440        if let Some(run) = runs.last_mut()
441            && run.source.end == source_gpa
442        {
443            run.source.end = run
444                .source
445                .end
446                .checked_add(PAGE_SIZE as u64)
447                .ok_or_else(|| crate::new_error!("snapshot source page run overflows"))?;
448        } else {
449            let source_end = source_gpa
450                .checked_add(PAGE_SIZE as u64)
451                .ok_or_else(|| crate::new_error!("snapshot source page overflows"))?;
452            runs.push(NewPageRun {
453                source: source_gpa..source_end,
454                destination_start: destination,
455            });
456        }
457    }
458    Ok(runs)
459}
460
461fn page_destination(runs: &[NewPageRun], source_gpa: u64) -> Option<u64> {
462    let index = runs.partition_point(|run| run.source.end <= source_gpa);
463    let run = runs.get(index)?;
464    let offset = source_gpa.checked_sub(run.source.start)?;
465    (source_gpa < run.source.end).then(|| run.destination_start.checked_add(offset))?
466}
467
468fn packed_data_len(page_count: usize, host_page_size: usize) -> Result<usize> {
469    let page_bytes = page_count
470        .checked_mul(PAGE_SIZE)
471        .ok_or_else(|| crate::new_error!("snapshot data size overflows"))?;
472    page_bytes
473        .checked_next_multiple_of(host_page_size)
474        .ok_or_else(|| crate::new_error!("snapshot data padding overflows"))
475}
476
477fn first_fit_blob_gpa(
478    data_len: usize,
479    layers: &[Arc<SnapshotBlob>],
480    scratch_base: u64,
481) -> Option<u64> {
482    if data_len == 0 {
483        return None;
484    }
485    let data_len = u64::try_from(data_len).ok()?;
486    let mut candidate = SandboxMemoryLayout::BASE_ADDRESS as u64;
487    for range in layers.iter().map(|layer| layer.gpa_range()) {
488        let end = candidate.checked_add(data_len)?;
489        if end <= range.start {
490            return Some(candidate);
491        }
492        candidate = candidate.max(range.end);
493    }
494    (candidate.checked_add(data_len)? <= scratch_base).then_some(candidate)
495}
496
497fn snapshot_mapping_kind(kind: MappingKind) -> Option<MappingKind> {
498    match kind {
499        MappingKind::Cow(mapping) => Some(MappingKind::Cow(mapping)),
500        MappingKind::Basic(mapping) if mapping.writable => Some(MappingKind::Cow(CowMapping {
501            readable: mapping.readable,
502            executable: mapping.executable,
503        })),
504        MappingKind::Basic(mapping) => Some(MappingKind::Basic(BasicMapping {
505            readable: mapping.readable,
506            writable: false,
507            executable: mapping.executable,
508        })),
509        MappingKind::ZeroInit(mapping) => Some(MappingKind::ZeroInit(mapping)),
510        MappingKind::Unmapped => None,
511    }
512}
513
514fn map_specials(pt_buf: &GuestPageTableBuffer, scratch_size: usize) {
515    if let Some((phys_base, virt_base)) = io_page() {
516        // Map the IO page
517        let mapping = Mapping {
518            phys_base,
519            virt_base,
520            len: PAGE_SIZE as u64,
521            kind: MappingKind::Basic(BasicMapping {
522                readable: true,
523                writable: true,
524                executable: false,
525            }),
526        };
527        unsafe { vmem::map(pt_buf, mapping) };
528    }
529    // Map the scratch region, except the guard pages under the reserved top
530    // pages. Left unmapped, they make an amd64 exception stack overrun fault
531    // before it reaches the transport arena.
532    let base_gpa = scratch_base_gpa(scratch_size);
533    let base_gva = scratch_base_gva(scratch_size);
534    let gap_gva = scratch_transport_end_gva();
535    let top_gva = scratch_reserved_top_gva();
536    let ranges = if base_gva < gap_gva {
537        [
538            (base_gpa, base_gva, gap_gva - base_gva),
539            (
540                scratch_reserved_top_gpa(),
541                top_gva,
542                SCRATCH_TOP_GVA as u64 + 1 - top_gva,
543            ),
544        ]
545    } else {
546        // Only tests build a scratch window too small to reach the gap.
547        [(base_gpa, base_gva, scratch_size as u64), (0, 0, 0)]
548    };
549    for (phys_base, virt_base, len) in ranges.into_iter().filter(|r| r.2 != 0) {
550        let mapping = Mapping {
551            phys_base,
552            virt_base,
553            len,
554            kind: MappingKind::Basic(BasicMapping {
555                readable: true,
556                writable: true,
557                // assume that the guest will map these pages elsewhere if
558                // it actually needs to execute from them
559                executable: false,
560            }),
561        };
562        unsafe { vmem::map(pt_buf, mapping) };
563    }
564}
565
566impl Snapshot {
567    /// Create a new snapshot from the guest binary identified by `env`. With the configuration
568    /// specified in `cfg`.
569    pub(crate) fn from_env<'b>(
570        env: impl Into<GuestEnvironment<'b>>,
571        cfg: SandboxConfiguration,
572    ) -> Result<Self> {
573        let env = env.into();
574        let mut bin = env.guest_binary;
575        bin.canonicalize()?;
576        let blob = env.init_data;
577
578        let exe_info = match bin {
579            GuestBinary::FilePath(bin_path) => ExeInfo::from_file(&bin_path)?,
580            GuestBinary::Buffer(buffer) => ExeInfo::from_buf(buffer)?,
581        };
582
583        // Check guest/host version compatibility.
584        let host_version = env!("CARGO_PKG_VERSION");
585        if let Some(v) = exe_info.guest_bin_version()
586            && v != host_version
587        {
588            return Err(crate::HyperlightError::GuestBinVersionMismatch {
589                guest_bin_version: v.to_string(),
590                host_version: host_version.to_string(),
591            });
592        }
593
594        let guest_blob_size = blob.as_ref().map(|b| b.data.len()).unwrap_or(0);
595        let guest_blob_mem_flags = blob.as_ref().map(|b| b.permissions);
596
597        let mut layout = crate::mem::layout::SandboxMemoryLayout::new(
598            cfg,
599            exe_info.loaded_size(),
600            guest_blob_size,
601            guest_blob_mem_flags,
602        )?;
603
604        let load_addr = layout.get_guest_code_gpa() as u64;
605        let base_va = exe_info.base_va();
606        let entrypoint_va: u64 = exe_info.entrypoint().into();
607        let is_pie = exe_info.is_pie();
608
609        let code_gva = if is_pie { load_addr } else { base_va };
610        layout.set_code_gva(code_gva)?;
611        let regions = layout.get_memory_regions()?;
612
613        // Set up page table entries for the snapshot
614        let pt_buf = GuestPageTableBuffer::new(layout.get_pt_base_gpa() as usize);
615
616        // 1. Map the (ideally readonly) pages of snapshot data
617        for rgn in regions.iter() {
618            let readable = rgn.flags.contains(MemoryRegionFlags::READ);
619            let executable = rgn.flags.contains(MemoryRegionFlags::EXECUTE);
620            let writable = rgn.flags.contains(MemoryRegionFlags::WRITE);
621            let kind = if writable {
622                MappingKind::Cow(CowMapping {
623                    readable,
624                    executable,
625                })
626            } else {
627                MappingKind::Basic(BasicMapping {
628                    readable,
629                    writable: false,
630                    executable,
631                })
632            };
633
634            let mapping = Mapping {
635                phys_base: rgn.host_region.start as u64,
636                virt_base: rgn.guest_region.start as u64,
637                len: rgn.guest_region.len() as u64,
638                kind,
639            };
640            unsafe { vmem::map(&pt_buf, mapping) };
641        }
642
643        // 2. Map the special mappings
644        map_specials(&pt_buf, layout.get_scratch_size());
645
646        let pt_bytes = pt_buf.into_bytes();
647        layout.ensure_page_tables_fit(pt_bytes.len())?;
648
649        let exn_stack_top_gva = hyperlight_common::layout::SCRATCH_TOP_GVA as u64
650            - hyperlight_common::layout::SCRATCH_TOP_EXN_STACK_OFFSET
651            + 1;
652
653        let entrypoint_offset = entrypoint_va.checked_sub(base_va).ok_or_else(|| {
654            crate::new_error!(
655                "ELF entrypoint VA ({:#x}) is below base VA ({:#x})",
656                entrypoint_va,
657                base_va
658            )
659        })?;
660
661        let entrypoint_gva = (layout.get_guest_code_gva() as u64)
662            .checked_add(entrypoint_offset)
663            .ok_or_else(|| crate::new_error!("ELF entrypoint GVA overflows"))?;
664
665        // The page tables follow the data, which is padded to a host page.
666        let host_page_size = self::memory::host_page_size();
667        let data_len = layout.get_memory_size()?.next_multiple_of(host_page_size);
668        let mut memory = ExclusiveSharedMemory::new(
669            (data_len + pt_bytes.len()).next_multiple_of(host_page_size),
670        )?;
671        let data = &mut memory.as_mut_slice()[..data_len];
672
673        let load_info = exe_info.load(
674            layout.get_guest_code_gva() as u64,
675            &mut data[layout.guest_code_offset()..],
676        )?;
677
678        layout.write_peb(data)?;
679
680        blob.map(|x| layout.write_init_data(data, x.data))
681            .transpose()?;
682        memory.copy_from_slice(&pt_bytes, data_len)?;
683        let memory = Arc::new(SnapshotMemory::from_flat(
684            memory.freeze(data_len)?,
685            SandboxMemoryLayout::BASE_ADDRESS as u64,
686            pt_bytes.len(),
687            scratch_base_gpa(layout.get_scratch_size()),
688        )?);
689
690        Ok(Self {
691            state: Arc::new(SnapshotState {
692                memory,
693                layout,
694                load_info,
695                stack_top_gva: exn_stack_top_gva,
696                sregs: None,
697                #[cfg(target_arch = "x86_64")]
698                msrs: None,
699                next_action: NextAction::Initialise(entrypoint_gva),
700                original_entrypoint: entrypoint_gva,
701                snapshot_generation: 0,
702                host_functions: HostFunctionDetails {
703                    host_functions: None,
704                },
705                virtq: None,
706            }),
707            metadata: BTreeMap::new(),
708        })
709    }
710
711    // It might be nice to consider moving at least stack_top_gva into
712    // layout, and sharing (via RwLock or similar) the layout between
713    // the (host-side) mem mgr (where it can be passed in here) and
714    // the sandbox vm itself (which modifies it as it receives
715    // requests from the sandbox).
716    #[allow(clippy::too_many_arguments)]
717    /// Capture memory with optional validated transport images.
718    ///
719    /// `layout` is the sandbox's own: the live page tables and scratch are
720    /// read with it. The snapshot's page tables are built for
721    /// `scratch_size`, which can differ from the sandbox's own. A larger
722    /// scratch window must not cover a guest mapping or a snapshot layer.
723    /// Page-table and snapshot sizes do not affect transport geometry.
724    /// `root_pt_gpas` must be distinct.
725    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
726    pub(crate) fn new(
727        memory_view: &GuestPhysicalMemoryView<'_>,
728        layout: SandboxMemoryLayout,
729        load_info: LoadInfo,
730        root_pt_gpas: &[u64],
731        stack_top_gva: u64,
732        sregs: CommonSpecialRegisters,
733        #[cfg(target_arch = "x86_64")] msrs: Vec<MsrEntry>,
734        next_action: NextAction,
735        original_entrypoint: u64,
736        snapshot_generation: u64,
737        host_functions: HostFunctionDetails,
738        virtq: Option<VirtqSnapshot>,
739        scratch_size: usize,
740    ) -> Result<Self> {
741        if root_pt_gpas.is_empty() {
742            return Err(crate::new_error!("snapshot has no page-table roots"));
743        }
744        let target = layout.with_scratch_size(scratch_size)?;
745        let scratch_gva = scratch_base_gva(layout.get_scratch_size());
746        // A larger scratch window also covers this band below the current
747        // one, which `map_specials` would map over the guest's mappings.
748        let grown_band = scratch_base_gva(scratch_size)..scratch_gva;
749        // Unbacked roots fail through `PageTableReader::finish`.
750        if let Some(root) = root_pt_gpas
751            .iter()
752            .find(|root| !root.is_multiple_of(PAGE_SIZE as u64))
753        {
754            return Err(crate::new_error!(
755                "snapshot page-table root {root:#x} is not aligned"
756            ));
757        }
758        // Phase 1: walk every PT root together. This detects
759        // aliased intermediate tables (e.g. Nanvix's kernel-
760        // half PTs, which multiple process PDs share by
761        // pointing at the same PT page). The walker emits
762        // `ThisSpace(leaf)` for private leaves and
763        // `AnotherSpace(ref)` for sub-trees that were already
764        // seen via an earlier root. Results are returned in
765        // `root_pt_gpas` order — which is also the topological
766        // order of the `AnotherSpace` references — so
767        // processing in iteration order is safe.
768        let op = PageTableReader::new(memory_view, root_pt_gpas[0]);
769        // SAFETY: Snapshot capture runs with the vCPU stopped, so the source
770        // page tables cannot change during the walk.
771        let walk = unsafe {
772            vmem::walk_va_spaces(
773                &op,
774                root_pt_gpas,
775                0,
776                hyperlight_common::layout::SCRATCH_TOP_GVA as u64,
777            )
778        };
779        op.finish()?;
780        let source_layers = memory_view.snapshot().reusable_layers();
781        let mut reused_layers = source_layers.map(|layers| vec![false; layers.len()]);
782        let mut new_pages = Vec::new();
783        for (_, mappings) in &walk {
784            for mapping in mappings {
785                let SpaceAwareMapping::ThisSpace(mapping) = mapping else {
786                    continue;
787                };
788                if !grown_band.is_empty()
789                    && mapping.virt_base < grown_band.end
790                    && grown_band.start < mapping.virt_base.saturating_add(mapping.len)
791                {
792                    for_each_mapping_page(mapping, |_, virt_gva, _| {
793                        if grown_band.contains(&virt_gva) && !skip_virt(virt_gva, scratch_gva) {
794                            return Err(crate::new_error!(
795                                "a scratch size of {scratch_size} would map scratch over the guest mapping at {virt_gva:#x}"
796                            ));
797                        }
798                        Ok(())
799                    })?;
800                }
801                if validate_mapping(mapping)? && !mapping_has_skipped_pages(mapping, scratch_gva)? {
802                    if matches!(mapping.kind, MappingKind::ZeroInit(_)) {
803                        continue;
804                    }
805                    let mapping_len = usize::try_from(mapping.len)?;
806                    if let Some(backing) = memory_view.resolve(mapping.phys_base, mapping_len) {
807                        record_backed_pages(
808                            backing,
809                            mapping.phys_base,
810                            mapping_len,
811                            reused_layers.as_deref_mut(),
812                            &mut new_pages,
813                        )?;
814                        continue;
815                    }
816                }
817                for_each_mapping_page(mapping, |source_gpa, virt_gva, kind| {
818                    if skip_virt(virt_gva, scratch_gva) || matches!(kind, MappingKind::ZeroInit(_))
819                    {
820                        return Ok(());
821                    }
822                    let backing = memory_view.resolve(source_gpa, PAGE_SIZE).ok_or_else(|| {
823                        crate::new_error!("snapshot leaf names unbacked GPA {source_gpa:#x}")
824                    })?;
825                    record_backed_pages(
826                        backing,
827                        source_gpa,
828                        PAGE_SIZE,
829                        reused_layers.as_deref_mut(),
830                        &mut new_pages,
831                    )
832                })?;
833            }
834        }
835
836        new_pages.sort_unstable_by_key(|page| page.source_gpa);
837        new_pages.dedup_by_key(|page| page.source_gpa);
838
839        let mut layers: Vec<Arc<SnapshotBlob>> = match (source_layers, reused_layers) {
840            (Some(source_layers), Some(reused_layers)) => source_layers
841                .iter()
842                .zip(reused_layers)
843                .filter(|(_, reused)| *reused)
844                .map(|(layer, _)| layer.clone())
845                .collect(),
846            _ => Vec::new(),
847        };
848        let target_scratch_gpa = scratch_base_gpa(scratch_size);
849        if let Some(layer) = layers
850            .iter()
851            .find(|layer| layer.gpa_range().end > target_scratch_gpa)
852        {
853            return Err(crate::new_error!(
854                "a scratch size of {scratch_size} would map scratch over the snapshot layer at {:#x}",
855                layer.gpa_start()
856            ));
857        }
858        let host_page_size = self::memory::host_page_size();
859        let data_len = packed_data_len(new_pages.len(), host_page_size)?;
860        let new_blob_gpa = if data_len == 0 {
861            None
862        } else {
863            Some(
864                first_fit_blob_gpa(data_len, &layers, target_scratch_gpa).ok_or_else(|| {
865                    crate::new_error!("snapshot has no address space for a new layer")
866                })?,
867            )
868        };
869        let new_page_runs = match new_blob_gpa {
870            Some(destination_start) => new_page_runs(&new_pages, destination_start)?,
871            None => Vec::new(),
872        };
873
874        // Phase 2: rebuild each space's page tables, compacting
875        // `ThisSpace` leaves into a dense snapshot blob and
876        // linking `AnotherSpace` entries to already-built
877        // spaces' tables.
878        // TODO: Look for opportunities to hugepage map
879        let pt_buf = GuestPageTableBuffer::new(target.get_pt_base_gpa() as usize);
880        // Allocate one root table per space and remember the
881        // addresses returned by `alloc_table` instead of
882        // assuming the buffer's physical layout.
883        let mut root_addrs = Vec::with_capacity(root_pt_gpas.len());
884        root_addrs.push(pt_buf.initial_root());
885        for _ in 1..root_pt_gpas.len() {
886            // SAFETY: `pt_buf` is local to this capture and accessed serially.
887            root_addrs.push(unsafe { pt_buf.alloc_table() });
888        }
889
890        let mut built_roots: BTreeMap<SpaceId, u64> = BTreeMap::new();
891        for (root_index, (space_id, mappings)) in walk.into_iter().enumerate() {
892            pt_buf.set_root(root_addrs[root_index]);
893            built_roots.insert(space_id, root_addrs[root_index]);
894            let mut pending_mapping: Option<Mapping> = None;
895            let flush_mapping = |pending: &mut Option<Mapping>| {
896                if let Some(mapping) = pending.take() {
897                    // SAFETY: The mapping is page-aligned and `pt_buf` is local
898                    // to this capture.
899                    unsafe { vmem::map(&pt_buf, mapping) };
900                }
901            };
902            for mapping in mappings {
903                match mapping {
904                    SpaceAwareMapping::ThisSpace(mapping) => {
905                        for_each_mapping_page(&mapping, |source_gpa, virt_gva, kind| {
906                            // Drop the scratch region and (on
907                            // amd64) the snapshot's own PT
908                            // self-map; both are re-mapped
909                            // freshly by `map_specials`.
910                            if skip_virt(virt_gva, scratch_gva) {
911                                flush_mapping(&mut pending_mapping);
912                                return Ok(());
913                            }
914                            // Writable pages become CoW in the
915                            // rebuilt snapshot; read-only pages
916                            // stay read-only.
917                            let kind = snapshot_mapping_kind(kind).ok_or_else(|| {
918                                crate::new_error!("snapshot walker returned an unmapped leaf")
919                            })?;
920                            let destination_gpa =
921                                page_destination(&new_page_runs, source_gpa).unwrap_or(source_gpa);
922                            if let Some(pending) = pending_mapping.as_mut()
923                                && pending.kind == kind
924                                && pending.phys_base.checked_add(pending.len)
925                                    == Some(destination_gpa)
926                                && pending.virt_base.checked_add(pending.len) == Some(virt_gva)
927                            {
928                                pending.len =
929                                    pending.len.checked_add(PAGE_SIZE as u64).ok_or_else(|| {
930                                        crate::new_error!("snapshot mapping length overflows")
931                                    })?;
932                            } else {
933                                flush_mapping(&mut pending_mapping);
934                                pending_mapping = Some(Mapping {
935                                    phys_base: destination_gpa,
936                                    virt_base: virt_gva,
937                                    len: PAGE_SIZE as u64,
938                                    kind,
939                                });
940                            }
941                            Ok(())
942                        })?;
943                    }
944                    SpaceAwareMapping::AnotherSpace(reference) => {
945                        flush_mapping(&mut pending_mapping);
946                        // Link to the owning space's already-
947                        // rebuilt intermediate table — this
948                        // is what preserves Nanvix's
949                        // kernel-half-shared invariant across
950                        // process PDs after relocation.
951                        // SAFETY: The reference came from the source walk and
952                        // `pt_buf` is local to this capture. The walk returns
953                        // spaces in topological order, so the owner named by
954                        // `reference` already has its root in `built_roots`.
955                        unsafe { vmem::space_aware_map(&pt_buf, reference, &built_roots) };
956                    }
957                }
958            }
959            flush_mapping(&mut pending_mapping);
960        }
961
962        // Phase 3: Map the scratch region into each root.
963        for &root_addr in &root_addrs {
964            pt_buf.set_root(root_addr);
965            map_specials(&pt_buf, scratch_size);
966        }
967        pt_buf.set_root(pt_buf.initial_root());
968        // Phase 4: write the new blob, the new pages followed by the page
969        // tables. A capture with no new pages still needs a blob for its
970        // page tables.
971        let page_tables = pt_buf.into_bytes();
972        target.ensure_page_tables_fit(page_tables.len())?;
973        let blob_len = data_len
974            .checked_add(page_tables.len())
975            .and_then(|len| len.checked_next_multiple_of(host_page_size))
976            .ok_or_else(|| crate::new_error!("snapshot blob size overflows"))?;
977        let mut allocation = ExclusiveSharedMemory::new(blob_len)?;
978        for copy in new_page_copies(&new_pages)? {
979            let destination = allocation
980                .as_mut_slice()
981                .get_mut(copy.destination)
982                .ok_or_else(|| crate::new_error!("snapshot destination page is out of bounds"))?;
983            memory_view.read_backing(copy.backing, destination)?;
984        }
985        allocation.copy_from_slice(&page_tables, data_len)?;
986        let blob = Arc::new(SnapshotBlob::new(
987            allocation.freeze(data_len)?,
988            new_blob_gpa.unwrap_or_default(),
989            page_tables.len(),
990            target_scratch_gpa,
991        )?);
992        if data_len > 0 {
993            layers.push(blob.clone());
994        }
995        // Validates the layer limit.
996        let memory = Arc::new(SnapshotMemory::new(layers.into_boxed_slice(), blob)?);
997
998        Ok(Self {
999            state: Arc::new(SnapshotState {
1000                layout: target,
1001                memory,
1002                load_info,
1003                stack_top_gva,
1004                sregs: Some(sregs),
1005                #[cfg(target_arch = "x86_64")]
1006                msrs: Some(msrs),
1007                next_action,
1008                original_entrypoint,
1009                snapshot_generation,
1010                host_functions,
1011                virtq,
1012            }),
1013            metadata: BTreeMap::new(),
1014        })
1015    }
1016
1017    /// Deserializes the metadata stored under `namespace` as `T`.
1018    ///
1019    /// Returns `None` if the namespace has no metadata.
1020    ///
1021    /// # Errors
1022    ///
1023    /// Returns an error if the JSON metadata cannot be deserialized as `T`.
1024    ///
1025    /// # Examples
1026    ///
1027    /// ```no_run
1028    /// # use std::sync::Arc;
1029    /// # use hyperlight_host::sandbox::snapshot::Snapshot;
1030    /// # use serde::{Deserialize, Serialize};
1031    /// #
1032    /// #[derive(Debug, PartialEq, Serialize, Deserialize)]
1033    /// struct Metadata {
1034    ///     version: u32,
1035    /// }
1036    ///
1037    /// # fn example(snapshot: Arc<Snapshot>) -> Result<(), Box<dyn std::error::Error>> {
1038    /// let snapshot =
1039    ///     snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
1040    /// let metadata = snapshot
1041    ///     .metadata::<Metadata>("snapshot-metadata-namespace-v1")?
1042    ///     .expect("metadata should exist");
1043    /// assert_eq!(metadata, Metadata { version: 1 });
1044    /// # Ok(())
1045    /// # }
1046    /// ```
1047    pub fn metadata<T>(&self, namespace: &str) -> Result<Option<T>>
1048    where
1049        T: serde::de::DeserializeOwned,
1050    {
1051        self.metadata
1052            .get(namespace)
1053            .map(serde::Deserialize::deserialize)
1054            .transpose()
1055            .map_err(Into::into)
1056    }
1057
1058    /// Adds `metadata` to this snapshot and returns the result as a new
1059    /// snapshot. Metadata already stored under `namespace` is replaced.
1060    ///
1061    /// This snapshot remains unchanged.
1062    /// Metadata is saved and loaded with the snapshot.
1063    ///
1064    /// # Errors
1065    ///
1066    /// Returns an error if `metadata` cannot be serialized as JSON.
1067    ///
1068    /// # Examples
1069    ///
1070    /// ```no_run
1071    /// # use std::sync::Arc;
1072    /// # use hyperlight_host::sandbox::snapshot::Snapshot;
1073    /// # use serde::{Deserialize, Serialize};
1074    /// #
1075    /// #[derive(Debug, PartialEq, Serialize, Deserialize)]
1076    /// struct Metadata {
1077    ///     version: u32,
1078    /// }
1079    ///
1080    /// # fn example(snapshot: Arc<Snapshot>) -> Result<(), Box<dyn std::error::Error>> {
1081    /// let snapshot =
1082    ///     snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
1083    /// let metadata = snapshot
1084    ///     .metadata::<Metadata>("snapshot-metadata-namespace-v1")?
1085    ///     .expect("metadata should exist");
1086    /// assert_eq!(metadata, Metadata { version: 1 });
1087    /// # Ok(())
1088    /// # }
1089    /// ```
1090    pub fn with_metadata<T>(&self, namespace: impl Into<String>, metadata: &T) -> Result<Arc<Self>>
1091    where
1092        T: serde::Serialize,
1093    {
1094        let namespace = namespace.into();
1095        let metadata = serde_json::to_value(metadata)?;
1096        let mut metadata_by_namespace = self.metadata.clone();
1097        metadata_by_namespace.insert(namespace, metadata);
1098        Ok(Arc::new(Self {
1099            state: Arc::clone(&self.state),
1100            metadata: metadata_by_namespace,
1101        }))
1102    }
1103
1104    /// Generation number assigned to this snapshot when it was taken.
1105    pub(crate) fn snapshot_generation(&self) -> u64 {
1106        self.state.snapshot_generation
1107    }
1108
1109    /// Return the main memory contents of the snapshot
1110    #[instrument(skip_all, parent = Span::current(), level= "Trace")]
1111    pub(crate) fn snapshot_memory(&self) -> &Arc<SnapshotMemory> {
1112        &self.state.memory
1113    }
1114
1115    /// Return a copy of the load info for the exe in the snapshot
1116    pub(crate) fn load_info(&self) -> LoadInfo {
1117        self.state.load_info.clone()
1118    }
1119
1120    pub(crate) fn layout(&self) -> &crate::mem::layout::SandboxMemoryLayout {
1121        &self.state.layout
1122    }
1123
1124    pub(crate) fn root_pt_gpa(&self) -> u64 {
1125        self.state.layout.get_pt_base_gpa()
1126    }
1127
1128    pub(crate) fn stack_top_gva(&self) -> u64 {
1129        self.state.stack_top_gva
1130    }
1131
1132    /// Returns the special registers stored in this snapshot.
1133    /// Returns None for snapshots created directly from a binary (before preinitialisation).
1134    /// Returns Some for snapshots taken from a running sandbox.
1135    /// Note: The CR3 value in the returned struct should NOT be used for restore;
1136    /// use `root_pt_gpa()` instead since page tables are relocated during snapshot.
1137    pub(crate) fn sregs(&self) -> Option<&CommonSpecialRegisters> {
1138        self.state.sregs.as_ref()
1139    }
1140
1141    /// The MSRs saved in this snapshot.
1142    #[cfg(target_arch = "x86_64")]
1143    pub(crate) fn msrs(&self) -> Option<&Vec<MsrEntry>> {
1144        self.state.msrs.as_ref()
1145    }
1146
1147    pub(crate) fn next_action(&self) -> NextAction {
1148        self.state.next_action
1149    }
1150
1151    pub(crate) fn virtq(&self) -> Option<&VirtqSnapshot> {
1152        self.state.virtq.as_ref()
1153    }
1154
1155    /// Guest virtual address of the guest binary's ELF entry point,
1156    /// preserved across the `Initialise` -> `Call` transition. Used
1157    /// to fill `AT_ENTRY` in guest core dumps. 0 if unknown.
1158    pub(crate) fn original_entrypoint(&self) -> u64 {
1159        self.state.original_entrypoint
1160    }
1161
1162    /// Validate that `provided` is a superset of the host functions
1163    /// recorded in this snapshot: every function that was registered
1164    /// at snapshot time must also be present in `provided` with a
1165    /// matching signature. Extras in `provided` are allowed.
1166    ///
1167    /// A snapshot with no recorded host functions (e.g. one
1168    /// produced by a test-only constructor) accepts any `provided`
1169    /// set.
1170    pub(crate) fn validate_host_functions(
1171        &self,
1172        provided: &crate::sandbox::host_funcs::FunctionRegistry,
1173    ) -> Result<()> {
1174        let required = match &self.state.host_functions.host_functions {
1175            Some(v) => v,
1176            None => return Ok(()),
1177        };
1178        if required.is_empty() {
1179            return Ok(());
1180        }
1181
1182        let mut missing: Vec<String> = Vec::new();
1183        let mut signature_mismatches: Vec<String> = Vec::new();
1184
1185        for req in required {
1186            match provided.function_signature(&req.function_name) {
1187                // Function name is absent from the provided registry.
1188                None => missing.push(req.function_name.clone()),
1189                // Function exists, but signature does not match.
1190                Some((found_parameter_types, found_return_type))
1191                    if {
1192                        let params_match = match req.parameter_types.as_deref() {
1193                            Some(params) => params == found_parameter_types,
1194                            None => found_parameter_types.is_empty(),
1195                        };
1196                        !params_match || req.return_type != found_return_type
1197                    } =>
1198                {
1199                    signature_mismatches.push(format!(
1200                        "{}: snapshot has {:?} -> {:?}, registered {:?} -> {:?}",
1201                        req.function_name,
1202                        req.parameter_types,
1203                        req.return_type,
1204                        Some(found_parameter_types.to_vec()),
1205                        found_return_type,
1206                    ));
1207                }
1208                // Function exists and signature matches.
1209                Some(_) => {}
1210            }
1211        }
1212
1213        if missing.is_empty() && signature_mismatches.is_empty() {
1214            return Ok(());
1215        }
1216
1217        Err(crate::HyperlightError::SnapshotHostFunctionMismatch {
1218            missing,
1219            signature_mismatches,
1220        })
1221    }
1222}
1223
1224#[cfg(test)]
1225mod tests {
1226    use std::sync::Arc;
1227
1228    use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
1229    use hyperlight_common::vmem::{
1230        self, BasicMapping, Mapping, MappingKind, PAGE_SIZE, PAGE_TABLE_SIZE,
1231    };
1232
1233    use super::SnapshotMemoryBacking;
1234    use crate::hypervisor::regs::CommonSpecialRegisters;
1235    use crate::mem::exe::LoadInfo;
1236    use crate::mem::layout::SandboxMemoryLayout;
1237    use crate::mem::mgr::{
1238        BackingSource, GuestBacking, GuestPageTableBuffer, GuestPhysicalMemoryView,
1239        SandboxMemoryManager,
1240    };
1241    use crate::mem::shared_mem::{ExclusiveSharedMemory, HostSharedMemory};
1242
1243    fn default_sregs() -> CommonSpecialRegisters {
1244        CommonSpecialRegisters::default()
1245    }
1246
1247    fn new_page(source_gpa: u64, offset: usize) -> super::NewPage {
1248        super::NewPage {
1249            source_gpa,
1250            backing: GuestBacking {
1251                source: BackingSource::Snapshot(0),
1252                offset,
1253            },
1254        }
1255    }
1256
1257    #[test]
1258    fn page_runs_map_each_source_to_its_destination() {
1259        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1260        let page = PAGE_SIZE as u64;
1261        let destination = base + 0x10_0000;
1262        // Two contiguous pages, then a gap, then one more.
1263        let pages = [
1264            new_page(base, 0),
1265            new_page(base + page, PAGE_SIZE),
1266            new_page(base + 8 * page, 8 * PAGE_SIZE),
1267        ];
1268
1269        let runs = super::new_page_runs(&pages, destination).unwrap();
1270        assert_eq!(runs.len(), 2);
1271
1272        // Destinations are packed in index order regardless of source gaps.
1273        assert_eq!(super::page_destination(&runs, base), Some(destination));
1274        assert_eq!(
1275            super::page_destination(&runs, base + page),
1276            Some(destination + page)
1277        );
1278        assert_eq!(
1279            super::page_destination(&runs, base + 8 * page),
1280            Some(destination + 2 * page)
1281        );
1282        // An address in the source gap belongs to no run.
1283        assert_eq!(super::page_destination(&runs, base + 2 * page), None);
1284        assert_eq!(super::page_destination(&runs, base + 9 * page), None);
1285    }
1286
1287    #[test]
1288    fn page_copies_merge_only_contiguous_backings() {
1289        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1290        let page = PAGE_SIZE as u64;
1291        // Contiguous source addresses, but the third page comes from a
1292        // backing offset that does not follow the second.
1293        let pages = [
1294            new_page(base, 0),
1295            new_page(base + page, PAGE_SIZE),
1296            new_page(base + 2 * page, 9 * PAGE_SIZE),
1297        ];
1298
1299        let copies = super::new_page_copies(&pages).unwrap();
1300        assert_eq!(copies.len(), 2);
1301        assert_eq!(copies[0].destination, 0..2 * PAGE_SIZE);
1302        assert_eq!(copies[1].destination, 2 * PAGE_SIZE..3 * PAGE_SIZE);
1303    }
1304
1305    #[test]
1306    fn blob_placement_respects_the_scratch_boundary() {
1307        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1308        let scratch_base = base + 2 * PAGE_SIZE as u64;
1309
1310        // An empty delta needs no address.
1311        assert_eq!(super::first_fit_blob_gpa(0, &[], scratch_base), None);
1312        // With nothing to reuse the delta lands at the base.
1313        assert_eq!(
1314            super::first_fit_blob_gpa(PAGE_SIZE, &[], scratch_base),
1315            Some(base)
1316        );
1317        // Exactly filling the space below scratch is allowed.
1318        assert_eq!(
1319            super::first_fit_blob_gpa(2 * PAGE_SIZE, &[], scratch_base),
1320            Some(base)
1321        );
1322        // One page more is not.
1323        assert_eq!(
1324            super::first_fit_blob_gpa(3 * PAGE_SIZE, &[], scratch_base),
1325            None
1326        );
1327    }
1328
1329    #[test]
1330    fn snapshot_page_policy_reuses_shared_and_copies_private_backings() {
1331        let source_gpa = SandboxMemoryLayout::BASE_ADDRESS as u64;
1332        let backing = GuestBacking {
1333            source: BackingSource::Snapshot(0),
1334            offset: 0,
1335        };
1336        let mut reused = vec![false];
1337        let mut copied = Vec::new();
1338
1339        super::record_backed_pages(
1340            backing,
1341            source_gpa,
1342            2 * PAGE_SIZE,
1343            Some(reused.as_mut_slice()),
1344            &mut copied,
1345        )
1346        .unwrap();
1347        assert_eq!(reused, [true]);
1348        assert!(copied.is_empty());
1349
1350        reused[0] = false;
1351        super::record_backed_pages(backing, source_gpa, 2 * PAGE_SIZE, None, &mut copied).unwrap();
1352        assert_eq!(reused, [false]);
1353        assert_eq!(copied.len(), 2);
1354        assert_eq!(copied[0].source_gpa, source_gpa);
1355        assert_eq!(copied[0].backing, backing);
1356        assert_eq!(copied[1].source_gpa, source_gpa + PAGE_SIZE as u64);
1357        assert_eq!(
1358            copied[1].backing,
1359            GuestBacking {
1360                source: BackingSource::Snapshot(0),
1361                offset: PAGE_SIZE,
1362            }
1363        );
1364    }
1365
1366    fn make_simple_pt_memory(contents: &[u8], pt_base: u64) -> super::SnapshotMemory {
1367        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1368        make_pt_memory(contents, pt_base, base, &[base])
1369    }
1370
1371    /// A one-layer snapshot at `data_gpa` whose page tables map its first
1372    /// page at each of `gvas`.
1373    fn make_pt_memory(
1374        contents: &[u8],
1375        pt_base: u64,
1376        data_gpa: u64,
1377        gvas: &[u64],
1378    ) -> super::SnapshotMemory {
1379        let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1380        for &virt_base in gvas {
1381            let mapping = Mapping {
1382                phys_base: data_gpa,
1383                virt_base,
1384                len: page_size::get() as u64,
1385                kind: MappingKind::Basic(BasicMapping {
1386                    readable: true,
1387                    writable: true,
1388                    executable: true,
1389                }),
1390            };
1391            unsafe { vmem::map(&pt_buf, mapping) };
1392        }
1393        super::map_specials(&pt_buf, PAGE_SIZE);
1394        let pt_bytes = pt_buf.into_bytes();
1395
1396        super::memory::tests::flat_memory(
1397            contents,
1398            &pt_bytes,
1399            data_gpa,
1400            hyperlight_common::layout::scratch_base_gpa(PAGE_SIZE),
1401        )
1402    }
1403
1404    fn make_simple_pt_host_mem(
1405        contents: &[u8],
1406        pt_base: u64,
1407    ) -> SnapshotMemoryBacking<HostSharedMemory> {
1408        SnapshotMemoryBacking::from_snapshot(Arc::new(make_simple_pt_memory(contents, pt_base)))
1409            .unwrap()
1410            .build()
1411            .0
1412    }
1413
1414    fn make_simple_pt_mgr() -> (SandboxMemoryManager<HostSharedMemory>, u64) {
1415        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1416        make_pt_mgr(base, &[base])
1417    }
1418
1419    /// A manager whose snapshot is one layer at `data_gpa`, with page tables
1420    /// that map its first page at each of `gvas`.
1421    fn make_pt_mgr(data_gpa: u64, gvas: &[u64]) -> (SandboxMemoryManager<HostSharedMemory>, u64) {
1422        let cfg = crate::sandbox::SandboxConfiguration::default();
1423        let scratch_mem = ExclusiveSharedMemory::new(cfg.get_scratch_size()).unwrap();
1424        let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
1425        let pt_base = layout.get_pt_base_gpa();
1426        let memory = make_pt_memory(&vec![0u8; page_size::get()], pt_base, data_gpa, gvas);
1427        layout
1428            .ensure_page_tables_fit(memory.page_table_len())
1429            .unwrap();
1430        let mgr = SandboxMemoryManager::new(
1431            layout,
1432            SnapshotMemoryBacking::from_snapshot(Arc::new(memory)).unwrap(),
1433            scratch_mem,
1434            super::NextAction::None,
1435        );
1436        let (mgr, _) = mgr.build().unwrap();
1437        (mgr, pt_base)
1438    }
1439
1440    #[test]
1441    fn capture_and_restore_preserve_multiple_page_table_roots() {
1442        let cfg = crate::sandbox::SandboxConfiguration::default();
1443        let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
1444        let pt_base = layout.get_pt_base_gpa();
1445        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1446        let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1447        let first_root = pt_buf.initial_root();
1448        // SAFETY: The local buffer owns its page tables and has no concurrent access.
1449        let second_root = unsafe { <GuestPageTableBuffer as vmem::TableOps>::alloc_table(&pt_buf) };
1450        let kind = MappingKind::Basic(BasicMapping {
1451            readable: true,
1452            writable: false,
1453            executable: false,
1454        });
1455        // SAFETY: Both roots belong to this local buffer and the mappings are page-aligned.
1456        unsafe {
1457            vmem::map(
1458                &pt_buf,
1459                Mapping {
1460                    phys_base: base,
1461                    virt_base: base,
1462                    len: PAGE_SIZE as u64,
1463                    kind,
1464                },
1465            );
1466            pt_buf.set_root(second_root);
1467            vmem::map(
1468                &pt_buf,
1469                Mapping {
1470                    phys_base: base + PAGE_SIZE as u64,
1471                    virt_base: base + PAGE_SIZE as u64,
1472                    len: PAGE_SIZE as u64,
1473                    kind,
1474                },
1475            );
1476        }
1477        pt_buf.set_root(first_root);
1478        let page_tables = pt_buf.into_bytes();
1479        layout.ensure_page_tables_fit(page_tables.len()).unwrap();
1480
1481        let data_len = 2 * page_size::get();
1482        let mut bytes = vec![0u8; data_len];
1483        bytes[..PAGE_SIZE].fill(0x11);
1484        bytes[PAGE_SIZE..2 * PAGE_SIZE].fill(0x22);
1485        let memory = super::memory::tests::flat_memory(
1486            &bytes,
1487            &page_tables,
1488            base,
1489            hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
1490        );
1491        let manager = SandboxMemoryManager::new(
1492            layout,
1493            SnapshotMemoryBacking::from_snapshot(Arc::new(memory)).unwrap(),
1494            ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap(),
1495            super::NextAction::None,
1496        );
1497        let (mut manager, _) = manager.build().unwrap();
1498
1499        let snapshot = manager
1500            .with_guest_memory(&[], |memory| {
1501                super::Snapshot::new(
1502                    memory,
1503                    manager.layout,
1504                    LoadInfo::dummy(),
1505                    &[first_root, second_root],
1506                    0,
1507                    default_sregs(),
1508                    #[cfg(target_arch = "x86_64")]
1509                    Vec::new(),
1510                    super::NextAction::None,
1511                    0,
1512                    1,
1513                    HostFunctionDetails::default(),
1514                    None,
1515                    manager.layout.get_scratch_size(),
1516                )
1517            })
1518            .unwrap();
1519        let rebuilt_first_root = snapshot.root_pt_gpa();
1520        let rebuilt_second_root = rebuilt_first_root + PAGE_TABLE_SIZE as u64;
1521        let roots = [rebuilt_first_root, rebuilt_second_root];
1522        // SAFETY: The immutable snapshot owns both roots throughout the walk.
1523        let walked = unsafe { vmem::walk_va_spaces(&snapshot, &roots, base, 2 * PAGE_SIZE as u64) };
1524        assert_eq!(walked.len(), 2);
1525        assert!(walked[0].1.iter().any(|mapping| matches!(
1526            mapping,
1527            vmem::SpaceAwareMapping::ThisSpace(mapping) if mapping.virt_base == base
1528        )));
1529        assert!(walked[1].1.iter().any(|mapping| matches!(
1530            mapping,
1531            vmem::SpaceAwareMapping::ThisSpace(mapping)
1532                if mapping.virt_base == base + PAGE_SIZE as u64
1533        )));
1534
1535        manager.restore_snapshot(&snapshot).unwrap();
1536        manager
1537            .with_guest_memory(&[], |memory| {
1538                for (root, gva, expected) in [
1539                    (rebuilt_first_root, base, 0x11),
1540                    (rebuilt_second_root, base + PAGE_SIZE as u64, 0x22),
1541                ] {
1542                    let reader = super::PageTableReader::new(memory, root);
1543                    // SAFETY: The reader borrows the stopped manager's mapped memory.
1544                    let mapping = unsafe { vmem::virt_to_phys(&reader, gva, 1) }
1545                        .next()
1546                        .unwrap();
1547                    let gpa = mapping.phys_base + gva - mapping.virt_base;
1548                    let mut byte = [0u8; 1];
1549                    memory.read(gpa, &mut byte).unwrap();
1550                    assert_eq!(byte, [expected]);
1551                }
1552                Ok(())
1553            })
1554            .unwrap();
1555    }
1556
1557    #[cfg(target_arch = "x86_64")]
1558    #[test]
1559    fn capture_rejects_unbacked_intermediate_page_table() {
1560        let (manager, pt_base) = make_simple_pt_mgr();
1561        let scratch_base =
1562            hyperlight_common::layout::scratch_base_gpa(manager.layout.get_scratch_size());
1563        let root_offset = usize::try_from(pt_base - scratch_base).unwrap();
1564        let invalid_entry = (0xdead_0000 | vmem::PAGE_PRESENT).to_le_bytes();
1565        manager
1566            .scratch_mem
1567            .copy_from_slice(&invalid_entry, root_offset)
1568            .unwrap();
1569
1570        let result = manager.with_guest_memory(&[], |memory| {
1571            super::Snapshot::new(
1572                memory,
1573                manager.layout,
1574                LoadInfo::dummy(),
1575                &[pt_base],
1576                0,
1577                default_sregs(),
1578                Vec::new(),
1579                super::NextAction::None,
1580                0,
1581                1,
1582                HostFunctionDetails::default(),
1583                None,
1584                manager.layout.get_scratch_size(),
1585            )
1586        });
1587        let error = match result {
1588            Ok(_) => panic!("capture unexpectedly accepted an unbacked page table"),
1589            Err(error) => error,
1590        };
1591        assert!(error.to_string().contains("accessed unbacked memory"));
1592    }
1593
1594    #[test]
1595    fn multiple_snapshots_independent() {
1596        let (mut mgr, pt_base) = make_simple_pt_mgr();
1597
1598        // Create first snapshot with pattern A
1599        let pattern_a = vec![0xAA; page_size::get()];
1600        let pattern_a_memory = make_simple_pt_host_mem(&pattern_a, pt_base);
1601        let snapshot_a = GuestPhysicalMemoryView::with_memory(
1602            &pattern_a_memory,
1603            &mgr.scratch_mem,
1604            &[],
1605            mgr.layout,
1606            |memory| {
1607                super::Snapshot::new(
1608                    memory,
1609                    mgr.layout,
1610                    LoadInfo::dummy(),
1611                    &[pt_base],
1612                    0,
1613                    default_sregs(),
1614                    #[cfg(target_arch = "x86_64")]
1615                    Vec::new(),
1616                    super::NextAction::None,
1617                    0,
1618                    1,
1619                    HostFunctionDetails::default(),
1620                    None,
1621                    mgr.layout.get_scratch_size(),
1622                )
1623            },
1624        )
1625        .unwrap();
1626        assert_eq!(snapshot_a.snapshot_memory().layers().len(), 1);
1627
1628        // Create second snapshot with pattern B
1629        let pattern_b = vec![0xBB; page_size::get()];
1630        let pattern_b_memory = make_simple_pt_host_mem(&pattern_b, pt_base);
1631        let snapshot_b = GuestPhysicalMemoryView::with_memory(
1632            &pattern_b_memory,
1633            &mgr.scratch_mem,
1634            &[],
1635            mgr.layout,
1636            |memory| {
1637                super::Snapshot::new(
1638                    memory,
1639                    mgr.layout,
1640                    LoadInfo::dummy(),
1641                    &[pt_base],
1642                    0,
1643                    default_sregs(),
1644                    #[cfg(target_arch = "x86_64")]
1645                    Vec::new(),
1646                    super::NextAction::None,
1647                    0,
1648                    2,
1649                    HostFunctionDetails::default(),
1650                    None,
1651                    mgr.layout.get_scratch_size(),
1652                )
1653            },
1654        )
1655        .unwrap();
1656
1657        // Restore snapshot A
1658        mgr.restore_snapshot(&snapshot_a).unwrap();
1659        let mut restored = vec![0u8; pattern_a.len()];
1660        mgr.shared_mem
1661            .read_snapshot_gpa(SandboxMemoryLayout::BASE_ADDRESS as u64, &mut restored)
1662            .unwrap();
1663        assert_eq!(restored, pattern_a);
1664
1665        // Restore snapshot B
1666        mgr.restore_snapshot(&snapshot_b).unwrap();
1667        restored.fill(0);
1668        mgr.shared_mem
1669            .read_snapshot_gpa(SandboxMemoryLayout::BASE_ADDRESS as u64, &mut restored)
1670            .unwrap();
1671        assert_eq!(restored, pattern_b);
1672    }
1673
1674    #[test]
1675    fn page_table_reader_reports_unbacked_memory() {
1676        let (manager, pt_base) = make_simple_pt_mgr();
1677        manager
1678            .with_guest_memory(&[], |memory| {
1679                let reader = super::PageTableReader::new(memory, pt_base);
1680                assert!(reader.finish().is_ok());
1681
1682                // A read off every backing is recorded rather than returned, so the
1683                // walk keeps going against not-present entries until finish() asks.
1684                // SAFETY: the reader borrows `memory`, which outlives this call.
1685                let entry = unsafe {
1686                    <super::PageTableReader as vmem::TableReadOps>::read_entry(
1687                        &reader,
1688                        !(PAGE_SIZE as u64 - 1),
1689                    )
1690                };
1691                assert_eq!(entry, 0);
1692                let error = reader.finish().unwrap_err().to_string();
1693                assert!(error.contains("accessed unbacked memory"), "{error}");
1694                Ok(())
1695            })
1696            .unwrap();
1697    }
1698    fn snapshot_with_scratch(
1699        data_gpa: u64,
1700        gvas: &[u64],
1701        scratch_size: usize,
1702    ) -> crate::Result<super::Snapshot> {
1703        let (mgr, pt_base) = make_pt_mgr(data_gpa, gvas);
1704        mgr.with_guest_memory(&[], |memory| {
1705            super::Snapshot::new(
1706                memory,
1707                mgr.layout,
1708                LoadInfo::dummy(),
1709                &[pt_base],
1710                0,
1711                default_sregs(),
1712                #[cfg(target_arch = "x86_64")]
1713                Vec::new(),
1714                super::NextAction::None,
1715                0,
1716                1,
1717                HostFunctionDetails::default(),
1718                None,
1719                scratch_size,
1720            )
1721        })
1722    }
1723
1724    /// A snapshot can have more scratch than its sandbox, unless the larger
1725    /// window would cover a guest mapping below the current one.
1726    #[test]
1727    fn larger_scratch_must_not_cover_guest_mappings() {
1728        let scratch_size = crate::sandbox::SandboxConfiguration::default().get_scratch_size();
1729        let larger = scratch_size * 2;
1730        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1731
1732        let Ok(snapshot) = snapshot_with_scratch(base, &[base], larger) else {
1733            panic!("a larger scratch window over no guest mapping is rejected");
1734        };
1735        assert_eq!(snapshot.layout().get_scratch_size(), larger);
1736
1737        let in_band = super::scratch_base_gva(scratch_size) - PAGE_SIZE as u64;
1738        let Err(err) = snapshot_with_scratch(base, &[base, in_band], larger) else {
1739            panic!("a larger scratch window covers a guest mapping");
1740        };
1741        assert!(err.to_string().contains(&format!("{in_band:#x}")), "{err}");
1742
1743        // The same mapping is kept when the scratch window does not grow.
1744        assert!(snapshot_with_scratch(base, &[base, in_band], scratch_size).is_ok());
1745    }
1746
1747    /// A larger scratch window must not cover a layer the capture keeps.
1748    #[test]
1749    #[cfg(not(unshared_snapshot_mem))]
1750    fn larger_scratch_must_not_cover_kept_layers() {
1751        let scratch_size = crate::sandbox::SandboxConfiguration::default().get_scratch_size();
1752        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1753        let high = super::scratch_base_gpa(scratch_size) - page_size::get() as u64;
1754
1755        let Err(err) = snapshot_with_scratch(high, &[base], scratch_size * 2) else {
1756            panic!("a larger scratch window covers a kept layer");
1757        };
1758        assert!(err.to_string().contains(&format!("{high:#x}")), "{err}");
1759
1760        let snapshot = snapshot_with_scratch(high, &[base], scratch_size).unwrap();
1761        assert_eq!(snapshot.snapshot_memory().layers()[0].gpa_start(), high);
1762    }
1763
1764    #[test]
1765    fn page_table_reader_switches_cached_table_pages() {
1766        let (manager, pt_base) = make_simple_pt_mgr();
1767        let first = 8;
1768        let second = PAGE_SIZE + 16;
1769        manager.scratch_mem.write::<u64>(first, 0x1111).unwrap();
1770        manager.scratch_mem.write::<u64>(second, 0x2222).unwrap();
1771        let scratch_base =
1772            hyperlight_common::layout::scratch_base_gpa(manager.layout.get_scratch_size());
1773        manager
1774            .with_guest_memory(&[], |memory| {
1775                let reader = super::PageTableReader::new(memory, pt_base);
1776                // SAFETY: the reader borrows `memory`, which outlives these calls.
1777                let read = |offset: usize| unsafe {
1778                    <super::PageTableReader as vmem::TableReadOps>::read_entry(
1779                        &reader,
1780                        scratch_base + offset as u64,
1781                    )
1782                };
1783
1784                assert_eq!(read(first), 0x1111);
1785                assert_eq!(read(second), 0x2222);
1786                assert_eq!(read(first), 0x1111);
1787                assert!(reader.finish().is_ok());
1788                Ok(())
1789            })
1790            .unwrap();
1791    }
1792
1793    #[test]
1794    fn capture_rejects_invalid_page_table_roots() {
1795        let (manager, root) = make_simple_pt_mgr();
1796        for roots in [
1797            Vec::new(),
1798            vec![root + 1],
1799            vec![u64::MAX - (PAGE_SIZE as u64 - 1)],
1800        ] {
1801            let result = manager.with_guest_memory(&[], |memory| {
1802                super::Snapshot::new(
1803                    memory,
1804                    manager.layout,
1805                    LoadInfo::dummy(),
1806                    &roots,
1807                    0,
1808                    default_sregs(),
1809                    #[cfg(target_arch = "x86_64")]
1810                    Vec::new(),
1811                    super::NextAction::None,
1812                    0,
1813                    1,
1814                    HostFunctionDetails::default(),
1815                    None,
1816                    manager.layout.get_scratch_size(),
1817                )
1818            });
1819            assert!(result.is_err(), "invalid roots accepted: {roots:?}");
1820        }
1821    }
1822
1823    #[test]
1824    fn capture_reuses_shared_pages_and_materializes_private_pages() {
1825        let host_page_size = page_size::get();
1826        let cfg = crate::sandbox::SandboxConfiguration::default();
1827        let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
1828        let pt_base = layout.get_pt_base_gpa();
1829        let scratch_offset = layout.get_scratch_size() / 2;
1830        let scratch_gpa = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size())
1831            + scratch_offset as u64;
1832        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1833
1834        let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1835        // SAFETY: The page-aligned mappings are written serially to this local
1836        // page-table buffer.
1837        unsafe {
1838            vmem::map(
1839                &pt_buf,
1840                Mapping {
1841                    phys_base: base,
1842                    virt_base: base,
1843                    len: host_page_size as u64,
1844                    kind: MappingKind::Basic(BasicMapping {
1845                        readable: true,
1846                        writable: false,
1847                        executable: true,
1848                    }),
1849                },
1850            );
1851            vmem::map(
1852                &pt_buf,
1853                Mapping {
1854                    phys_base: scratch_gpa,
1855                    virt_base: base + (2 * host_page_size) as u64,
1856                    len: host_page_size as u64,
1857                    kind: MappingKind::Basic(BasicMapping {
1858                        readable: true,
1859                        writable: true,
1860                        executable: false,
1861                    }),
1862                },
1863            );
1864            vmem::map(
1865                &pt_buf,
1866                Mapping {
1867                    phys_base: scratch_gpa,
1868                    virt_base: base + host_page_size as u64,
1869                    len: host_page_size as u64,
1870                    kind: MappingKind::Basic(BasicMapping {
1871                        readable: true,
1872                        writable: true,
1873                        executable: false,
1874                    }),
1875                },
1876            );
1877        }
1878        super::map_specials(&pt_buf, layout.get_scratch_size());
1879        let page_tables = pt_buf.into_bytes();
1880        layout.ensure_page_tables_fit(page_tables.len()).unwrap();
1881
1882        let mut source_bytes = vec![0u8; 2 * host_page_size];
1883        source_bytes[..host_page_size].fill(0x11);
1884        source_bytes[host_page_size..2 * host_page_size].fill(0x22);
1885        let source = super::memory::tests::flat_memory(
1886            &source_bytes,
1887            &page_tables,
1888            base,
1889            hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
1890        );
1891        let source_blob = source.layers()[0].clone();
1892        let managed = SnapshotMemoryBacking::from_snapshot(Arc::new(source)).unwrap();
1893        let scratch = ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap();
1894        let manager = SandboxMemoryManager::new(layout, managed, scratch, super::NextAction::None);
1895        let (manager, _) = manager.build().unwrap();
1896        let reuses_source_layers = manager.shared_mem.reusable_layers().is_some();
1897        #[cfg(gdb)]
1898        {
1899            let (layer_index, offset) = manager.shared_mem.resolve(base, host_page_size).unwrap();
1900            manager
1901                .shared_mem
1902                .write_layer(layer_index, offset, &vec![0x44; host_page_size])
1903                .unwrap();
1904        }
1905        let mut source_page = vec![0u8; host_page_size];
1906        manager
1907            .shared_mem
1908            .read_snapshot_gpa(base, &mut source_page)
1909            .unwrap();
1910        manager
1911            .scratch_mem
1912            .copy_from_slice(&vec![0x33; host_page_size], scratch_offset)
1913            .unwrap();
1914
1915        let captured = manager
1916            .with_guest_memory(&[], |memory| {
1917                super::Snapshot::new(
1918                    memory,
1919                    manager.layout,
1920                    LoadInfo::dummy(),
1921                    &[pt_base],
1922                    0,
1923                    default_sregs(),
1924                    #[cfg(target_arch = "x86_64")]
1925                    Vec::new(),
1926                    super::NextAction::None,
1927                    0,
1928                    1,
1929                    HostFunctionDetails::default(),
1930                    None,
1931                    manager.layout.get_scratch_size(),
1932                )
1933            })
1934            .unwrap();
1935
1936        let layers = captured.snapshot_memory().layers();
1937        let delta_gpa = if reuses_source_layers {
1938            assert_eq!(layers.len(), 2);
1939            assert!(std::sync::Arc::ptr_eq(&layers[0], &source_blob));
1940            assert_eq!(layers[1].data_len(), host_page_size);
1941            assert_eq!(layers[1].gpa_start(), base + (2 * host_page_size) as u64);
1942            base + (2 * host_page_size) as u64
1943        } else {
1944            assert_eq!(layers.len(), 1);
1945            assert!(!std::sync::Arc::ptr_eq(&layers[0], &source_blob));
1946            assert_eq!(layers[0].data_len(), 2 * host_page_size);
1947            assert_eq!(layers[0].gpa_start(), base);
1948            base + host_page_size as u64
1949        };
1950
1951        // SAFETY: `captured` is immutable for the duration of this walk.
1952        let mappings = unsafe { vmem::virt_to_phys(&captured, base, 3 * host_page_size as u64) }
1953            .step_by(host_page_size / PAGE_SIZE)
1954            .collect::<Vec<_>>();
1955        assert_eq!(mappings.len(), 3);
1956        assert_eq!(mappings[0].phys_base, base);
1957        assert_eq!(mappings[1].phys_base, delta_gpa);
1958        assert_eq!(mappings[2].phys_base, mappings[1].phys_base);
1959        assert_eq!(
1960            mappings[0].kind,
1961            MappingKind::Basic(BasicMapping {
1962                readable: true,
1963                writable: false,
1964                executable: true,
1965            })
1966        );
1967        assert_eq!(
1968            mappings[1].kind,
1969            MappingKind::Cow(hyperlight_common::vmem::CowMapping {
1970                readable: true,
1971                executable: false,
1972            })
1973        );
1974        let (delta_layer, delta_offset) = captured
1975            .snapshot_memory()
1976            .resolve(mappings[1].phys_base, host_page_size)
1977            .unwrap();
1978        assert_eq!(
1979            layers[delta_layer].memory().as_slice()[delta_offset..delta_offset + host_page_size],
1980            vec![0x33; host_page_size]
1981        );
1982        let (kept_layer, kept_offset) = captured
1983            .snapshot_memory()
1984            .resolve(base, host_page_size)
1985            .unwrap();
1986        assert_eq!(
1987            layers[kept_layer].memory().as_slice()[kept_offset..kept_offset + host_page_size],
1988            source_page
1989        );
1990        // The reused layer stays mapped whole, including the page the guest
1991        // replaced.
1992        let (replaced_layer, replaced_offset) = captured
1993            .snapshot_memory()
1994            .resolve(base + host_page_size as u64, host_page_size)
1995            .unwrap();
1996        let replaced = vec![if reuses_source_layers { 0x22 } else { 0x33 }; host_page_size];
1997        assert_eq!(
1998            layers[replaced_layer].memory().as_slice()
1999                [replaced_offset..replaced_offset + host_page_size],
2000            replaced
2001        );
2002    }
2003
2004    #[test]
2005    fn capture_rejects_leaf_into_page_table_tail() {
2006        let host_page_size = page_size::get();
2007        let cfg = crate::sandbox::SandboxConfiguration::default();
2008        let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
2009        let pt_base = layout.get_pt_base_gpa();
2010        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
2011        let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
2012        // SAFETY: The page-aligned mapping is written to a local page-table
2013        // buffer with no concurrent access.
2014        unsafe {
2015            vmem::map(
2016                &pt_buf,
2017                Mapping {
2018                    phys_base: base + host_page_size as u64,
2019                    virt_base: base,
2020                    len: PAGE_SIZE as u64,
2021                    kind: MappingKind::Basic(BasicMapping {
2022                        readable: true,
2023                        writable: false,
2024                        executable: false,
2025                    }),
2026                },
2027            );
2028        }
2029        super::map_specials(&pt_buf, layout.get_scratch_size());
2030        let page_tables = pt_buf.into_bytes();
2031        layout.ensure_page_tables_fit(page_tables.len()).unwrap();
2032
2033        let bytes = vec![0u8; host_page_size];
2034        let source = super::memory::tests::flat_memory(
2035            &bytes,
2036            &page_tables,
2037            base,
2038            hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
2039        );
2040        let manager = SandboxMemoryManager::new(
2041            layout,
2042            SnapshotMemoryBacking::from_snapshot(Arc::new(source)).unwrap(),
2043            ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap(),
2044            super::NextAction::None,
2045        );
2046        let (manager, _) = manager.build().unwrap();
2047
2048        let result = manager.with_guest_memory(&[], |memory| {
2049            super::Snapshot::new(
2050                memory,
2051                manager.layout,
2052                LoadInfo::dummy(),
2053                &[pt_base],
2054                0,
2055                default_sregs(),
2056                #[cfg(target_arch = "x86_64")]
2057                Vec::new(),
2058                super::NextAction::None,
2059                0,
2060                1,
2061                HostFunctionDetails::default(),
2062                None,
2063                manager.layout.get_scratch_size(),
2064            )
2065        });
2066        let error = match result {
2067            Ok(_) => panic!("capture unexpectedly accepted a page-table-tail leaf"),
2068            Err(error) => error,
2069        };
2070
2071        assert!(
2072            error
2073                .to_string()
2074                .contains("snapshot leaf names unbacked GPA")
2075        );
2076    }
2077
2078    #[test]
2079    #[cfg(not(unshared_snapshot_mem))]
2080    fn capture_rejects_delta_exceeding_layer_limit() {
2081        let host_page_size = page_size::get();
2082        let cfg = crate::sandbox::SandboxConfiguration::default();
2083        let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
2084        let pt_base = layout.get_pt_base_gpa();
2085        let scratch_offset = layout.get_scratch_size() / 2;
2086        let scratch_gpa = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size())
2087            + scratch_offset as u64;
2088        let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
2089        let max_layers = super::memory::MAX_SNAPSHOT_LAYERS;
2090
2091        let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
2092        // One page in each of `max_layers` source layers, then one scratch page
2093        // that needs a new layer.
2094        for index in 0..=max_layers {
2095            let phys_base = if index < max_layers {
2096                base + (index * host_page_size) as u64
2097            } else {
2098                scratch_gpa
2099            };
2100            // SAFETY: The page-aligned mapping is written to a local page-table
2101            // buffer with no concurrent access.
2102            unsafe {
2103                vmem::map(
2104                    &pt_buf,
2105                    Mapping {
2106                        phys_base,
2107                        virt_base: base + (index * host_page_size) as u64,
2108                        len: host_page_size as u64,
2109                        kind: MappingKind::Basic(BasicMapping {
2110                            readable: true,
2111                            writable: index == max_layers,
2112                            executable: false,
2113                        }),
2114                    },
2115                );
2116            }
2117        }
2118        super::map_specials(&pt_buf, layout.get_scratch_size());
2119        let page_tables = pt_buf.into_bytes();
2120        layout.ensure_page_tables_fit(page_tables.len()).unwrap();
2121
2122        let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
2123        let source_layers = (0..max_layers)
2124            .map(|index| {
2125                let storage = crate::mem::shared_mem::ReadonlySharedMemory::from_bytes(
2126                    &vec![index as u8; host_page_size],
2127                    host_page_size,
2128                )
2129                .unwrap();
2130                Arc::new(
2131                    super::SnapshotBlob::new(
2132                        storage,
2133                        base + (index * host_page_size) as u64,
2134                        0,
2135                        scratch_base,
2136                    )
2137                    .unwrap(),
2138                )
2139            })
2140            .collect::<Box<[_]>>();
2141        let source = super::SnapshotMemory::new(
2142            source_layers.clone(),
2143            super::memory::tests::page_tables_from_bytes(&page_tables),
2144        )
2145        .unwrap();
2146        let managed = SnapshotMemoryBacking::from_snapshot(Arc::new(source)).unwrap();
2147        let scratch = ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap();
2148        let manager = SandboxMemoryManager::new(layout, managed, scratch, super::NextAction::None);
2149        let (mut manager, _) = manager.build().unwrap();
2150        manager
2151            .scratch_mem
2152            .copy_from_slice(&vec![0x55; host_page_size], scratch_offset)
2153            .unwrap();
2154
2155        let result = manager.snapshot(
2156            Vec::new(),
2157            &[pt_base],
2158            0,
2159            default_sregs(),
2160            #[cfg(target_arch = "x86_64")]
2161            Vec::new(),
2162            super::NextAction::None,
2163            HostFunctionDetails::default(),
2164            manager.layout.get_scratch_size(),
2165        );
2166        let error = match result {
2167            Ok(_) => panic!("capture unexpectedly exceeded the layer limit"),
2168            Err(error) => error,
2169        };
2170
2171        assert!(error.to_string().contains("layer count 31 exceeds 30"));
2172        assert_eq!(manager.snapshot_count, 0);
2173        assert!(
2174            manager
2175                .shared_mem
2176                .layers()
2177                .iter()
2178                .zip(&source_layers)
2179                .all(|(layer, source)| Arc::ptr_eq(layer, source))
2180        );
2181        assert_eq!(
2182            manager.scratch_mem.read::<u8>(scratch_offset).unwrap(),
2183            0x55
2184        );
2185    }
2186}