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;
6mod tripwires;
7
8use std::collections::{BTreeMap, HashMap};
9use std::sync::Arc;
10
11pub(crate) use file::host_cpu_vendor_golden_tag;
12pub use file::reference::{OciDigest, OciReference, OciTag};
13use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
14use hyperlight_common::layout::{io_page, scratch_base_gpa, scratch_base_gva};
15use hyperlight_common::vmem;
16use hyperlight_common::vmem::{
17    BasicMapping, CowMapping, Mapping, MappingKind, PAGE_SIZE, SpaceAwareMapping, SpaceId, TableOps,
18};
19use tracing::{Span, instrument};
20
21use crate::Result;
22use crate::hypervisor::regs::CommonSpecialRegisters;
23#[cfg(target_arch = "x86_64")]
24use crate::hypervisor::regs::MsrEntry;
25use crate::mem::exe::{ExeInfo, LoadInfo};
26use crate::mem::layout::SandboxMemoryLayout;
27use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags};
28use crate::mem::mgr::{GuestPageTableBuffer, SnapshotSharedMemory};
29use crate::mem::shared_mem::{ReadonlySharedMemory, SharedMemory};
30use crate::mem::virtq::VirtqSnapshot;
31use crate::sandbox::SandboxConfiguration;
32use crate::sandbox::uninitialized::{GuestBinary, GuestEnvironment};
33
34const PTE_SIZE: usize = size_of::<vmem::PageTableEntry>();
35
36/// Presently, a snapshot can be of a preinitialised sandbox, which
37/// still needs an initialise function called in order to determine
38/// how to call into it, or of an already-properly-initialised sandbox
39/// which can be immediately called into. This keeps track of the
40/// difference.
41///
42/// TODO: this should not necessarily be around in the long term:
43/// ideally we would just preinitialise earlier in the snapshot
44/// creation process and never need this.
45#[derive(Copy, Clone, PartialEq, Eq)]
46pub enum NextAction {
47    /// A sandbox in the preinitialise state still needs to be
48    /// initialised by calling the initialise function
49    Initialise(u64),
50    /// A sandbox in the ready state can immediately be called into,
51    /// using the dispatch function pointer.
52    Call(u64),
53    /// Only when compiling for tests: a sandbox that cannot actually
54    /// be used
55    #[cfg(test)]
56    None,
57}
58
59/// An immutable snapshot of sandbox state.
60pub struct Snapshot {
61    state: Arc<SnapshotState>,
62    // Stable key order keeps config bytes deterministic.
63    metadata: BTreeMap<String, serde_json::Value>,
64}
65
66/// Immutable sandbox state held by a snapshot.
67struct SnapshotState {
68    /// Layout object for the sandbox. TODO: get rid of this and
69    /// replace with something saner and set up from the guest (early
70    /// on?).
71    layout: crate::mem::layout::SandboxMemoryLayout,
72    /// Memory of the sandbox at the time this snapshot was taken
73    memory: ReadonlySharedMemory,
74    /// Extra debug information about the binary in this snapshot,
75    /// from when the binary was first loaded into the snapshot.
76    ///
77    /// This information is provided on a best-effort basis, and there
78    /// is a pretty good chance that it does not exist; generally speaking,
79    /// things like persisting a snapshot and reloading it are likely
80    /// to destroy this information.
81    load_info: LoadInfo,
82    /// The address of the top of the guest stack
83    stack_top_gva: u64,
84
85    /// Special register state captured from the vCPU during snapshot.
86    /// None for snapshots created directly from a binary (before
87    /// guest runs).  Some for snapshots taken from a running sandbox.
88    /// Note: CR3 in this struct is NOT used on restore, since page
89    /// tables are relocated during snapshot.
90    sregs: Option<CommonSpecialRegisters>,
91
92    /// The MSRs saved in this snapshot. None before the guest has run.
93    #[cfg(target_arch = "x86_64")]
94    msrs: Option<Vec<MsrEntry>>,
95
96    /// The next action that should be performed on this snapshot
97    next_action: NextAction,
98
99    /// Guest virtual address of the guest binary's ELF entry point
100    /// (`code GVA + e_entry - base_va`). Unlike `next_action`, which
101    /// transitions to `Call(dispatch_addr)` once the guest has run,
102    /// this preserves the original entry across that transition. Used
103    /// to fill `AT_ENTRY` in guest core dumps so a debugger can
104    /// compute the PIE load bias. 0 if unknown (e.g. an older
105    /// on-disk snapshot that predates this field).
106    original_entrypoint: u64,
107
108    /// The generation number assigned to this snapshot when it was
109    /// taken — i.e. "this is the Nth snapshot taken from the sandbox's
110    /// execution path from init to here". Propagated into the
111    /// restored sandbox's guest-visible counter so the guest can tell
112    /// which snapshot it is currently a clone of.
113    snapshot_generation: u64,
114
115    /// Names and signatures of host functions registered on the
116    /// sandbox at the time this snapshot was taken. Used by
117    /// [`crate::Sandbox::from_snapshot`] to reject a
118    /// `HostFunctions` set that is missing required functions or
119    /// has mismatched signatures.
120    host_functions: HostFunctionDetails,
121
122    /// Validated ring images omitted from ordinary snapshot pages.
123    ///
124    /// Construction and loading validate these images against `layout`.
125    /// Both the images and layout remain immutable afterwards.
126    virtq: Option<VirtqSnapshot>,
127}
128
129impl core::convert::AsRef<Snapshot> for Snapshot {
130    fn as_ref(&self) -> &Self {
131        self
132    }
133}
134impl hyperlight_common::vmem::TableReadOps for Snapshot {
135    type TableAddr = u64;
136    fn entry_addr(addr: u64, offset: u64) -> u64 {
137        addr + offset
138    }
139    unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
140        let addr = addr as usize;
141        let Some(pte_bytes) = self.state.memory.as_slice().get(addr..addr + PTE_SIZE) else {
142            // Attacker-controlled data pointed out-of-bounds. We'll
143            // default to returning 0 in this case, which, for most
144            // architectures (including x86-64 and arm64, the ones we
145            // care about presently) will be a not-present entry.
146            return 0;
147        };
148        // The `get()` above ensures exactly PTE_SIZE bytes.
149        #[allow(clippy::unwrap_used)]
150        vmem::PageTableEntry::from_le_bytes(pte_bytes.try_into().unwrap())
151    }
152    #[allow(clippy::unnecessary_cast)]
153    fn to_phys(addr: u64) -> vmem::PhysAddr {
154        addr as vmem::PhysAddr
155    }
156    #[allow(clippy::unnecessary_cast)]
157    fn from_phys(addr: vmem::PhysAddr) -> u64 {
158        addr as u64
159    }
160    fn root_table(&self) -> u64 {
161        self.root_pt_gpa()
162    }
163}
164
165pub(crate) fn access_gpa<'a>(
166    snap: &'a [u8],
167    scratch: &'a [u8],
168    layout: SandboxMemoryLayout,
169    gpa: u64,
170) -> Option<(&'a [u8], usize)> {
171    let resolved = layout.resolve_gpa(gpa, &[])?.with_memories(snap, scratch);
172    Some((resolved.base.as_ref(), resolved.offset))
173}
174
175pub(crate) struct SharedMemoryPageTableBuffer<'a> {
176    snap: &'a [u8],
177    scratch: &'a [u8],
178    layout: SandboxMemoryLayout,
179    root: u64,
180}
181impl<'a> SharedMemoryPageTableBuffer<'a> {
182    pub(crate) fn new(
183        snap: &'a [u8],
184        scratch: &'a [u8],
185        layout: SandboxMemoryLayout,
186        root: u64,
187    ) -> Self {
188        Self {
189            snap,
190            scratch,
191            layout,
192            root,
193        }
194    }
195}
196impl<'a> hyperlight_common::vmem::TableReadOps for SharedMemoryPageTableBuffer<'a> {
197    type TableAddr = u64;
198    fn entry_addr(addr: u64, offset: u64) -> u64 {
199        addr + offset
200    }
201    unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
202        let memoff = access_gpa(self.snap, self.scratch, self.layout, addr);
203        let Some(pte_bytes) = memoff.and_then(|(mem, off)| mem.get(off..off + PTE_SIZE)) else {
204            // Attacker-controlled data pointed out-of-bounds. We'll
205            // default to returning 0 in this case, which, for most
206            // architectures (including x86-64 and arm64, the ones we
207            // care about presently) will be a not-present entry.
208            return 0;
209        };
210        // The `get()` above ensures exactly PTE_SIZE bytes.
211        #[allow(clippy::unwrap_used)]
212        vmem::PageTableEntry::from_le_bytes(pte_bytes.try_into().unwrap())
213    }
214    #[allow(clippy::unnecessary_cast)]
215    fn to_phys(addr: u64) -> vmem::PhysAddr {
216        addr as vmem::PhysAddr
217    }
218    #[allow(clippy::unnecessary_cast)]
219    fn from_phys(addr: vmem::PhysAddr) -> u64 {
220        addr as u64
221    }
222    fn root_table(&self) -> u64 {
223        self.root
224    }
225}
226impl<'a> core::convert::AsRef<SharedMemoryPageTableBuffer<'a>> for SharedMemoryPageTableBuffer<'a> {
227    fn as_ref(&self) -> &Self {
228        self
229    }
230}
231/// Return true if `virt_base` is a VA we must not preserve into the
232/// rebuilt snapshot page tables: it is either part of the scratch
233/// region (re-mapped freshly by `map_specials`) or, on amd64, part of
234/// the self-map of the snapshot's own page tables.
235fn skip_virt(virt_base: u64, scratch_gva: u64) -> bool {
236    if virt_base >= scratch_gva {
237        return true;
238    }
239    if virt_base >= hyperlight_common::layout::SNAPSHOT_PT_GVA_MIN as u64
240        && virt_base <= hyperlight_common::layout::SNAPSHOT_PT_GVA_MAX as u64
241    {
242        return true;
243    }
244    false
245}
246
247/// Find the contents of the page which starts at gpa in guest physical
248/// memory, taking into account excess host->guest regions
249///
250/// # Safety
251/// The host side of the regions identified by MemoryRegion must be
252/// alive and must not be mutated by any other thread: references to
253/// these regions may be created and live for `'a`.
254unsafe fn guest_page<'a>(
255    snap: &'a [u8],
256    scratch: &'a [u8],
257    regions: &[MemoryRegion],
258    layout: SandboxMemoryLayout,
259    gpa: u64,
260) -> Option<&'a [u8]> {
261    let resolved = layout
262        .resolve_gpa(gpa, regions)?
263        .with_memories(snap, scratch);
264    if resolved.as_ref().len() < PAGE_SIZE {
265        return None;
266    }
267    Some(&resolved.as_ref()[..PAGE_SIZE])
268}
269
270fn map_specials(pt_buf: &GuestPageTableBuffer, scratch_size: usize) {
271    if let Some((phys_base, virt_base)) = io_page() {
272        // Map the IO page
273        let mapping = Mapping {
274            phys_base,
275            virt_base,
276            len: PAGE_SIZE as u64,
277            kind: MappingKind::Basic(BasicMapping {
278                readable: true,
279                writable: true,
280                executable: false,
281            }),
282        };
283        unsafe { vmem::map(pt_buf, mapping) };
284    }
285    // Map the scratch region
286    let mapping = Mapping {
287        phys_base: scratch_base_gpa(scratch_size),
288        virt_base: scratch_base_gva(scratch_size),
289        len: scratch_size as u64,
290        kind: MappingKind::Basic(BasicMapping {
291            readable: true,
292            writable: true,
293            // assume that the guest will map these pages elsewhere if
294            // it actually needs to execute from them
295            executable: false,
296        }),
297    };
298    unsafe { vmem::map(pt_buf, mapping) };
299}
300
301impl Snapshot {
302    /// Create a new snapshot from the guest binary identified by `env`. With the configuration
303    /// specified in `cfg`.
304    pub(crate) fn from_env<'b>(
305        env: impl Into<GuestEnvironment<'b>>,
306        cfg: SandboxConfiguration,
307    ) -> Result<Self> {
308        let env = env.into();
309        let mut bin = env.guest_binary;
310        bin.canonicalize()?;
311        let blob = env.init_data;
312
313        let exe_info = match bin {
314            GuestBinary::FilePath(bin_path) => ExeInfo::from_file(&bin_path)?,
315            GuestBinary::Buffer(buffer) => ExeInfo::from_buf(buffer)?,
316        };
317
318        // Check guest/host version compatibility.
319        let host_version = env!("CARGO_PKG_VERSION");
320        if let Some(v) = exe_info.guest_bin_version()
321            && v != host_version
322        {
323            return Err(crate::HyperlightError::GuestBinVersionMismatch {
324                guest_bin_version: v.to_string(),
325                host_version: host_version.to_string(),
326            });
327        }
328
329        let guest_blob_size = blob.as_ref().map(|b| b.data.len()).unwrap_or(0);
330        let guest_blob_mem_flags = blob.as_ref().map(|b| b.permissions);
331
332        let mut layout = crate::mem::layout::SandboxMemoryLayout::new(
333            cfg,
334            exe_info.loaded_size(),
335            guest_blob_size,
336            guest_blob_mem_flags,
337        )?;
338
339        let load_addr = layout.get_guest_code_gpa() as u64;
340        let base_va = exe_info.base_va();
341        let entrypoint_va: u64 = exe_info.entrypoint().into();
342        let is_pie = exe_info.is_pie();
343
344        let code_gva = if is_pie { load_addr } else { base_va };
345        layout.set_code_gva(code_gva)?;
346        let regions = layout.get_memory_regions()?;
347
348        let mut memory = vec![0; layout.get_memory_size()?];
349
350        let load_info = exe_info.load(
351            layout.get_guest_code_gva() as u64,
352            &mut memory[layout.guest_code_offset()..],
353        )?;
354
355        layout.write_peb(&mut memory)?;
356
357        blob.map(|x| layout.write_init_data(&mut memory, x.data))
358            .transpose()?;
359
360        // Set up page table entries for the snapshot
361        let pt_buf = GuestPageTableBuffer::new(layout.get_pt_base_gpa() as usize);
362
363        // 1. Map the (ideally readonly) pages of snapshot data
364        for rgn in regions.iter() {
365            let readable = rgn.flags.contains(MemoryRegionFlags::READ);
366            let executable = rgn.flags.contains(MemoryRegionFlags::EXECUTE);
367            let writable = rgn.flags.contains(MemoryRegionFlags::WRITE);
368            let kind = if writable {
369                MappingKind::Cow(CowMapping {
370                    readable,
371                    executable,
372                })
373            } else {
374                MappingKind::Basic(BasicMapping {
375                    readable,
376                    writable: false,
377                    executable,
378                })
379            };
380
381            let mapping = Mapping {
382                phys_base: rgn.host_region.start as u64,
383                virt_base: rgn.guest_region.start as u64,
384                len: rgn.guest_region.len() as u64,
385                kind,
386            };
387            unsafe { vmem::map(&pt_buf, mapping) };
388        }
389
390        // 2. Map the special mappings
391        map_specials(&pt_buf, layout.get_scratch_size());
392
393        let pt_bytes = pt_buf.into_bytes();
394        layout.set_pt_size(pt_bytes.len())?;
395        memory.extend(&pt_bytes);
396
397        let exn_stack_top_gva = hyperlight_common::layout::SCRATCH_TOP_GVA as u64
398            - hyperlight_common::layout::SCRATCH_TOP_EXN_STACK_OFFSET
399            + 1;
400
401        let entrypoint_offset = entrypoint_va.checked_sub(base_va).ok_or_else(|| {
402            crate::new_error!(
403                "ELF entrypoint VA ({:#x}) is below base VA ({:#x})",
404                entrypoint_va,
405                base_va
406            )
407        })?;
408
409        let entrypoint_gva = (layout.get_guest_code_gva() as u64)
410            .checked_add(entrypoint_offset)
411            .ok_or_else(|| crate::new_error!("ELF entrypoint GVA overflows"))?;
412
413        Ok(Self {
414            state: Arc::new(SnapshotState {
415                memory: ReadonlySharedMemory::from_bytes(&memory, layout.snapshot_size())?,
416                layout,
417                load_info,
418                stack_top_gva: exn_stack_top_gva,
419                sregs: None,
420                #[cfg(target_arch = "x86_64")]
421                msrs: None,
422                next_action: NextAction::Initialise(entrypoint_gva),
423                original_entrypoint: entrypoint_gva,
424                snapshot_generation: 0,
425                host_functions: HostFunctionDetails {
426                    host_functions: None,
427                },
428                virtq: None,
429            }),
430            metadata: BTreeMap::new(),
431        })
432    }
433
434    // It might be nice to consider moving at least stack_top_gva into
435    // layout, and sharing (via RwLock or similar) the layout between
436    // the (host-side) mem mgr (where it can be passed in here) and
437    // the sandbox vm itself (which modifies it as it receives
438    // requests from the sandbox).
439    #[allow(clippy::too_many_arguments)]
440    /// Capture memory with optional validated transport images.
441    ///
442    /// Page-table and snapshot sizes do not affect transport geometry.
443    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
444    pub(crate) fn new<S: SharedMemory>(
445        shared_mem: &mut SnapshotSharedMemory<S>,
446        scratch_mem: &mut S,
447        mut layout: SandboxMemoryLayout,
448        load_info: LoadInfo,
449        regions: Vec<MemoryRegion>,
450        root_pt_gpas: &[u64],
451        stack_top_gva: u64,
452        sregs: CommonSpecialRegisters,
453        #[cfg(target_arch = "x86_64")] msrs: Vec<MsrEntry>,
454        next_action: NextAction,
455        original_entrypoint: u64,
456        snapshot_generation: u64,
457        host_functions: HostFunctionDetails,
458        virtq: Option<VirtqSnapshot>,
459    ) -> Result<Self> {
460        let mut phys_seen = HashMap::<u64, usize>::new();
461        let scratch_gva = scratch_base_gva(layout.get_scratch_size());
462        let memory = shared_mem.with_contents(|snap_c| {
463            scratch_mem.with_contents(|scratch_c| {
464                // Phase 1: walk every PT root together. This detects
465                // aliased intermediate tables (e.g. Nanvix's kernel-
466                // half PTs, which multiple process PDs share by
467                // pointing at the same PT page). The walker emits
468                // `ThisSpace(leaf)` for private leaves and
469                // `AnotherSpace(ref)` for sub-trees that were already
470                // seen via an earlier root. Results are returned in
471                // `root_pt_gpas` order — which is also the topological
472                // order of the `AnotherSpace` references — so
473                // processing in iteration order is safe.
474                let op = SharedMemoryPageTableBuffer::new(
475                    snap_c,
476                    scratch_c,
477                    layout,
478                    root_pt_gpas.first().copied().unwrap_or(0),
479                );
480                let walk = unsafe {
481                    vmem::walk_va_spaces(
482                        &op,
483                        root_pt_gpas,
484                        0,
485                        hyperlight_common::layout::SCRATCH_TOP_GVA as u64,
486                    )
487                };
488
489                // Phase 2: rebuild each space's page tables, compacting
490                // `ThisSpace` leaves into a dense snapshot blob and
491                // linking `AnotherSpace` entries to already-built
492                // spaces' tables.
493                // TODO: Look for opportunities to hugepage map
494                let mut snapshot_memory: Vec<u8> = Vec::new();
495                let pt_buf = GuestPageTableBuffer::new(layout.get_pt_base_gpa() as usize);
496                // Allocate one root table per space and remember the
497                // addresses returned by `alloc_table` instead of
498                // assuming the buffer's physical layout.
499                let mut root_addrs: Vec<u64> = Vec::with_capacity(root_pt_gpas.len());
500                root_addrs.push(pt_buf.initial_root());
501                for _ in 1..root_pt_gpas.len() {
502                    root_addrs.push(unsafe { pt_buf.alloc_table() });
503                }
504
505                let mut built_roots: BTreeMap<SpaceId, u64> = BTreeMap::new();
506                for (root_idx, (space_id, mappings)) in walk.into_iter().enumerate() {
507                    pt_buf.set_root(root_addrs[root_idx]);
508                    built_roots.insert(space_id, root_addrs[root_idx]);
509
510                    for sam in mappings {
511                        match sam {
512                            SpaceAwareMapping::ThisSpace(mapping) => {
513                                // Drop the scratch region and (on
514                                // amd64) the snapshot's own PT
515                                // self-map; both are re-mapped
516                                // freshly by `map_specials`.
517                                if skip_virt(mapping.virt_base, scratch_gva) {
518                                    continue;
519                                }
520
521                                // Writable pages become CoW in the
522                                // rebuilt snapshot; read-only pages
523                                // stay read-only.
524                                let (kind, has_contents) = match mapping.kind {
525                                    MappingKind::Cow(cm) => (MappingKind::Cow(cm), true),
526                                    MappingKind::Basic(bm) if bm.writable => (
527                                        MappingKind::Cow(CowMapping {
528                                            readable: bm.readable,
529                                            executable: bm.executable,
530                                        }),
531                                        true,
532                                    ),
533                                    MappingKind::Basic(bm) => (
534                                        MappingKind::Basic(BasicMapping {
535                                            readable: bm.readable,
536                                            writable: false,
537                                            executable: bm.executable,
538                                        }),
539                                        true,
540                                    ),
541                                    MappingKind::Unmapped => continue,
542                                    MappingKind::ZeroInit(bm) => (MappingKind::ZeroInit(bm), false),
543                                };
544                                let new_gpa = if has_contents {
545                                    let Some(contents) = (unsafe {
546                                        guest_page(
547                                            snap_c,
548                                            scratch_c,
549                                            &regions,
550                                            layout,
551                                            mapping.phys_base,
552                                        )
553                                    }) else {
554                                        continue;
555                                    };
556                                    Some(*phys_seen.entry(mapping.phys_base).or_insert_with(|| {
557                                        let new_offset = snapshot_memory.len();
558                                        snapshot_memory.extend(contents);
559                                        new_offset + SandboxMemoryLayout::BASE_ADDRESS
560                                    }))
561                                } else {
562                                    None
563                                };
564
565                                let compacted = Mapping {
566                                    phys_base: new_gpa.unwrap_or(0) as u64,
567                                    virt_base: mapping.virt_base,
568                                    len: PAGE_SIZE as u64,
569                                    kind,
570                                };
571                                unsafe { vmem::map(&pt_buf, compacted) };
572                            }
573                            SpaceAwareMapping::AnotherSpace(ref_map) => {
574                                // Link to the owning space's already-
575                                // rebuilt intermediate table — this
576                                // is what preserves Nanvix's
577                                // kernel-half-shared invariant across
578                                // process PDs after relocation.
579                                unsafe {
580                                    vmem::space_aware_map(&pt_buf, ref_map, &built_roots);
581                                }
582                            }
583                        }
584                    }
585                }
586
587                // Phase 3: Map the scratch region into each root.
588                for &root_addr in &root_addrs {
589                    pt_buf.set_root(root_addr);
590                    map_specials(&pt_buf, layout.get_scratch_size());
591                }
592                pt_buf.set_root(pt_buf.initial_root());
593
594                snapshot_memory.resize(
595                    snapshot_memory.len().next_multiple_of(page_size::get()),
596                    0u8,
597                );
598
599                // Phase 4: finalize PT bytes.
600                let pt_data = pt_buf.into_bytes();
601                layout.set_pt_size(pt_data.len())?;
602                snapshot_memory.extend(&pt_data);
603                Ok::<_, crate::HyperlightError>(snapshot_memory)
604            })
605        })???;
606        // Only the data prefix is exposed to the guest. The PT tail
607        // sits past it in the host mapping and is copied into the
608        // scratch region on restore. Keeping it out of the guest
609        // mapping of the snapshot region avoids overlap with
610        // `map_file_cow` regions installed immediately after the
611        // snapshot in guest PA space.
612        let guest_visible_size = memory.len() - layout.get_pt_size();
613        debug_assert!(guest_visible_size.is_multiple_of(page_size::get()));
614        layout.set_snapshot_size(guest_visible_size);
615
616        Ok(Self {
617            state: Arc::new(SnapshotState {
618                layout,
619                memory: ReadonlySharedMemory::from_bytes(&memory, guest_visible_size)?,
620                load_info,
621                stack_top_gva,
622                sregs: Some(sregs),
623                #[cfg(target_arch = "x86_64")]
624                msrs: Some(msrs),
625                next_action,
626                original_entrypoint,
627                snapshot_generation,
628                host_functions,
629                virtq,
630            }),
631            metadata: BTreeMap::new(),
632        })
633    }
634
635    /// Deserializes the metadata stored under `namespace` as `T`.
636    ///
637    /// Returns `None` if the namespace has no metadata.
638    ///
639    /// # Errors
640    ///
641    /// Returns an error if the JSON metadata cannot be deserialized as `T`.
642    ///
643    /// # Examples
644    ///
645    /// ```no_run
646    /// # use std::sync::Arc;
647    /// # use hyperlight_host::sandbox::snapshot::Snapshot;
648    /// # use serde::{Deserialize, Serialize};
649    /// #
650    /// #[derive(Debug, PartialEq, Serialize, Deserialize)]
651    /// struct Metadata {
652    ///     version: u32,
653    /// }
654    ///
655    /// # fn example(snapshot: Arc<Snapshot>) -> Result<(), Box<dyn std::error::Error>> {
656    /// let snapshot =
657    ///     snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
658    /// let metadata = snapshot
659    ///     .metadata::<Metadata>("snapshot-metadata-namespace-v1")?
660    ///     .expect("metadata should exist");
661    /// assert_eq!(metadata, Metadata { version: 1 });
662    /// # Ok(())
663    /// # }
664    /// ```
665    pub fn metadata<T>(&self, namespace: &str) -> Result<Option<T>>
666    where
667        T: serde::de::DeserializeOwned,
668    {
669        self.metadata
670            .get(namespace)
671            .map(serde::Deserialize::deserialize)
672            .transpose()
673            .map_err(Into::into)
674    }
675
676    /// Adds `metadata` to this snapshot and returns the result as a new
677    /// snapshot. Metadata already stored under `namespace` is replaced.
678    ///
679    /// This snapshot remains unchanged.
680    /// Metadata is saved and loaded with the snapshot.
681    ///
682    /// # Errors
683    ///
684    /// Returns an error if `metadata` cannot be serialized as JSON.
685    ///
686    /// # Examples
687    ///
688    /// ```no_run
689    /// # use std::sync::Arc;
690    /// # use hyperlight_host::sandbox::snapshot::Snapshot;
691    /// # use serde::{Deserialize, Serialize};
692    /// #
693    /// #[derive(Debug, PartialEq, Serialize, Deserialize)]
694    /// struct Metadata {
695    ///     version: u32,
696    /// }
697    ///
698    /// # fn example(snapshot: Arc<Snapshot>) -> Result<(), Box<dyn std::error::Error>> {
699    /// let snapshot =
700    ///     snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
701    /// let metadata = snapshot
702    ///     .metadata::<Metadata>("snapshot-metadata-namespace-v1")?
703    ///     .expect("metadata should exist");
704    /// assert_eq!(metadata, Metadata { version: 1 });
705    /// # Ok(())
706    /// # }
707    /// ```
708    pub fn with_metadata<T>(&self, namespace: impl Into<String>, metadata: &T) -> Result<Arc<Self>>
709    where
710        T: serde::Serialize,
711    {
712        let namespace = namespace.into();
713        let metadata = serde_json::to_value(metadata)?;
714        let mut metadata_by_namespace = self.metadata.clone();
715        metadata_by_namespace.insert(namespace, metadata);
716        Ok(Arc::new(Self {
717            state: Arc::clone(&self.state),
718            metadata: metadata_by_namespace,
719        }))
720    }
721
722    /// Generation number assigned to this snapshot when it was taken.
723    pub(crate) fn snapshot_generation(&self) -> u64 {
724        self.state.snapshot_generation
725    }
726
727    /// Return the main memory contents of the snapshot
728    #[instrument(skip_all, parent = Span::current(), level= "Trace")]
729    pub(crate) fn memory(&self) -> &ReadonlySharedMemory {
730        &self.state.memory
731    }
732
733    /// Return a copy of the load info for the exe in the snapshot
734    pub(crate) fn load_info(&self) -> LoadInfo {
735        self.state.load_info.clone()
736    }
737
738    pub(crate) fn layout(&self) -> &crate::mem::layout::SandboxMemoryLayout {
739        &self.state.layout
740    }
741
742    pub(crate) fn root_pt_gpa(&self) -> u64 {
743        self.state.layout.get_pt_base_gpa()
744    }
745
746    pub(crate) fn stack_top_gva(&self) -> u64 {
747        self.state.stack_top_gva
748    }
749
750    /// Returns the special registers stored in this snapshot.
751    /// Returns None for snapshots created directly from a binary (before preinitialisation).
752    /// Returns Some for snapshots taken from a running sandbox.
753    /// Note: The CR3 value in the returned struct should NOT be used for restore;
754    /// use `root_pt_gpa()` instead since page tables are relocated during snapshot.
755    pub(crate) fn sregs(&self) -> Option<&CommonSpecialRegisters> {
756        self.state.sregs.as_ref()
757    }
758
759    /// The MSRs saved in this snapshot.
760    #[cfg(target_arch = "x86_64")]
761    pub(crate) fn msrs(&self) -> Option<&Vec<MsrEntry>> {
762        self.state.msrs.as_ref()
763    }
764
765    pub(crate) fn next_action(&self) -> NextAction {
766        self.state.next_action
767    }
768
769    pub(crate) fn virtq(&self) -> Option<&VirtqSnapshot> {
770        self.state.virtq.as_ref()
771    }
772
773    /// Guest virtual address of the guest binary's ELF entry point,
774    /// preserved across the `Initialise` -> `Call` transition. Used
775    /// to fill `AT_ENTRY` in guest core dumps. 0 if unknown.
776    pub(crate) fn original_entrypoint(&self) -> u64 {
777        self.state.original_entrypoint
778    }
779
780    /// Validate that `provided` is a superset of the host functions
781    /// recorded in this snapshot: every function that was registered
782    /// at snapshot time must also be present in `provided` with a
783    /// matching signature. Extras in `provided` are allowed.
784    ///
785    /// A snapshot with no recorded host functions (e.g. one
786    /// produced by a test-only constructor) accepts any `provided`
787    /// set.
788    pub(crate) fn validate_host_functions(
789        &self,
790        provided: &crate::sandbox::host_funcs::FunctionRegistry,
791    ) -> Result<()> {
792        let required = match &self.state.host_functions.host_functions {
793            Some(v) => v,
794            None => return Ok(()),
795        };
796        if required.is_empty() {
797            return Ok(());
798        }
799
800        let mut missing: Vec<String> = Vec::new();
801        let mut signature_mismatches: Vec<String> = Vec::new();
802
803        for req in required {
804            match provided.function_signature(&req.function_name) {
805                // Function name is absent from the provided registry.
806                None => missing.push(req.function_name.clone()),
807                // Function exists, but signature does not match.
808                Some((found_parameter_types, found_return_type))
809                    if {
810                        let params_match = match req.parameter_types.as_deref() {
811                            Some(params) => params == found_parameter_types,
812                            None => found_parameter_types.is_empty(),
813                        };
814                        !params_match || req.return_type != found_return_type
815                    } =>
816                {
817                    signature_mismatches.push(format!(
818                        "{}: snapshot has {:?} -> {:?}, registered {:?} -> {:?}",
819                        req.function_name,
820                        req.parameter_types,
821                        req.return_type,
822                        Some(found_parameter_types.to_vec()),
823                        found_return_type,
824                    ));
825                }
826                // Function exists and signature matches.
827                Some(_) => {}
828            }
829        }
830
831        if missing.is_empty() && signature_mismatches.is_empty() {
832            return Ok(());
833        }
834
835        Err(crate::HyperlightError::SnapshotHostFunctionMismatch {
836            missing,
837            signature_mismatches,
838        })
839    }
840}
841
842#[cfg(test)]
843mod tests {
844    use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
845    use hyperlight_common::vmem::{self, BasicMapping, Mapping, MappingKind, PAGE_SIZE};
846
847    use crate::hypervisor::regs::CommonSpecialRegisters;
848    use crate::mem::exe::LoadInfo;
849    use crate::mem::layout::SandboxMemoryLayout;
850    use crate::mem::mgr::{GuestPageTableBuffer, SandboxMemoryManager, SnapshotSharedMemory};
851    use crate::mem::shared_mem::{
852        ExclusiveSharedMemory, HostSharedMemory, ReadonlySharedMemory, SharedMemory,
853    };
854
855    fn default_sregs() -> CommonSpecialRegisters {
856        CommonSpecialRegisters::default()
857    }
858
859    fn simple_pt_base() -> usize {
860        page_size::get() + SandboxMemoryLayout::BASE_ADDRESS
861    }
862
863    fn make_simple_pt_mem(contents: &[u8]) -> SnapshotSharedMemory<ExclusiveSharedMemory> {
864        let pt_buf = GuestPageTableBuffer::new(simple_pt_base());
865        let mapping = Mapping {
866            phys_base: SandboxMemoryLayout::BASE_ADDRESS as u64,
867            virt_base: SandboxMemoryLayout::BASE_ADDRESS as u64,
868            len: page_size::get() as u64,
869            kind: MappingKind::Basic(BasicMapping {
870                readable: true,
871                writable: true,
872                executable: true,
873            }),
874        };
875        unsafe { vmem::map(&pt_buf, mapping) };
876        super::map_specials(&pt_buf, PAGE_SIZE);
877        let pt_bytes = pt_buf.into_bytes();
878
879        let mut snapshot_mem = vec![0u8; page_size::get() + pt_bytes.len()];
880        snapshot_mem[0..page_size::get()].copy_from_slice(contents);
881        snapshot_mem[page_size::get()..].copy_from_slice(&pt_bytes);
882        ReadonlySharedMemory::from_bytes(&snapshot_mem, page_size::get())
883            .unwrap()
884            .to_mgr_snapshot_mem()
885            .unwrap()
886    }
887
888    fn make_simple_pt_mgr() -> (SandboxMemoryManager<HostSharedMemory>, u64) {
889        let cfg = crate::sandbox::SandboxConfiguration::default();
890        let scratch_mem = ExclusiveSharedMemory::new(cfg.get_scratch_size()).unwrap();
891        let mgr = SandboxMemoryManager::new(
892            SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap(),
893            make_simple_pt_mem(&vec![0u8; page_size::get()]),
894            scratch_mem,
895            super::NextAction::None,
896        );
897        let (mgr, _) = mgr.build().unwrap();
898        (mgr, simple_pt_base() as u64)
899    }
900
901    #[test]
902    fn multiple_snapshots_independent() {
903        let (mut mgr, pt_base) = make_simple_pt_mgr();
904
905        // Create first snapshot with pattern A
906        let pattern_a = vec![0xAA; page_size::get()];
907        let snapshot_a = super::Snapshot::new(
908            &mut make_simple_pt_mem(&pattern_a).build().0,
909            &mut mgr.scratch_mem,
910            mgr.layout,
911            LoadInfo::dummy(),
912            Vec::new(),
913            &[pt_base],
914            0,
915            default_sregs(),
916            #[cfg(target_arch = "x86_64")]
917            Vec::new(),
918            super::NextAction::None,
919            0,
920            1,
921            HostFunctionDetails::default(),
922            None,
923        )
924        .unwrap();
925
926        // Create second snapshot with pattern B
927        let pattern_b = vec![0xBB; page_size::get()];
928        let snapshot_b = super::Snapshot::new(
929            &mut make_simple_pt_mem(&pattern_b).build().0,
930            &mut mgr.scratch_mem,
931            mgr.layout,
932            LoadInfo::dummy(),
933            Vec::new(),
934            &[pt_base],
935            0,
936            default_sregs(),
937            #[cfg(target_arch = "x86_64")]
938            Vec::new(),
939            super::NextAction::None,
940            0,
941            2,
942            HostFunctionDetails::default(),
943            None,
944        )
945        .unwrap();
946
947        // Restore snapshot A
948        mgr.restore_snapshot(&snapshot_a).unwrap();
949        mgr.shared_mem
950            .with_contents(|contents| assert_eq!(&contents[0..pattern_a.len()], &pattern_a[..]))
951            .unwrap();
952
953        // Restore snapshot B
954        mgr.restore_snapshot(&snapshot_b).unwrap();
955        mgr.shared_mem
956            .with_contents(|contents| assert_eq!(&contents[0..pattern_b.len()], &pattern_b[..]))
957            .unwrap();
958    }
959}