Snapshot persistence to disk

Save snapshots to disk via Snapshot::to_file(), load them back via
Snapshot::from_file(). Create sandboxes directly from loaded snapshots via
MultiUseSandbox::from_snapshot(), bypassing ELF parsing and guest init.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Author: ludfjig

src/hyperlight_host/benches/benchmarks.rs

@@ -556,6 +556,93 @@ fn shared_memory_benchmark(c: &mut Criterion) {
     group.finish();
 }
 
+// ============================================================================
+// Benchmark Category: Snapshot Files
+// ============================================================================
+
+fn snapshot_file_benchmark(c: &mut Criterion) {
+    use hyperlight_host::sandbox::snapshot::Snapshot;
+
+    let mut group = c.benchmark_group("snapshot_files");
+
+    // Pre-create snapshot files for all sizes
+    let dirs: Vec<_> = SandboxSize::all()
+        .iter()
+        .map(|size| {
+            let dir = tempfile::tempdir().unwrap();
+            let snap_path = dir.path().join(format!("{}.hls", size.name()));
+            let snapshot = {
+                let mut sbox = create_multiuse_sandbox_with_size(*size);
+                sbox.snapshot().unwrap()
+            };
+            snapshot.to_file(&snap_path).unwrap();
+            (dir, snapshot)
+        })
+        .collect();
+
+    // Benchmark: save_snapshot
+    for (i, size) in SandboxSize::all().iter().enumerate() {
+        let snap_dir = tempfile::tempdir().unwrap();
+        let path = snap_dir.path().join("bench.hls");
+        let snapshot = &dirs[i].1;
+        group.bench_function(format!("save_snapshot/{}", size.name()), |b| {
+            b.iter(|| {
+                snapshot.to_file(&path).unwrap();
+            });
+        });
+    }
+
+    // Benchmark: load_snapshot (mmap + header parse + hash verify)
+    for (i, size) in SandboxSize::all().iter().enumerate() {
+        let snap_path = dirs[i].0.path().join(format!("{}.hls", size.name()));
+        group.bench_function(format!("load_snapshot/{}", size.name()), |b| {
+            b.iter(|| {
+                let _ = Snapshot::from_file(&snap_path).unwrap();
+            });
+        });
+    }
+
+    // Benchmark: cold_start_via_evolve (new + evolve + call)
+    for size in SandboxSize::all() {
+        group.bench_function(format!("cold_start_via_evolve/{}", size.name()), |b| {
+            b.iter(|| {
+                let mut sbox = create_multiuse_sandbox_with_size(size);
+                sbox.call::<String>("Echo", "hello\n".to_string()).unwrap();
+            });
+        });
+    }
+
+    // Benchmark: cold_start_via_snapshot (load + from_snapshot + call)
+    for (i, size) in SandboxSize::all().iter().enumerate() {
+        let snap_path = dirs[i].0.path().join(format!("{}.hls", size.name()));
+        group.bench_function(format!("cold_start_via_snapshot/{}", size.name()), |b| {
+            b.iter(|| {
+                let loaded = Snapshot::from_file(&snap_path).unwrap();
+                let mut sbox = MultiUseSandbox::from_snapshot(std::sync::Arc::new(loaded)).unwrap();
+                sbox.call::<String>("Echo", "hello\n".to_string()).unwrap();
+            });
+        });
+    }
+
+    // Benchmark: cold_start_via_snapshot_unchecked (no hash verify)
+    for (i, size) in SandboxSize::all().iter().enumerate() {
+        let snap_path = dirs[i].0.path().join(format!("{}.hls", size.name()));
+        group.bench_function(
+            format!("cold_start_via_snapshot_unchecked/{}", size.name()),
+            |b| {
+                b.iter(|| {
+                    let loaded = Snapshot::from_file_unchecked(&snap_path).unwrap();
+                    let mut sbox =
+                        MultiUseSandbox::from_snapshot(std::sync::Arc::new(loaded)).unwrap();
+                    sbox.call::<String>("Echo", "hello\n".to_string()).unwrap();
+                });
+            },
+        );
+    }
+
+    group.finish();
+}
+
 criterion_group! {
     name = benches;
     config = Criterion::default();
@@ -566,6 +653,7 @@ criterion_group! {
         guest_call_benchmark_large_param,
         function_call_serialization_benchmark,
         sample_workloads_benchmark,
-        shared_memory_benchmark
+        shared_memory_benchmark,
+        snapshot_file_benchmark
 }
 criterion_main!(benches);

src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs

@@ -352,6 +352,17 @@ impl HyperlightVm {
         self.vm.set_debug_regs(&CommonDebugRegs::default())?;
         self.vm.reset_xsave()?;
 
+        self.apply_sregs(cr3, sregs)
+    }
+
+    /// Apply special registers and mark TLB for flush. Used by both
+    /// `reset_vcpu` (which also resets GPRs/debug/FPU) and
+    /// `from_snapshot` (which skips the redundant resets).
+    pub(crate) fn apply_sregs(
+        &mut self,
+        cr3: u64,
+        sregs: &CommonSpecialRegisters,
+    ) -> std::result::Result<(), RegisterError> {
         #[cfg(not(feature = "nanvix-unstable"))]
         {
             // Restore the full special registers from snapshot, but update CR3

src/hyperlight_host/src/mem/layout.rs

@@ -225,16 +225,16 @@ pub(crate) struct SandboxMemoryLayout {
     /// The size of the guest code section.
     pub(crate) code_size: usize,
     /// The size of the init data section (guest blob).
-    init_data_size: usize,
+    pub(crate) init_data_size: usize,
     /// Permission flags for the init data region.
     #[cfg_attr(feature = "nanvix-unstable", allow(unused))]
-    init_data_permissions: Option<MemoryRegionFlags>,
+    pub(crate) init_data_permissions: Option<MemoryRegionFlags>,
     /// The size of the scratch region in physical memory.
-    scratch_size: usize,
+    pub(crate) scratch_size: usize,
     /// The size of the snapshot region in physical memory.
-    snapshot_size: usize,
+    pub(crate) snapshot_size: usize,
     /// The size of the page tables (None if not yet set).
-    pt_size: Option<usize>,
+    pub(crate) pt_size: Option<usize>,
 }
 
 impl SandboxMemoryLayout {
@@ -394,12 +394,6 @@ impl SandboxMemoryLayout {
         self.peb_file_mappings_offset()
     }
 
-    /// Get the offset in guest memory to the file_mappings pointer field.
-    #[cfg(feature = "nanvix-unstable")]
-    fn get_file_mappings_pointer_offset(&self) -> usize {
-        self.get_file_mappings_size_offset() + size_of::<u64>()
-    }
-
     /// Get the offset in snapshot memory where the FileMappingInfo array starts
     /// (immediately after the PEB struct, within the same page).
     #[cfg(feature = "nanvix-unstable")]

src/hyperlight_host/src/mem/memory_region.rs

@@ -158,7 +158,9 @@ impl MemoryRegionType {
     /// shared memory mapping with guard pages.
     pub fn surrogate_mapping(&self) -> SurrogateMapping {
         match self {
-            MemoryRegionType::MappedFile => SurrogateMapping::ReadOnlyFile,
+            MemoryRegionType::MappedFile | MemoryRegionType::Snapshot => {
+                SurrogateMapping::ReadOnlyFile
+            }
             _ => SurrogateMapping::SandboxMemory,
         }
     }

src/hyperlight_host/src/mem/shared_mem.rs

@@ -2029,6 +2029,221 @@ impl ReadonlySharedMemory {
         })
     }
 
+    /// Create a `ReadonlySharedMemory` backed by a file on disk.
+    ///
+    /// The memory blob at `[offset..offset+len)` in the file is mapped
+    /// with copy-on-write semantics so that guest writes trigger
+    /// per-page CoW faults without modifying the backing file.
+    ///
+    /// The mapping is surrounded by guard pages, matching the
+    /// `ExclusiveSharedMemory::new` layout, so that `base_ptr()` and
+    /// `mem_size()` return the correct values via the `SharedMemory`
+    /// trait.
+    ///
+    /// - **Linux**: `mmap(MAP_PRIVATE)` for zero-copy file-backed CoW.
+    /// - **Windows**: `CreateFileMappingA(PAGE_WRITECOPY)` +
+    ///   `MapViewOfFile(FILE_MAP_COPY)` for zero-copy file-backed CoW.
+    ///   The returned `HostMapping` carries the file mapping handle so
+    ///   the surrogate process can create its own view via
+    ///   `MapViewOfFileNuma2`.
+    pub(crate) fn from_file(file: &std::fs::File, offset: u64, len: usize) -> Result<Self> {
+        if len == 0 {
+            return Err(new_error!(
+                "Cannot create file-backed shared memory with size 0"
+            ));
+        }
+
+        let total_size = len.checked_add(2 * PAGE_SIZE_USIZE).ok_or_else(|| {
+            new_error!("Memory required for file-backed snapshot exceeded usize::MAX")
+        })?;
+
+        #[cfg(target_os = "linux")]
+        {
+            Self::from_file_linux(file, offset, len, total_size)
+        }
+        #[cfg(target_os = "windows")]
+        {
+            // The Windows path maps the entire file from offset 0 and uses
+            // the header page as the leading guard page. This requires the
+            // memory blob to start at exactly PAGE_SIZE.
+            if offset as usize != PAGE_SIZE_USIZE {
+                return Err(new_error!(
+                    "Windows from_file requires offset == PAGE_SIZE, got {}",
+                    offset
+                ));
+            }
+            Self::from_file_windows(file, total_size)
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    fn from_file_linux(
+        file: &std::fs::File,
+        offset: u64,
+        len: usize,
+        total_size: usize,
+    ) -> Result<Self> {
+        use std::ffi::c_void;
+        use std::os::unix::io::AsRawFd;
+
+        use libc::{
+            MAP_ANONYMOUS, MAP_FAILED, MAP_FIXED, MAP_NORESERVE, MAP_PRIVATE, PROT_NONE, PROT_READ,
+            PROT_WRITE, mmap, off_t, size_t,
+        };
+
+        let fd = file.as_raw_fd();
+        let offset: off_t = offset
+            .try_into()
+            .map_err(|_| new_error!("snapshot file offset {} exceeds off_t range", offset))?;
+
+        // Allocate the full region (guard + usable + guard) as anonymous
+        let base = unsafe {
+            mmap(
+                null_mut(),
+                total_size as size_t,
+                PROT_NONE,
+                MAP_ANONYMOUS | MAP_PRIVATE | MAP_NORESERVE,
+                -1,
+                0 as off_t,
+            )
+        };
+        if base == MAP_FAILED {
+            return Err(HyperlightError::MmapFailed(
+                std::io::Error::last_os_error().raw_os_error(),
+            ));
+        }
+
+        // Map the file content over the usable portion (between guard pages).
+        // PROT_READ | PROT_WRITE: KVM/MSHV require writable host mappings
+        // to handle copy-on-write page faults from the guest.
+        // MAP_PRIVATE: writes go to private copies, not the file.
+        let usable_ptr = unsafe { (base as *mut u8).add(PAGE_SIZE_USIZE) };
+        let mapped = unsafe {
+            mmap(
+                usable_ptr as *mut c_void,
+                len as size_t,
+                PROT_READ | PROT_WRITE,
+                MAP_PRIVATE | MAP_FIXED | MAP_NORESERVE,
+                fd,
+                offset,
+            )
+        };
+        if mapped == MAP_FAILED {
+            unsafe { libc::munmap(base, total_size as size_t) };
+            return Err(HyperlightError::MmapFailed(
+                std::io::Error::last_os_error().raw_os_error(),
+            ));
+        }
+
+        // Guard pages at base and base+total_size-PAGE_SIZE are already
+        // PROT_NONE from the anonymous mapping; MAP_FIXED only replaced
+        // the middle portion.
+
+        #[allow(clippy::arc_with_non_send_sync)]
+        Ok(ReadonlySharedMemory {
+            region: Arc::new(HostMapping {
+                ptr: base as *mut u8,
+                size: total_size,
+            }),
+        })
+    }
+
+    /// Windows implementation of file-backed read-only shared memory.
+    ///
+    /// The snapshot file layout is:
+    /// `[header (PAGE_SIZE)][memory blob][trailing padding (PAGE_SIZE)]`.
+    /// We create a read-only file mapping covering the entire file and
+    /// map a view of `len + 2*PAGE_SIZE` bytes starting at file offset 0.
+    /// The header becomes the leading guard page and the trailing padding
+    /// becomes the trailing guard page, both via
+    /// `VirtualProtect(PAGE_NOACCESS)`.  This gives the standard
+    /// `HostMapping` layout: `[guard | usable | guard]`.
+    #[cfg(target_os = "windows")]
+    fn from_file_windows(file: &std::fs::File, total_size: usize) -> Result<Self> {
+        use std::os::windows::io::AsRawHandle;
+
+        use windows::Win32::Foundation::HANDLE;
+        use windows::Win32::System::Memory::{
+            CreateFileMappingA, FILE_MAP_READ, MapViewOfFile, PAGE_NOACCESS, PAGE_PROTECTION_FLAGS,
+            PAGE_READONLY, VirtualProtect,
+        };
+        use windows::core::PCSTR;
+
+        let file_handle = HANDLE(file.as_raw_handle());
+
+        // Create a read-only file mapping at the exact file size (pass 0,0).
+        // The file includes trailing PAGE_SIZE padding written by to_file(),
+        // so the file is at least offset + len + PAGE_SIZE = total_size bytes.
+        let handle =
+            unsafe { CreateFileMappingA(file_handle, None, PAGE_READONLY, 0, 0, PCSTR::null())? };
+
+        if handle.is_invalid() {
+            log_then_return!(HyperlightError::MemoryAllocationFailed(
+                Error::last_os_error().raw_os_error()
+            ));
+        }
+
+        // Map exactly total_size (header + blob + trailing padding) bytes.
+        let addr = unsafe { MapViewOfFile(handle, FILE_MAP_READ, 0, 0, total_size) };
+        if addr.Value.is_null() {
+            unsafe {
+                let _ = windows::Win32::Foundation::CloseHandle(handle);
+            }
+            log_then_return!(HyperlightError::MemoryAllocationFailed(
+                Error::last_os_error().raw_os_error()
+            ));
+        }
+
+        let cleanup = |ptr: *mut c_void, handle: windows::Win32::Foundation::HANDLE| unsafe {
+            if let Err(e) = windows::Win32::System::Memory::UnmapViewOfFile(
+                windows::Win32::System::Memory::MEMORY_MAPPED_VIEW_ADDRESS { Value: ptr },
+            ) {
+                tracing::error!("from_file_windows cleanup: UnmapViewOfFile failed: {:?}", e);
+            }
+            if let Err(e) = windows::Win32::Foundation::CloseHandle(handle) {
+                tracing::error!("from_file_windows cleanup: CloseHandle failed: {:?}", e);
+            }
+        };
+
+        // Set guard pages on both ends.
+        let mut unused_old_prot = PAGE_PROTECTION_FLAGS(0);
+
+        let first_guard = addr.Value;
+        if let Err(e) = unsafe {
+            VirtualProtect(
+                first_guard,
+                PAGE_SIZE_USIZE,
+                PAGE_NOACCESS,
+                &mut unused_old_prot,
+            )
+        } {
+            cleanup(addr.Value, handle);
+            log_then_return!(WindowsAPIError(e.clone()));
+        }
+
+        let last_guard = unsafe { first_guard.add(total_size - PAGE_SIZE_USIZE) };
+        if let Err(e) = unsafe {
+            VirtualProtect(
+                last_guard,
+                PAGE_SIZE_USIZE,
+                PAGE_NOACCESS,
+                &mut unused_old_prot,
+            )
+        } {
+            cleanup(addr.Value, handle);
+            log_then_return!(WindowsAPIError(e.clone()));
+        }
+
+        #[allow(clippy::arc_with_non_send_sync)]
+        Ok(ReadonlySharedMemory {
+            region: Arc::new(HostMapping {
+                ptr: addr.Value as *mut u8,
+                size: total_size,
+                handle,
+            }),
+        })
+    }
+
     pub(crate) fn as_slice(&self) -> &[u8] {
         unsafe { std::slice::from_raw_parts(self.base_ptr(), self.mem_size()) }
     }