Skip to main content

hyperlight_host/sandbox/
initialized.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4use std::collections::BTreeSet;
5use std::path::Path;
6#[cfg(crashdump)]
7use std::path::PathBuf;
8use std::sync::{Arc, Mutex};
9
10use hyperlight_common::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
11use hyperlight_common::flatbuffer_wrappers::function_types::{
12    ParameterValue, ReturnType, ReturnValue,
13};
14use tracing::{Span, instrument};
15use tracing_core::LevelFilter;
16
17use super::Callable;
18use super::file_mapping::prepare_file_cow;
19use super::host_funcs::FunctionRegistry;
20use super::snapshot::{Snapshot, SnapshotOptions};
21use crate::func::{ParameterTuple, SupportedReturnType};
22use crate::hypervisor::InterruptHandle;
23use crate::hypervisor::hyperlight_vm::{HyperlightVm, HyperlightVmError};
24use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags};
25use crate::mem::mgr::{ExecutionMode, SandboxMemoryManager};
26use crate::mem::shared_mem::{HostSharedMemory, SharedMemory as _};
27use crate::metrics::{
28    METRIC_GUEST_ERROR, METRIC_GUEST_ERROR_LABEL_CODE, maybe_time_and_emit_guest_call,
29};
30use crate::sandbox::snapshot::SnapshotMemoryBacking;
31use crate::{HyperlightError, Result, log_then_return};
32
33/// The lifecycle state of a [`Sandbox`].
34#[derive(Clone, Copy, Debug, Eq, PartialEq)]
35pub enum SandboxStatus {
36    /// The sandbox can execute guest operations.
37    Ready,
38    /// The sandbox requires a successful restore before further use.
39    Poisoned,
40    /// The sandbox cannot be used and must be discarded.
41    Unrecoverable,
42}
43
44impl SandboxStatus {
45    /// Returns whether the sandbox can execute guest operations.
46    pub const fn is_ready(self) -> bool {
47        matches!(self, Self::Ready)
48    }
49
50    /// Returns whether the sandbox requires a successful restore.
51    pub const fn is_poisoned(self) -> bool {
52        matches!(self, Self::Poisoned)
53    }
54
55    /// Returns whether the sandbox must be discarded.
56    pub const fn is_unrecoverable(self) -> bool {
57        matches!(self, Self::Unrecoverable)
58    }
59}
60
61/// A fully initialized sandbox that can execute guest function calls.
62///
63/// Guest functions can be called repeatedly while maintaining state between calls.
64/// The sandbox supports creating snapshots and restoring to previous states.
65///
66/// ## Sandbox status
67///
68/// The sandbox becomes [`Poisoned`](SandboxStatus::Poisoned) when guest
69/// execution does not complete normally. Causes include guest panics or aborts,
70/// invalid memory access, stack overflow, heap exhaustion, and cancellation
71/// through [`InterruptHandle::kill()`]. Interrupted execution can leak
72/// allocations, corrupt allocator metadata, leave resources locked, or partially
73/// update state.
74///
75/// Use [`restore()`](Self::restore) with a snapshot taken before the interrupted
76/// execution to make a poisoned sandbox ready again. Restore reinstates the
77/// captured memory and vCPU state and removes dynamic mappings.
78///
79/// A restore failure that prevents Hyperlight from establishing valid base
80/// memory mappings can leave the sandbox
81/// [`Unrecoverable`](SandboxStatus::Unrecoverable). Further restore attempts and
82/// guest operations are rejected. The sandbox must be discarded.
83pub struct Sandbox {
84    status: SandboxStatus,
85    pub(crate) host_funcs: Arc<Mutex<FunctionRegistry>>,
86    pub(crate) mem_mgr: SandboxMemoryManager<HostSharedMemory>,
87    vm: HyperlightVm,
88    /// If the current state of the sandbox has been captured in a snapshot,
89    /// that snapshot is stored here.
90    pub(crate) snapshot: Option<Arc<Snapshot>>,
91    /// Whether the transport needs a checkpoint before snapshot capture.
92    transport_dirty: bool,
93    /// Optional callback to discover page table roots from guest memory.
94    /// Given (snapshot_mem, scratch_mem, cr3), returns a list of root GPAs.
95    /// If not set, only CR3 is used as the single root.
96    pt_root_finder: Option<PtRootFinder>,
97    /// Runtime guest log-level override reapplied after snapshot restores.
98    max_guest_log_level: Option<LevelFilter>,
99}
100
101/// Deprecated name for [`Sandbox`].
102#[deprecated(since = "0.18.0", note = "use Sandbox")]
103pub type MultiUseSandbox = Sandbox;
104
105/// Read-only access to live snapshot memory by guest physical address.
106pub struct SnapshotMemoryReader<'a> {
107    memory: &'a SnapshotMemoryBacking<HostSharedMemory>,
108}
109
110impl SnapshotMemoryReader<'_> {
111    /// Copy live snapshot bytes at `gpa` into `destination`.
112    pub fn read_exact(&self, gpa: u64, destination: &mut [u8]) -> Result<()> {
113        self.memory.read_snapshot_gpa(gpa, destination)
114    }
115}
116
117/// Callback for discovering page table roots from guest memory.
118///
119/// Called during [`Sandbox::snapshot`] with:
120/// - `snapshot_mem` - live snapshot memory accessed by GPA
121/// - `scratch_mem` - the sandbox's scratch memory as a byte slice
122/// - `root_pt_gpa` - the root page table GPA of the currently-executing
123///   address space
124///
125/// Returns additional root page table GPAs to walk. `root_pt_gpa` is always
126/// walked first, ignoring duplicates. An error aborts the capture.
127pub type PtRootFinder =
128    Box<dyn Fn(&SnapshotMemoryReader<'_>, &[u8], u64) -> Result<Vec<u64>> + Send>;
129
130fn normalize_page_table_roots(roots: Vec<u64>, active_root: u64) -> Vec<u64> {
131    let mut seen = BTreeSet::from([active_root]);
132    let mut normalized = vec![active_root];
133    normalized.extend(roots.into_iter().filter(|root| seen.insert(*root)));
134    normalized
135}
136
137impl Sandbox {
138    fn check_ready(&self) -> Result<()> {
139        match self.status {
140            SandboxStatus::Ready => Ok(()),
141            SandboxStatus::Poisoned => Err(HyperlightError::PoisonedSandbox),
142            SandboxStatus::Unrecoverable => Err(HyperlightError::UnrecoverableSandbox),
143        }
144    }
145
146    fn poison(&mut self) {
147        if self.status.is_ready() {
148            self.status = SandboxStatus::Poisoned;
149        }
150    }
151
152    /// Move an `UninitializedSandbox` into a new `Sandbox` instance.
153    ///
154    /// This function is not equivalent to doing an `evolve` from uninitialized
155    /// to initialized, and is purposely not exposed publicly outside the crate
156    /// (as a `From` implementation would be)
157    #[instrument(skip_all, parent = Span::current(), level = "Trace")]
158    pub(super) fn from_uninit(
159        host_funcs: Arc<Mutex<FunctionRegistry>>,
160        mgr: SandboxMemoryManager<HostSharedMemory>,
161        vm: HyperlightVm,
162    ) -> Sandbox {
163        // Initialization can log or call the host before the first guest call.
164        let transport_dirty = matches!(mgr.next_action, super::snapshot::NextAction::Initialise(_));
165
166        Self {
167            status: SandboxStatus::Ready,
168            host_funcs,
169            mem_mgr: mgr,
170            vm,
171            snapshot: None,
172            transport_dirty,
173            pt_root_finder: None,
174            max_guest_log_level: None,
175        }
176    }
177
178    /// Sets the maximum log level used by future guest calls.
179    ///
180    /// The setting is reapplied after restoring a snapshot.
181    pub fn log_level(&mut self, log_level: LevelFilter) -> Result<()> {
182        self.check_ready()?;
183        self.mem_mgr.request_guest_log_level_update(log_level)?;
184        self.max_guest_log_level = Some(log_level);
185        Ok(())
186    }
187
188    /// Set a callback that discovers page table roots from guest memory.
189    /// The callback receives (snapshot_mem, scratch_mem, cr3) and returns
190    /// additional root GPAs to walk during snapshot creation.
191    ///
192    /// The callback must support every guest restored into this sandbox.
193    pub fn set_pt_root_finder(&mut self, finder: PtRootFinder) {
194        self.pt_root_finder = Some(finder);
195    }
196
197    /// Create a `Sandbox` directly from a [`Snapshot`],
198    /// bypassing guest binary loading and initialization.
199    ///
200    /// This is useful for fast sandbox creation when a snapshot of
201    /// an already-initialized guest is available, either saved to disk
202    /// or captured in memory from another sandbox.
203    ///
204    /// The provided [`HostFunctions`] must include every host function
205    /// that was registered on the sandbox at the time the snapshot was
206    /// taken (matched by name and signature). Additional host functions
207    /// not present in the snapshot are allowed. A mismatch returns
208    /// [`SnapshotHostFunctionMismatch`](crate::HyperlightError::SnapshotHostFunctionMismatch)
209    /// carrying the missing names and signature differences.
210    ///
211    /// An optional [`SandboxConfiguration`](crate::sandbox::SandboxConfiguration)
212    /// can be supplied to override runtime settings such as timeouts and
213    /// interrupt behavior. Memory layout fields and transport geometry are
214    /// always taken from the snapshot. Any values supplied in `config` for
215    /// those fields are ignored. On x86_64 the `config` must
216    /// declare every guest MSR the snapshot was taken with (see
217    /// [`SandboxConfiguration::guest_msrs`](crate::sandbox::SandboxConfiguration::guest_msrs)),
218    /// or the load fails with an MSR mismatch.
219    ///
220    /// [`SandboxConfiguration::set_max_guest_log_level`](crate::sandbox::SandboxConfiguration::set_max_guest_log_level)
221    /// or [`Self::log_level`] sets the maximum log level used by the restored guest. For snapshots
222    /// captured before guest initialization, the level is passed to the guest
223    /// during initialization. For snapshots captured after guest
224    /// initialization, the level is requested through guest memory before the
225    /// next guest call.
226    ///
227    /// # Examples
228    ///
229    /// From a snapshot taken on another sandbox:
230    ///
231    /// ```no_run
232    /// # use std::sync::Arc;
233    /// # use hyperlight_host::{HostFunctions, Sandbox, SandboxBuilder};
234    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
235    /// // Create and initialize a sandbox the normal way
236    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
237    ///
238    /// // Capture a snapshot of the initialized state
239    /// let snapshot = sandbox.snapshot()?;
240    ///
241    /// // Create a new sandbox directly from the snapshot
242    /// let mut sandbox2 = Sandbox::from_snapshot(snapshot, HostFunctions::default(), None)?;
243    /// let result: i32 = sandbox2.call("GetValue", ())?;
244    /// # Ok(())
245    /// # }
246    /// ```
247    ///
248    /// From a snapshot loaded from disk:
249    ///
250    /// ```no_run
251    /// # use std::sync::Arc;
252    /// # use hyperlight_host::{HostFunctions, Sandbox};
253    /// # use hyperlight_host::sandbox::snapshot::{OciTag, Snapshot};
254    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
255    /// let tag = OciTag::new("latest")?;
256    /// let snapshot = Arc::new(Snapshot::load("./guest_snapshot", tag)?);
257    /// let mut sandbox = Sandbox::from_snapshot(snapshot, HostFunctions::default(), None)?;
258    /// let result: String = sandbox.call("Echo", "hello".to_string())?;
259    /// # Ok(())
260    /// # }
261    /// ```
262    #[instrument(err(Debug), skip_all, parent = Span::current(), level = "Trace")]
263    pub fn from_snapshot(
264        snapshot: Arc<Snapshot>,
265        host_funcs: crate::HostFunctions,
266        config: Option<crate::sandbox::SandboxConfiguration>,
267    ) -> Result<Self> {
268        use rand::RngExt;
269
270        use crate::mem::ptr::RawPtr;
271        use crate::sandbox::uninitialized_evolve::set_up_hypervisor_partition;
272
273        // Validate that the provided host functions are a superset of
274        // those required by the snapshot.
275        snapshot.validate_host_functions(host_funcs.inner())?;
276
277        let host_funcs = Arc::new(Mutex::new(host_funcs.into_inner()));
278
279        let stack_top_gva = snapshot.stack_top_gva();
280        // Start from the caller's config (if any) so runtime fields
281        // such as timeouts and interrupt knobs are honored, then
282        // overwrite the layout fields from the snapshot. The on-disk
283        // layout is fixed, so any layout values supplied by the
284        // caller are silently ignored. Warn if the caller passed a
285        // config whose layout fields disagree with the snapshot, so
286        // the override is at least visible.
287        let caller_supplied_config = config.is_some();
288        let mut config = config.unwrap_or_default();
289        if caller_supplied_config {
290            warn_on_layout_override(&config, snapshot.layout());
291        }
292        config.set_scratch_size(snapshot.layout().get_scratch_size());
293        config.set_g2h_queue_size(snapshot.layout().get_g2h_queue_size());
294        config.set_h2g_queue_size(snapshot.layout().get_h2g_queue_size());
295        config.set_g2h_buffer_size(snapshot.layout().get_g2h_buffer_size());
296        config.set_h2g_buffer_size(snapshot.layout().get_h2g_buffer_size());
297        config.set_g2h_pool_pages(snapshot.layout().get_g2h_pool_pages());
298        config.set_h2g_pool_pages(snapshot.layout().get_h2g_pool_pages());
299        let max_guest_log_level = config.get_max_guest_log_level();
300        let load_info = snapshot.load_info();
301
302        let mgr = crate::mem::mgr::SandboxMemoryManager::from_snapshot(&snapshot)?;
303        let (mut hshm, gshm) = mgr.build()?;
304        let restore_virtq = matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_));
305
306        let page_size = u32::try_from(page_size::get())? as usize;
307
308        #[cfg(target_os = "linux")]
309        crate::signal_handlers::setup_signal_handlers(&config)?;
310
311        let mut vm =
312            set_up_hypervisor_partition(gshm, &config, stack_top_gva, page_size, load_info)?;
313
314        let seed = {
315            let mut rng = rand::rng();
316            rng.random::<u64>()
317        };
318        let peb_addr = RawPtr::from(u64::try_from(hshm.layout.peb_address())?);
319
320        // For NextAction::Call, initialise is a no-op. Runtime overrides are
321        // delivered through the scratch-memory request below.
322        vm.initialise(peb_addr, seed, &mut hshm, &host_funcs, max_guest_log_level)
323            .map_err(crate::hypervisor::hyperlight_vm::HyperlightVmError::Initialize)?;
324        if matches!(
325            snapshot.next_action(),
326            super::snapshot::NextAction::Initialise(_)
327        ) {
328            hshm.finish_snapshot_checkpoint()?;
329        }
330
331        if matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_)) {
332            hshm.request_libc_rng_reseed(seed as u32)?;
333        }
334
335        // If the snapshot was taken from an already-initialized guest
336        // (NextAction::Call), apply the captured special registers so
337        // the guest resumes in the correct CPU state.
338        if matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_)) {
339            let sregs = snapshot.sregs().ok_or_else(|| {
340                crate::new_error!("snapshot with NextAction::Call must have captured sregs")
341            })?;
342            #[cfg(target_arch = "x86_64")]
343            let msrs = snapshot.msrs().ok_or_else(|| {
344                crate::new_error!("snapshot with NextAction::Call must have captured MSRs")
345            })?;
346            vm.apply_sregs(hshm.layout.get_pt_base_gpa(), sregs)
347                .map_err(|e| {
348                    crate::HyperlightError::HyperlightVmError(
349                        crate::hypervisor::hyperlight_vm::HyperlightVmError::Restore(e.into()),
350                    )
351                })?;
352
353            // Restore captured MSR state.
354            #[cfg(target_arch = "x86_64")]
355            vm.restore_msrs(msrs).map_err(|e| {
356                crate::HyperlightError::HyperlightVmError(
357                    crate::hypervisor::hyperlight_vm::HyperlightVmError::Restore(e),
358                )
359            })?;
360        }
361
362        if restore_virtq {
363            let virtq = snapshot.virtq().ok_or_else(|| {
364                crate::new_error!("running snapshot has no canonical transport state")
365            })?;
366            hshm.restore_virtq(virtq)?;
367        }
368
369        let mut sbox = Sandbox::from_uninit(host_funcs, hshm, vm);
370
371        if let Some(log_level) = max_guest_log_level {
372            sbox.log_level(log_level)?;
373        }
374
375        Ok(sbox)
376    }
377
378    /// Creates a snapshot of the sandbox's current memory state.
379    ///
380    /// If the sandbox was created from or restored to a snapshot, this capture can
381    /// reuse memory that has not changed. A successful capture becomes the basis
382    /// for later captures. This avoids copying the full sandbox each time, reducing
383    /// capture time and memory use.
384    ///
385    /// Taking another snapshot after changing the sandbox creates a child of the
386    /// previous snapshot. Restoring an earlier snapshot, changing the sandbox, and
387    /// taking another creates a separate branch. Snapshots therefore form a
388    /// conceptual tree of states. Calling this method again without changing the
389    /// sandbox returns the same snapshot.
390    ///
391    /// A snapshot holds at most 30 memory layers. A capture that changes memory adds
392    /// one layer. A layer drops out once later changes replace all of its pages.
393    /// Creating a snapshot fails when it would exceed this limit or finds no room
394    /// for the new layer. This check leaves the sandbox unchanged and ready.
395    ///
396    /// The guest can map any page of a layer, including pages that a later layer
397    /// replaced. A sandbox restored from this snapshot, or from a saved copy, can
398    /// read guest data overwritten before the snapshot. Zeroing a secret does not
399    /// remove it from the snapshot.
400    ///
401    /// Memory added through [`Self::map_region`] and [`Self::map_file_cow`] is
402    /// copied into the snapshot only for pages the guest has mapped into its page
403    /// tables. Capture then removes these regions from this sandbox. Pages the
404    /// guest has not mapped are lost, and their guest physical addresses can be
405    /// reused by later snapshots.
406    ///
407    /// The returned snapshot can be applied to any
408    /// [`Sandbox`] whose registered host functions are a
409    /// superset of those registered here at the time of capture. See
410    /// [`Sandbox::restore`] and
411    /// [`Sandbox::from_snapshot`] for the exact compatibility
412    /// rules and the error variants returned on mismatch.
413    ///
414    /// On x86_64, the snapshot saves a small core of essential CPU state plus
415    /// each MSR declared with
416    /// [`SandboxBuilder::guest_msrs`](crate::SandboxBuilder::guest_msrs).
417    ///
418    /// ## Sandbox status
419    ///
420    /// This method returns [`crate::HyperlightError::PoisonedSandbox`] when the
421    /// sandbox is poisoned and [`crate::HyperlightError::UnrecoverableSandbox`]
422    /// when it is unrecoverable. An unexpected hypervisor or platform error during
423    /// capture may leave the sandbox poisoned or unrecoverable.
424    ///
425    /// # Examples
426    ///
427    /// ```no_run
428    /// # use hyperlight_host::SandboxBuilder;
429    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
430    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
431    ///
432    /// // Modify sandbox state
433    /// sandbox.call_guest_function_by_name::<i32>("SetValue", 42)?;
434    ///
435    /// // Capture a snapshot of the current memory state
436    /// let snapshot = sandbox.snapshot()?;
437    /// # Ok(())
438    /// # }
439    /// ```
440    pub fn snapshot(&mut self) -> Result<Arc<Snapshot>> {
441        self.snapshot_with_options(&SnapshotOptions::default())
442    }
443
444    /// Like [`Self::snapshot`], with [`SnapshotOptions`] for how the
445    /// snapshot restores. Default options take the same snapshot as
446    /// [`Self::snapshot`]. The sandbox continues from the captured snapshot,
447    /// with its scratch size. It returns the same sandbox status errors as
448    /// [`Self::snapshot`].
449    ///
450    /// # Examples
451    ///
452    /// ```no_run
453    /// # use hyperlight_host::SandboxBuilder;
454    /// # use hyperlight_host::sandbox::snapshot::SnapshotOptions;
455    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
456    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
457    ///
458    /// // Run later guest function calls with 4 MiB of scratch.
459    /// let options = SnapshotOptions::default().scratch_size(4 << 20);
460    /// let snapshot = sandbox.snapshot_with_options(&options)?;
461    /// sandbox.restore(snapshot)?;
462    /// # Ok(())
463    /// # }
464    /// ```
465    #[instrument(err(Debug), skip_all, parent = Span::current())]
466    pub fn snapshot_with_options(&mut self, options: &SnapshotOptions) -> Result<Arc<Snapshot>> {
467        self.check_ready()?;
468        // Unpacked in full so that a new option has to decide whether the
469        // cached plain snapshot still answers it.
470        let SnapshotOptions { scratch_size } = options;
471        let current = self.mem_mgr.layout.get_scratch_size();
472        let scratch_size = scratch_size.unwrap_or(current);
473
474        if scratch_size == current {
475            if let Some(snapshot) = &self.snapshot {
476                return Ok(snapshot.clone());
477            }
478            return self.capture_snapshot(scratch_size);
479        }
480
481        // Reject a bad size before the capture enters the guest.
482        self.mem_mgr.layout.with_scratch_size(scratch_size)?;
483        self.capture_snapshot(scratch_size)
484    }
485
486    /// Capture a snapshot whose scratch has `scratch_size` bytes. The sandbox
487    /// continues from it.
488    fn capture_snapshot(&mut self, scratch_size: usize) -> Result<Arc<Snapshot>> {
489        if self.transport_dirty {
490            self.checkpoint_transport_for_snapshot()?;
491        }
492
493        let mapped_regions_iter = self.vm.get_mapped_regions();
494        let mapped_regions_vec: Vec<MemoryRegion> = mapped_regions_iter.cloned().collect();
495        // Get CR3 from the vCPU
496        let cr3 = self
497            .vm
498            .get_root_pt()
499            .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
500        // Use the callback if set, otherwise just CR3
501        let root_pt_gpas = if let Some(finder) = &self.pt_root_finder {
502            let snapshot = SnapshotMemoryReader {
503                memory: &self.mem_mgr.shared_mem,
504            };
505            let roots = self
506                .mem_mgr
507                .scratch_mem
508                .with_contents(|scratch| finder(&snapshot, scratch, cr3))??;
509            normalize_page_table_roots(roots, cr3)
510        } else {
511            vec![cr3]
512        };
513
514        let stack_top_gpa = self.vm.get_stack_top();
515        let sregs = self
516            .vm
517            .get_snapshot_sregs()
518            .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
519        #[cfg(target_arch = "x86_64")]
520        let msrs = self
521            .vm
522            .get_msr_reset_state()
523            .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
524        let next_action = self.vm.get_next_action();
525        let host_functions = (&*self.host_funcs.try_lock().map_err(|e| {
526            crate::new_error!("Error locking host_funcs at {}:{}: {}", file!(), line!(), e)
527        })?)
528            .into();
529
530        let memory_snapshot = self.mem_mgr.snapshot(
531            mapped_regions_vec,
532            &root_pt_gpas,
533            stack_top_gpa,
534            sregs,
535            #[cfg(target_arch = "x86_64")]
536            msrs,
537            next_action,
538            host_functions,
539            scratch_size,
540        )?;
541        let snapshot = Arc::new(memory_snapshot);
542
543        if let Err(error) = self.remove_dynamic_mappings() {
544            self.status = SandboxStatus::Poisoned;
545            self.snapshot = None;
546            return Err(error);
547        }
548        let (snapshot_mem, scratch_mem) = match self.mem_mgr.install_captured_snapshot(&snapshot) {
549            Ok(memory) => memory,
550            Err(error) => {
551                self.status = SandboxStatus::Unrecoverable;
552                self.snapshot = None;
553                return Err(error);
554            }
555        };
556        if let Err(error) = self.vm.update_snapshot_mapping(snapshot_mem) {
557            self.status = SandboxStatus::Unrecoverable;
558            self.snapshot = None;
559            return Err(HyperlightVmError::UpdateRegion(error).into());
560        }
561        if let Some(scratch_mem) = scratch_mem
562            && let Err(error) = self.vm.update_scratch_mapping(scratch_mem)
563        {
564            self.status = SandboxStatus::Unrecoverable;
565            self.snapshot = None;
566            return Err(HyperlightVmError::UpdateRegion(error).into());
567        }
568        if let Err(error) = self.vm.apply_sregs(snapshot.root_pt_gpa(), &sregs) {
569            self.status = SandboxStatus::Poisoned;
570            self.snapshot = None;
571            return Err(HyperlightVmError::Restore(error.into()).into());
572        }
573
574        self.snapshot = Some(snapshot.clone());
575        Ok(snapshot)
576    }
577
578    fn checkpoint_transport_for_snapshot(&mut self) -> Result<()> {
579        self.with_guest_execution(|sbox| {
580            sbox.mem_mgr.begin_snapshot_checkpoint()?;
581            sbox.dispatch_guest_call_restricted()?;
582
583            sbox.mem_mgr.finish_snapshot_checkpoint()?;
584
585            sbox.transport_dirty = false;
586            Ok(())
587        })
588    }
589
590    fn remove_dynamic_mappings(&mut self) -> Result<()> {
591        let regions = self.vm.get_mapped_regions().cloned().collect::<Vec<_>>();
592        for region in &regions {
593            self.vm
594                .unmap_region(region)
595                .map_err(HyperlightVmError::UnmapRegion)?;
596        }
597        Ok(())
598    }
599
600    fn restore_memory_and_mappings(&mut self, snapshot: &Snapshot) -> Result<()> {
601        let (snapshot_mem, scratch_mem) = self.mem_mgr.restore_snapshot(snapshot)?;
602        self.vm
603            .update_snapshot_mapping(snapshot_mem)
604            .map_err(HyperlightVmError::UpdateRegion)?;
605        if let Some(scratch_mem) = scratch_mem {
606            self.vm
607                .update_scratch_mapping(scratch_mem)
608                .map_err(HyperlightVmError::UpdateRegion)?;
609        }
610        Ok(())
611    }
612
613    /// Restores the sandbox's memory to a previously captured snapshot state.
614    ///
615    /// The sandbox's registered host functions must be a superset of
616    /// those required by the snapshot (matched by name and
617    /// signature). Extras on the sandbox are allowed. The registry
618    /// itself is left unchanged. A mismatch returns
619    /// [`SnapshotHostFunctionMismatch`](crate::HyperlightError::SnapshotHostFunctionMismatch)
620    /// carrying the missing names and signature differences.
621    ///
622    /// On x86_64, this restores the MSR state captured by
623    /// [`Sandbox::snapshot`]:
624    /// [`SandboxBuilder::guest_msrs`](crate::SandboxBuilder::guest_msrs)
625    /// selects which MSRs are saved and restored.
626    ///
627    /// Restore writes the snapshot's saved MSRs. On KVM the destination must
628    /// declare every MSR the snapshot saved. An MSR restore failure leaves the
629    /// sandbox poisoned.
630    ///
631    /// ## Status after restore
632    ///
633    /// A successful restore sets the status to [`Ready`](SandboxStatus::Ready).
634    /// The restored snapshot becomes the basis for later calls to
635    /// [`Self::snapshot`].
636    /// The restored state includes snapshot and scratch memory, vCPU state,
637    /// stack state, the next VM action, captured MSRs on x86_64, and the removal
638    /// of dynamic memory mappings. This discards leaked allocations, restores
639    /// allocator and lock state, and rolls back partial updates. The sandbox
640    /// takes the snapshot's scratch size, which can differ from its own, as
641    /// for one taken with [`SnapshotOptions::scratch_size`].
642    ///
643    /// Restore failures have three status outcomes:
644    ///
645    /// * Snapshot compatibility failures happen before mutation and leave the
646    ///   current status unchanged.
647    /// * A failure while restoring base memory or its VM mappings sets the
648    ///   status to [`Unrecoverable`](SandboxStatus::Unrecoverable). The sandbox
649    ///   must be discarded.
650    /// * A later failure while restoring vCPU state, MSRs, or dynamic mappings
651    ///   leaves the sandbox [`Poisoned`](SandboxStatus::Poisoned). Restore can be
652    ///   retried with a compatible snapshot.
653    ///
654    /// Calling this method on an unrecoverable sandbox returns
655    /// [`crate::HyperlightError::UnrecoverableSandbox`].
656    ///
657    /// # Examples
658    ///
659    /// ```no_run
660    /// # use hyperlight_host::SandboxBuilder;
661    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
662    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
663    ///
664    /// // Take initial snapshot from this sandbox
665    /// let snapshot = sandbox.snapshot()?;
666    ///
667    /// // Modify sandbox state
668    /// sandbox.call_guest_function_by_name::<i32>("SetValue", 100)?;
669    /// let value: i32 = sandbox.call_guest_function_by_name("GetValue", ())?;
670    /// assert_eq!(value, 100);
671    ///
672    /// // Restore to previous state (same sandbox)
673    /// sandbox.restore(snapshot)?;
674    /// let restored_value: i32 = sandbox.call_guest_function_by_name("GetValue", ())?;
675    /// assert_eq!(restored_value, 0); // Back to initial state
676    /// # Ok(())
677    /// # }
678    /// ```
679    ///
680    /// ## Recovering from Poison
681    ///
682    /// ```no_run
683    /// # use hyperlight_host::SandboxBuilder;
684    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
685    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
686    ///
687    /// // Take snapshot before potentially poisoning operation
688    /// let snapshot = sandbox.snapshot()?;
689    ///
690    /// // This might poison the sandbox (guest not run to completion)
691    /// let result = sandbox.call::<()>("guest_panic", ());
692    /// if result.is_err() {
693    ///     if sandbox.status().is_poisoned() {
694    ///         // Restore from snapshot to clear poison
695    ///         sandbox.restore(snapshot.clone())?;
696    ///         assert!(sandbox.status().is_ready());
697    ///         
698    ///         // Sandbox is now usable again
699    ///         sandbox.call::<String>("Echo", "hello".to_string())?;
700    ///     }
701    /// }
702    /// # Ok(())
703    /// # }
704    /// ```
705    #[instrument(err(Debug), skip_all, parent = Span::current())]
706    pub fn restore(&mut self, snapshot: Arc<Snapshot>) -> Result<()> {
707        if self.status.is_unrecoverable() {
708            return Err(HyperlightError::UnrecoverableSandbox);
709        }
710
711        // Currently, we do not try to optimise restore to the
712        // most-current snapshot. This is because the most-current
713        // snapshot, while it must have identical virtual memory
714        // layout to the current sandbox, does not necessarily have
715        // the exact same /physical/ memory contents. It is not
716        // entirely inconceivable that this could lead to breakage of
717        // cross-request isolation in some way, although it would
718        // require some /very/ odd code.  For example, suppose that a
719        // service uses Hyperlight to sandbox native code from
720        // clients, and promises cross-request isolation. A tenant
721        // provides a binary that can process two forms of request,
722        // either writing a secret into physical memory, or reading
723        // from arbitrary physical memory, assuming that the two kinds
724        // of requests can never (dangerously) meet in the same
725        // sandbox.
726        //
727        // It is presently unclear whether this is a sensible threat
728        // model, especially since Hyperlight is often used with
729        // managed-code runtimes which do not allow even arbitrary
730        // access to virtual memory, much less physical memory.
731        // However, out of an abundance of caution, the optimisation
732        // is presently disabled.
733
734        {
735            let host_funcs = self
736                .host_funcs
737                .try_lock()
738                .map_err(|e| crate::new_error!("Error locking host_funcs: {}", e))?;
739            snapshot.validate_host_functions(&host_funcs)?;
740        }
741
742        let sregs = snapshot.sregs().ok_or_else(|| {
743            HyperlightError::Error("snapshot from running sandbox should have sregs".to_string())
744        })?;
745        #[cfg(target_arch = "x86_64")]
746        let msrs = snapshot.msrs().ok_or_else(|| {
747            HyperlightError::Error("snapshot from running sandbox should have MSRs".to_string())
748        })?;
749
750        if snapshot.virtq().is_none()
751            && matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_))
752        {
753            return Err(crate::new_error!(
754                "running snapshot has no canonical transport state"
755            ));
756        }
757
758        // Errors below leave the sandbox poisoned unless base mapping updates make it unrecoverable.
759        self.status = SandboxStatus::Poisoned;
760        self.snapshot = None;
761
762        self.remove_dynamic_mappings()?;
763
764        if let Err(error) = self.restore_memory_and_mappings(&snapshot) {
765            self.status = SandboxStatus::Unrecoverable;
766            return Err(error);
767        }
768
769        // Restore captured MSR state as part of the x86_64 vCPU reset.
770        self.vm
771            .reset_vcpu(
772                snapshot.root_pt_gpa(),
773                sregs,
774                #[cfg(target_arch = "x86_64")]
775                msrs,
776            )
777            .map_err(HyperlightVmError::Restore)?;
778
779        self.vm.set_stack_top(snapshot.stack_top_gva());
780        self.vm.set_next_action(snapshot.next_action());
781
782        self.mem_mgr
783            .request_libc_rng_reseed(rand::random::<u32>())?;
784        if let Some(log_level) = self.max_guest_log_level {
785            self.mem_mgr.request_guest_log_level_update(log_level)?;
786        }
787
788        // The restored snapshot is now our most current snapshot
789        self.snapshot = Some(snapshot.clone());
790        self.transport_dirty = false;
791
792        // Clear poison state when successfully restoring from snapshot.
793        //
794        // # Safety:
795        // This is safe because:
796        // 1. Snapshots can only be taken from non-poisoned sandboxes (verified at snapshot creation)
797        // 2. Restoration completely replaces all memory state, eliminating:
798        //    - All leaked heap allocations (memory is restored to snapshot state)
799        //    - All corrupted data structures (overwritten with consistent snapshot data)
800        //    - All inconsistent global state (reset to snapshot values)
801        self.status = SandboxStatus::Ready;
802
803        Ok(())
804    }
805
806    /// Calls a guest function by name with the specified arguments.
807    ///
808    /// Changes made to the sandbox during execution are *not* persisted.
809    ///
810    /// ## Poisoned Sandbox
811    ///
812    /// This method will return [`crate::HyperlightError::PoisonedSandbox`] if the sandbox
813    /// is currently poisoned. Use [`restore()`](Self::restore) to recover from a poisoned state.
814    ///
815    /// # Examples
816    ///
817    /// ```no_run
818    /// # use hyperlight_host::SandboxBuilder;
819    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
820    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
821    ///
822    /// // Call function with no arguments
823    /// let result: i32 = sandbox.call_guest_function_by_name("GetCounter", ())?;
824    ///
825    /// // Call function with single argument
826    /// let doubled: i32 = sandbox.call_guest_function_by_name("Double", 21)?;
827    /// assert_eq!(doubled, 42);
828    ///
829    /// // Call function with multiple arguments
830    /// let sum: i32 = sandbox.call_guest_function_by_name("Add", (10, 32))?;
831    /// assert_eq!(sum, 42);
832    ///
833    /// // Call function returning string
834    /// let message: String = sandbox.call_guest_function_by_name("Echo", "Hello, World!".to_string())?;
835    /// assert_eq!(message, "Hello, World!");
836    /// # Ok(())
837    /// # }
838    /// ```
839    #[doc(hidden)]
840    #[deprecated(
841        since = "0.8.0",
842        note = "Deprecated in favour of call and snapshot/restore."
843    )]
844    #[instrument(err(Debug), skip(self, args), parent = Span::current())]
845    pub fn call_guest_function_by_name<Output: SupportedReturnType>(
846        &mut self,
847        func_name: &str,
848        args: impl ParameterTuple,
849    ) -> Result<Output> {
850        self.check_ready()?;
851        let snapshot = self.snapshot()?;
852        let res = self.call(func_name, args);
853        self.restore(snapshot)?;
854        res
855    }
856
857    /// Calls a guest function by name with the specified arguments.
858    ///
859    /// Changes made to the sandbox during execution are persisted.
860    ///
861    /// ## Poisoned Sandbox
862    ///
863    /// This method will return [`crate::HyperlightError::PoisonedSandbox`] if the sandbox
864    /// is already poisoned before the call. Use [`restore()`](Self::restore) to recover from
865    /// a poisoned state.
866    ///
867    /// ## Sandbox Poisoning
868    ///
869    /// If this method returns an error, the sandbox may be poisoned if the guest was not run
870    /// to completion (due to panic, abort, memory violation, stack/heap exhaustion, or forced
871    /// termination). Use [`status()`](Self::status) to check the sandbox state and
872    /// [`restore()`](Self::restore) to recover if needed.
873    ///
874    /// If this method returns `Ok`, the sandbox is guaranteed to **not** be poisoned - the guest
875    /// function completed successfully and the sandbox state is consistent.
876    ///
877    /// # Examples
878    ///
879    /// ```no_run
880    /// # use hyperlight_host::SandboxBuilder;
881    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
882    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
883    ///
884    /// // Call function with no arguments
885    /// let result: i32 = sandbox.call("GetCounter", ())?;
886    ///
887    /// // Call function with single argument
888    /// let doubled: i32 = sandbox.call("Double", 21)?;
889    /// assert_eq!(doubled, 42);
890    ///
891    /// // Call function with multiple arguments
892    /// let sum: i32 = sandbox.call("Add", (10, 32))?;
893    /// assert_eq!(sum, 42);
894    ///
895    /// // Call function returning string
896    /// let message: String = sandbox.call("Echo", "Hello, World!".to_string())?;
897    /// assert_eq!(message, "Hello, World!");
898    /// # Ok(())
899    /// # }
900    /// ```
901    ///
902    /// ## Handling Potential Poisoning
903    ///
904    /// ```no_run
905    /// # use hyperlight_host::SandboxBuilder;
906    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
907    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
908    ///
909    /// // Take snapshot before risky operation
910    /// let snapshot = sandbox.snapshot()?;
911    ///
912    /// // Call potentially unsafe guest function
913    /// let result = sandbox.call::<String>("RiskyOperation", "input".to_string());
914    ///
915    /// // Check if the call failed and poisoned the sandbox
916    /// if let Err(e) = result {
917    ///     eprintln!("Guest function failed: {}", e);
918    ///     
919    ///     if sandbox.status().is_poisoned() {
920    ///         eprintln!("Sandbox was poisoned, restoring from snapshot");
921    ///         sandbox.restore(snapshot.clone())?;
922    ///     }
923    /// }
924    /// # Ok(())
925    /// # }
926    /// ```
927    #[instrument(err(Debug), skip(self, args), parent = Span::current())]
928    pub fn call<Output: SupportedReturnType>(
929        &mut self,
930        func_name: &str,
931        args: impl ParameterTuple,
932    ) -> Result<Output> {
933        self.check_ready()?;
934        // Reset snapshot since we are mutating the sandbox state
935        self.snapshot = None;
936        maybe_time_and_emit_guest_call(func_name, || {
937            let ret = self.call_guest_function_by_name_no_reset(
938                func_name,
939                Output::TYPE,
940                args.into_value(),
941            );
942            // Use the ? operator to allow converting any hyperlight_common::func::Error
943            // returned by from_value into a HyperlightError
944            let ret = Output::from_value(ret?)?;
945            Ok(ret)
946        })
947    }
948
949    /// Maps a region of host memory into the sandbox address space.
950    ///
951    /// The base address and length must meet platform alignment requirements
952    /// (typically page-aligned). The `region_type` field is ignored as guest
953    /// page table entries are not created.
954    ///
955    /// [`Self::snapshot`] copies only the pages of this region that the guest has
956    /// mapped into its page tables, then removes the region. Pages the guest has
957    /// not mapped are lost.
958    ///
959    /// ## Poisoned Sandbox
960    ///
961    /// This method will return [`crate::HyperlightError::PoisonedSandbox`] if the sandbox
962    /// is currently poisoned. Use [`restore()`](Self::restore) to recover from a poisoned state.
963    ///
964    /// # Safety
965    ///
966    /// The caller must ensure the host memory region remains valid and unmodified
967    /// for the lifetime of `self`.
968    #[instrument(err(Debug), skip(self, rgn), parent = Span::current())]
969    pub unsafe fn map_region(&mut self, rgn: &MemoryRegion) -> Result<()> {
970        self.check_ready()?;
971        if rgn.flags.contains(MemoryRegionFlags::WRITE) {
972            // TODO: Implement support for writable mappings, which
973            // need to be registered with the memory manager so that
974            // writes can be rolled back when necessary.
975            log_then_return!("TODO: Writable mappings not yet supported");
976        }
977
978        // Map first so overlaps are rejected before resetting the snapshot
979        unsafe { self.vm.map_region(rgn) }.map_err(HyperlightVmError::MapRegion)?;
980        self.snapshot = None;
981        Ok(())
982    }
983
984    /// Map the contents of a file into the guest at a particular address
985    ///
986    /// Returns the length of the mapping in bytes.
987    ///
988    /// [`Self::snapshot`] copies only the pages of this region that the guest has
989    /// mapped into its page tables, then removes the region. Pages the guest has
990    /// not mapped are lost.
991    ///
992    /// ## Poisoned Sandbox
993    ///
994    /// This method will return [`crate::HyperlightError::PoisonedSandbox`] if the sandbox
995    /// is currently poisoned. Use [`restore()`](Self::restore) to recover from a poisoned state.
996    #[instrument(err(Debug), skip(self, file_path, guest_base), parent = Span::current())]
997    pub fn map_file_cow(&mut self, file_path: &Path, guest_base: u64) -> Result<u64> {
998        self.check_ready()?;
999
1000        // Phase 1: host-side OS work (open file, create mapping)
1001        let mut prepared = prepare_file_cow(file_path, guest_base)?;
1002
1003        // Validate that the full mapped range doesn't overlap the
1004        // sandbox's primary shared memory region.
1005        let shared_size = self.mem_mgr.shared_mem.gpa_span_len() as u64;
1006        let base_addr = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
1007        let shared_end = base_addr.checked_add(shared_size).ok_or_else(|| {
1008            crate::HyperlightError::Error("shared memory end overflow".to_string())
1009        })?;
1010        let mapping_end = guest_base
1011            .checked_add(prepared.size as u64)
1012            .ok_or_else(|| {
1013                crate::HyperlightError::Error(format!(
1014                    "map_file_cow: guest address overflow: {:#x} + {:#x}",
1015                    guest_base, prepared.size
1016                ))
1017            })?;
1018        if guest_base < shared_end && mapping_end > base_addr {
1019            return Err(crate::HyperlightError::Error(format!(
1020                "map_file_cow: mapping [{:#x}..{:#x}) overlaps sandbox shared memory [{:#x}..{:#x})",
1021                guest_base, mapping_end, base_addr, shared_end,
1022            )));
1023        }
1024
1025        // Phase 2: VM-side work (map into guest address space)
1026        let region = prepared.to_memory_region()?;
1027
1028        unsafe { self.vm.map_region(&region) }
1029            .map_err(HyperlightVmError::MapRegion)
1030            .map_err(crate::HyperlightError::HyperlightVmError)?;
1031
1032        self.snapshot = None;
1033
1034        let size = prepared.size as u64;
1035
1036        // Mark consumed immediately after map_region succeeds.
1037        // On Windows, WhpVm::map_memory copies the file mapping handle
1038        // into its own `file_mappings` vec for cleanup on drop. If we
1039        // deferred mark_consumed(), both PreparedFileMapping::drop and
1040        // WhpVm::drop would release the same handle — a double-close.
1041        // On Linux the hypervisor holds a reference to the host mmap;
1042        // freeing it here would leave a dangling backing.
1043        prepared.mark_consumed();
1044
1045        Ok(size)
1046    }
1047
1048    /// Calls a guest function with type-erased parameters and return values.
1049    ///
1050    /// This function is used for fuzz testing parameter and return type handling.
1051    ///
1052    /// ## Poisoned Sandbox
1053    ///
1054    /// This method will return [`crate::HyperlightError::PoisonedSandbox`] if the sandbox
1055    /// is currently poisoned. Use [`restore()`](Self::restore) to recover from a poisoned state.
1056    #[cfg(feature = "fuzzing")]
1057    #[instrument(err(Debug), skip(self, args), parent = Span::current())]
1058    pub fn call_type_erased_guest_function_by_name(
1059        &mut self,
1060        func_name: &str,
1061        ret_type: ReturnType,
1062        args: Vec<ParameterValue>,
1063    ) -> Result<ReturnValue> {
1064        self.check_ready()?;
1065        // Reset snapshot since we are mutating the sandbox state
1066        self.snapshot = None;
1067        maybe_time_and_emit_guest_call(func_name, || {
1068            self.call_guest_function_by_name_no_reset(func_name, ret_type, args)
1069        })
1070    }
1071
1072    fn call_guest_function_by_name_no_reset(
1073        &mut self,
1074        function_name: &str,
1075        return_type: ReturnType,
1076        args: Vec<ParameterValue>,
1077    ) -> Result<ReturnValue> {
1078        self.check_ready()?;
1079        self.with_guest_execution(|sbox| {
1080            sbox.transport_dirty = true;
1081
1082            let fc = FunctionCall::new(
1083                function_name.to_string(),
1084                Some(args),
1085                FunctionCallType::Guest,
1086                return_type,
1087            );
1088
1089            let cid = sbox.mem_mgr.write_guest_function_call(&fc)?;
1090            sbox.dispatch_guest_call()?;
1091
1092            let guest_result = sbox.mem_mgr.read_h2g_result_from_g2h(cid)?.into_inner();
1093
1094            match guest_result {
1095                Ok(val) => Ok(val),
1096                Err(guest_error) => {
1097                    metrics::counter!(
1098                        METRIC_GUEST_ERROR,
1099                        METRIC_GUEST_ERROR_LABEL_CODE => (guest_error.code as u64).to_string()
1100                    )
1101                    .increment(1);
1102
1103                    Err(HyperlightError::GuestError(
1104                        guest_error.code,
1105                        guest_error.message,
1106                    ))
1107                }
1108            }
1109        })
1110    }
1111
1112    fn with_guest_execution<T>(&mut self, op: impl FnOnce(&mut Self) -> Result<T>) -> Result<T> {
1113        // ===== KILL() TIMING POINT 1 =====
1114        // Cancellation set before this reset is ignored for this operation.
1115        // Cancellation during request preparation must reach the VM.
1116        self.vm.clear_cancel();
1117        let result = op(self);
1118        self.mem_mgr.abort_buffer.clear();
1119
1120        if result.as_ref().is_err_and(HyperlightError::is_poison_error) {
1121            self.poison();
1122        }
1123
1124        result
1125    }
1126
1127    fn dispatch_guest_call(&mut self) -> Result<()> {
1128        self.vm
1129            .dispatch_call_from_host(&mut self.mem_mgr, &self.host_funcs)
1130            .map_err(|error| {
1131                let (error, should_poison) = error.promote();
1132                if should_poison {
1133                    self.poison();
1134                }
1135                error
1136            })
1137    }
1138
1139    /// Dispatch in restricted mode, then restore the previous mode.
1140    fn dispatch_guest_call_restricted(&mut self) -> Result<()> {
1141        let mode = std::mem::replace(&mut self.mem_mgr.execution_mode, ExecutionMode::Restricted);
1142        let res = self.dispatch_guest_call();
1143        self.mem_mgr.execution_mode = mode;
1144
1145        res
1146    }
1147
1148    /// Returns a handle for interrupting guest execution.
1149    ///
1150    /// # Examples
1151    ///
1152    /// ```no_run
1153    /// # use hyperlight_host::SandboxBuilder;
1154    /// # use std::thread;
1155    /// # use std::time::Duration;
1156    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
1157    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
1158    ///
1159    /// // Get interrupt handle before starting long-running operation
1160    /// let interrupt_handle = sandbox.interrupt_handle();
1161    ///
1162    /// // Spawn thread to interrupt after timeout
1163    /// let handle_clone = interrupt_handle.clone();
1164    /// thread::spawn(move || {
1165    ///     thread::sleep(Duration::from_secs(5));
1166    ///     handle_clone.kill();
1167    /// });
1168    ///
1169    /// // This call may be interrupted by the spawned thread
1170    /// let result = sandbox.call_guest_function_by_name::<i32>("LongRunningFunction", ());
1171    /// # Ok(())
1172    /// # }
1173    /// ```
1174    pub fn interrupt_handle(&self) -> Arc<dyn InterruptHandle> {
1175        self.vm.interrupt_handle()
1176    }
1177
1178    /// Generate a crash dump of the current state of the VM underlying this sandbox.
1179    ///
1180    /// Creates an ELF core dump file that can be used for debugging. The dump
1181    /// captures the current state of the sandbox including registers, memory regions,
1182    /// and other execution context.
1183    ///
1184    /// The location of the core dump file is determined by the `HYPERLIGHT_CORE_DUMP_DIR`
1185    /// environment variable. If not set, it defaults to the system's temporary directory.
1186    ///
1187    /// This is only available when the `crashdump` feature is enabled and then only if the sandbox
1188    /// is also configured to allow core dumps (which is the default behavior).
1189    ///
1190    /// This can be useful for generating a crash dump from gdb when trying to debug issues in the
1191    /// guest that dont cause crashes (e.g. a guest function that does not return)
1192    ///
1193    /// # Examples
1194    ///
1195    /// Attach to your running process with gdb and call this function:
1196    ///
1197    /// ```shell
1198    /// sudo gdb -p <pid_of_your_process>
1199    /// (gdb) info threads
1200    /// # find the thread that is running the guest function you want to debug
1201    /// (gdb) thread <thread_number>
1202    /// # switch to the frame where you have access to your Sandbox instance
1203    /// (gdb) backtrace
1204    /// (gdb) frame <frame_number>
1205    /// # get the pointer to your Sandbox instance
1206    /// # Get the sandbox pointer
1207    /// (gdb) print sandbox
1208    /// # Call the crashdump function
1209    /// call sandbox.generate_crashdump()
1210    /// ```
1211    /// The crashdump should be available in crash dump directory (see `HYPERLIGHT_CORE_DUMP_DIR` env var).
1212    ///
1213    #[cfg(crashdump)]
1214    #[instrument(err(Debug), skip_all, parent = Span::current())]
1215    pub fn generate_crashdump(&mut self) -> Result<()> {
1216        crate::hypervisor::crashdump::generate_crashdump(&self.vm, &mut self.mem_mgr, None)
1217    }
1218
1219    /// Generate a crash dump of the current state of the VM, writing to `dir`.
1220    ///
1221    /// Like [`generate_crashdump`](Self::generate_crashdump), but the core dump
1222    /// file is placed in `dir` instead of consulting the `HYPERLIGHT_CORE_DUMP_DIR`
1223    /// environment variable.  This avoids the need for callers to use
1224    /// `unsafe { std::env::set_var(...) }`.
1225    #[cfg(crashdump)]
1226    #[instrument(err(Debug), skip_all, parent = Span::current())]
1227    pub fn generate_crashdump_to_dir(&mut self, dir: impl Into<PathBuf>) -> Result<()> {
1228        crate::hypervisor::crashdump::generate_crashdump(
1229            &self.vm,
1230            &mut self.mem_mgr,
1231            Some(dir.into()),
1232        )
1233    }
1234
1235    /// Returns whether the sandbox is poisoned.
1236    ///
1237    /// Use [`status()`](Self::status) to distinguish every lifecycle state.
1238    ///
1239    /// ## Causes of Poisoning
1240    ///
1241    /// The sandbox becomes poisoned when guest execution is interrupted:
1242    /// - **Panics/Aborts** - Guest code panics or calls `abort()`
1243    /// - **Invalid Memory Access** - Read/write/execute violations  
1244    /// - **Stack Overflow** - Guest exhausts stack space
1245    /// - **Heap Exhaustion** - Guest runs out of heap memory
1246    /// - **Forced Termination** - [`InterruptHandle::kill()`] called during execution
1247    ///
1248    /// ## Recovery
1249    ///
1250    /// To clear the poison state, use [`restore()`](Self::restore) with a snapshot
1251    /// that was taken before the sandbox became poisoned.
1252    ///
1253    /// # Examples
1254    ///
1255    /// ```no_run
1256    /// # use hyperlight_host::SandboxBuilder;
1257    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
1258    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
1259    ///
1260    /// if sandbox.status().is_poisoned() {
1261    ///     println!("Sandbox is poisoned");
1262    /// }
1263    /// # Ok(())
1264    /// # }
1265    /// ```
1266    #[deprecated(since = "0.17.0", note = "use status().is_poisoned()")]
1267    pub fn poisoned(&self) -> bool {
1268        self.status.is_poisoned()
1269    }
1270
1271    /// Returns the sandbox lifecycle status.
1272    ///
1273    /// * [`Ready`](SandboxStatus::Ready) permits guest operations and snapshots.
1274    /// * [`Poisoned`](SandboxStatus::Poisoned) rejects guest operations and
1275    ///   snapshots. A successful [`restore()`](Self::restore) makes it ready.
1276    /// * [`Unrecoverable`](SandboxStatus::Unrecoverable) rejects all further
1277    ///   operations, including restore. The sandbox must be discarded.
1278    pub fn status(&self) -> SandboxStatus {
1279        self.status
1280    }
1281
1282    /// Returns how many bytes of scratch memory the guest has allocated
1283    /// since the sandbox was last restored or snapshotted.
1284    /// Before the first restore or snapshot, this includes allocations
1285    /// made during guest initialisation.
1286    ///
1287    /// Host-reserved scratch, such as the transport and exception stack,
1288    /// is excluded.
1289    ///
1290    /// The guest controls this value. A malicious guest can make it
1291    /// report less or more scratch than it actually allocated.
1292    ///
1293    /// ```no_run
1294    /// # use hyperlight_host::SandboxBuilder;
1295    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
1296    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
1297    /// let snapshot = sandbox.snapshot()?;
1298    /// sandbox.call::<()>("WriteSomething", ())?;
1299    /// println!(
1300    ///     "guest-reported scratch allocation: {} bytes",
1301    ///     sandbox.scratch_allocated_bytes()?
1302    /// );
1303    /// sandbox.restore(snapshot)?;
1304    /// # Ok(())
1305    /// # }
1306    /// ```
1307    pub fn scratch_allocated_bytes(&self) -> Result<u64> {
1308        self.mem_mgr.scratch_allocated_bytes()
1309    }
1310}
1311
1312impl Callable for Sandbox {
1313    fn call<Output: SupportedReturnType>(
1314        &mut self,
1315        func_name: &str,
1316        args: impl ParameterTuple,
1317    ) -> Result<Output> {
1318        self.check_ready()?;
1319        self.call(func_name, args)
1320    }
1321}
1322
1323impl std::fmt::Debug for Sandbox {
1324    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1325        f.debug_struct("Sandbox").finish()
1326    }
1327}
1328
1329/// Emit a warning for each memory-layout field in `caller` that
1330/// disagrees with `snapshot`. Used by [`Sandbox::from_snapshot`]
1331/// to surface ignored caller-supplied layout values, since those
1332/// fields are always taken from the snapshot.
1333fn warn_on_layout_override(
1334    caller: &crate::sandbox::SandboxConfiguration,
1335    snapshot: &crate::mem::layout::SandboxMemoryLayout,
1336) {
1337    let mismatches: &[(&str, u64, u64)] = &[
1338        (
1339            "scratch_size",
1340            caller.get_scratch_size() as u64,
1341            snapshot.get_scratch_size() as u64,
1342        ),
1343        (
1344            "g2h_queue_size",
1345            caller.get_g2h_queue_size() as u64,
1346            snapshot.get_g2h_queue_size() as u64,
1347        ),
1348        (
1349            "h2g_queue_size",
1350            caller.get_h2g_queue_size() as u64,
1351            snapshot.get_h2g_queue_size() as u64,
1352        ),
1353        (
1354            "g2h_buffer_size",
1355            caller.get_g2h_buffer_size() as u64,
1356            snapshot.get_g2h_buffer_size() as u64,
1357        ),
1358        (
1359            "h2g_buffer_size",
1360            caller.get_h2g_buffer_size() as u64,
1361            snapshot.get_h2g_buffer_size() as u64,
1362        ),
1363        (
1364            "g2h_pool_pages",
1365            caller.get_g2h_pool_pages() as u64,
1366            snapshot.get_g2h_pool_pages() as u64,
1367        ),
1368        (
1369            "h2g_pool_pages",
1370            caller.get_h2g_pool_pages() as u64,
1371            snapshot.get_h2g_pool_pages() as u64,
1372        ),
1373    ];
1374    for (name, supplied, snap) in mismatches {
1375        if supplied != snap {
1376            tracing::warn!(
1377                "from_snapshot ignoring caller-supplied {} ({}); using snapshot value ({})",
1378                name,
1379                supplied,
1380                snap
1381            );
1382        }
1383    }
1384}
1385
1386#[cfg(test)]
1387mod tests {
1388    use std::sync::{Arc, Barrier};
1389    use std::thread;
1390
1391    use hyperlight_common::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
1392    use hyperlight_common::flatbuffer_wrappers::function_types::ParameterValue;
1393    use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
1394    use hyperlight_common::func::{Bytes, SupportedReturnType};
1395    use hyperlight_testing::sandbox_sizes::{
1396        LARGE_SCRATCH_SIZE, MEDIUM_SCRATCH_SIZE, SMALL_SCRATCH_SIZE,
1397    };
1398    use hyperlight_testing::{c_simple_guest_as_pathbuf, simple_guest_as_pathbuf};
1399
1400    use super::normalize_page_table_roots;
1401    use crate::func::host_functions::Registerable;
1402    #[cfg(not(gdb))]
1403    use crate::hypervisor::hyperlight_vm::test_support::VmOperation;
1404    use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags, MemoryRegionType};
1405    use crate::mem::mgr::ExecutionMode;
1406    use crate::mem::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, SharedMemory as _};
1407    use crate::sandbox::SandboxConfiguration;
1408    use crate::sandbox::snapshot::SnapshotOptions;
1409    use crate::sandbox::uninitialized::{GuestBlob, GuestEnvironment};
1410    use crate::{
1411        GuestBinary, HyperlightError, Result, Sandbox, SandboxBuilder, SandboxStatus,
1412        UninitializedSandbox,
1413    };
1414
1415    #[test]
1416    fn sandbox_status_predicates() {
1417        assert!(SandboxStatus::Ready.is_ready());
1418        assert!(!SandboxStatus::Ready.is_poisoned());
1419        assert!(!SandboxStatus::Ready.is_unrecoverable());
1420
1421        assert!(!SandboxStatus::Poisoned.is_ready());
1422        assert!(SandboxStatus::Poisoned.is_poisoned());
1423        assert!(!SandboxStatus::Poisoned.is_unrecoverable());
1424
1425        assert!(!SandboxStatus::Unrecoverable.is_ready());
1426        assert!(!SandboxStatus::Unrecoverable.is_poisoned());
1427        assert!(SandboxStatus::Unrecoverable.is_unrecoverable());
1428    }
1429
1430    fn scratch(scratch_size: usize) -> SnapshotOptions {
1431        SnapshotOptions::default().scratch_size(scratch_size)
1432    }
1433
1434    fn assert_virtq_attached(sbox: &Sandbox) {
1435        assert!(sbox.mem_mgr.g2h_consumer.is_some());
1436        assert!(sbox.mem_mgr.h2g_consumer.is_some());
1437    }
1438
1439    /// The page between the transport arena and the reserved top pages is
1440    /// unmapped at boot, after a resized capture, and after restoring it, so
1441    /// an exception stack overrun faults before it reaches the arena.
1442    #[test]
1443    fn transport_guard_page_is_unmapped() {
1444        use hyperlight_common::layout::{scratch_reserved_top_gva, scratch_transport_end_gva};
1445
1446        fn assert_guarded(sbox: &mut Sandbox) {
1447            let guard = scratch_transport_end_gva();
1448            let mut mapped = |gva: u64| sbox.call::<bool>("CheckMapped", gva).unwrap();
1449            assert!(mapped(guard - hyperlight_common::vmem::PAGE_SIZE as u64));
1450            assert!(!mapped(guard));
1451            assert!(mapped(scratch_reserved_top_gva()));
1452        }
1453
1454        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1455            .scratch_size(8 << 20)
1456            .build()
1457            .unwrap();
1458        assert_guarded(&mut sbox);
1459        let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1460        assert_guarded(&mut sbox);
1461        sbox.restore(small).unwrap();
1462        assert_guarded(&mut sbox);
1463    }
1464
1465    /// A snapshot can give its sandbox, and sandboxes restored from it, less
1466    /// scratch. They run guest function calls and can go back to the
1467    /// original size.
1468    #[test]
1469    fn snapshot_scratch_size_resizes_on_restore() {
1470        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1471            .scratch_size(8 << 20)
1472            .build()
1473            .unwrap();
1474        let full = sbox.snapshot().unwrap();
1475        // Default options and the sandbox's own size are a plain snapshot,
1476        // already taken.
1477        let default = sbox
1478            .snapshot_with_options(&SnapshotOptions::default())
1479            .unwrap();
1480        assert!(Arc::ptr_eq(&default, &full));
1481        let same = sbox.snapshot_with_options(&scratch(8 << 20)).unwrap();
1482        assert!(Arc::ptr_eq(&same, &full));
1483        let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1484        assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1485        assert!(Arc::ptr_eq(&sbox.snapshot().unwrap(), &small));
1486        assert!(matches!(
1487            sbox.snapshot_with_options(&scratch(4096)),
1488            Err(HyperlightError::MemoryRequestTooSmall(..))
1489        ));
1490        assert!(matches!(
1491            sbox.snapshot_with_options(&scratch(32 << 30)),
1492            Err(HyperlightError::MemoryRequestTooBig(..))
1493        ));
1494        // Rejected sizes do not enter the guest: a pending transport
1495        // checkpoint, which a capture would run, is still pending.
1496        let echo: String = sbox.call("Echo", "still".to_string()).unwrap();
1497        assert_eq!(echo, "still");
1498        assert!(sbox.transport_dirty);
1499        assert!(sbox.snapshot_with_options(&scratch(4096)).is_err());
1500        assert!(sbox.snapshot_with_options(&scratch(32 << 30)).is_err());
1501        assert!(sbox.transport_dirty);
1502
1503        // A size with room for the transport but not the page tables fails
1504        // when the snapshot is built, and leaves the sandbox usable.
1505        let page = crate::mem::layout::SandboxMemoryLayout::host_page_size();
1506        let no_pt_room = sbox.mem_mgr.layout.min_scratch().next_multiple_of(page);
1507        assert!(matches!(
1508            sbox.snapshot_with_options(&scratch(no_pt_room)),
1509            Err(HyperlightError::MemoryRequestTooSmall(..))
1510        ));
1511        let echo: String = sbox.call("Echo", "usable".to_string()).unwrap();
1512        assert_eq!(echo, "usable");
1513
1514        for _ in 0..3 {
1515            sbox.restore(small.clone()).unwrap();
1516            assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1517            let echo: String = sbox.call("Echo", "hello".to_string()).unwrap();
1518            assert_eq!(echo, "hello");
1519            sbox.call::<()>("AllocAndWritePattern", 32u64 << 10)
1520                .unwrap();
1521        }
1522        // A snapshot of the resized sandbox keeps its size.
1523        let again = sbox.snapshot().unwrap();
1524        assert_eq!(again.layout().get_scratch_size(), 2 << 20);
1525
1526        // So does one saved to a file and loaded back.
1527        let dir = tempfile::tempdir().unwrap();
1528        let tag = crate::sandbox::snapshot::OciTag::new("small").unwrap();
1529        small.save(dir.path(), &tag).unwrap();
1530        let loaded = crate::sandbox::snapshot::Snapshot::checked_load(dir.path(), tag).unwrap();
1531        sbox.restore(Arc::new(loaded)).unwrap();
1532        assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1533        let echo: String = sbox.call("Echo", "loaded".to_string()).unwrap();
1534        assert_eq!(echo, "loaded");
1535
1536        sbox.restore(full).unwrap();
1537        assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 8 << 20);
1538        let echo: String = sbox.call("Echo", "back".to_string()).unwrap();
1539        assert_eq!(echo, "back");
1540    }
1541
1542    /// A snapshot can give a sandbox more scratch than it booted with, for
1543    /// guest function calls that need it.
1544    #[test]
1545    fn snapshot_scratch_size_grows_on_restore() {
1546        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1547            .scratch_size(4 << 20)
1548            .build()
1549            .unwrap();
1550        let booted = sbox.snapshot().unwrap();
1551        // 8 MiB of heap writes need 8 MiB of copy-on-write scratch.
1552        assert!(sbox.call::<()>("AllocAndWritePattern", 8u64 << 20).is_err());
1553        sbox.restore(booted).unwrap();
1554
1555        let large = sbox.snapshot_with_options(&scratch(16 << 20)).unwrap();
1556        assert_eq!(large.layout().get_scratch_size(), 16 << 20);
1557        assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 16 << 20);
1558        sbox.call::<()>("AllocAndWritePattern", 8u64 << 20).unwrap();
1559
1560        for _ in 0..2 {
1561            sbox.restore(large.clone()).unwrap();
1562            assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 16 << 20);
1563            sbox.call::<()>("AllocAndWritePattern", 8u64 << 20).unwrap();
1564            let echo: String = sbox.call("Echo", "grown".to_string()).unwrap();
1565            assert_eq!(echo, "grown");
1566        }
1567    }
1568
1569    /// A held byte chunk keeps a slot in the transport arena live, mapped
1570    /// through an alias page. A resize moves the scratch base but not the
1571    /// arena. Held bytes, their release, and slot reuse must work after
1572    /// snapshots taken at other scratch sizes.
1573    #[test]
1574    fn held_buffers_survive_resized_snapshots() {
1575        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1576            .scratch_size(8 << 20)
1577            // Pin the default pool sizes so 32 holds always outnumber the slots.
1578            .h2g_pool_pages(8)
1579            .g2h_pool_pages(12)
1580            .host_function("HostEchoByteChunks", |v: Vec<Bytes>| v)
1581            .host_function("HostNoOp", || {})
1582            .build()
1583            .unwrap();
1584        // Bytes differ between pages, chunks and holds, so a read from a
1585        // shifted or stale page fails.
1586        let chunks = |seed: u8| {
1587            let mut first: Bytes = (0..11 * 1024usize)
1588                .map(|i| (i ^ (i >> 8)) as u8 ^ seed)
1589                .collect();
1590            let second = first.split_off(6 * 1024);
1591            vec![first, second]
1592        };
1593        // Chunk boundaries follow transport buffers, so compare bytes.
1594        let read_back =
1595            |sbox: &mut Sandbox, read: &str| sbox.call::<Vec<Bytes>>(read, ()).unwrap().concat();
1596        let base = sbox.snapshot().unwrap();
1597
1598        for (seed, hold, read, release) in [
1599            (
1600                0x00,
1601                "RetainGuestByteChunks",
1602                "ReadRetainedGuestByteChunks",
1603                "ReleaseGuestByteChunks",
1604            ),
1605            (
1606                0x40,
1607                "RetainHostByteChunks",
1608                "ReadRetainedHostByteChunks",
1609                "ReleaseHostByteChunks",
1610            ),
1611        ] {
1612            sbox.restore(base.clone()).unwrap();
1613            let held = chunks(seed);
1614            let len: i32 = sbox.call(hold, held.clone()).unwrap();
1615            assert_eq!(len, 11 * 1024);
1616            assert_eq!(read_back(&mut sbox, read), held.concat());
1617
1618            // Shrink from the 8 MiB boot size, then grow from 2 MiB, with
1619            // the chunks held in each snapshot.
1620            for size in [2 << 20, 16 << 20] {
1621                let snapshot = sbox.snapshot_with_options(&scratch(size)).unwrap();
1622                // Other chunks are held at the restore, so only the snapshot
1623                // can bring the first ones back, and the restore must drop
1624                // the live ones.
1625                assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1626                assert_eq!(sbox.call::<i32>(hold, chunks(!seed)).unwrap(), len);
1627                sbox.restore(snapshot).unwrap();
1628                assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), size);
1629
1630                // Bytes through both pools, which recycle the held slots after
1631                // a restore. The held chunks read from their captured copy, so
1632                // this traffic must not change them.
1633                let other = chunks(seed ^ 0x80);
1634                let echoed: Vec<Bytes> =
1635                    sbox.call("RoundTripHostByteChunks", other.clone()).unwrap();
1636                assert_eq!(echoed.concat(), other.concat());
1637                assert_eq!(read_back(&mut sbox, read), held.concat());
1638            }
1639            assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1640            // The restores dropped the swapped-in chunks, so nothing is left.
1641            assert!(read_back(&mut sbox, read).is_empty());
1642
1643            // Hold and release more times than either pool has slots, so a
1644            // release that leaks its slot runs the pool dry.
1645            for round in 1..=32 {
1646                let next = chunks(seed + round);
1647                assert_eq!(sbox.call::<i32>(hold, next.clone()).unwrap(), len);
1648                assert_eq!(read_back(&mut sbox, read), next.concat());
1649                assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1650            }
1651
1652            // After the churn the sandbox can still resize, back to 8 MiB,
1653            // and hold chunks there.
1654            let back = sbox.snapshot_with_options(&scratch(8 << 20)).unwrap();
1655            assert!(!sbox.transport_dirty);
1656            sbox.restore(back).unwrap();
1657            assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 8 << 20);
1658            let last = chunks(seed + 0x21);
1659            assert_eq!(sbox.call::<i32>(hold, last.clone()).unwrap(), len);
1660            assert_eq!(read_back(&mut sbox, read), last.concat());
1661            assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1662        }
1663    }
1664
1665    /// The guest's page allocator stops at the transport arena. A resized
1666    /// sandbox that runs out of scratch aborts once an allocation reaches the
1667    /// arena, with nothing handed out inside it, and a restore recovers it.
1668    #[test]
1669    fn running_out_of_scratch_stops_at_the_transport_arena() {
1670        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1671            .scratch_size(8 << 20)
1672            .build()
1673            .unwrap();
1674        let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1675        sbox.restore(small.clone()).unwrap();
1676        // 4 MiB of heap writes need 4 MiB of copy-on-write scratch.
1677        let err = sbox
1678            .call::<()>("AllocAndWritePattern", 4u64 << 20)
1679            .unwrap_err();
1680        assert!(
1681            matches!(&err, HyperlightError::GuestAborted(code, msg)
1682                if *code == ErrorCode::MallocFailed as u8 && msg.contains("Out of physical memory")),
1683            "{err:?}"
1684        );
1685        let size = sbox.mem_mgr.scratch_mem.mem_size();
1686        let offset = size - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
1687        let allocator = sbox.mem_mgr.scratch_mem.read::<u64>(offset).unwrap();
1688        let arena = sbox.mem_mgr.layout.get_transport_arena();
1689        // The failed allocation moved the pointer past the arena base. The
1690        // limit is the arena, and nothing was handed out inside it.
1691        assert!(allocator > arena.base_addr(), "{allocator:#x}");
1692        assert!(allocator < arena.base_addr() + 0x4000, "{allocator:#x}");
1693
1694        sbox.restore(small).unwrap();
1695        let echo: String = sbox.call("Echo", "recovered".to_string()).unwrap();
1696        assert_eq!(echo, "recovered");
1697    }
1698
1699    /// The scratch a guest has allocated covers every page it wrote, grows
1700    /// as it writes more, and starts again from zero at a snapshot and at a
1701    /// restore.
1702    #[test]
1703    fn scratch_allocated_bytes_counts_written_pages() {
1704        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1705            .scratch_size(16 << 20)
1706            .build()
1707            .unwrap();
1708        let snapshot = sbox.snapshot().unwrap();
1709        assert_eq!(sbox.scratch_allocated_bytes().unwrap(), 0);
1710
1711        sbox.call::<()>("AllocAndWritePattern", 1u64 << 20).unwrap();
1712        let one = sbox.scratch_allocated_bytes().unwrap();
1713        assert!(one >= 1 << 20, "{one}");
1714        // The new pattern is built before the old one is dropped.
1715        sbox.call::<()>("AllocAndWritePattern", 2u64 << 20).unwrap();
1716        let three = sbox.scratch_allocated_bytes().unwrap();
1717        assert!(three >= 3 << 20, "{three}");
1718
1719        sbox.restore(snapshot).unwrap();
1720        assert_eq!(sbox.scratch_allocated_bytes().unwrap(), 0);
1721        sbox.call::<()>("AllocAndWritePattern", 1u64 << 20).unwrap();
1722        assert_eq!(sbox.scratch_allocated_bytes().unwrap(), one);
1723        sbox.snapshot().unwrap();
1724        assert_eq!(sbox.scratch_allocated_bytes().unwrap(), 0);
1725    }
1726
1727    /// A resized capture installs like any capture. The sandbox keeps its
1728    /// state, folds mapped regions into the snapshot, and caches it.
1729    #[test]
1730    fn resized_capture_installs_the_snapshot() {
1731        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1732            .scratch_size(8 << 20)
1733            .build()
1734            .unwrap();
1735        sbox.call::<i32>("AddToStatic", 42i32).unwrap();
1736        let map_mem = allocate_guest_memory();
1737        let guest_base = 0x200000000_u64;
1738        let region = region_for_memory(&map_mem, guest_base as usize, MemoryRegionFlags::READ);
1739        // SAFETY: `map_mem` outlives the mapping, which the capture removes.
1740        unsafe { sbox.map_region(&region).unwrap() };
1741        let len = hyperlight_common::vmem::PAGE_SIZE as u64;
1742        let mapped = sbox
1743            .call::<Vec<u8>>("ReadMappedBuffer", (guest_base, len, true))
1744            .unwrap();
1745
1746        let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1747
1748        assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1749        assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
1750        assert!(Arc::ptr_eq(&sbox.snapshot().unwrap(), &small));
1751        assert_virtq_attached(&sbox);
1752        assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 42);
1753        let read = sbox
1754            .call::<Vec<u8>>("ReadMappedBuffer", (guest_base, len, false))
1755            .unwrap();
1756        assert_eq!(read, mapped);
1757    }
1758
1759    /// The guest applies host requests on its next entry. A resized capture
1760    /// before that entry carries them to the new scratch.
1761    #[test]
1762    fn resized_capture_keeps_pending_guest_requests() {
1763        use hyperlight_common::layout::{
1764            SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET, SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
1765        };
1766
1767        fn requests(sbox: &Sandbox) -> [u64; 2] {
1768            let scratch = &sbox.mem_mgr.scratch_mem;
1769            [
1770                SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
1771                SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
1772            ]
1773            .map(|offset| {
1774                scratch
1775                    .read::<u64>(scratch.mem_size() - offset as usize)
1776                    .unwrap()
1777            })
1778        }
1779
1780        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1781            .scratch_size(8 << 20)
1782            .build()
1783            .unwrap();
1784        let snapshot = sbox.snapshot().unwrap();
1785        sbox.restore(snapshot).unwrap();
1786        sbox.log_level(tracing_core::LevelFilter::INFO).unwrap();
1787        let pending = requests(&sbox);
1788        assert!(pending.iter().all(|&request| request != 0));
1789
1790        sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1791
1792        assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1793        assert_eq!(requests(&sbox), pending);
1794    }
1795
1796    /// The capture after a resized one builds on it. Without guest progress
1797    /// it shares every layer.
1798    #[test]
1799    #[cfg(not(unshared_snapshot_mem))]
1800    fn capture_after_resized_capture_reuses_its_layers() {
1801        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1802            .scratch_size(8 << 20)
1803            .build()
1804            .unwrap();
1805        let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1806        let map_mem = allocate_guest_memory();
1807        let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
1808        // SAFETY: `map_mem` outlives the mapping, which the capture removes.
1809        unsafe { sbox.map_region(&region).unwrap() };
1810
1811        let next = sbox.snapshot().unwrap();
1812
1813        assert!(!Arc::ptr_eq(&small, &next));
1814        assert_eq!(next.layout().get_scratch_size(), 2 << 20);
1815        let small_layers = small.snapshot_memory().layers();
1816        let next_layers = next.snapshot_memory().layers();
1817        assert_eq!(next_layers.len(), small_layers.len());
1818        for layer in next_layers.iter() {
1819            assert!(small_layers.iter().any(|kept| Arc::ptr_eq(kept, layer)));
1820        }
1821    }
1822
1823    /// Snapshots of different scratch sizes form one tree. Each restores its
1824    /// own state and scratch size, including after a save and load.
1825    #[test]
1826    fn snapshots_of_different_scratch_sizes_restore_their_state() {
1827        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1828            .scratch_size(4 << 20)
1829            .build()
1830            .unwrap();
1831        sbox.call::<i32>("AddToStatic", 1i32).unwrap();
1832        let grown = sbox.snapshot_with_options(&scratch(8 << 20)).unwrap();
1833        sbox.call::<i32>("AddToStatic", 2i32).unwrap();
1834        let shrunk = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1835        sbox.call::<i32>("AddToStatic", 3i32).unwrap();
1836        let unchanged = sbox.snapshot().unwrap();
1837
1838        sbox.restore(grown.clone()).unwrap();
1839        sbox.call::<i32>("AddToStatic", 10i32).unwrap();
1840        let branch = sbox.snapshot_with_options(&scratch(4 << 20)).unwrap();
1841
1842        for (snapshot, size, value) in [
1843            (&grown, 8 << 20, 1),
1844            (&shrunk, 2 << 20, 3),
1845            (&unchanged, 2 << 20, 6),
1846            (&branch, 4 << 20, 11),
1847        ] {
1848            sbox.restore(snapshot.clone()).unwrap();
1849            assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), size);
1850            assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), value);
1851        }
1852
1853        let dir = tempfile::tempdir().unwrap();
1854        let tag = crate::sandbox::snapshot::OciTag::new("branch").unwrap();
1855        branch.save(dir.path(), &tag).unwrap();
1856        let loaded = crate::sandbox::snapshot::Snapshot::checked_load(dir.path(), tag).unwrap();
1857        let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1858            .build()
1859            .unwrap();
1860        target.restore(Arc::new(loaded)).unwrap();
1861        assert_eq!(target.mem_mgr.scratch_mem.mem_size(), 4 << 20);
1862        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
1863    }
1864
1865    #[test]
1866    #[cfg(not(gdb))]
1867    fn resized_capture_scratch_mapping_failure_is_unrecoverable() {
1868        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1869            .scratch_size(8 << 20)
1870            .build()
1871            .unwrap();
1872        let fault_plan = sandbox
1873            .vm
1874            .inject_vm_faults([VmOperation::Map(MemoryRegionType::Scratch)]);
1875
1876        let error = sandbox
1877            .snapshot_with_options(&scratch(2 << 20))
1878            .err()
1879            .unwrap();
1880
1881        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
1882        assert!(fault_plan.is_consumed());
1883        assert_eq!(sandbox.status(), SandboxStatus::Unrecoverable);
1884    }
1885
1886    #[test]
1887    fn poison() {
1888        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1889            .build()
1890            .unwrap();
1891        let snapshot = sbox.snapshot().unwrap();
1892
1893        // poison on purpose
1894        let res = sbox
1895            .call::<()>("guest_panic", "hello".to_string())
1896            .unwrap_err();
1897        assert!(
1898            matches!(res, HyperlightError::GuestAborted(code, context) if code == ErrorCode::UnknownError as u8 && context.contains("hello"))
1899        );
1900        assert!(sbox.status().is_poisoned());
1901
1902        // guest calls should fail when poisoned
1903        let res = sbox
1904            .call::<()>("guest_panic", "hello2".to_string())
1905            .unwrap_err();
1906        assert!(matches!(res, HyperlightError::PoisonedSandbox));
1907
1908        // snapshot should fail when poisoned
1909        if let Err(e) = sbox.snapshot() {
1910            assert!(sbox.status().is_poisoned());
1911            assert!(matches!(e, HyperlightError::PoisonedSandbox));
1912        } else {
1913            panic!("Snapshot should fail");
1914        }
1915
1916        // map_region should fail when poisoned
1917        {
1918            let map_mem = allocate_guest_memory();
1919            let guest_base = 0x0;
1920            let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
1921            let res = unsafe { sbox.map_region(&region) }.unwrap_err();
1922            assert!(matches!(res, HyperlightError::PoisonedSandbox));
1923        }
1924
1925        // map_file_cow should fail when poisoned
1926        {
1927            let temp_file = std::env::temp_dir().join("test_poison_map_file.bin");
1928            let res = sbox.map_file_cow(&temp_file, 0x0).unwrap_err();
1929            assert!(matches!(res, HyperlightError::PoisonedSandbox));
1930            std::fs::remove_file(&temp_file).ok(); // Clean up
1931        }
1932
1933        // call_guest_function_by_name (deprecated) should fail when poisoned
1934        #[allow(deprecated)]
1935        let res = sbox
1936            .call_guest_function_by_name::<String>("Echo", "test".to_string())
1937            .unwrap_err();
1938        assert!(matches!(res, HyperlightError::PoisonedSandbox));
1939
1940        // restore to non-poisoned snapshot should work and clear poison
1941        sbox.restore(snapshot.clone()).unwrap();
1942        assert_eq!(sbox.status(), SandboxStatus::Ready);
1943
1944        // guest calls should work again after restore
1945        let res = sbox.call::<String>("Echo", "hello2".to_string()).unwrap();
1946        assert_eq!(res, "hello2".to_string());
1947        assert_eq!(sbox.status(), SandboxStatus::Ready);
1948
1949        // re-poison on purpose
1950        let res = sbox
1951            .call::<()>("guest_panic", "hello".to_string())
1952            .unwrap_err();
1953        assert!(
1954            matches!(res, HyperlightError::GuestAborted(code, context) if code == ErrorCode::UnknownError as u8 && context.contains("hello"))
1955        );
1956        assert!(sbox.status().is_poisoned());
1957
1958        // restore to non-poisoned snapshot should work again
1959        sbox.restore(snapshot.clone()).unwrap();
1960        assert_eq!(sbox.status(), SandboxStatus::Ready);
1961
1962        // guest calls should work again
1963        let res = sbox.call::<String>("Echo", "hello3".to_string()).unwrap();
1964        assert_eq!(res, "hello3".to_string());
1965        assert_eq!(sbox.status(), SandboxStatus::Ready);
1966
1967        // snapshot should work again
1968        let _ = sbox.snapshot().unwrap();
1969    }
1970
1971    /// Make sure transport buffers are reclaimed after host call failures.
1972    #[test]
1973    fn host_func_error() {
1974        let path = simple_guest_as_pathbuf();
1975        let mut sandbox = SandboxBuilder::from_file(path)
1976            .host_function("HostError", || -> Result<()> {
1977                Err(HyperlightError::Error("hi".to_string()))
1978            })
1979            .build()
1980            .unwrap();
1981
1982        // Repeated calls exhaust the transport if buffers leak.
1983        for _ in 0..1000 {
1984            let result = sandbox
1985                .call::<i64>(
1986                    "CallGivenParamlessHostFuncThatReturnsI64",
1987                    "HostError".to_string(),
1988                )
1989                .unwrap_err();
1990
1991            assert!(
1992                matches!(result, HyperlightError::GuestError(code, msg) if code == ErrorCode::HostFunctionError && msg == "hi"),
1993            );
1994        }
1995    }
1996
1997    #[test]
1998    fn call_host_func_expect_error() {
1999        let path = simple_guest_as_pathbuf();
2000        let mut sandbox = SandboxBuilder::from_file(path).build().unwrap();
2001        sandbox
2002            .call::<()>("CallHostExpectError", "SomeUnknownHostFunc".to_string())
2003            .unwrap();
2004    }
2005
2006    /// Make sure transport buffers are reclaimed after guest calls.
2007    #[test]
2008    fn transport_buffers_are_reclaimed() {
2009        let path = simple_guest_as_pathbuf();
2010        let mut sandbox = SandboxBuilder::from_file(path)
2011            .host_function("HostAdd", |a: i32, b: i32| a + b)
2012            .build()
2013            .unwrap();
2014
2015        // will exhaust io if leaky. Tests both success and error paths
2016        for _ in 0..1000 {
2017            let result = sandbox.call::<i32>("Add", (5i32, 10i32)).unwrap();
2018            assert_eq!(result, 15);
2019            let result = sandbox.call::<i32>("AddToStaticAndFail", ()).unwrap_err();
2020            assert!(
2021                matches!(result, HyperlightError::GuestError (code, msg ) if code == ErrorCode::GuestError && msg == "Crash on purpose")
2022            );
2023        }
2024    }
2025
2026    /// Tests that call_guest_function_by_name restores the state correctly
2027    #[test]
2028    fn test_call_guest_function_by_name() {
2029        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2030            .build()
2031            .unwrap();
2032
2033        let snapshot = sbox.snapshot().unwrap();
2034
2035        let _ = sbox.call::<i32>("AddToStatic", 5i32).unwrap();
2036        let res: i32 = sbox.call("GetStatic", ()).unwrap();
2037        assert_eq!(res, 5);
2038
2039        sbox.restore(snapshot).unwrap();
2040        #[allow(deprecated)]
2041        let _ = sbox
2042            .call_guest_function_by_name::<i32>("AddToStatic", 5i32)
2043            .unwrap();
2044        #[allow(deprecated)]
2045        let res: i32 = sbox.call_guest_function_by_name("GetStatic", ()).unwrap();
2046        assert_eq!(res, 0);
2047    }
2048
2049    // Checks that 1,000 calls work with constrained guest memory.
2050    // This catches guest stack reset and heap leaks.
2051    #[test]
2052    fn test_with_small_scratch() {
2053        // Leave room for runtime allocations and eagerly copied page tables.
2054        let scratch_size = {
2055            let defaults = SandboxConfiguration::default();
2056            let layout =
2057                crate::mem::layout::SandboxMemoryLayout::new(defaults, 0, 0, None).unwrap();
2058            layout.min_scratch().next_multiple_of(page_size::get())
2059        } + 0x40000;
2060
2061        let mut sbox1 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2062            .scratch_size(scratch_size)
2063            .build()
2064            .unwrap();
2065
2066        for _ in 0..1000 {
2067            sbox1.call::<String>("Echo", "hello".to_string()).unwrap();
2068        }
2069
2070        let mut sbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2071            .scratch_size(scratch_size)
2072            .build()
2073            .unwrap();
2074
2075        for i in 0..1000 {
2076            sbox2
2077                .call::<i32>(
2078                    "PrintUsingPrintf",
2079                    format!("Hello World {}\n", i).to_string(),
2080                )
2081                .unwrap();
2082        }
2083    }
2084
2085    /// Tests that evolving from Sandbox to Sandbox creates a new state
2086    /// and restoring a snapshot from before evolving restores the previous state
2087    #[test]
2088    fn snapshot_evolve_restore_handles_state_correctly() {
2089        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2090            .build()
2091            .unwrap();
2092
2093        let snapshot = sbox.snapshot().unwrap();
2094
2095        let _ = sbox.call::<i32>("AddToStatic", 5i32).unwrap();
2096
2097        let res: i32 = sbox.call("GetStatic", ()).unwrap();
2098        assert_eq!(res, 5);
2099
2100        sbox.restore(snapshot).unwrap();
2101        let res: i32 = sbox.call("GetStatic", ()).unwrap();
2102        assert_eq!(res, 0);
2103    }
2104
2105    #[test]
2106    fn snapshots_checkpoint_only_dirty_transport() {
2107        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2108            .build()
2109            .unwrap();
2110
2111        assert!(sandbox.transport_dirty);
2112        let initial = sandbox.snapshot().unwrap();
2113        assert!(!sandbox.transport_dirty);
2114
2115        let restored = SandboxBuilder::from_snapshot(initial).build().unwrap();
2116        assert!(!restored.transport_dirty);
2117
2118        sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2119        assert!(sandbox.transport_dirty);
2120
2121        let first = sandbox.snapshot().unwrap();
2122        assert!(!sandbox.transport_dirty);
2123        let cached = sandbox.snapshot().unwrap();
2124        assert!(Arc::ptr_eq(&first, &cached));
2125        assert!(!sandbox.transport_dirty);
2126
2127        sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2128        assert!(sandbox.transport_dirty);
2129        sandbox.snapshot().unwrap();
2130        assert!(!sandbox.transport_dirty);
2131    }
2132
2133    #[test]
2134    fn snapshots_reject_noncanonical_transport_after_checkpoint() {
2135        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2136            .build()
2137            .unwrap();
2138
2139        sandbox.checkpoint_transport_for_snapshot().unwrap();
2140        sandbox.snapshot = None;
2141
2142        let generation = sandbox.mem_mgr.snapshot_count;
2143        let ring = sandbox.mem_mgr.layout.get_transport_arena().g2h_ring_addr();
2144        let scratch_base =
2145            hyperlight_common::layout::scratch_base_gpa(sandbox.mem_mgr.layout.get_scratch_size());
2146        let offset = usize::try_from(ring - scratch_base).unwrap();
2147
2148        sandbox.mem_mgr.scratch_mem.write::<u64>(offset, 1).unwrap();
2149
2150        let Err(error) = sandbox.snapshot() else {
2151            panic!("expected invalid canonical transport");
2152        };
2153
2154        assert!(
2155            error.to_string().contains("invalid canonical G2H image"),
2156            "{error}"
2157        );
2158        assert_eq!(sandbox.mem_mgr.snapshot_count, generation);
2159        assert!(sandbox.snapshot.is_none());
2160
2161        // Restore the canonical descriptor before continuing the source.
2162        sandbox.mem_mgr.scratch_mem.write::<u64>(offset, 0).unwrap();
2163        let expected = vec![0x5a; 2 * hyperlight_common::vmem::PAGE_SIZE + 137];
2164        let actual: Vec<u8> = sandbox.call("EchoGuestVecBytes", expected.clone()).unwrap();
2165        assert_eq!(actual, expected);
2166    }
2167
2168    #[test]
2169    fn snapshot_checkpoint_ignores_idle_cancellation() {
2170        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2171            .build()
2172            .unwrap();
2173
2174        sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2175        assert!(!sandbox.interrupt_handle().kill());
2176
2177        sandbox.snapshot().unwrap();
2178        assert_eq!(sandbox.status(), SandboxStatus::Ready);
2179        assert!(!sandbox.transport_dirty);
2180        assert!(!sandbox.interrupt_handle().kill());
2181        assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 5);
2182    }
2183
2184    #[test]
2185    fn snapshot_checkpoint_clears_partial_abort_bytes() {
2186        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2187            .build()
2188            .unwrap();
2189
2190        sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2191        sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
2192
2193        sandbox.snapshot().unwrap();
2194
2195        assert!(sandbox.mem_mgr.abort_buffer.is_empty());
2196        assert_eq!(sandbox.status(), SandboxStatus::Ready);
2197    }
2198
2199    #[test]
2200    fn restricted_dispatch_rejects_host_calls() {
2201        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2202            .build()
2203            .unwrap();
2204
2205        let call = FunctionCall::new(
2206            "PrintOutput".into(),
2207            Some(vec![ParameterValue::String("checkpoint".into())]),
2208            FunctionCallType::Guest,
2209            i32::TYPE,
2210        );
2211        sandbox.mem_mgr.write_guest_function_call(&call).unwrap();
2212
2213        let error = sandbox.dispatch_guest_call_restricted().unwrap_err();
2214
2215        assert!(
2216            error.to_string().contains("during a snapshot checkpoint"),
2217            "{error}"
2218        );
2219        assert_eq!(sandbox.status(), SandboxStatus::Poisoned);
2220        assert_eq!(sandbox.mem_mgr.execution_mode, ExecutionMode::Unrestricted);
2221    }
2222
2223    #[test]
2224    fn restore_resets_execution_mode() {
2225        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2226            .build()
2227            .unwrap();
2228
2229        let snapshot = sandbox.snapshot().unwrap();
2230        sandbox.mem_mgr.execution_mode = ExecutionMode::Restricted;
2231        sandbox.restore(snapshot).unwrap();
2232
2233        sandbox
2234            .call::<i32>("PrintOutput", "restored".to_string())
2235            .unwrap();
2236    }
2237
2238    #[test]
2239    fn guest_execution_preserves_pre_entry_cancellation() {
2240        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2241            .build()
2242            .unwrap();
2243        sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2244        sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
2245
2246        let error = sandbox
2247            .with_guest_execution(|sandbox| {
2248                sandbox.mem_mgr.begin_snapshot_checkpoint()?;
2249                assert!(!sandbox.interrupt_handle().kill());
2250                sandbox.dispatch_guest_call()
2251            })
2252            .unwrap_err();
2253
2254        assert!(matches!(error, HyperlightError::ExecutionCanceledByHost()));
2255        assert_eq!(sandbox.status(), SandboxStatus::Poisoned);
2256        assert!(sandbox.mem_mgr.abort_buffer.is_empty());
2257    }
2258
2259    #[test]
2260    fn snapshots_preserve_retained_transport_and_clear_abort_state() {
2261        let path = simple_guest_as_pathbuf();
2262        let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
2263        sandbox
2264            .register("HostEchoByteChunks", |value: Vec<Bytes>| value)
2265            .unwrap();
2266
2267        let mut sandbox = sandbox.evolve().unwrap();
2268        let retained = vec![Bytes::from(vec![0xa5; 6 * 1024])];
2269
2270        for (retain, release) in [
2271            ("RetainGuestByteChunks", "ReleaseGuestByteChunks"),
2272            ("RetainHostByteChunks", "ReleaseHostByteChunks"),
2273        ] {
2274            let retained_len: i32 = sandbox.call(retain, retained.clone()).unwrap();
2275            assert_eq!(retained_len, 6 * 1024);
2276            sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
2277
2278            let snapshot = sandbox.snapshot().unwrap();
2279            assert!(!sandbox.status().is_poisoned());
2280            assert!(!sandbox.transport_dirty);
2281            assert!(sandbox.mem_mgr.abort_buffer.is_empty());
2282
2283            assert_eq!(sandbox.call::<i32>(release, ()).unwrap(), retained_len);
2284
2285            sandbox.restore(snapshot).unwrap();
2286            assert_eq!(sandbox.call::<i32>(release, ()).unwrap(), retained_len);
2287            sandbox.snapshot().unwrap();
2288            assert!(!sandbox.transport_dirty);
2289        }
2290    }
2291
2292    #[test]
2293    fn retained_restore_is_ready_for_first_request() {
2294        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2295            .build()
2296            .unwrap();
2297        sandbox
2298            .call::<i32>(
2299                "RetainGuestByteChunks",
2300                vec![Bytes::from(vec![0x5a; 6 * 1024])],
2301            )
2302            .unwrap();
2303        sandbox.checkpoint_transport_for_snapshot().unwrap();
2304        let source_root = sandbox.vm.get_root_pt().unwrap();
2305        let snapshot = sandbox.snapshot().unwrap();
2306        assert_eq!(sandbox.vm.get_root_pt().unwrap(), source_root);
2307
2308        sandbox.restore(snapshot.clone()).unwrap();
2309        let mut clone =
2310            Sandbox::from_snapshot(snapshot, crate::HostFunctions::default(), None).unwrap();
2311        let expected = vec![0x3c; 3 * hyperlight_common::vmem::PAGE_SIZE + 117];
2312        let call = FunctionCall::new(
2313            "EchoGuestVecBytes".into(),
2314            Some(vec![ParameterValue::VecBytes(expected.clone())]),
2315            FunctionCallType::Guest,
2316            Vec::<u8>::TYPE,
2317        );
2318
2319        for restored in [&mut sandbox, &mut clone] {
2320            restored.transport_dirty = true;
2321            let cid = restored.mem_mgr.write_guest_function_call(&call).unwrap();
2322            restored.dispatch_guest_call().unwrap();
2323            let value = restored
2324                .mem_mgr
2325                .read_h2g_result_from_g2h(cid)
2326                .unwrap()
2327                .into_inner()
2328                .unwrap();
2329            assert_eq!(Vec::<u8>::from_value(value).unwrap(), expected);
2330        }
2331
2332        assert_eq!(
2333            clone.call::<i32>("ReleaseGuestByteChunks", ()).unwrap(),
2334            6 * 1024
2335        );
2336    }
2337
2338    #[test]
2339    fn test_trigger_exception_on_guest() {
2340        let mut multi_use_sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2341            .build()
2342            .unwrap();
2343
2344        let res: Result<()> = multi_use_sandbox.call("TriggerException", ());
2345
2346        assert!(res.is_err());
2347
2348        match res.unwrap_err() {
2349            HyperlightError::GuestAborted(_, msg) => {
2350                // msg should indicate we got an invalid opcode exception
2351                #[cfg(target_arch = "x86_64")]
2352                assert!(msg.contains("InvalidOpcode"));
2353                #[cfg(target_arch = "aarch64")]
2354                assert!(msg.contains("0x2000000"));
2355            }
2356            e => panic!("Expected HyperlightError::GuestAborted but got {:?}", e),
2357        }
2358    }
2359
2360    fn create_many_on_threads_test<const NUM_THREADS: usize, const SANDBOXES_PER_THREAD: usize>() {
2361        // barrier to make sure all threads start their work simultaneously
2362        let start_barrier = Arc::new(Barrier::new(NUM_THREADS + 1));
2363        let mut thread_handles = vec![];
2364
2365        for _ in 0..NUM_THREADS {
2366            let barrier = start_barrier.clone();
2367
2368            let handle = thread::spawn(move || {
2369                barrier.wait();
2370
2371                for _ in 0..SANDBOXES_PER_THREAD {
2372                    let guest_path = simple_guest_as_pathbuf();
2373                    let mut sandbox = SandboxBuilder::from_file(guest_path).build().unwrap();
2374
2375                    let result: i32 = sandbox.call("GetStatic", ()).unwrap();
2376                    assert_eq!(result, 0);
2377                }
2378            });
2379
2380            thread_handles.push(handle);
2381        }
2382
2383        start_barrier.wait();
2384
2385        for handle in thread_handles {
2386            handle.join().unwrap();
2387        }
2388    }
2389
2390    #[test]
2391    fn create_200_sandboxes() {
2392        create_many_on_threads_test::<20, 10>();
2393    }
2394
2395    #[test]
2396    fn create_200_threads() {
2397        #[cfg(target_arch = "aarch64")]
2398        create_many_on_threads_test::<32, 1>();
2399        #[cfg(not(target_arch = "aarch64"))]
2400        create_many_on_threads_test::<200, 1>();
2401    }
2402
2403    #[test]
2404    fn create_2000_sandboxes() {
2405        #[cfg(target_arch = "aarch64")]
2406        create_many_on_threads_test::<20, 100>();
2407        #[cfg(not(target_arch = "aarch64"))]
2408        create_many_on_threads_test::<200, 10>();
2409    }
2410
2411    #[test]
2412    fn test_mmap() {
2413        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2414            .build()
2415            .unwrap();
2416
2417        let expected = b"hello world";
2418        let map_mem = page_aligned_memory(expected);
2419        let guest_base = 0x1_0000_0000; // Arbitrary guest base address
2420
2421        unsafe {
2422            sbox.map_region(&region_for_memory(
2423                &map_mem,
2424                guest_base,
2425                MemoryRegionFlags::READ,
2426            ))
2427            .unwrap();
2428        }
2429
2430        let _guard = map_mem.lock.try_read().unwrap();
2431        let actual: Vec<u8> = sbox
2432            .call(
2433                "ReadMappedBuffer",
2434                (guest_base as u64, expected.len() as u64, true),
2435            )
2436            .unwrap();
2437
2438        assert_eq!(actual, expected);
2439    }
2440
2441    // Makes sure MemoryRegionFlags::READ | MemoryRegionFlags::EXECUTE executable but not writable
2442    #[test]
2443    fn test_mmap_write_exec() {
2444        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2445            .build()
2446            .unwrap();
2447
2448        #[cfg(target_arch = "x86_64")]
2449        let expected = &[0x90, 0x90, 0x90, 0xC3]; // NOOP slide to RET
2450        #[cfg(target_arch = "aarch64")]
2451        let expected = &[0x1f, 0x20, 0x03, 0xd5, 0xc0, 0x03, 0x5f, 0xd6];
2452        let map_mem = page_aligned_memory(expected);
2453        let guest_base = 0x1_0000_0000; // Arbitrary guest base address
2454
2455        unsafe {
2456            sbox.map_region(&region_for_memory(
2457                &map_mem,
2458                guest_base,
2459                MemoryRegionFlags::READ | MemoryRegionFlags::EXECUTE,
2460            ))
2461            .unwrap();
2462        }
2463
2464        let _guard = map_mem.lock.try_read().unwrap();
2465
2466        // Execute should pass since memory is executable
2467        let succeed = sbox
2468            .call::<bool>(
2469                "ExecMappedBuffer",
2470                (guest_base as u64, expected.len() as u64),
2471            )
2472            .unwrap();
2473        assert!(succeed, "Expected execution of mapped buffer to succeed");
2474
2475        // write should fail because the memory is mapped as read-only
2476        let err = sbox
2477            .call::<bool>(
2478                "WriteMappedBuffer",
2479                (guest_base as u64, expected.len() as u64),
2480            )
2481            .unwrap_err();
2482
2483        match err {
2484            HyperlightError::MemoryAccessViolation(addr, ..) if addr == guest_base as u64 => {}
2485            _ => panic!("Expected MemoryAccessViolation error"),
2486        };
2487    }
2488
2489    fn page_aligned_memory(src: &[u8]) -> GuestSharedMemory {
2490        let page_size = page_size::get();
2491        let len = src.len().div_ceil(page_size) * page_size;
2492
2493        let mut mem = ExclusiveSharedMemory::new(len).unwrap();
2494        mem.copy_from_slice(src, 0).unwrap();
2495
2496        let (_, guest_mem) = mem.build();
2497
2498        guest_mem
2499    }
2500
2501    fn region_for_memory(
2502        mem: &GuestSharedMemory,
2503        guest_base: usize,
2504        flags: MemoryRegionFlags,
2505    ) -> MemoryRegion {
2506        let len = mem.mem_size();
2507        MemoryRegion {
2508            host_region: mem.host_region_base()..mem.host_region_end(),
2509            guest_region: guest_base..(guest_base + len),
2510            flags,
2511            region_type: MemoryRegionType::Heap,
2512        }
2513    }
2514
2515    fn allocate_guest_memory() -> GuestSharedMemory {
2516        let mut data = vec![0; 2 * page_size::get()];
2517        data[..b"test data for snapshot".len()].copy_from_slice(b"test data for snapshot");
2518        page_aligned_memory(&data)
2519    }
2520
2521    #[test]
2522    fn snapshot_restore_handles_remapping_correctly() {
2523        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2524            .build()
2525            .unwrap();
2526
2527        // 1. Take snapshot 1 with no additional regions mapped
2528        let snapshot1 = sbox.snapshot().unwrap();
2529        assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2530
2531        // 2. Map a memory region
2532        let map_mem = allocate_guest_memory();
2533        let guest_base = 0x200000000_usize;
2534        let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2535
2536        unsafe { sbox.map_region(&region).unwrap() };
2537        assert_eq!(sbox.vm.get_mapped_regions().count(), 1);
2538        let orig_read = sbox
2539            .call::<Vec<u8>>(
2540                "ReadMappedBuffer",
2541                (
2542                    guest_base as u64,
2543                    hyperlight_common::vmem::PAGE_SIZE as u64,
2544                    true,
2545                ),
2546            )
2547            .unwrap();
2548
2549        // 3. Take snapshot 2 with 1 region mapped
2550        let snapshot2 = sbox.snapshot().unwrap();
2551        assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2552
2553        // 4. Re(store to snapshot 1 (should unmap the region)
2554        sbox.restore(snapshot1.clone()).unwrap();
2555        assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2556        let is_mapped = sbox
2557            .call::<bool>("CheckMapped", (guest_base as u64,))
2558            .unwrap();
2559        assert!(!is_mapped);
2560
2561        // 5. Restore forward to snapshot 2 (should have folded the
2562        //    region into the snapshot)
2563        sbox.restore(snapshot2.clone()).unwrap();
2564        assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2565        let is_mapped = sbox
2566            .call::<bool>("CheckMapped", (guest_base as u64,))
2567            .unwrap();
2568        assert!(is_mapped);
2569
2570        // Verify the region is the same
2571        let new_read = sbox
2572            .call::<Vec<u8>>(
2573                "ReadMappedBuffer",
2574                (
2575                    guest_base as u64,
2576                    hyperlight_common::vmem::PAGE_SIZE as u64,
2577                    false,
2578                ),
2579            )
2580            .unwrap();
2581        assert_eq!(new_read, orig_read);
2582    }
2583
2584    /// `map_region` invalidates the cached snapshot without running the guest,
2585    /// and its pages are not in guest VA space until a later call maps them. So
2586    /// the next capture walks the same page tables the previous one built, finds
2587    /// every page already backed by a layer, and materializes nothing.
2588    #[test]
2589    #[cfg(not(unshared_snapshot_mem))]
2590    fn capture_without_guest_progress_reuses_every_layer() {
2591        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2592            .build()
2593            .unwrap();
2594
2595        let first = sbox.snapshot().unwrap();
2596        assert!(
2597            !first.snapshot_memory().layers().is_empty(),
2598            "the first capture materializes the initialization delta"
2599        );
2600
2601        let map_mem = allocate_guest_memory();
2602        let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2603        // SAFETY: `map_mem` remains alive until capture removes the mapping.
2604        unsafe { sbox.map_region(&region).unwrap() };
2605
2606        let second = sbox.snapshot().unwrap();
2607        assert!(
2608            !Arc::ptr_eq(&first, &second),
2609            "map_region must invalidate the cached snapshot"
2610        );
2611        assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2612
2613        // Every data-bearing layer is shared with the previous snapshot.
2614        for layer in second.snapshot_memory().layers().iter() {
2615            assert!(
2616                first
2617                    .snapshot_memory()
2618                    .layers()
2619                    .iter()
2620                    .any(|previous| Arc::ptr_eq(previous, layer)),
2621                "capture copied a page it could have shared"
2622            );
2623        }
2624
2625        assert_eq!(
2626            second.snapshot_memory().layers().len(),
2627            first.snapshot_memory().layers().len()
2628        );
2629
2630        sbox.restore(second).unwrap();
2631        assert_eq!(
2632            sbox.call::<String>("Echo", "hello".to_string()).unwrap(),
2633            "hello"
2634        );
2635    }
2636
2637    /// Compaction copies mapped-region pages into the snapshot blob,
2638    /// so cross-instance restore preserves their contents without the
2639    /// target ever mapping the region.
2640    #[test]
2641    fn snapshot_restore_across_sandboxes_preserves_mapped_region_contents() {
2642        let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2643            .build()
2644            .unwrap();
2645
2646        let map_mem = allocate_guest_memory();
2647        let guest_base = 0x200000000_usize;
2648        let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2649        unsafe { source.map_region(&region).unwrap() };
2650
2651        // do_map=true installs the guest PTE for the region.
2652        let orig_read = source
2653            .call::<Vec<u8>>(
2654                "ReadMappedBuffer",
2655                (
2656                    guest_base as u64,
2657                    hyperlight_common::vmem::PAGE_SIZE as u64,
2658                    true,
2659                ),
2660            )
2661            .unwrap();
2662
2663        let snapshot = source.snapshot().unwrap();
2664
2665        let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2666            .build()
2667            .unwrap();
2668        assert_eq!(target.vm.get_mapped_regions().count(), 0);
2669
2670        target.restore(snapshot).unwrap();
2671        assert_eq!(target.vm.get_mapped_regions().count(), 0);
2672
2673        // Snapshot PTEs resolve to GPAs in the snapshot blob, so the
2674        // data is readable without re-mapping.
2675        let new_read = target
2676            .call::<Vec<u8>>(
2677                "ReadMappedBuffer",
2678                (
2679                    guest_base as u64,
2680                    hyperlight_common::vmem::PAGE_SIZE as u64,
2681                    false,
2682                ),
2683            )
2684            .unwrap();
2685        assert_eq!(new_read, orig_read);
2686    }
2687
2688    #[test]
2689    fn snapshot_restore_across_sandboxes() {
2690        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2691            .build()
2692            .unwrap();
2693
2694        let mut sandbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2695            .build()
2696            .unwrap();
2697
2698        sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2699        assert_eq!(sandbox2.call::<i32>("GetStatic", ()).unwrap(), 0);
2700
2701        let snapshot = sandbox.snapshot().unwrap();
2702        sandbox2.restore(snapshot).unwrap();
2703        assert_virtq_attached(&sandbox2);
2704        assert_eq!(sandbox2.call::<i32>("GetStatic", ()).unwrap(), 42);
2705    }
2706
2707    #[test]
2708    #[cfg(not(gdb))]
2709    fn snapshot_restore_keeps_current_base_mappings() {
2710        let path = simple_guest_as_pathbuf();
2711        let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2712            .unwrap()
2713            .evolve()
2714            .unwrap();
2715        let snapshot = sandbox.snapshot().unwrap();
2716        sandbox.restore(snapshot.clone()).unwrap();
2717        sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2718        let mappings = sandbox.vm.base_mapping_state();
2719        let fault_plan = sandbox
2720            .vm
2721            .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Snapshot)]);
2722
2723        sandbox.restore(snapshot).unwrap();
2724
2725        assert_eq!(sandbox.status(), SandboxStatus::Ready);
2726        let new_mappings = sandbox.vm.base_mapping_state();
2727        // Snapshot mapping must be identical (no remap).
2728        assert_eq!(new_mappings.0, mappings.0);
2729        // On Windows, scratch is freshly allocated each restore so the
2730        // base address may change, but the size must stay the same.
2731        assert_eq!(new_mappings.1.map(|m| m.1), mappings.1.map(|m| m.1));
2732        assert!(!fault_plan.is_consumed());
2733        assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 0);
2734    }
2735
2736    #[test]
2737    #[cfg(not(gdb))]
2738    fn snapshot_capture_mapping_failure_is_unrecoverable() {
2739        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2740            .build()
2741            .unwrap();
2742        let recovery_snapshot = sandbox.snapshot().unwrap();
2743        sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2744        let fault_plan = sandbox
2745            .vm
2746            .inject_vm_faults([VmOperation::Map(MemoryRegionType::Snapshot)]);
2747
2748        let error = sandbox.snapshot().err().unwrap();
2749
2750        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2751        assert!(fault_plan.is_consumed());
2752        assert_eq!(sandbox.status(), SandboxStatus::Unrecoverable);
2753        assert!(matches!(
2754            sandbox.restore(recovery_snapshot),
2755            Err(HyperlightError::UnrecoverableSandbox)
2756        ));
2757        assert!(matches!(
2758            sandbox.call::<i32>("GetStatic", ()),
2759            Err(HyperlightError::UnrecoverableSandbox)
2760        ));
2761        assert!(matches!(
2762            sandbox.snapshot(),
2763            Err(HyperlightError::UnrecoverableSandbox)
2764        ));
2765    }
2766
2767    #[test]
2768    #[cfg(not(gdb))]
2769    fn snapshot_restore_mapping_failure_is_unrecoverable() {
2770        let path = simple_guest_as_pathbuf();
2771        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2772            .unwrap()
2773            .evolve()
2774            .unwrap();
2775        source.call::<i32>("AddToStatic", 42i32).unwrap();
2776        let snapshot = source.snapshot().unwrap();
2777
2778        let path = simple_guest_as_pathbuf();
2779        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2780            .unwrap()
2781            .evolve()
2782            .unwrap();
2783        let mappings = target.vm.base_mapping_state();
2784        let fault_plan = target
2785            .vm
2786            .inject_vm_faults([VmOperation::Map(MemoryRegionType::Snapshot)]);
2787
2788        let error = target.restore(snapshot.clone()).unwrap_err();
2789        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2790        assert_eq!(target.status(), SandboxStatus::Unrecoverable);
2791        assert_eq!(target.vm.base_mapping_state(), (Vec::new(), mappings.1));
2792        assert!(fault_plan.is_consumed());
2793
2794        assert!(matches!(
2795            target.restore(snapshot),
2796            Err(HyperlightError::UnrecoverableSandbox)
2797        ));
2798        assert!(matches!(
2799            target.call::<i32>("GetStatic", ()),
2800            Err(HyperlightError::UnrecoverableSandbox)
2801        ));
2802        assert!(matches!(
2803            target.snapshot(),
2804            Err(HyperlightError::UnrecoverableSandbox)
2805        ));
2806
2807        let map_mem = allocate_guest_memory();
2808        let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2809        assert!(matches!(
2810            unsafe { target.map_region(&region) },
2811            Err(HyperlightError::UnrecoverableSandbox)
2812        ));
2813    }
2814
2815    #[test]
2816    #[cfg(not(gdb))]
2817    fn scratch_mapping_failure_clears_mapping_state() {
2818        let path = simple_guest_as_pathbuf();
2819        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2820            .unwrap()
2821            .evolve()
2822            .unwrap();
2823        let snapshot_mapping = target.vm.base_mapping_state().0;
2824        let scratch = ExclusiveSharedMemory::new(target.mem_mgr.scratch_mem.mem_size()).unwrap();
2825        let (_, scratch) = scratch.build();
2826        let fault_plan = target
2827            .vm
2828            .inject_vm_faults([VmOperation::Map(MemoryRegionType::Scratch)]);
2829
2830        target.vm.update_scratch_mapping(scratch).unwrap_err();
2831        assert_eq!(target.vm.base_mapping_state(), (snapshot_mapping, None));
2832        assert!(fault_plan.is_consumed());
2833    }
2834
2835    #[test]
2836    #[cfg(not(gdb))]
2837    fn snapshot_restore_unmapping_failure_is_unrecoverable() {
2838        let path = simple_guest_as_pathbuf();
2839        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2840            .unwrap()
2841            .evolve()
2842            .unwrap();
2843        source.call::<i32>("AddToStatic", 42i32).unwrap();
2844        let snapshot = source.snapshot().unwrap();
2845
2846        let path = simple_guest_as_pathbuf();
2847        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2848            .unwrap()
2849            .evolve()
2850            .unwrap();
2851        let mappings = target.vm.base_mapping_state();
2852        let fault_plan = target
2853            .vm
2854            .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Snapshot)]);
2855
2856        let error = target.restore(snapshot).unwrap_err();
2857        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2858        assert_eq!(target.status(), SandboxStatus::Unrecoverable);
2859        assert_eq!(target.vm.base_mapping_state(), mappings);
2860        assert!(fault_plan.is_consumed());
2861    }
2862
2863    #[test]
2864    #[cfg(not(gdb))]
2865    fn snapshot_restore_dynamic_unmapping_failure_is_recoverable() {
2866        let path = simple_guest_as_pathbuf();
2867        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2868            .unwrap()
2869            .evolve()
2870            .unwrap();
2871        source.call::<i32>("AddToStatic", 42i32).unwrap();
2872        let snapshot = source.snapshot().unwrap();
2873
2874        let path = simple_guest_as_pathbuf();
2875        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2876            .unwrap()
2877            .evolve()
2878            .unwrap();
2879        let map_mem = allocate_guest_memory();
2880        let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2881        unsafe { target.map_region(&region).unwrap() };
2882        let fault_plan = target
2883            .vm
2884            .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Heap)]);
2885
2886        let error = target.restore(snapshot.clone()).unwrap_err();
2887        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2888        assert!(target.status().is_poisoned());
2889        assert_eq!(target.vm.get_mapped_regions().count(), 1);
2890        assert!(fault_plan.is_consumed());
2891
2892        target.restore(snapshot).unwrap();
2893        assert_eq!(target.status(), SandboxStatus::Ready);
2894        assert_eq!(target.vm.get_mapped_regions().count(), 0);
2895        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2896    }
2897
2898    #[test]
2899    #[cfg(not(gdb))]
2900    fn snapshot_restore_partial_dynamic_unmapping_failure_is_recoverable() {
2901        let path = simple_guest_as_pathbuf();
2902        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2903            .unwrap()
2904            .evolve()
2905            .unwrap();
2906        source.call::<i32>("AddToStatic", 42i32).unwrap();
2907        let snapshot = source.snapshot().unwrap();
2908
2909        let path = simple_guest_as_pathbuf();
2910        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2911            .unwrap()
2912            .evolve()
2913            .unwrap();
2914        let first_mem = allocate_guest_memory();
2915        let first_region =
2916            region_for_memory(&first_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2917        unsafe { target.map_region(&first_region).unwrap() };
2918        let (mapped_path, _) =
2919            create_test_file("hyperlight_test_partial_dynamic_unmapping.bin", &[0; 4096]);
2920        target.map_file_cow(&mapped_path, 0x300000000).unwrap();
2921        let second_region = target.vm.get_mapped_regions().last().unwrap().clone();
2922        let fault_plan = target
2923            .vm
2924            .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::MappedFile)]);
2925
2926        let error = target.restore(snapshot.clone()).unwrap_err();
2927        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2928        assert!(target.status().is_poisoned());
2929        assert_eq!(
2930            target.vm.get_mapped_regions().collect::<Vec<_>>(),
2931            vec![&second_region]
2932        );
2933        assert!(fault_plan.is_consumed());
2934
2935        target.restore(snapshot).unwrap();
2936        assert_eq!(target.status(), SandboxStatus::Ready);
2937        assert_eq!(target.vm.get_mapped_regions().count(), 0);
2938        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2939        std::fs::remove_file(mapped_path).unwrap();
2940    }
2941
2942    #[test]
2943    #[cfg(not(gdb))]
2944    fn snapshot_capture_dynamic_unmapping_failure_is_recoverable() {
2945        let path = simple_guest_as_pathbuf();
2946        let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2947            .unwrap()
2948            .evolve()
2949            .unwrap();
2950        let recovery_snapshot = sandbox.snapshot().unwrap();
2951        sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2952
2953        let map_mem = allocate_guest_memory();
2954        let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2955        // SAFETY: `map_mem` remains alive until restore removes the mapping.
2956        unsafe { sandbox.map_region(&region).unwrap() };
2957        let fault_plan = sandbox
2958            .vm
2959            .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Heap)]);
2960
2961        let error = sandbox.snapshot().err().unwrap();
2962        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2963        assert!(sandbox.status().is_poisoned());
2964        assert!(fault_plan.is_consumed());
2965
2966        sandbox.restore(recovery_snapshot).unwrap();
2967        assert_eq!(sandbox.status(), SandboxStatus::Ready);
2968        assert_eq!(sandbox.vm.get_mapped_regions().count(), 0);
2969        assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 0);
2970    }
2971
2972    #[test]
2973    #[cfg(not(gdb))]
2974    fn snapshot_restore_vcpu_reset_failure_is_recoverable() {
2975        let path = simple_guest_as_pathbuf();
2976        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2977            .unwrap()
2978            .evolve()
2979            .unwrap();
2980        source.call::<i32>("AddToStatic", 42i32).unwrap();
2981        let snapshot = source.snapshot().unwrap();
2982
2983        #[cfg(target_arch = "x86_64")]
2984        let reset_operations = [
2985            VmOperation::SetRegs,
2986            VmOperation::SetDebugRegs,
2987            VmOperation::ResetXsave,
2988            VmOperation::SetSregs,
2989        ];
2990        #[cfg(target_arch = "aarch64")]
2991        let reset_operations = [VmOperation::ResetVcpu];
2992
2993        for reset_operation in reset_operations {
2994            let path = simple_guest_as_pathbuf();
2995            let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2996                .unwrap()
2997                .evolve()
2998                .unwrap();
2999            let fault_plan = target.vm.inject_vm_faults([reset_operation]);
3000
3001            let error = target.restore(snapshot.clone()).unwrap_err();
3002            assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
3003            assert!(target.status().is_poisoned());
3004            assert!(fault_plan.is_consumed());
3005            let (snapshot_mappings, scratch_mapping) = target.vm.base_mapping_state();
3006            assert!(!snapshot_mappings.is_empty());
3007            assert_eq!(
3008                scratch_mapping,
3009                Some((
3010                    target.mem_mgr.scratch_mem.base_addr(),
3011                    target.mem_mgr.scratch_mem.mem_size(),
3012                ))
3013            );
3014
3015            target.restore(snapshot.clone()).unwrap();
3016            assert_eq!(target.status(), SandboxStatus::Ready);
3017            assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3018        }
3019    }
3020
3021    #[test]
3022    #[cfg(not(gdb))]
3023    fn snapshot_capture_page_table_switch_failure_is_recoverable() {
3024        let path = simple_guest_as_pathbuf();
3025        let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3026            .unwrap()
3027            .evolve()
3028            .unwrap();
3029        let recovery_snapshot = sandbox.snapshot().unwrap();
3030        sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
3031
3032        let fault_plan = sandbox.vm.inject_vm_faults([VmOperation::SetSregs]);
3033
3034        let error = sandbox.snapshot().err().unwrap();
3035        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
3036        assert!(sandbox.status().is_poisoned());
3037        assert!(fault_plan.is_consumed());
3038
3039        sandbox.restore(recovery_snapshot).unwrap();
3040        assert_eq!(sandbox.status(), SandboxStatus::Ready);
3041        assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 0);
3042    }
3043
3044    #[test]
3045    #[cfg(not(gdb))]
3046    fn snapshot_capture_does_not_reset_vcpu() {
3047        #[cfg(target_arch = "x86_64")]
3048        let reset_operations = [
3049            VmOperation::SetRegs,
3050            VmOperation::SetDebugRegs,
3051            VmOperation::ResetXsave,
3052            VmOperation::SetMsrs,
3053        ];
3054        #[cfg(target_arch = "aarch64")]
3055        let reset_operations = [VmOperation::ResetVcpu];
3056
3057        for resize in [false, true] {
3058            for reset_operation in reset_operations {
3059                let path = simple_guest_as_pathbuf();
3060                let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3061                    .unwrap()
3062                    .evolve()
3063                    .unwrap();
3064                sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
3065                sandbox.checkpoint_transport_for_snapshot().unwrap();
3066                let mut options = SnapshotOptions::default();
3067                if resize {
3068                    options = scratch(sandbox.mem_mgr.layout.get_scratch_size() * 2);
3069                }
3070                let fault_plan = sandbox.vm.inject_vm_faults([reset_operation]);
3071
3072                sandbox.snapshot_with_options(&options).unwrap();
3073
3074                assert!(!fault_plan.is_consumed());
3075                assert_eq!(sandbox.status(), SandboxStatus::Ready);
3076            }
3077        }
3078    }
3079
3080    #[test]
3081    fn snapshot_capture_reclaims_internal_scratch_pages() {
3082        let path = simple_guest_as_pathbuf();
3083        let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3084            .unwrap()
3085            .evolve()
3086            .unwrap();
3087        sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
3088
3089        sandbox.snapshot().unwrap();
3090
3091        let allocator_offset = sandbox.mem_mgr.scratch_mem.mem_size()
3092            - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
3093        assert_eq!(
3094            sandbox
3095                .mem_mgr
3096                .scratch_mem
3097                .read::<u64>(allocator_offset)
3098                .unwrap(),
3099            sandbox.mem_mgr.first_free_scratch_gpa()
3100        );
3101    }
3102
3103    #[test]
3104    fn snapshot_capture_zeroes_reclaimed_scratch() {
3105        let path = simple_guest_as_pathbuf();
3106        let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3107            .unwrap()
3108            .evolve()
3109            .unwrap();
3110        let page_gva = 0x4000_0000_u64;
3111        let page_size = hyperlight_common::vmem::PAGE_SIZE;
3112        assert!(sandbox.call::<bool>("MapZeroInitPage", page_gva).unwrap());
3113        let allocator_offset = sandbox.mem_mgr.scratch_mem.mem_size()
3114            - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
3115        let used_end = sandbox
3116            .mem_mgr
3117            .scratch_mem
3118            .read::<u64>(allocator_offset)
3119            .unwrap();
3120        let before = sandbox
3121            .mem_mgr
3122            .scratch_mem
3123            .with_contents(|scratch| scratch.to_vec())
3124            .unwrap();
3125        sandbox.snapshot().unwrap();
3126
3127        let scratch_base =
3128            hyperlight_common::layout::scratch_base_gpa(sandbox.mem_mgr.scratch_mem.mem_size());
3129        let free_start =
3130            usize::try_from(sandbox.mem_mgr.first_free_scratch_gpa() - scratch_base).unwrap();
3131        let free_end = usize::try_from(used_end - scratch_base).unwrap();
3132        let after = sandbox
3133            .mem_mgr
3134            .scratch_mem
3135            .with_contents(|scratch| scratch.to_vec())
3136            .unwrap();
3137        assert!(before[free_start..free_end].iter().any(|&byte| byte != 0));
3138        assert!(after[free_start..free_end].iter().all(|&byte| byte == 0));
3139
3140        let page = sandbox
3141            .call::<Vec<u8>>("ReadMappedBuffer", (page_gva, page_size as u64, false))
3142            .unwrap();
3143        assert_eq!(page, vec![0; page_size]);
3144    }
3145
3146    /// The guest writes the allocator value that bounds install's scratch zeroing.
3147    /// Out-of-range values must not zero memory outside free scratch.
3148    #[test]
3149    fn snapshot_capture_clamps_guest_allocator_value() {
3150        use hyperlight_common::layout::{
3151            SCRATCH_TOP_ALLOCATOR_OFFSET, SCRATCH_TOP_SIZE_OFFSET, scratch_base_gpa,
3152        };
3153
3154        for allocator in [0, u64::MAX] {
3155            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3156                .build()
3157                .unwrap();
3158            sbox.snapshot().unwrap();
3159            let scratch_size = sbox.mem_mgr.scratch_mem.mem_size();
3160            let first_free = sbox.mem_mgr.first_free_scratch_gpa();
3161            let marker_offset =
3162                usize::try_from(first_free - scratch_base_gpa(scratch_size)).unwrap();
3163            let marker = 0x1234_5678_9abc_def0_u64;
3164            let scratch = &sbox.mem_mgr.scratch_mem;
3165            scratch.write(marker_offset, marker).unwrap();
3166            scratch
3167                .write(
3168                    scratch_size - SCRATCH_TOP_ALLOCATOR_OFFSET as usize,
3169                    allocator,
3170                )
3171                .unwrap();
3172            // The getter holds a corrupt allocator to the scratch the guest
3173            // can allocate.
3174            let arena = sbox.mem_mgr.layout.get_transport_arena().base_addr();
3175            let allocated = if allocator == 0 {
3176                0
3177            } else {
3178                arena - first_free
3179            };
3180            assert_eq!(sbox.scratch_allocated_bytes().unwrap(), allocated);
3181
3182            // `map_region` drops the cached snapshot without running the guest.
3183            let map_mem = allocate_guest_memory();
3184            let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
3185            // SAFETY: `map_mem` remains alive until capture removes the mapping.
3186            unsafe { sbox.map_region(&region).unwrap() };
3187            sbox.snapshot().unwrap();
3188
3189            let scratch = &sbox.mem_mgr.scratch_mem;
3190            assert_eq!(sbox.mem_mgr.first_free_scratch_gpa(), first_free);
3191            let expected = if allocator == 0 { marker } else { 0 };
3192            assert_eq!(scratch.read::<u64>(marker_offset).unwrap(), expected);
3193            assert_eq!(
3194                scratch
3195                    .read::<u64>(scratch_size - SCRATCH_TOP_SIZE_OFFSET as usize)
3196                    .unwrap(),
3197                scratch_size as u64
3198            );
3199            assert_eq!(
3200                sbox.call::<String>("Echo", "hello\n".to_string()).unwrap(),
3201                "hello\n"
3202            );
3203        }
3204    }
3205
3206    #[test]
3207    #[cfg(all(target_arch = "x86_64", not(gdb)))]
3208    fn snapshot_restore_msr_failure_is_recoverable() {
3209        let path = simple_guest_as_pathbuf();
3210        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3211            .unwrap()
3212            .evolve()
3213            .unwrap();
3214        source.call::<i32>("AddToStatic", 42i32).unwrap();
3215        let snapshot = source.snapshot().unwrap();
3216
3217        let path = simple_guest_as_pathbuf();
3218        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3219            .unwrap()
3220            .evolve()
3221            .unwrap();
3222        let fault_plan = target.vm.inject_vm_faults([VmOperation::SetMsrs]);
3223
3224        let error = target.restore(snapshot.clone()).unwrap_err();
3225        assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
3226        assert!(target.status().is_poisoned());
3227        assert!(fault_plan.is_consumed());
3228        let (snapshot_mappings, scratch_mapping) = target.vm.base_mapping_state();
3229        assert!(!snapshot_mappings.is_empty());
3230        assert_eq!(
3231            scratch_mapping,
3232            Some((
3233                target.mem_mgr.scratch_mem.base_addr(),
3234                target.mem_mgr.scratch_mem.mem_size(),
3235            ))
3236        );
3237
3238        target.restore(snapshot).unwrap();
3239        assert_eq!(target.status(), SandboxStatus::Ready);
3240        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3241    }
3242
3243    #[test]
3244    fn snapshot_restore_accepts_different_configured_layout() {
3245        type Configure = fn(&mut SandboxConfiguration);
3246        type LayoutValue = fn(&crate::mem::layout::SandboxMemoryLayout) -> usize;
3247        let cases: &[(&str, Configure, LayoutValue)] = &[
3248            (
3249                "G2H queue size",
3250                |cfg| cfg.set_g2h_queue_size(128),
3251                |layout| layout.get_g2h_queue_size(),
3252            ),
3253            (
3254                "H2G queue size",
3255                |cfg| cfg.set_h2g_queue_size(64),
3256                |layout| layout.get_h2g_queue_size(),
3257            ),
3258            (
3259                "G2H buffer size",
3260                |cfg| cfg.set_g2h_buffer_size(0x2000),
3261                |layout| layout.get_g2h_buffer_size(),
3262            ),
3263            (
3264                "H2G buffer size",
3265                |cfg| cfg.set_h2g_buffer_size(0x2000),
3266                |layout| layout.get_h2g_buffer_size(),
3267            ),
3268            (
3269                "G2H pool pages",
3270                |cfg| cfg.set_g2h_pool_pages(16),
3271                |layout| layout.get_g2h_pool_pages(),
3272            ),
3273            (
3274                "H2G pool pages",
3275                |cfg| cfg.set_h2g_pool_pages(16),
3276                |layout| layout.get_h2g_pool_pages(),
3277            ),
3278            (
3279                "scratch",
3280                |cfg| cfg.set_scratch_size(0x90_000),
3281                |layout| layout.get_scratch_size(),
3282            ),
3283        ];
3284
3285        for (name, configure, layout_value) in cases {
3286            for incoming_is_larger in [true, false] {
3287                let mut custom_cfg = SandboxConfiguration::default();
3288                configure(&mut custom_cfg);
3289                let (source_cfg, target_cfg) = if incoming_is_larger {
3290                    (custom_cfg, SandboxConfiguration::default())
3291                } else {
3292                    (SandboxConfiguration::default(), custom_cfg)
3293                };
3294
3295                let path = simple_guest_as_pathbuf();
3296                let mut source =
3297                    UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3298                        .unwrap()
3299                        .evolve()
3300                        .unwrap();
3301
3302                let path = simple_guest_as_pathbuf();
3303                let mut target =
3304                    UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
3305                        .unwrap()
3306                        .evolve()
3307                        .unwrap();
3308
3309                let source_value = layout_value(&source.mem_mgr.layout);
3310                assert_ne!(source_value, layout_value(&target.mem_mgr.layout));
3311
3312                source.call::<i32>("AddToStatic", 42i32).unwrap();
3313                target
3314                    .restore(source.snapshot().unwrap())
3315                    .unwrap_or_else(|err| panic!("restore with different {name} layout: {err}"));
3316                assert_eq!(layout_value(&target.mem_mgr.layout), source_value);
3317                assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3318            }
3319        }
3320    }
3321
3322    #[test]
3323    fn snapshot_restore_recovers_oom_with_larger_scratch() {
3324        let mut source_cfg = SandboxConfiguration::default();
3325        source_cfg.set_scratch_size(0x200_000);
3326        let path = simple_guest_as_pathbuf();
3327        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3328            .unwrap()
3329            .evolve()
3330            .unwrap();
3331        let snapshot = source.snapshot().unwrap();
3332
3333        let path = simple_guest_as_pathbuf();
3334        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3335            .unwrap()
3336            .evolve()
3337            .unwrap();
3338
3339        assert!(target.call::<()>("ExhaustHeap", ()).is_err());
3340        assert!(target.status().is_poisoned());
3341
3342        target.restore(snapshot).unwrap();
3343        assert!(!target.status().is_poisoned());
3344        target
3345            .call::<()>("AllocAndWritePattern", 0x100_000u64)
3346            .unwrap();
3347    }
3348
3349    #[test]
3350    fn snapshot_restore_applies_smaller_scratch_limit() {
3351        let path = simple_guest_as_pathbuf();
3352        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3353            .unwrap()
3354            .evolve()
3355            .unwrap();
3356        let snapshot = source.snapshot().unwrap();
3357
3358        let mut target_cfg = SandboxConfiguration::default();
3359        target_cfg.set_scratch_size(0x200_000);
3360        let path = simple_guest_as_pathbuf();
3361        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
3362            .unwrap()
3363            .evolve()
3364            .unwrap();
3365
3366        target
3367            .call::<()>("AllocAndWritePattern", 0x100_000u64)
3368            .unwrap();
3369        target.restore(snapshot).unwrap();
3370        assert_eq!(
3371            target.mem_mgr.layout.get_scratch_size(),
3372            SandboxConfiguration::DEFAULT_SCRATCH_SIZE
3373        );
3374        assert!(
3375            target
3376                .call::<()>("AllocAndWritePattern", 0x100_000u64)
3377                .is_err()
3378        );
3379        assert!(target.status().is_poisoned());
3380    }
3381
3382    #[test]
3383    fn snapshot_restore_applies_smaller_h2g_capacity() {
3384        let mut source_cfg = SandboxConfiguration::default();
3385        source_cfg.set_scratch_size(1024 * 1024);
3386        source_cfg.set_h2g_pool_pages(4);
3387        let path = simple_guest_as_pathbuf();
3388        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3389            .unwrap()
3390            .evolve()
3391            .unwrap();
3392        let snapshot = source.snapshot().unwrap();
3393        let mut target_cfg = SandboxConfiguration::default();
3394        target_cfg.set_scratch_size(1024 * 1024);
3395        target_cfg.set_h2g_pool_pages(8);
3396        let path = simple_guest_as_pathbuf();
3397        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
3398            .unwrap()
3399            .evolve()
3400            .unwrap();
3401        let large = "x".repeat(4 * hyperlight_common::vmem::PAGE_SIZE);
3402
3403        assert_eq!(target.call::<String>("Echo", large.clone()).unwrap(), large);
3404        target.restore(snapshot).unwrap();
3405        assert_eq!(target.mem_mgr.layout.get_h2g_pool_pages(), 4);
3406        let error = target.call::<String>("Echo", large).unwrap_err();
3407        assert!(error.to_string().contains("H2G capacity"));
3408        assert!(!target.status().is_poisoned());
3409        assert_eq!(
3410            target.call::<String>("Echo", "small".to_string()).unwrap(),
3411            "small"
3412        );
3413    }
3414
3415    #[test]
3416    fn snapshot_restore_alternates_different_layouts() {
3417        let mut small_cfg = SandboxConfiguration::default();
3418        small_cfg.set_scratch_size(0x70_000);
3419        let path = simple_guest_as_pathbuf();
3420        let mut small = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(small_cfg))
3421            .unwrap()
3422            .evolve()
3423            .unwrap();
3424        small.call::<i32>("AddToStatic", 11i32).unwrap();
3425        let small_snapshot = small.snapshot().unwrap();
3426
3427        let mut large_cfg = SandboxConfiguration::default();
3428        large_cfg.set_scratch_size(0x90_000);
3429        let path = simple_guest_as_pathbuf();
3430        let mut large = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(large_cfg))
3431            .unwrap()
3432            .evolve()
3433            .unwrap();
3434        large.call::<i32>("AddToStatic", 22i32).unwrap();
3435        let large_snapshot = large.snapshot().unwrap();
3436
3437        let path = simple_guest_as_pathbuf();
3438        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3439            .unwrap()
3440            .evolve()
3441            .unwrap();
3442
3443        target.restore(small_snapshot.clone()).unwrap();
3444        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
3445        assert_eq!(target.mem_mgr.layout.get_scratch_size(), 0x70_000);
3446
3447        target.restore(large_snapshot).unwrap();
3448        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 22);
3449        assert_eq!(target.mem_mgr.layout.get_scratch_size(), 0x90_000);
3450
3451        target.restore(small_snapshot).unwrap();
3452        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
3453        assert_eq!(target.mem_mgr.layout.get_scratch_size(), 0x70_000);
3454    }
3455
3456    #[test]
3457    fn snapshot_restore_replaces_rust_guest_with_c_guest() {
3458        let init_data = b"cross-layout-init-data";
3459        let source_env = GuestEnvironment {
3460            guest_binary: GuestBinary::FilePath(c_simple_guest_as_pathbuf()),
3461            init_data: Some(GuestBlob {
3462                data: init_data,
3463                permissions: MemoryRegionFlags::READ | MemoryRegionFlags::WRITE,
3464            }),
3465        };
3466        let mut source = UninitializedSandbox::new(source_env, None)
3467            .unwrap()
3468            .evolve()
3469            .unwrap();
3470        let mut target =
3471            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3472                .unwrap()
3473                .evolve()
3474                .unwrap();
3475
3476        assert_eq!(source.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3477        assert_eq!(target.call::<i32>("AddToStatic", 17i32).unwrap(), 17);
3478        target.set_pt_root_finder(Box::new(|_, _, root| Ok(vec![root])));
3479        assert!(target.pt_root_finder.is_some());
3480
3481        assert_ne!(
3482            source.mem_mgr.layout.code_size(),
3483            target.mem_mgr.layout.code_size()
3484        );
3485        assert_ne!(
3486            source.mem_mgr.layout.init_data_size(),
3487            target.mem_mgr.layout.init_data_size()
3488        );
3489        assert_ne!(
3490            source.mem_mgr.layout.init_data_permissions(),
3491            target.mem_mgr.layout.init_data_permissions()
3492        );
3493
3494        let snapshot = source.snapshot().unwrap();
3495        target.restore(snapshot).unwrap();
3496        assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
3497        assert!(matches!(
3498            target.call::<i32>("GetStatic", ()),
3499            Err(HyperlightError::GuestError(
3500                ErrorCode::GuestFunctionNotFound,
3501                name
3502            )) if name == "GetStatic"
3503        ));
3504    }
3505
3506    #[test]
3507    fn active_page_table_root_is_first() {
3508        const ACTIVE: u64 = 0x1000;
3509        const OTHER: u64 = 0x2000;
3510
3511        assert_eq!(
3512            normalize_page_table_roots(vec![OTHER, ACTIVE, ACTIVE], ACTIVE),
3513            vec![ACTIVE, OTHER]
3514        );
3515        assert_eq!(
3516            normalize_page_table_roots(vec![OTHER, OTHER], ACTIVE),
3517            vec![ACTIVE, OTHER]
3518        );
3519        assert_eq!(
3520            normalize_page_table_roots(vec![OTHER], ACTIVE),
3521            vec![ACTIVE, OTHER]
3522        );
3523        assert_eq!(normalize_page_table_roots(Vec::new(), ACTIVE), vec![ACTIVE]);
3524    }
3525
3526    #[test]
3527    fn page_table_root_finder_reads_snapshot_memory() {
3528        use std::sync::atomic::{AtomicBool, Ordering};
3529
3530        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3531            .build()
3532            .unwrap();
3533        let base = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
3534        let mut expected = [0; 16];
3535        sandbox
3536            .mem_mgr
3537            .shared_mem
3538            .read_snapshot_gpa(base, &mut expected)
3539            .unwrap();
3540        let invoked = Arc::new(AtomicBool::new(false));
3541        let callback_invoked = invoked.clone();
3542        sandbox.set_pt_root_finder(Box::new(move |snapshot, _, root| {
3543            let mut bytes = [0; 16];
3544            snapshot.read_exact(base, &mut bytes)?;
3545            assert_eq!(bytes, expected);
3546            callback_invoked.store(true, Ordering::Relaxed);
3547            Ok(vec![root])
3548        }));
3549
3550        sandbox.snapshot().unwrap();
3551        assert!(invoked.load(Ordering::Relaxed));
3552    }
3553
3554    #[test]
3555    fn page_table_root_finder_error_aborts_snapshot() {
3556        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3557            .build()
3558            .unwrap();
3559        sandbox.set_pt_root_finder(Box::new(|_, _, _| {
3560            Err(crate::new_error!("failed to discover page-table roots"))
3561        }));
3562
3563        let error = sandbox.snapshot().err().unwrap();
3564
3565        assert!(
3566            error
3567                .to_string()
3568                .contains("failed to discover page-table roots")
3569        );
3570        assert_eq!(sandbox.status(), SandboxStatus::Ready);
3571        assert!(sandbox.snapshot.is_none());
3572    }
3573
3574    #[test]
3575    fn snapshot_restore_replaces_c_guest_with_rust_guest() {
3576        let mut source =
3577            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3578                .unwrap()
3579                .evolve()
3580                .unwrap();
3581        assert_eq!(source.call::<i32>("AddToStatic", 42i32).unwrap(), 42);
3582        let snapshot = source.snapshot().unwrap();
3583
3584        let mut target =
3585            UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3586                .unwrap()
3587                .evolve()
3588                .unwrap();
3589        assert_eq!(target.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3590
3591        target.restore(snapshot).unwrap();
3592        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3593        assert!(matches!(
3594            target.call::<i32>("StackAllocate", 512i32),
3595            Err(HyperlightError::GuestError(
3596                ErrorCode::GuestFunctionNotFound,
3597                name
3598            )) if name == "StackAllocate"
3599        ));
3600    }
3601
3602    #[test]
3603    fn snapshot_restore_alternates_c_and_rust_guests() {
3604        let mut c_source =
3605            UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3606                .unwrap()
3607                .evolve()
3608                .unwrap();
3609        assert_eq!(c_source.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3610        let c_snapshot = c_source.snapshot().unwrap();
3611
3612        let mut rust_source =
3613            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3614                .unwrap()
3615                .evolve()
3616                .unwrap();
3617        rust_source.call::<i32>("AddToStatic", 42i32).unwrap();
3618        let rust_snapshot = rust_source.snapshot().unwrap();
3619
3620        let mut target =
3621            UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3622                .unwrap()
3623                .evolve()
3624                .unwrap();
3625        assert_eq!(target.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3626
3627        target.restore(rust_snapshot).unwrap();
3628        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3629        assert!(matches!(
3630            target.call::<i32>("StackAllocate", 512i32),
3631            Err(HyperlightError::GuestError(
3632                ErrorCode::GuestFunctionNotFound,
3633                name
3634            )) if name == "StackAllocate"
3635        ));
3636
3637        target.restore(c_snapshot).unwrap();
3638        assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
3639        assert!(matches!(
3640            target.call::<i32>("GetStatic", ()),
3641            Err(HyperlightError::GuestError(
3642                ErrorCode::GuestFunctionNotFound,
3643                name
3644            )) if name == "GetStatic"
3645        ));
3646    }
3647
3648    #[test]
3649    fn snapshot_restore_keeps_target_host_function_implementation() {
3650        let path = simple_guest_as_pathbuf();
3651        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3652        source
3653            .register_host_function("Echo42", || Ok(1i64))
3654            .unwrap();
3655        let mut source = source.evolve().unwrap();
3656        let snapshot = source.snapshot().unwrap();
3657
3658        let path = simple_guest_as_pathbuf();
3659        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3660        target
3661            .register_host_function("Echo42", || Ok(42i64))
3662            .unwrap();
3663        let mut target = target.evolve().unwrap();
3664
3665        target.restore(snapshot).unwrap();
3666        assert_eq!(
3667            target
3668                .call::<i64>(
3669                    "CallGivenParamlessHostFuncThatReturnsI64",
3670                    "Echo42".to_string(),
3671                )
3672                .unwrap(),
3673            42
3674        );
3675    }
3676
3677    #[test]
3678    fn snapshot_restore_recovers_poison_with_different_guest() {
3679        let mut source =
3680            UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3681                .unwrap()
3682                .evolve()
3683                .unwrap();
3684        let snapshot = source.snapshot().unwrap();
3685
3686        let path = simple_guest_as_pathbuf();
3687        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3688            .unwrap()
3689            .evolve()
3690            .unwrap();
3691        assert!(target.call::<()>("ExhaustHeap", ()).is_err());
3692        assert!(target.status().is_poisoned());
3693
3694        target.restore(snapshot).unwrap();
3695        assert!(!target.status().is_poisoned());
3696        assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
3697        assert!(matches!(
3698            target.call::<i32>("GetStatic", ()),
3699            Err(HyperlightError::GuestError(
3700                ErrorCode::GuestFunctionNotFound,
3701                name
3702            )) if name == "GetStatic"
3703        ));
3704    }
3705
3706    /// Validation runs before any memory or vCPU mutation, so a
3707    /// rejected `restore` leaves the target usable.
3708    #[test]
3709    fn snapshot_restore_failure_leaves_target_usable() {
3710        let path = simple_guest_as_pathbuf();
3711        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3712        source
3713            .register_host_function("Add", |a: i32, b: i32| Ok(a + b))
3714            .unwrap();
3715        let mut source = source.evolve().unwrap();
3716
3717        let map_mem = allocate_guest_memory();
3718        let path = simple_guest_as_pathbuf();
3719        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3720            .unwrap()
3721            .evolve()
3722            .unwrap();
3723
3724        target.call::<i32>("AddToStatic", 5i32).unwrap();
3725        let guest_base = 0x200000000_usize;
3726        let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3727        // SAFETY: `map_mem` is page-aligned and outlives every use of `target`.
3728        unsafe { target.map_region(&region).unwrap() };
3729        target
3730            .call::<Vec<u8>>(
3731                "ReadMappedBuffer",
3732                (
3733                    guest_base as u64,
3734                    hyperlight_common::vmem::PAGE_SIZE as u64,
3735                    true,
3736                ),
3737            )
3738            .unwrap();
3739        let cached_snapshot = target.snapshot().unwrap();
3740        let bad_snapshot = source.snapshot().unwrap();
3741        let err = target.restore(bad_snapshot);
3742        assert!(matches!(
3743            err,
3744            Err(HyperlightError::SnapshotHostFunctionMismatch { missing, .. })
3745                if missing.iter().any(|name| name == "Add")
3746        ));
3747
3748        assert!(Arc::ptr_eq(&target.snapshot().unwrap(), &cached_snapshot));
3749        assert_eq!(target.vm.get_mapped_regions().count(), 0);
3750        assert!(
3751            target
3752                .call::<bool>("CheckMapped", guest_base as u64)
3753                .unwrap()
3754        );
3755        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 5);
3756        target.call::<i32>("AddToStatic", 3i32).unwrap();
3757        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 8);
3758
3759        let good_snapshot = target.snapshot().unwrap();
3760        target.call::<i32>("AddToStatic", 100i32).unwrap();
3761        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 108);
3762        target.restore(good_snapshot).unwrap();
3763        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 8);
3764    }
3765
3766    /// `snapshot.regions()` is empty post-compaction, so restore
3767    /// unmaps anything the target had mapped.
3768    #[test]
3769    fn snapshot_restore_across_sandboxes_target_has_mapped_regions() {
3770        let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3771            .build()
3772            .unwrap();
3773        source.call::<i32>("AddToStatic", 23i32).unwrap();
3774        let snapshot = source.snapshot().unwrap();
3775
3776        let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3777            .build()
3778            .unwrap();
3779        let map_mem = allocate_guest_memory();
3780        let guest_base = 0x200000000_usize;
3781        let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3782        unsafe { target.map_region(&region).unwrap() };
3783        assert_eq!(target.vm.get_mapped_regions().count(), 1);
3784
3785        target.restore(snapshot).unwrap();
3786        assert_eq!(target.vm.get_mapped_regions().count(), 0);
3787        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
3788    }
3789
3790    #[test]
3791    fn snapshot_restore_unmaps_regions_overlapping_incoming_layout() {
3792        let mut source_cfg = SandboxConfiguration::default();
3793        source_cfg.set_scratch_size(0x90_000);
3794        let path = simple_guest_as_pathbuf();
3795        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3796            .unwrap()
3797            .evolve()
3798            .unwrap();
3799        source.call::<i32>("AddToStatic", 23i32).unwrap();
3800        let snapshot = source.snapshot().unwrap();
3801
3802        let path = simple_guest_as_pathbuf();
3803        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3804            .unwrap()
3805            .evolve()
3806            .unwrap();
3807        assert!(
3808            snapshot.snapshot_memory().gpa_span_len() > target.mem_mgr.shared_mem.gpa_span_len()
3809        );
3810
3811        let map_mem = allocate_guest_memory();
3812        let guest_base = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS
3813            + target.mem_mgr.shared_mem.gpa_span_len();
3814        let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3815        // SAFETY: `map_mem` is page-aligned and outlives every use of `target`.
3816        unsafe { target.map_region(&region).unwrap() };
3817
3818        target.restore(snapshot).unwrap();
3819        assert_eq!(target.vm.get_mapped_regions().count(), 0);
3820        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
3821    }
3822
3823    #[test]
3824    fn snapshot_restore_unmaps_region_overlapping_incoming_scratch() {
3825        let incoming_scratch_size = 0x90_000;
3826        let mut source_cfg = SandboxConfiguration::default();
3827        source_cfg.set_scratch_size(incoming_scratch_size);
3828        let path = simple_guest_as_pathbuf();
3829        let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3830            .unwrap()
3831            .evolve()
3832            .unwrap();
3833        source.call::<i32>("AddToStatic", 23i32).unwrap();
3834        let snapshot = source.snapshot().unwrap();
3835
3836        let path = simple_guest_as_pathbuf();
3837        let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3838            .unwrap()
3839            .evolve()
3840            .unwrap();
3841        let guest_base =
3842            hyperlight_common::layout::scratch_base_gpa(incoming_scratch_size) as usize;
3843        let target_scratch_base =
3844            hyperlight_common::layout::scratch_base_gpa(SandboxConfiguration::DEFAULT_SCRATCH_SIZE)
3845                as usize;
3846        let map_mem = allocate_guest_memory();
3847        assert!(guest_base + map_mem.mem_size() <= target_scratch_base);
3848        let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3849        // SAFETY: `map_mem` is page-aligned and outlives every use of `target`.
3850        unsafe { target.map_region(&region).unwrap() };
3851
3852        target.restore(snapshot).unwrap();
3853        assert_eq!(target.vm.get_mapped_regions().count(), 0);
3854        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
3855    }
3856
3857    /// Compacted snapshot data is reachable at the source's GVA even
3858    /// when the target had a different region mapped at a different
3859    /// GVA.
3860    #[test]
3861    fn snapshot_restore_across_sandboxes_both_have_different_mapped_regions() {
3862        let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3863            .build()
3864            .unwrap();
3865        let source_mem = allocate_guest_memory();
3866        let source_base = 0x200000000_usize;
3867        let source_region = region_for_memory(&source_mem, source_base, MemoryRegionFlags::READ);
3868        unsafe { source.map_region(&source_region).unwrap() };
3869        let orig_read = source
3870            .call::<Vec<u8>>(
3871                "ReadMappedBuffer",
3872                (
3873                    source_base as u64,
3874                    hyperlight_common::vmem::PAGE_SIZE as u64,
3875                    true,
3876                ),
3877            )
3878            .unwrap();
3879        source.call::<i32>("AddToStatic", 9i32).unwrap();
3880        let snapshot = source.snapshot().unwrap();
3881
3882        let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3883            .build()
3884            .unwrap();
3885        let target_mem = allocate_guest_memory();
3886        let target_base = 0x300000000_usize;
3887        let target_region = region_for_memory(&target_mem, target_base, MemoryRegionFlags::READ);
3888        unsafe { target.map_region(&target_region).unwrap() };
3889        assert_eq!(target.vm.get_mapped_regions().count(), 1);
3890
3891        target.restore(snapshot).unwrap();
3892
3893        assert_eq!(target.vm.get_mapped_regions().count(), 0);
3894        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 9);
3895
3896        let new_read = target
3897            .call::<Vec<u8>>(
3898                "ReadMappedBuffer",
3899                (
3900                    source_base as u64,
3901                    hyperlight_common::vmem::PAGE_SIZE as u64,
3902                    false,
3903                ),
3904            )
3905            .unwrap();
3906        assert_eq!(new_read, orig_read);
3907    }
3908
3909    /// Repeated restore of the same snapshot is idempotent.
3910    #[test]
3911    fn snapshot_restore_across_sandboxes_repeated() {
3912        let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3913            .build()
3914            .unwrap();
3915        source.call::<i32>("AddToStatic", 7i32).unwrap();
3916        let snapshot = source.snapshot().unwrap();
3917
3918        let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3919            .build()
3920            .unwrap();
3921
3922        target.restore(snapshot.clone()).unwrap();
3923        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 7);
3924
3925        target.call::<i32>("AddToStatic", 1000i32).unwrap();
3926        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 1007);
3927
3928        target.restore(snapshot).unwrap();
3929        assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 7);
3930    }
3931
3932    /// Test that snapshot restore properly resets vCPU debug registers. This test verifies
3933    /// that restore() calls reset_vcpu().
3934    #[test]
3935    fn snapshot_restore_resets_debug_registers() {
3936        let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3937            .build()
3938            .unwrap();
3939
3940        let snapshot = sandbox.snapshot().unwrap();
3941
3942        // Verify DR0 is initially 0 (clean state)
3943        let dr0_initial: u64 = sandbox.call("GetDr0", ()).unwrap();
3944        assert_eq!(dr0_initial, 0, "DR0 should initially be 0");
3945
3946        // Dirty DR0 by setting it to a known non-zero value, avoiding
3947        // bits that are reserved in aarch64 DBGBVR0_EL1
3948        const DIRTY_VALUE: u64 = 0xFFFF_FEDC_7654_3210;
3949        sandbox.call::<()>("SetDr0", DIRTY_VALUE).unwrap();
3950
3951        // Validate that DR0 was in fact dirtied
3952        #[cfg(not(hvf))]
3953        {
3954            // This check does not work on hvf, because it relies on
3955            // state being persisted across sandbox calls in a system
3956            // register that is not usually supported by Hyperlight
3957            // (DBGBVR0), whereas hvf may (if there is a lot of
3958            // contention on the system) destroy and re-create its
3959            // vcpu, preserving only the "supported" hyperlight state
3960            // msrs.
3961            //
3962            // We could disable this test entirely on hvf, but a test
3963            // that occasionally checks for what it is meant to is
3964            // probably better than one that never does.
3965            let dr0_dirty: u64 = sandbox.call("GetDr0", ()).unwrap();
3966            assert_eq!(
3967                dr0_dirty, DIRTY_VALUE,
3968                "DR0 should be dirty after SetDr0 call"
3969            );
3970        }
3971
3972        // Restore to the snapshot - this should reset vCPU state including debug registers
3973        sandbox.restore(snapshot).unwrap();
3974
3975        let dr0_after_restore: u64 = sandbox.call("GetDr0", ()).unwrap();
3976        assert_eq!(
3977            dr0_after_restore, 0,
3978            "DR0 should be 0 after restore (reset_vcpu should have been called)"
3979        );
3980    }
3981
3982    #[test]
3983    #[cfg(target_arch = "x86_64")]
3984    fn snapshot_restore_resets_xcr0() {
3985        let mut sandbox: Sandbox = {
3986            let path = simple_guest_as_pathbuf();
3987            let u_sbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3988            u_sbox.evolve().unwrap()
3989        };
3990
3991        assert_eq!(sandbox.call::<u64>("ReadXcr0", ()).unwrap(), 1);
3992        let snapshot = sandbox.snapshot().unwrap();
3993
3994        sandbox.call::<()>("WriteXcr0", 3u64).unwrap();
3995        assert_eq!(sandbox.call::<u64>("ReadXcr0", ()).unwrap(), 3);
3996
3997        sandbox.restore(snapshot).unwrap();
3998
3999        assert_eq!(
4000            sandbox.call::<u64>("ReadXcr0", ()).unwrap(),
4001            1,
4002            "restore must reset XCR0"
4003        );
4004    }
4005
4006    /// Test that stale abort buffer bytes from a previous call don't
4007    /// leak into the next call.
4008    #[test]
4009    fn stale_abort_buffer_does_not_leak_across_calls() {
4010        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4011            .build()
4012            .unwrap();
4013
4014        // Simulate a partial abort
4015        sbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 1020]);
4016
4017        let res = sbox.call::<String>("Echo", "hello".to_string());
4018        assert!(
4019            res.is_ok(),
4020            "Expected Ok after stale abort buffer, got: {:?}",
4021            res.unwrap_err()
4022        );
4023
4024        // The buffer should be empty after the call.
4025        assert!(
4026            sbox.mem_mgr.abort_buffer.is_empty(),
4027            "abort_buffer should be empty after a guest call"
4028        );
4029    }
4030
4031    #[test]
4032    fn test_sandbox_creation_various_sizes() {
4033        let test_cases: [(&str, usize); 3] = [
4034            ("small (8MiB scratch)", SMALL_SCRATCH_SIZE),
4035            ("medium (64MiB scratch)", MEDIUM_SCRATCH_SIZE),
4036            ("large (256MiB scratch)", LARGE_SCRATCH_SIZE),
4037        ];
4038
4039        for (name, scratch_size) in test_cases {
4040            let path = simple_guest_as_pathbuf();
4041            let sbox = SandboxBuilder::from_file(path)
4042                .scratch_size(scratch_size)
4043                .build()
4044                .unwrap_or_else(|e| panic!("Failed to create {} sandbox: {}", name, e));
4045
4046            drop(sbox);
4047        }
4048    }
4049
4050    /// Helper: create a Sandbox from the simple guest with default config.
4051    #[cfg(feature = "trace_guest")]
4052    fn sandbox_for_gva_tests() -> Sandbox {
4053        let path = simple_guest_as_pathbuf();
4054        SandboxBuilder::from_file(path).build().unwrap()
4055    }
4056
4057    /// Helper: read memory at `gva` of length `len` from the guest side via
4058    /// `ReadMappedBuffer(gva, len, false)` and from the host side via
4059    /// `read_guest_memory_by_gva`, then assert both views are identical.
4060    #[cfg(feature = "trace_guest")]
4061    fn assert_gva_read_matches(sbox: &mut Sandbox, gva: u64, len: usize) {
4062        // Guest reads via its own page tables
4063        let expected: Vec<u8> = sbox
4064            .call("ReadMappedBuffer", (gva, len as u64, true))
4065            .unwrap();
4066        assert_eq!(expected.len(), len);
4067
4068        // Host reads by walking the same page tables
4069        let root_pt = sbox.vm.get_root_pt().unwrap();
4070        let actual = sbox
4071            .mem_mgr
4072            .read_guest_memory_by_gva(gva, len, root_pt)
4073            .unwrap();
4074
4075        assert_eq!(
4076            actual, expected,
4077            "read_guest_memory_by_gva at GVA {:#x} (len {}) differs from guest ReadMappedBuffer",
4078            gva, len,
4079        );
4080    }
4081
4082    /// Test reading a small buffer (< 1 page) from guest memory via GVA.
4083    /// Uses the guest code section which is already identity-mapped.
4084    #[test]
4085    #[cfg(feature = "trace_guest")]
4086    fn read_guest_memory_by_gva_single_page() {
4087        let mut sbox = sandbox_for_gva_tests();
4088        let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4089        assert_gva_read_matches(&mut sbox, code_gva, 128);
4090    }
4091
4092    /// Test reading exactly one full page (4096 bytes) from guest memory.
4093    /// Uses the guest code section
4094    #[test]
4095    #[cfg(feature = "trace_guest")]
4096    fn read_guest_memory_by_gva_full_page() {
4097        let mut sbox = sandbox_for_gva_tests();
4098        let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4099        assert_gva_read_matches(&mut sbox, code_gva, 4096);
4100    }
4101
4102    /// Test that a read starting at an odd (non-page-aligned) address and
4103    /// spanning two page boundaries returns correct data.
4104    #[test]
4105    #[cfg(feature = "trace_guest")]
4106    fn read_guest_memory_by_gva_unaligned_cross_page() {
4107        let mut sbox = sandbox_for_gva_tests();
4108        let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4109        // Start 1 byte before the second page boundary and read 4097 bytes
4110        // (spans 2 full page boundaries).
4111        let start = code_gva + 4096 - 1;
4112        println!(
4113            "Testing unaligned cross-page read starting at {:#x} spanning 4097 bytes",
4114            start
4115        );
4116        assert_gva_read_matches(&mut sbox, start, 4097);
4117    }
4118
4119    /// Test reading exactly two full pages (8192 bytes) from guest memory.
4120    #[test]
4121    #[cfg(feature = "trace_guest")]
4122    fn read_guest_memory_by_gva_two_full_pages() {
4123        let mut sbox = sandbox_for_gva_tests();
4124        let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4125        assert_gva_read_matches(&mut sbox, code_gva, 4096 * 2);
4126    }
4127
4128    /// Test reading a region that spans across a page boundary: starts
4129    /// 100 bytes before the end of the first page and reads 200 bytes
4130    /// into the second page.
4131    #[test]
4132    #[cfg(feature = "trace_guest")]
4133    fn read_guest_memory_by_gva_cross_page_boundary() {
4134        let mut sbox = sandbox_for_gva_tests();
4135        let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4136        // Start 100 bytes before the first page boundary, read across it.
4137        let start = code_gva + 4096 - 100;
4138        assert_gva_read_matches(&mut sbox, start, 200);
4139    }
4140
4141    /// Helper: create a temp file with known content, padded to be
4142    /// at least page-aligned (4096 bytes). Returns the path and the
4143    /// *original* content bytes (before padding).
4144    fn create_test_file(name: &str, content: &[u8]) -> (std::path::PathBuf, Vec<u8>) {
4145        use std::io::Write;
4146
4147        let page_size = page_size::get();
4148        let padded_len = content.len().max(page_size).div_ceil(page_size) * page_size + page_size;
4149        let mut padded = vec![0u8; padded_len];
4150        padded[..content.len()].copy_from_slice(content);
4151
4152        let temp_dir = std::env::temp_dir();
4153        let path = temp_dir.join(name);
4154        let _ = std::fs::remove_file(&path); // clean up from previous runs
4155        let mut f = std::fs::File::create(&path).unwrap();
4156        f.write_all(&padded).unwrap();
4157        (path, content.to_vec())
4158    }
4159
4160    /// Tests the basic `map_file_cow` flow: map a file, read its content
4161    /// from the guest, and verify it matches.
4162    #[test]
4163    fn test_map_file_cow_basic() {
4164        let expected = b"hello world from map_file_cow";
4165        let (path, expected_bytes) =
4166            create_test_file("hyperlight_test_map_file_cow_basic.bin", expected);
4167
4168        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4169            .build()
4170            .unwrap();
4171
4172        let guest_base: u64 = 0x1_0000_0000;
4173        let mapped_size = sbox.map_file_cow(&path, guest_base).unwrap();
4174        assert!(mapped_size > 0, "mapped_size should be positive");
4175        assert!(
4176            mapped_size >= expected.len() as u64,
4177            "mapped_size should be >= file content length"
4178        );
4179
4180        // Read the content back from the guest
4181        let actual: Vec<u8> = sbox
4182            .call(
4183                "ReadMappedBuffer",
4184                (guest_base, expected_bytes.len() as u64, true),
4185            )
4186            .unwrap();
4187
4188        assert_eq!(
4189            actual, expected_bytes,
4190            "Guest should read back the exact file content"
4191        );
4192
4193        // Clean up
4194        let _ = std::fs::remove_file(&path);
4195    }
4196
4197    /// Tests that `map_file_cow` enforces read-only access: writing to
4198    /// the mapped region from the guest should cause a MemoryAccessViolation.
4199    #[test]
4200    fn test_map_file_cow_read_only_enforcement() {
4201        let content = &[0xBB; 4096];
4202        let (path, _) = create_test_file("hyperlight_test_map_file_cow_readonly.bin", content);
4203
4204        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4205            .build()
4206            .unwrap();
4207
4208        let guest_base: u64 = 0x1_0000_0000;
4209        sbox.map_file_cow(&path, guest_base).unwrap();
4210
4211        // Writing to the mapped region should fail with MemoryAccessViolation
4212        let err = sbox
4213            .call::<bool>("WriteMappedBuffer", (guest_base, content.len() as u64))
4214            .unwrap_err();
4215
4216        match err {
4217            HyperlightError::MemoryAccessViolation(addr, ..) if addr == guest_base => {}
4218            _ => panic!(
4219                "Expected MemoryAccessViolation at guest_base, got: {:?}",
4220                err
4221            ),
4222        };
4223
4224        // Clean up
4225        let _ = std::fs::remove_file(&path);
4226    }
4227
4228    /// Tests that `map_file_cow` returns `PoisonedSandbox` when the
4229    /// sandbox is poisoned.
4230    #[test]
4231    fn test_map_file_cow_poisoned() {
4232        let (path, _) = create_test_file("hyperlight_test_map_file_cow_poison.bin", &[0xCC; 4096]);
4233
4234        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4235            .build()
4236            .unwrap();
4237        let snapshot = sbox.snapshot().unwrap();
4238
4239        // Poison the sandbox
4240        let _ = sbox
4241            .call::<()>("guest_panic", "hello".to_string())
4242            .unwrap_err();
4243        assert!(sbox.status().is_poisoned());
4244
4245        // map_file_cow should fail with PoisonedSandbox
4246        let err = sbox.map_file_cow(&path, 0x1_0000_0000).unwrap_err();
4247        assert!(matches!(err, HyperlightError::PoisonedSandbox));
4248
4249        // Restore and verify map_file_cow works again
4250        sbox.restore(snapshot).unwrap();
4251        assert_eq!(sbox.status(), SandboxStatus::Ready);
4252        let result = sbox.map_file_cow(&path, 0x1_0000_0000);
4253        assert!(result.is_ok());
4254
4255        let _ = std::fs::remove_file(&path);
4256    }
4257
4258    /// Tests that two separate sandboxes can map the same file
4259    /// simultaneously and both read it correctly.
4260    #[test]
4261    fn test_map_file_cow_multi_vm_same_file() {
4262        let expected = b"shared file content across VMs";
4263        let (path, expected_bytes) =
4264            create_test_file("hyperlight_test_map_file_cow_multi_vm.bin", expected);
4265
4266        let guest_base: u64 = 0x1_0000_0000;
4267
4268        let mut sbox1 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4269            .build()
4270            .unwrap();
4271
4272        let mut sbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4273            .build()
4274            .unwrap();
4275
4276        // Map the same file into both sandboxes
4277        sbox1.map_file_cow(&path, guest_base).unwrap();
4278        sbox2.map_file_cow(&path, guest_base).unwrap();
4279
4280        // Both should read the correct content
4281        let actual1: Vec<u8> = sbox1
4282            .call(
4283                "ReadMappedBuffer",
4284                (guest_base, expected_bytes.len() as u64, true),
4285            )
4286            .unwrap();
4287        let actual2: Vec<u8> = sbox2
4288            .call(
4289                "ReadMappedBuffer",
4290                (guest_base, expected_bytes.len() as u64, true),
4291            )
4292            .unwrap();
4293
4294        assert_eq!(
4295            actual1, expected_bytes,
4296            "Sandbox 1 should read correct content"
4297        );
4298        assert_eq!(
4299            actual2, expected_bytes,
4300            "Sandbox 2 should read correct content"
4301        );
4302
4303        let _ = std::fs::remove_file(&path);
4304    }
4305
4306    /// Tests that multiple threads can each create a sandbox, map the
4307    /// same file, read it, and drop without errors.
4308    #[test]
4309    fn test_map_file_cow_multi_vm_threaded() {
4310        let expected = b"threaded file mapping test data";
4311        let (path, expected_bytes) =
4312            create_test_file("hyperlight_test_map_file_cow_threaded.bin", expected);
4313
4314        const NUM_THREADS: usize = 5;
4315        let path = Arc::new(path);
4316        let expected_bytes = Arc::new(expected_bytes);
4317        let barrier = Arc::new(Barrier::new(NUM_THREADS));
4318        let mut handles = vec![];
4319
4320        for _ in 0..NUM_THREADS {
4321            let path = path.clone();
4322            let expected_bytes = expected_bytes.clone();
4323            let barrier = barrier.clone();
4324
4325            handles.push(thread::spawn(move || {
4326                barrier.wait();
4327
4328                let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4329                    .build()
4330                    .unwrap();
4331
4332                let guest_base: u64 = 0x1_0000_0000;
4333                sbox.map_file_cow(&path, guest_base).unwrap();
4334
4335                let actual: Vec<u8> = sbox
4336                    .call(
4337                        "ReadMappedBuffer",
4338                        (guest_base, expected_bytes.len() as u64, true),
4339                    )
4340                    .unwrap();
4341
4342                assert_eq!(actual, *expected_bytes);
4343            }));
4344        }
4345
4346        for h in handles {
4347            h.join().unwrap();
4348        }
4349
4350        let _ = std::fs::remove_file(&*path);
4351    }
4352
4353    /// Tests that file cleanup works after dropping a sandbox that used
4354    /// `map_file_cow` — the file should be deletable (no leaked handles).
4355    #[test]
4356    #[cfg(target_os = "windows")]
4357    fn test_map_file_cow_cleanup_no_handle_leak() {
4358        let (path, _) = create_test_file("hyperlight_test_map_file_cow_cleanup.bin", &[0xDD; 4096]);
4359
4360        {
4361            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4362                .build()
4363                .unwrap();
4364
4365            sbox.map_file_cow(&path, 0x1_0000_0000).unwrap();
4366            // sandbox dropped here
4367        }
4368
4369        std::fs::remove_file(&path)
4370            .expect("File should be deletable after sandbox with map_file_cow is dropped");
4371    }
4372
4373    /// Tests snapshot/restore cycle with map_file_cow:
4374    /// snapshot₁ (no file) → map file → snapshot₂ → restore₁ (unmapped)
4375    /// → restore₂ (data folded into snapshot).
4376    #[test]
4377    fn test_map_file_cow_snapshot_remapping_cycle() {
4378        let expected = b"snapshot remapping cycle test!";
4379        let (path, expected_bytes) =
4380            create_test_file("hyperlight_test_map_file_cow_snapshot_remap.bin", expected);
4381
4382        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4383            .build()
4384            .unwrap();
4385
4386        let guest_base: u64 = 0x1_0000_0000;
4387
4388        // 1. snapshot₁ — no file mapped
4389        let snapshot1 = sbox.snapshot().unwrap();
4390
4391        // 2. Map the file
4392        sbox.map_file_cow(&path, guest_base).unwrap();
4393
4394        // Verify we can read it
4395        let actual: Vec<u8> = sbox
4396            .call(
4397                "ReadMappedBuffer",
4398                (guest_base, expected_bytes.len() as u64, true),
4399            )
4400            .unwrap();
4401        assert_eq!(actual, expected_bytes);
4402
4403        // 3. snapshot₂ — file mapped (data folded into snapshot)
4404        let snapshot2 = sbox.snapshot().unwrap();
4405
4406        // 4. Restore to snapshot₁ — file should be unmapped
4407        sbox.restore(snapshot1.clone()).unwrap();
4408        let is_mapped: bool = sbox.call("CheckMapped", (guest_base,)).unwrap();
4409        assert!(
4410            !is_mapped,
4411            "Region should be unmapped after restoring to snapshot₁"
4412        );
4413
4414        // 5. Restore to snapshot₂ — data should still be readable
4415        //    (folded into snapshot memory, not the original file mapping)
4416        sbox.restore(snapshot2).unwrap();
4417        let is_mapped: bool = sbox.call("CheckMapped", (guest_base,)).unwrap();
4418        assert!(
4419            is_mapped,
4420            "Region should be mapped after restoring to snapshot₂"
4421        );
4422        let actual2: Vec<u8> = sbox
4423            .call(
4424                "ReadMappedBuffer",
4425                (guest_base, expected_bytes.len() as u64, false),
4426            )
4427            .unwrap();
4428        assert_eq!(
4429            actual2, expected_bytes,
4430            "Data should be intact after snapshot₂ restore"
4431        );
4432
4433        let _ = std::fs::remove_file(&path);
4434    }
4435
4436    /// Tests that snapshot correctly captures map_file_cow data and
4437    /// restore brings it back.
4438    #[test]
4439    fn test_map_file_cow_snapshot_restore() {
4440        let expected = b"snapshot restore basic test!!";
4441        let (path, expected_bytes) =
4442            create_test_file("hyperlight_test_map_file_cow_snap_restore.bin", expected);
4443
4444        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4445            .build()
4446            .unwrap();
4447
4448        let guest_base: u64 = 0x1_0000_0000;
4449        sbox.map_file_cow(&path, guest_base).unwrap();
4450
4451        // Read the content to verify mapping works
4452        let actual: Vec<u8> = sbox
4453            .call(
4454                "ReadMappedBuffer",
4455                (guest_base, expected_bytes.len() as u64, true),
4456            )
4457            .unwrap();
4458        assert_eq!(actual, expected_bytes);
4459
4460        // Take snapshot — folds file data into snapshot memory
4461        let snapshot = sbox.snapshot().unwrap();
4462
4463        // Restore — the file-backed region is unmapped but data is in snapshot
4464        sbox.restore(snapshot).unwrap();
4465
4466        // Data should still be readable from snapshot memory
4467        let actual2: Vec<u8> = sbox
4468            .call(
4469                "ReadMappedBuffer",
4470                (guest_base, expected_bytes.len() as u64, false),
4471            )
4472            .unwrap();
4473        assert_eq!(
4474            actual2, expected_bytes,
4475            "Data should be readable after restore from snapshot"
4476        );
4477
4478        let _ = std::fs::remove_file(&path);
4479    }
4480
4481    /// Tests the deferred `map_file_cow` flow: map a file on
4482    /// `UninitializedSandbox` (before evolve), then evolve and verify
4483    /// the guest can read the mapped content.
4484    #[test]
4485    fn test_map_file_cow_deferred_basic() {
4486        let expected = b"deferred map_file_cow test data";
4487        let (path, expected_bytes) =
4488            create_test_file("hyperlight_test_map_file_cow_deferred.bin", expected);
4489
4490        let guest_base: u64 = 0x1_0000_0000;
4491
4492        let mut u_sbox =
4493            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4494                .unwrap();
4495
4496        // Map the file before evolving — this defers the VM-side work.
4497        let mapped_size = u_sbox.map_file_cow(&path, guest_base).unwrap();
4498        assert!(mapped_size > 0, "mapped_size should be positive");
4499        assert!(
4500            mapped_size >= expected.len() as u64,
4501            "mapped_size should be >= file content length"
4502        );
4503
4504        // Evolve — deferred mappings are applied during this step.
4505        let mut sbox = u_sbox.evolve().unwrap();
4506
4507        // Verify the guest can read the mapped content.
4508        let actual: Vec<u8> = sbox
4509            .call(
4510                "ReadMappedBuffer",
4511                (guest_base, expected_bytes.len() as u64, true),
4512            )
4513            .unwrap();
4514
4515        assert_eq!(
4516            actual, expected_bytes,
4517            "Guest should read back the exact file content after deferred mapping"
4518        );
4519
4520        let _ = std::fs::remove_file(&path);
4521    }
4522
4523    /// Tests that dropping an `UninitializedSandbox` with pending
4524    /// deferred file mappings does not leak or crash — the
4525    /// `PreparedFileMapping::Drop` should clean up host resources.
4526    #[test]
4527    fn test_map_file_cow_deferred_drop_without_evolve() {
4528        let (path, _) = create_test_file(
4529            "hyperlight_test_map_file_cow_deferred_drop.bin",
4530            &[0xAA; 4096],
4531        );
4532
4533        let guest_base: u64 = 0x1_0000_0000;
4534
4535        {
4536            let mut u_sbox =
4537                UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4538                    .unwrap();
4539
4540            u_sbox.map_file_cow(&path, guest_base).unwrap();
4541            // u_sbox dropped here without evolving — PreparedFileMapping::drop
4542            // should clean up host-side OS resources.
4543        }
4544
4545        // If we get here without a crash/hang, cleanup worked.
4546        // On Windows, also verify the file handle was released.
4547        #[cfg(target_os = "windows")]
4548        std::fs::remove_file(&path)
4549            .expect("File should be deletable after dropping UninitializedSandbox");
4550        #[cfg(not(target_os = "windows"))]
4551        let _ = std::fs::remove_file(&path);
4552    }
4553
4554    /// Tests that `prepare_file_cow` rejects unaligned `guest_base`
4555    /// addresses eagerly, before allocating any OS resources.
4556    #[test]
4557    fn test_map_file_cow_unaligned_guest_base() {
4558        let (path, _) =
4559            create_test_file("hyperlight_test_map_file_cow_unaligned.bin", &[0xBB; 4096]);
4560
4561        let mut u_sbox =
4562            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4563                .unwrap();
4564
4565        // Use an intentionally unaligned address (page_size + 1).
4566        let unaligned_base: u64 = (page_size::get() + 1) as u64;
4567        let result = u_sbox.map_file_cow(&path, unaligned_base);
4568        assert!(
4569            result.is_err(),
4570            "map_file_cow should reject unaligned guest_base"
4571        );
4572
4573        let _ = std::fs::remove_file(&path);
4574    }
4575
4576    /// Tests that `prepare_file_cow` rejects empty files.
4577    #[test]
4578    fn test_map_file_cow_empty_file() {
4579        let temp_dir = std::env::temp_dir();
4580        let path = temp_dir.join("hyperlight_test_map_file_cow_empty.bin");
4581        let _ = std::fs::remove_file(&path);
4582        std::fs::File::create(&path).unwrap(); // create empty file
4583
4584        let mut u_sbox =
4585            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4586                .unwrap();
4587
4588        let guest_base: u64 = 0x1_0000_0000;
4589        let result = u_sbox.map_file_cow(&path, guest_base);
4590        assert!(result.is_err(), "map_file_cow should reject empty files");
4591
4592        let _ = std::fs::remove_file(&path);
4593    }
4594
4595    /// Tests that mapping two files to overlapping GPA ranges is rejected.
4596    #[test]
4597    fn test_map_file_cow_overlapping_mappings() {
4598        let (path1, _) =
4599            create_test_file("hyperlight_test_map_file_cow_overlap1.bin", &[0xAA; 4096]);
4600        let (path2, _) =
4601            create_test_file("hyperlight_test_map_file_cow_overlap2.bin", &[0xBB; 4096]);
4602
4603        let guest_base: u64 = 0x1_0000_0000;
4604
4605        let mut u_sbox =
4606            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4607                .unwrap();
4608
4609        // First mapping should succeed.
4610        u_sbox.map_file_cow(&path1, guest_base).unwrap();
4611
4612        // Second mapping at the same address should fail (overlap).
4613        let result = u_sbox.map_file_cow(&path2, guest_base);
4614        assert!(
4615            result.is_err(),
4616            "map_file_cow should reject overlapping guest address ranges"
4617        );
4618
4619        let _ = std::fs::remove_file(&path1);
4620        let _ = std::fs::remove_file(&path2);
4621    }
4622
4623    /// Tests that `map_file_cow` rejects a guest_base that overlaps
4624    /// the sandbox's shared memory region.
4625    #[test]
4626    fn test_map_file_cow_shared_mem_overlap() {
4627        let (path, _) = create_test_file(
4628            "hyperlight_test_map_file_cow_overlap_shm.bin",
4629            &[0xCC; 4096],
4630        );
4631
4632        let mut u_sbox =
4633            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4634                .unwrap();
4635
4636        // Use BASE_ADDRESS itself — smack in the middle of shared memory.
4637        let base_addr = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
4638        // page-align it (BASE_ADDRESS is 0x1000, already page-aligned)
4639        let result = u_sbox.map_file_cow(&path, base_addr);
4640        assert!(
4641            result.is_err(),
4642            "map_file_cow should reject guest_base inside shared memory"
4643        );
4644
4645        let _ = std::fs::remove_file(&path);
4646    }
4647
4648    #[test]
4649    fn map_region_rejects_overlapping_regions() {
4650        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4651            .build()
4652            .unwrap();
4653
4654        let mem1 = allocate_guest_memory();
4655        let mem2 = allocate_guest_memory();
4656        let guest_base: usize = 0x200000000;
4657        let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
4658
4659        // First mapping should succeed
4660        unsafe { sbox.map_region(&region1).unwrap() };
4661
4662        // Exact same range should fail
4663        let region2 = region_for_memory(&mem2, guest_base, MemoryRegionFlags::READ);
4664        let err = unsafe { sbox.map_region(&region2) }.unwrap_err();
4665        assert!(
4666            format!("{err:?}").contains("Overlapping"),
4667            "Expected Overlapping error, got: {err:?}"
4668        );
4669    }
4670
4671    #[test]
4672    fn map_region_rejects_partial_overlap() {
4673        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4674            .build()
4675            .unwrap();
4676
4677        // Use multi-page regions so partial overlap is geometrically possible
4678        let ps = page_size::get();
4679        let mem1 = page_aligned_memory(&vec![0xAA; ps * 2]); // 2 pages
4680        let mem2 = page_aligned_memory(&vec![0xBB; ps * 2]); // 2 pages
4681        let guest_base: usize = 0x200000000;
4682        let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
4683
4684        unsafe { sbox.map_region(&region1).unwrap() };
4685
4686        // region2 starts one page before region1, overlapping by one page
4687        let overlap_base = guest_base - ps;
4688        let region2 = region_for_memory(&mem2, overlap_base, MemoryRegionFlags::READ);
4689        let err = unsafe { sbox.map_region(&region2) }.unwrap_err();
4690        assert!(
4691            format!("{err:?}").contains("verlap"),
4692            "Expected overlap error for partial overlap, got: {err:?}"
4693        );
4694    }
4695
4696    #[test]
4697    fn map_region_allows_adjacent_non_overlapping() {
4698        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4699            .build()
4700            .unwrap();
4701
4702        let mem1 = allocate_guest_memory();
4703        let mem2 = allocate_guest_memory();
4704        let guest_base: usize = 0x200000000;
4705        let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
4706        let region_size = mem1.mem_size();
4707
4708        unsafe { sbox.map_region(&region1).unwrap() };
4709
4710        // Adjacent region (starts right after the first one ends) should succeed
4711        let adjacent_base = guest_base + region_size;
4712        let region2 = region_for_memory(&mem2, adjacent_base, MemoryRegionFlags::READ);
4713        unsafe { sbox.map_region(&region2).unwrap() };
4714    }
4715
4716    #[test]
4717    fn map_region_rejects_overlap_with_snapshot() {
4718        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4719            .build()
4720            .unwrap();
4721
4722        // Try to map at BASE_ADDRESS (0x1000) which overlaps the snapshot region
4723        let mem = allocate_guest_memory();
4724        let region = region_for_memory(
4725            &mem,
4726            crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS,
4727            MemoryRegionFlags::READ,
4728        );
4729        let err = unsafe { sbox.map_region(&region) }.unwrap_err();
4730        assert!(
4731            format!("{err:?}").contains("Overlapping"),
4732            "Expected Overlapping error for snapshot overlap, got: {err:?}"
4733        );
4734    }
4735
4736    #[test]
4737    fn map_region_rejects_overlap_with_scratch() {
4738        let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4739            .build()
4740            .unwrap();
4741
4742        // The scratch region occupies the top of the GPA space
4743        let scratch_addr = hyperlight_common::layout::scratch_base_gpa(
4744            crate::sandbox::SandboxConfiguration::DEFAULT_SCRATCH_SIZE,
4745        ) as usize;
4746        let mem = allocate_guest_memory();
4747        let region = region_for_memory(&mem, scratch_addr, MemoryRegionFlags::READ);
4748        let err = unsafe { sbox.map_region(&region) }.unwrap_err();
4749        assert!(
4750            format!("{err:?}").contains("verlap"),
4751            "Expected overlap error for scratch region, got: {err:?}"
4752        );
4753    }
4754
4755    #[cfg(target_arch = "x86_64")]
4756    mod msr_tests {
4757        use super::*;
4758        use crate::hypervisor::hyperlight_vm::{CreateHyperlightVmError, HyperlightVmError};
4759        use crate::hypervisor::regs::{
4760            MSR_APERF, MSR_BNDCFGS, MSR_CSTAR, MSR_DEBUGCTL, MSR_IA32_SSP,
4761            MSR_INTERRUPT_SSP_TABLE_ADDR, MSR_KERNEL_GS_BASE as KERNEL_GS_BASE, MSR_LSTAR,
4762            MSR_MPERF, MSR_MTRR_DEF_TYPE, MSR_MTRR_FIX64K_00000, MSR_PAT, MSR_PL0_SSP, MSR_PL1_SSP,
4763            MSR_PL2_SSP, MSR_PL3_SSP, MSR_S_CET, MSR_SFMASK, MSR_SPEC_CTRL, MSR_STAR,
4764            MSR_SYSENTER_CS as SYSENTER_CS, MSR_SYSENTER_EIP, MSR_SYSENTER_ESP, MSR_TSC,
4765            MSR_TSC_ADJUST, MSR_TSC_AUX, MSR_TSC_DEADLINE, MSR_TSX_CTRL, MSR_U_CET,
4766            MSR_UMWAIT_CONTROL, MSR_VIRT_SPEC_CTRL, MSR_XFD, MSR_XFD_ERR, MSR_XSS,
4767        };
4768        use crate::hypervisor::virtual_machine::{
4769            CreateVmError, RegisterError, ResetVcpuError, VmError,
4770        };
4771        use crate::sandbox::snapshot::Snapshot;
4772
4773        fn assert_msr_not_declarable(error: &HyperlightError, expected: u32) {
4774            assert!(
4775                matches!(
4776                    error,
4777                    HyperlightError::HyperlightVmError(HyperlightVmError::Create(
4778                        CreateHyperlightVmError::Vm(VmError::CreateVm(
4779                            CreateVmError::MsrNotDeclarable { msr, .. }
4780                        ))
4781                    )) if *msr == expected
4782                ),
4783                "expected MsrNotAllowable for {expected:#x}, got: {error:?}"
4784            );
4785        }
4786
4787        fn assert_snapshot_msr_index_invalid(error: &HyperlightError) {
4788            assert!(
4789                matches!(
4790                    error,
4791                    HyperlightError::HyperlightVmError(HyperlightVmError::Restore(
4792                        ResetVcpuError::Register(RegisterError::InvalidSnapshotMsrIndex { .. })
4793                    ))
4794                ),
4795                "expected InvalidSnapshotMsrIndex, got: {error:?}"
4796            );
4797        }
4798
4799        #[test]
4800        fn kernel_gs_base_does_not_leak_through_swapgs() {
4801            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4802                .build()
4803                .unwrap();
4804
4805            let original: u64 = sandbox.call("ReadKernelGsBaseViaSwapgs", ()).unwrap();
4806            let sentinel = if original == 0x0000_7AAA_5555_AAAA {
4807                0x0000_6BBB_4444_BBBB
4808            } else {
4809                0x0000_7AAA_5555_AAAA
4810            };
4811            let snapshot = sandbox.snapshot().unwrap();
4812
4813            sandbox
4814                .call::<()>("WriteKernelGsBaseViaSwapgs", sentinel)
4815                .unwrap();
4816            assert_eq!(
4817                sandbox
4818                    .call::<u64>("ReadKernelGsBaseViaSwapgs", ())
4819                    .unwrap(),
4820                sentinel
4821            );
4822
4823            sandbox.restore(snapshot).unwrap();
4824            assert_eq!(
4825                sandbox
4826                    .call::<u64>("ReadKernelGsBaseViaSwapgs", ())
4827                    .unwrap(),
4828                original,
4829                "KERNEL_GS_BASE leaked across restore"
4830            );
4831        }
4832
4833        /// KVM ignores a host TSC write within one second of the value it
4834        /// expects, so restores closer together than that exercise the KVM path.
4835        /// The 500 ms gaps tolerate host stalls shorter than that. WHP is
4836        /// excluded because it keeps elapsed time on hosts with `TSC_ADJUST`.
4837        #[test]
4838        #[cfg(any(kvm, mshv3))]
4839        fn restore_rewinds_tsc() {
4840            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4841                .build()
4842                .unwrap();
4843            let snapshot = sbox.snapshot().unwrap();
4844
4845            for restore in 0..3 {
4846                std::thread::sleep(std::time::Duration::from_millis(500));
4847                let before: u64 = sbox.call("ReadTsc", ()).unwrap();
4848                sbox.restore(snapshot.clone()).unwrap();
4849                let after: u64 = sbox.call("ReadTsc", ()).unwrap();
4850                assert!(
4851                    after < before,
4852                    "restore {restore} did not rewind TSC (before={before}, after={after})"
4853                );
4854            }
4855        }
4856
4857        /// KVM syncs a host TSC write of zero to the current offset.
4858        #[test]
4859        #[cfg(kvm)]
4860        fn restore_handles_zero_tsc() {
4861            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4862                .build()
4863                .unwrap();
4864            sbox.vm
4865                .restore_msrs(&[crate::hypervisor::regs::MsrEntry {
4866                    index: MSR_TSC,
4867                    value: 0,
4868                }])
4869                .unwrap();
4870            let tsc: u64 = sbox.call("ReadTsc", ()).unwrap();
4871            assert!(tsc < 1 << 62, "TSC jumped to {tsc:#x} after restoring zero");
4872        }
4873
4874        #[test]
4875        fn snapshot_msr_values_survive_full_in_memory_lifecycle() {
4876            let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4877                .guest_msrs(&[KERNEL_GS_BASE])
4878                .unwrap()
4879                .build()
4880                .unwrap();
4881            let first = 0x1111;
4882            let second = 0x2222;
4883            let third = 0x3333;
4884
4885            source
4886                .call::<()>("WriteMSR", (KERNEL_GS_BASE, first))
4887                .unwrap();
4888            assert_eq!(
4889                source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4890                first
4891            );
4892            let first_snapshot = source.snapshot().unwrap();
4893
4894            source
4895                .call::<()>("WriteMSR", (KERNEL_GS_BASE, second))
4896                .unwrap();
4897            assert_eq!(
4898                source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4899                second
4900            );
4901            source.restore(first_snapshot.clone()).unwrap();
4902            assert_eq!(
4903                source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4904                first
4905            );
4906
4907            let mut clone = SandboxBuilder::from_snapshot(first_snapshot.clone())
4908                .guest_msrs(&[KERNEL_GS_BASE])
4909                .unwrap()
4910                .build()
4911                .unwrap();
4912            assert_eq!(clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(), first);
4913
4914            clone
4915                .call::<()>("WriteMSR", (KERNEL_GS_BASE, third))
4916                .unwrap();
4917            assert_eq!(clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(), third);
4918            let third_snapshot = clone.snapshot().unwrap();
4919            source.restore(third_snapshot.clone()).unwrap();
4920            assert_eq!(
4921                source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4922                third
4923            );
4924
4925            let mut second_clone = SandboxBuilder::from_snapshot(third_snapshot)
4926                .guest_msrs(&[KERNEL_GS_BASE])
4927                .unwrap()
4928                .build()
4929                .unwrap();
4930            assert_eq!(
4931                second_clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4932                third
4933            );
4934            second_clone.restore(first_snapshot).unwrap();
4935            assert_eq!(
4936                second_clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4937                first
4938            );
4939        }
4940
4941        #[test]
4942        fn equivalent_msr_configs_are_order_independent_across_sandboxes() {
4943            let source_order = [KERNEL_GS_BASE, SYSENTER_CS];
4944            let target_order = [SYSENTER_CS, KERNEL_GS_BASE];
4945            let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4946                .guest_msrs(&source_order)
4947                .unwrap()
4948                .build()
4949                .unwrap();
4950            source
4951                .call::<()>("WriteMSR", (KERNEL_GS_BASE, 0x4444u64))
4952                .unwrap();
4953            assert_eq!(
4954                source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4955                0x4444
4956            );
4957            source
4958                .call::<()>("WriteMSR", (SYSENTER_CS, 0x5555u64))
4959                .unwrap();
4960            assert_eq!(source.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4961            let snapshot = source.snapshot().unwrap();
4962
4963            let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4964                .guest_msrs(&target_order)
4965                .unwrap()
4966                .build()
4967                .unwrap();
4968            target
4969                .call::<()>("WriteMSR", (KERNEL_GS_BASE, 0xAAAAu64))
4970                .unwrap();
4971            assert_eq!(
4972                target.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4973                0xAAAA
4974            );
4975            target
4976                .call::<()>("WriteMSR", (SYSENTER_CS, 0xBBBBu64))
4977                .unwrap();
4978            assert_eq!(target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0xBBBB);
4979            target.restore(snapshot.clone()).unwrap();
4980            assert_eq!(
4981                target.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4982                0x4444
4983            );
4984            assert_eq!(target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4985
4986            let mut clone = SandboxBuilder::from_snapshot(snapshot)
4987                .guest_msrs(&target_order)
4988                .unwrap()
4989                .build()
4990                .unwrap();
4991            assert_eq!(
4992                clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4993                0x4444
4994            );
4995            assert_eq!(clone.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4996        }
4997
4998        /// A restore succeeds when the destination declares a superset of the
4999        /// snapshot's guest MSRs. The snapshot's declared MSR keeps its saved
5000        /// value. An MSR the destination adds resets to the baseline.
5001        #[test]
5002        fn snapshot_restores_into_superset_guest_msrs() {
5003            const SYSENTER_ESP: u32 = 0x175;
5004            let sentinel: u64 = 0x1234;
5005            let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5006                .guest_msrs(&[SYSENTER_CS])
5007                .unwrap()
5008                .build()
5009                .unwrap();
5010            source
5011                .call::<()>("WriteMSR", (SYSENTER_CS, sentinel))
5012                .unwrap();
5013            let snapshot = source.snapshot().unwrap();
5014
5015            let mut clone = SandboxBuilder::from_snapshot(snapshot.clone())
5016                .guest_msrs(&[SYSENTER_CS, SYSENTER_ESP])
5017                .unwrap()
5018                .build()
5019                .unwrap();
5020            assert_eq!(clone.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), sentinel);
5021            let baseline: u64 = clone.call("ReadMSR", SYSENTER_ESP).unwrap();
5022
5023            let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5024                .guest_msrs(&[SYSENTER_CS, SYSENTER_ESP])
5025                .unwrap()
5026                .build()
5027                .unwrap();
5028            target
5029                .call::<()>("WriteMSR", (SYSENTER_ESP, baseline ^ 0x55))
5030                .unwrap();
5031            target.restore(snapshot).unwrap();
5032            assert_eq!(
5033                target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(),
5034                sentinel
5035            );
5036            // An MSR the destination adds resets to its baseline.
5037            assert_eq!(
5038                target.call::<u64>("ReadMSR", SYSENTER_ESP).unwrap(),
5039                baseline
5040            );
5041        }
5042
5043        /// A restore is rejected when the snapshot captured an MSR the
5044        /// destination neither declares nor covers as a core MSR. The contract
5045        /// is the same on every backend: both restore paths fail and poison
5046        /// the sandbox.
5047        #[test]
5048        fn snapshot_rejects_non_superset_guest_msrs() {
5049            const SYSENTER_ESP: u32 = 0x175;
5050            let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5051                .guest_msrs(&[SYSENTER_CS])
5052                .unwrap()
5053                .build()
5054                .unwrap();
5055            source
5056                .call::<()>("WriteMSR", (SYSENTER_CS, 0x1234u64))
5057                .unwrap();
5058            let snapshot = source.snapshot().unwrap();
5059
5060            // A destination that declares nothing, and one that declares a
5061            // disjoint MSR, both reject because the snapshot's SYSENTER_CS is
5062            // neither declared by the destination nor a core MSR.
5063            for dest in [&[][..], &[SYSENTER_ESP][..]] {
5064                let err = SandboxBuilder::from_snapshot(snapshot.clone())
5065                    .guest_msrs(dest)
5066                    .unwrap()
5067                    .build()
5068                    .expect_err("from_snapshot must reject an unrestorable snapshot MSR");
5069                assert_snapshot_msr_index_invalid(&err);
5070
5071                let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5072                    .guest_msrs(dest)
5073                    .unwrap()
5074                    .build()
5075                    .unwrap();
5076                let err = target
5077                    .restore(snapshot.clone())
5078                    .expect_err("restore must reject an unrestorable snapshot MSR");
5079                assert_snapshot_msr_index_invalid(&err);
5080                assert!(target.status().is_poisoned());
5081                assert!(matches!(
5082                    target.call::<String>("Echo", "hi".to_string()),
5083                    Err(HyperlightError::PoisonedSandbox)
5084                ));
5085            }
5086        }
5087
5088        #[test]
5089        fn from_pre_init_snapshot_uses_local_msr_reset_set() {
5090            let mut config = SandboxConfiguration::default();
5091            config.guest_msrs(&[KERNEL_GS_BASE]).unwrap();
5092            let snapshot = Arc::new(
5093                Snapshot::from_env(GuestBinary::FilePath(simple_guest_as_pathbuf()), config)
5094                    .unwrap(),
5095            );
5096            assert!(snapshot.msrs().is_none());
5097
5098            let mut sandbox = SandboxBuilder::from_snapshot(snapshot.clone())
5099                .guest_msrs(&[KERNEL_GS_BASE])
5100                .unwrap()
5101                .build()
5102                .unwrap();
5103            let baseline: u64 = sandbox.call("ReadMSR", KERNEL_GS_BASE).unwrap();
5104            sandbox
5105                .call::<()>("WriteMSR", (KERNEL_GS_BASE, baseline ^ 0x55))
5106                .unwrap();
5107            assert_eq!(
5108                sandbox.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
5109                baseline ^ 0x55
5110            );
5111        }
5112
5113        #[test]
5114        #[cfg(kvm)]
5115        fn guest_cannot_enable_x2apic_through_apic_base() {
5116            use crate::hypervisor::regs::APIC_BASE_X2APIC_ENABLE;
5117            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5118
5119            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5120                return;
5121            }
5122
5123            const MSR_IA32_APIC_BASE: u32 = 0x1B;
5124            const MSR_X2APIC_BASE: u32 = 0x800;
5125            const APIC_BASE_DEFAULT: u64 = 0xFEE0_0900;
5126
5127            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5128                .build()
5129                .unwrap();
5130            let snapshot = sandbox.snapshot().unwrap();
5131
5132            let x2apic_base = APIC_BASE_DEFAULT | APIC_BASE_X2APIC_ENABLE;
5133            let result = sandbox.call::<()>("WriteMSR", (MSR_IA32_APIC_BASE, x2apic_base));
5134            assert!(
5135                matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5136                "guest enabled x2APIC through APIC_BASE: {result:?}"
5137            );
5138            assert!(sandbox.status().is_poisoned());
5139            sandbox.restore(snapshot).unwrap();
5140            assert!(!sandbox.status().is_poisoned());
5141
5142            let result = sandbox.call::<()>("WriteMSR", (MSR_X2APIC_BASE, 1u64));
5143            assert!(
5144                matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5145                "x2APIC MSR access succeeded after restore: {result:?}"
5146            );
5147            assert!(sandbox.status().is_poisoned());
5148        }
5149
5150        #[test]
5151        #[cfg(kvm)]
5152        fn denied_msr_access_poisons_sandbox() {
5153            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5154
5155            match get_available_hypervisor() {
5156                Some(HypervisorType::Kvm) => {}
5157                _ => {
5158                    return;
5159                }
5160            }
5161
5162            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5163                .build()
5164                .unwrap();
5165
5166            let snapshot = sbox.snapshot().unwrap();
5167            let msr_index: u32 = 0xC000_0102; // IA32_KERNEL_GS_BASE
5168
5169            let result = sbox.call::<u64>("ReadMSR", msr_index);
5170            assert!(
5171                matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
5172                "RDMSR 0x{:X}: expected direct #GP, got: {:?}",
5173                msr_index,
5174                result
5175            );
5176            assert!(sbox.status().is_poisoned());
5177
5178            sbox.restore(snapshot.clone()).unwrap();
5179
5180            let result = sbox.call::<()>("WriteMSR", (msr_index, 0x5u64));
5181            assert!(
5182                matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
5183                "WRMSR 0x{:X}: expected direct #GP, got: {:?}",
5184                msr_index,
5185                result
5186            );
5187            assert!(sbox.status().is_poisoned());
5188        }
5189
5190        #[test]
5191        #[cfg(kvm)]
5192        fn batched_msr_probe_recovers_from_denied_reads() {
5193            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5194
5195            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5196                return;
5197            }
5198
5199            const KVM_CUSTOM_MSR: u32 = 0x4B56_4D00;
5200            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5201                .guest_msrs(&[KERNEL_GS_BASE])
5202                .unwrap()
5203                .build()
5204                .unwrap();
5205
5206            assert_eq!(
5207                sbox.call::<Vec<u8>>("ProbeReadableMSRs", (0u32, 4096u32))
5208                    .unwrap()
5209                    .len(),
5210                512
5211            );
5212            assert_eq!(
5213                sbox.call::<Vec<u8>>("ProbeReadableMSRs", (KERNEL_GS_BASE, 1u32))
5214                    .unwrap(),
5215                vec![1]
5216            );
5217            assert_eq!(
5218                sbox.call::<Vec<u8>>("ProbeReadableMSRs", (KVM_CUSTOM_MSR, 1u32))
5219                    .unwrap(),
5220                vec![0]
5221            );
5222            assert!(!sbox.status().is_poisoned());
5223            sbox.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap();
5224        }
5225
5226        #[test]
5227        #[cfg(target_arch = "x86_64")]
5228        fn nested_virtualization_is_hidden_from_guest() {
5229            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5230                .build()
5231                .unwrap();
5232
5233            let features: u32 = sandbox.call("NestedVirtualizationCpuid", ()).unwrap();
5234            assert_eq!(features & 0b11, 0, "guest CPUID exposes VMX or SVM");
5235        }
5236
5237        #[test]
5238        #[cfg(kvm)]
5239        fn nested_vmx_setup_msrs_are_denied() {
5240            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5241
5242            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5243                return;
5244            }
5245
5246            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5247                .build()
5248                .unwrap();
5249
5250            let snapshot = sandbox.snapshot().unwrap();
5251            let vmx_basic: u32 = 0x480;
5252            let result = sandbox.call::<u64>("ReadMSR", vmx_basic);
5253            assert!(
5254                matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5255                "RDMSR 0x{vmx_basic:X}: expected direct #GP, got: {result:?}"
5256            );
5257
5258            sandbox.restore(snapshot).unwrap();
5259            let feature_control: u32 = 0x3A;
5260            let result = sandbox.call::<()>("WriteMSR", (feature_control, 0x5u64));
5261            assert!(
5262                matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5263                "WRMSR 0x{feature_control:X}: expected direct #GP, got: {result:?}"
5264            );
5265        }
5266
5267        /// The guest cannot enter VMX operation, so the nested VM-enter/exit
5268        /// path that loads and stores MSRs through dedicated VMCS fields is
5269        /// unreachable. VMX is hidden from guest CPUID on every backend, so
5270        /// `CR4.VMXE` is a reserved bit and the guest faults.
5271        #[test]
5272        #[cfg(target_arch = "x86_64")]
5273        fn guest_cannot_enter_vmx_operation() {
5274            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5275                .build()
5276                .unwrap();
5277
5278            let result = sandbox.call::<()>("EnableVmxOperation", ());
5279            assert!(
5280                matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5281                "guest entered VMX operation via CR4.VMXE: {result:?}"
5282            );
5283            assert!(sandbox.status().is_poisoned());
5284        }
5285
5286        /// Executing a VM-enter (`VMLAUNCH`) in the guest faults. The guest is
5287        /// never in VMX operation, so the instruction raises `#UD` before any
5288        /// VMCS-field MSR load or store can run. This exercises the instruction
5289        /// path directly, not just the `CR4.VMXE` prerequisite.
5290        #[test]
5291        #[cfg(target_arch = "x86_64")]
5292        fn guest_vmlaunch_faults() {
5293            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5294                .build()
5295                .unwrap();
5296
5297            let result = sandbox.call::<()>("ExecuteVmlaunch", ());
5298            assert!(
5299                matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5300                "guest executed VMLAUNCH without faulting: {result:?}"
5301            );
5302            assert!(sandbox.status().is_poisoned());
5303        }
5304
5305        /// x2APIC is denied at the MSR level and Hyperlight keeps the APIC in
5306        /// xAPIC mode, so the guest CPUID does not advertise x2APIC.
5307        #[test]
5308        #[cfg(kvm)]
5309        fn x2apic_is_hidden_from_guest_cpuid() {
5310            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5311
5312            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5313                return;
5314            }
5315
5316            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5317                .build()
5318                .unwrap();
5319
5320            assert!(
5321                !sandbox.call::<bool>("X2apicSupported", ()).unwrap(),
5322                "guest CPUID advertises x2APIC"
5323            );
5324        }
5325
5326        /// A write-only command cannot enter the reset set.
5327        #[test]
5328        #[cfg(target_arch = "x86_64")]
5329        fn test_allow_non_resettable_msr_fails_creation() {
5330            // IA32_PRED_CMD, a write-only command MSR
5331            let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5332                .guest_msrs(&[0x49])
5333                .unwrap()
5334                .build()
5335                .unwrap_err();
5336
5337            assert_msr_not_declarable(&err, 0x49);
5338        }
5339
5340        /// Host support cannot authorize an unclassified MSR.
5341        #[test]
5342        #[cfg(kvm)]
5343        fn unclassified_declared_msr_rejected_at_creation() {
5344            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5345
5346            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5347                return;
5348            }
5349
5350            // IA32_MISC_ENABLE: host-probeable, not in MSR_TABLE
5351            let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5352                .guest_msrs(&[0x1A0])
5353                .unwrap()
5354                .build()
5355                .expect_err("an unclassified declared MSR must be rejected at creation");
5356
5357            assert_msr_not_declarable(&err, 0x1A0);
5358        }
5359
5360        #[test]
5361        #[cfg(target_arch = "x86_64")]
5362        fn test_multiple_guest_msrs_reset_across_restore() {
5363            // Resettable MSRs the guest may write once declared.
5364            let msrs: [u32; 4] = [0x174, 0x175, 0x176, 0xC000_0102];
5365
5366            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5367                .guest_msrs(&msrs)
5368                .unwrap()
5369                .build()
5370                .unwrap();
5371
5372            let baseline_snapshot = sbox.snapshot().unwrap();
5373
5374            let value: u64 = 0x1000;
5375            for &msr in &msrs {
5376                sbox.call::<()>("WriteMSR", (msr, value)).unwrap();
5377                let read_value: u64 = sbox.call("ReadMSR", msr).unwrap();
5378                assert_eq!(read_value, value, "MSR 0x{msr:X} should be writable");
5379            }
5380
5381            sbox.restore(baseline_snapshot).unwrap();
5382            for &msr in &msrs {
5383                let read_value: u64 = sbox.call("ReadMSR", msr).unwrap();
5384                assert_ne!(
5385                    read_value, value,
5386                    "MSR 0x{msr:X} should be reset to baseline across restore"
5387                );
5388            }
5389        }
5390
5391        /// A declared guest write must not survive restore.
5392        #[test]
5393        #[cfg(target_arch = "x86_64")]
5394        fn test_declared_msr_does_not_leak_across_restore() {
5395            let msr_index: u32 = 0xC000_0102; // IA32_KERNEL_GS_BASE
5396            let sentinel: u64 = 0xCAFE_F00D;
5397
5398            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5399                .guest_msrs(&[msr_index])
5400                .unwrap()
5401                .build()
5402                .unwrap();
5403
5404            let baseline = sbox.snapshot().unwrap();
5405            let original: u64 = sbox.call("ReadMSR", msr_index).unwrap();
5406            assert_ne!(
5407                original, sentinel,
5408                "test sentinel must differ from the baseline value"
5409            );
5410
5411            sbox.call::<()>("WriteMSR", (msr_index, sentinel)).unwrap();
5412            assert_eq!(
5413                sbox.call::<u64>("ReadMSR", msr_index).unwrap(),
5414                sentinel,
5415                "sentinel should be observable before restore"
5416            );
5417            sbox.restore(baseline).unwrap();
5418
5419            let after: u64 = sbox.call("ReadMSR", msr_index).unwrap();
5420            assert_ne!(after, sentinel, "sentinel leaked across restore");
5421            assert_eq!(after, original, "MSR not reset to its baseline value");
5422        }
5423
5424        /// KVM denies DEBUGCTL through its filter and x2APIC through xAPIC mode.
5425        #[test]
5426        #[cfg(all(kvm, target_arch = "x86_64"))]
5427        fn test_debugctl_and_x2apic_msr_denied_by_default() {
5428            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5429
5430            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5431                return;
5432            }
5433
5434            for msr_index in [0x1D9_u32, 0x800] {
5435                let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5436                    .build()
5437                    .unwrap();
5438
5439                let result = sbox.call::<()>("WriteMSR", (msr_index, 0x1u64));
5440                assert!(
5441                    matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
5442                    "WRMSR 0x{msr_index:X}: expected direct #GP, got: {result:?}"
5443                );
5444                assert!(
5445                    sbox.status().is_poisoned(),
5446                    "sandbox should be poisoned after a denied WRMSR to 0x{msr_index:X}"
5447                );
5448            }
5449        }
5450
5451        #[test]
5452        #[cfg(all(kvm, target_arch = "x86_64"))]
5453        fn all_kvm_custom_msrs_are_denied() {
5454            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5455
5456            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5457                return;
5458            }
5459
5460            const KVM_CUSTOM_MSR_START: u32 = 0x4B56_4D00;
5461            const KVM_CUSTOM_MSR_END: u32 = 0x4B56_4DFF;
5462
5463            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5464                .build()
5465                .unwrap();
5466            let snapshot = sandbox.snapshot().unwrap();
5467
5468            for index in KVM_CUSTOM_MSR_START..=KVM_CUSTOM_MSR_END {
5469                let result = sandbox.call::<u64>("ReadMSR", index);
5470                assert!(
5471                    matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5472                    "RDMSR {index:#x} was not denied: {result:?}"
5473                );
5474                sandbox.restore(snapshot.clone()).unwrap();
5475
5476                let result = sandbox.call::<()>("WriteMSR", (index, 1u64));
5477                assert!(
5478                    matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5479                    "WRMSR {index:#x} was not denied: {result:?}"
5480                );
5481                sandbox.restore(snapshot.clone()).unwrap();
5482            }
5483        }
5484
5485        /// Unresettable feature-class MSRs must not retain guest writes. PMU,
5486        /// LBR, and FRED are perfmon or feature gated. The AMD virtualization
5487        /// MSRs are gated on nested-virt capability the sandbox never requests.
5488        #[test]
5489        #[cfg(target_arch = "x86_64")]
5490        fn unresettable_msr_classes_do_not_leak() {
5491            let cases: &[(u32, &str)] = &[
5492                (0xC1, "PMU IA32_PMC0"),
5493                (0x186, "PMU IA32_PERFEVTSEL0"),
5494                (0x38F, "PMU IA32_PERF_GLOBAL_CTRL"),
5495                (0x1C8, "LBR_SELECT"),
5496                (0x14CE, "arch-LBR IA32_LBR_CTL"),
5497                (0x1D4, "FRED IA32_FRED_CONFIG"),
5498                (0xC001_0114, "AMD VM_CR"),
5499                (0xC001_0117, "AMD VM_HSAVE_PA"),
5500            ];
5501
5502            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5503                .build()
5504                .unwrap();
5505
5506            for &(msr, _name) in cases {
5507                assert_msr_write_does_not_survive_restore(&mut sbox, msr, 0x1);
5508            }
5509        }
5510
5511        /// A guest write to IA32_MISC_ENABLE leaves no retained state. Hyper-V
5512        /// drops the write on Intel and faults it on AMD.
5513        #[test]
5514        #[cfg(target_arch = "x86_64")]
5515        fn misc_enable_guest_write_does_not_survive_restore() {
5516            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5517                .build()
5518                .unwrap();
5519            assert_msr_write_does_not_survive_restore(&mut sbox, 0x1A0, 1u64 << 40);
5520        }
5521
5522        /// Every stateful table entry needs runtime reset coverage.
5523        #[test]
5524        #[cfg(target_arch = "x86_64")]
5525        fn runtime_msr_table_entries_are_justified() {
5526            use crate::hypervisor::regs::resettable_msr_indices;
5527
5528            #[cfg(kvm)]
5529            let is_kvm = matches!(
5530                crate::hypervisor::virtual_machine::get_available_hypervisor(),
5531                Some(crate::hypervisor::virtual_machine::HypervisorType::Kvm)
5532            );
5533            #[cfg(not(kvm))]
5534            let is_kvm = false;
5535
5536            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5537                .build()
5538                .unwrap();
5539
5540            let reset_indices: Vec<u32> = sbox.vm.reset_set_indices();
5541
5542            for index in resettable_msr_indices() {
5543                if !reset_indices.contains(&index) {
5544                    assert_omitted_msr_does_not_retain(&mut sbox, index);
5545                } else if is_kvm && index == KERNEL_GS_BASE {
5546                    // Direct WRMSR is denied. The dedicated SWAPGS test proves
5547                    // the instruction-side mutation is restored.
5548                } else if (index == MSR_TSC && !is_kvm) || matches!(index, MSR_MPERF | MSR_APERF) {
5549                    assert_guest_counter_is_writable_and_restored(&mut sbox, index);
5550                } else if let Some(test_value) = guest_write_test_value(index) {
5551                    assert_guest_msr_is_writable_and_restored(&mut sbox, index, test_value);
5552                } else {
5553                    assert!(
5554                        reset_exception_reason(index).is_some(),
5555                        "MSR 0x{index:X} is in the reset set without positive guest-write coverage or an explicit reason"
5556                    );
5557                }
5558            }
5559        }
5560
5561        fn assert_omitted_msr_does_not_retain(sbox: &mut Sandbox, index: u32) {
5562            let baseline = sbox.snapshot().unwrap();
5563            let original: u64 = match sbox.call("ReadMSR", index) {
5564                Ok(value) => value,
5565                Err(_) => {
5566                    assert!(
5567                        sbox.status().is_poisoned(),
5568                        "0x{index:X}: fault did not poison sandbox"
5569                    );
5570                    sbox.restore(baseline).unwrap();
5571                    return;
5572                }
5573            };
5574            let preferred = guest_write_test_value(index).unwrap_or(original ^ 1);
5575            let candidates = [preferred, original ^ 1, original ^ 2, 0, 1, 0x1000];
5576
5577            for candidate in candidates {
5578                if candidate == original {
5579                    continue;
5580                }
5581                if sbox.call::<()>("WriteMSR", (index, candidate)).is_err() {
5582                    assert!(
5583                        sbox.status().is_poisoned(),
5584                        "0x{index:X}: fault did not poison sandbox"
5585                    );
5586                    sbox.restore(baseline.clone()).unwrap();
5587                    continue;
5588                }
5589                let written: u64 = sbox.call("ReadMSR", index).unwrap_or_else(|error| {
5590                    panic!("0x{index:X}: read after successful write failed: {error:?}")
5591                });
5592                if written != original {
5593                    sbox.restore(baseline).unwrap();
5594                    let after: u64 = sbox.call("ReadMSR", index).unwrap();
5595                    assert_eq!(
5596                        after, original,
5597                        "0x{index:X}: guest retained a write but the MSR is absent from the reset set"
5598                    );
5599                    return;
5600                }
5601                sbox.restore(baseline.clone()).unwrap();
5602            }
5603        }
5604
5605        fn guest_write_test_value(index: u32) -> Option<u64> {
5606            match index {
5607                SYSENTER_CS => Some(0x10),
5608                MSR_SYSENTER_ESP | MSR_SYSENTER_EIP => Some(0x1000),
5609                MSR_PAT => Some(0x0007_0406_0007_0406),
5610                MSR_STAR => Some(0x001B_0008_0000_0000),
5611                MSR_LSTAR | MSR_CSTAR => Some(0x1000),
5612                MSR_SFMASK => Some(0x200),
5613                KERNEL_GS_BASE => Some(0x1000),
5614                MSR_TSC_ADJUST => Some(0x1000),
5615                MSR_TSC_AUX => Some(0x5),
5616                MSR_MTRR_DEF_TYPE => Some(0xC00),
5617                0x200..=0x21F if index & 1 == 0 => Some(0x6), // MTRR_PHYSBASEn
5618                0x200..=0x21F => Some(0x800),                 // MTRR_PHYSMASKn
5619                MSR_MTRR_FIX64K_00000 | 0x258 | 0x259 | 0x268..=0x26F => {
5620                    Some(0x0606_0606_0606_0606)
5621                }
5622                _ => None,
5623            }
5624        }
5625
5626        fn reset_exception_reason(index: u32) -> Option<&'static str> {
5627            match index {
5628                MSR_TSC => Some("KVM denies direct guest TSC MSR access"),
5629                MSR_IA32_SSP => Some(
5630                    "active SSP has no architectural RDMSR/WRMSR; covered by active_ssp_does_not_leak_across_restore",
5631                ),
5632                MSR_DEBUGCTL => Some("DEBUGCTL support depends on exposed debug features"),
5633                MSR_SPEC_CTRL => Some("SPEC_CTRL writable bits depend on mitigation features"),
5634                MSR_U_CET
5635                | MSR_S_CET
5636                | MSR_PL0_SSP
5637                | MSR_PL1_SSP
5638                | MSR_PL2_SSP
5639                | MSR_PL3_SSP
5640                | MSR_INTERRUPT_SSP_TABLE_ADDR => {
5641                    Some("CET writable state depends on exposed CET features")
5642                }
5643                MSR_TSX_CTRL => Some("TSX_CTRL writable bits depend on exposed TSX features"),
5644                MSR_XFD | MSR_XFD_ERR => Some("XFD writable bits depend on exposed XSAVE features"),
5645                MSR_UMWAIT_CONTROL => {
5646                    Some("UMWAIT_CONTROL writable bits depend on exposed WAITPKG features")
5647                }
5648                MSR_TSC_DEADLINE => {
5649                    Some("TSC_DEADLINE writable bits depend on exposed APIC-timer features")
5650                }
5651                MSR_BNDCFGS => Some("BNDCFGS writable bits depend on exposed MPX features"),
5652                MSR_XSS => Some("XSS writable bits depend on exposed XSAVE features"),
5653                MSR_VIRT_SPEC_CTRL => {
5654                    Some("VIRT_SPEC_CTRL writable bits depend on exposed AMD SSBD virtualization")
5655                }
5656                _ => None,
5657            }
5658        }
5659
5660        fn assert_guest_msr_is_writable_and_restored(
5661            sbox: &mut Sandbox,
5662            index: u32,
5663            sentinel: u64,
5664        ) {
5665            let baseline = sbox.snapshot().unwrap();
5666            let original: u64 = sbox
5667                .call("ReadMSR", index)
5668                .unwrap_or_else(|error| panic!("0x{index:X}: guest RDMSR failed: {error:?}"));
5669            let value = if original == sentinel { 0 } else { sentinel };
5670
5671            sbox.call::<()>("WriteMSR", (index, value))
5672                .unwrap_or_else(|error| panic!("0x{index:X}: guest WRMSR failed: {error:?}"));
5673            let written: u64 = sbox
5674                .call("ReadMSR", index)
5675                .unwrap_or_else(|error| panic!("0x{index:X}: guest read-back failed: {error:?}"));
5676            assert_eq!(written, value, "0x{index:X}: guest write did not stick");
5677
5678            sbox.restore(baseline).unwrap();
5679            let restored: u64 = sbox.call("ReadMSR", index).unwrap();
5680            assert_eq!(
5681                restored, original,
5682                "0x{index:X}: restore did not recover the baseline"
5683            );
5684        }
5685
5686        fn assert_guest_counter_is_writable_and_restored(sbox: &mut Sandbox, index: u32) {
5687            let baseline = sbox.snapshot().unwrap();
5688            let original: u64 = sbox.call("ReadMSR", index).unwrap();
5689            let jump = original.wrapping_add(1 << 60);
5690
5691            sbox.call::<()>("WriteMSR", (index, jump)).unwrap();
5692            let written: u64 = sbox.call("ReadMSR", index).unwrap();
5693            assert!(
5694                written >= jump / 2,
5695                "0x{index:X}: guest write did not stick"
5696            );
5697
5698            sbox.restore(baseline).unwrap();
5699            let restored: u64 = sbox.call("ReadMSR", index).unwrap();
5700            assert!(
5701                restored < jump / 2,
5702                "0x{index:X}: restore did not pull the counter below the guest-written jump"
5703            );
5704        }
5705
5706        /// Verifies that a guest MSR write faults or resets to its baseline.
5707        #[cfg(target_arch = "x86_64")]
5708        fn assert_msr_write_does_not_survive_restore(sbox: &mut Sandbox, msr: u32, sentinel: u64) {
5709            let baseline = sbox.snapshot().unwrap();
5710            let original: u64 = match sbox.call("ReadMSR", msr) {
5711                Ok(v) => v,
5712                Err(_) => {
5713                    assert!(
5714                        sbox.status().is_poisoned(),
5715                        "0x{msr:X}: a faulting RDMSR should poison the sandbox"
5716                    );
5717                    sbox.restore(baseline).unwrap();
5718                    return;
5719                }
5720            };
5721            assert_ne!(
5722                original, sentinel,
5723                "0x{msr:X}: sentinel must differ from baseline"
5724            );
5725
5726            if sbox.call::<()>("WriteMSR", (msr, sentinel)).is_err() {
5727                assert!(
5728                    sbox.status().is_poisoned(),
5729                    "0x{msr:X}: a faulting WRMSR should poison the sandbox"
5730                );
5731                sbox.restore(baseline).unwrap();
5732                return;
5733            }
5734
5735            sbox.restore(baseline).unwrap();
5736            let after: u64 = sbox.call("ReadMSR", msr).unwrap();
5737            assert_eq!(
5738                after, original,
5739                "0x{msr:X}: MSR leaked across restore (expected 0x{original:X}, got 0x{after:X})"
5740            );
5741        }
5742
5743        /// Audits Hyper-V MSR bitmap ranges for guest state retained by restore.
5744        #[test]
5745        #[ignore = "slow host-dependent hardware MSR audit"]
5746        #[cfg(target_arch = "x86_64")]
5747        fn test_no_msr_leaks_across_restore_full_window_sweep() {
5748            // Free-running counters use a magnitude check after restore.
5749            const FREE_RUNNING: &[u32] = &[
5750                0x10, // IA32_TIME_STAMP_COUNTER
5751                0xE7, // IA32_MPERF
5752                0xE8, // IA32_APERF
5753            ];
5754
5755            #[cfg(kvm)]
5756            if matches!(
5757                crate::hypervisor::virtual_machine::get_available_hypervisor(),
5758                Some(crate::hypervisor::virtual_machine::HypervisorType::Kvm)
5759            ) {
5760                return;
5761            }
5762
5763            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5764                .build()
5765                .unwrap();
5766
5767            let baseline = sbox.snapshot().unwrap();
5768
5769            // At least one retained write must exercise restore.
5770            let mut readable = 0usize;
5771            let mut exercised: Vec<u32> = Vec::new();
5772            let mut read_only: Vec<u32> = Vec::new();
5773            let mut masked_only: Vec<u32> = Vec::new();
5774            // Collect all free-running leaks for one diagnostic.
5775            let mut free_running_leaked: Vec<u32> = Vec::new();
5776
5777            const PROBE_CHUNK_SIZE: u32 = 4096;
5778            // Architectural and low model-specific indices.
5779            let low = 0x0000_0000u32..=0x0000_1FFF;
5780            // Hyper-V synthetic indices.
5781            let hyperv_synthetic = 0x4000_0000u32..=0x4000_1FFF;
5782            // Extended and AMD model-specific indices.
5783            let extended = 0xC000_0000u32..=0xC001_FFFF;
5784
5785            let mut readable_msrs = Vec::new();
5786            for window in [low, hyperv_synthetic, extended] {
5787                let window_end = *window.end();
5788                for chunk_start in window.step_by(PROBE_CHUNK_SIZE as usize) {
5789                    let chunk_len = PROBE_CHUNK_SIZE.min(window_end - chunk_start + 1);
5790                    let bitmap: Vec<u8> = sbox
5791                        .call("ProbeReadableMSRs", (chunk_start, chunk_len))
5792                        .unwrap();
5793                    assert_eq!(bitmap.len(), chunk_len.div_ceil(8) as usize);
5794                    readable_msrs.extend((0..chunk_len).filter_map(|offset| {
5795                        let byte = bitmap[offset as usize / 8];
5796                        (byte & (1 << (offset % 8)) != 0).then_some(chunk_start + offset)
5797                    }));
5798                }
5799            }
5800
5801            for msr in readable_msrs {
5802                let original: u64 = sbox.call("ReadMSR", msr).unwrap();
5803                readable += 1;
5804
5805                // A large jump distinguishes reset from normal counter progress.
5806                if FREE_RUNNING.contains(&msr) {
5807                    let jump = original.wrapping_add(1 << 60);
5808                    if sbox.call::<()>("WriteMSR", (msr, jump)).is_err() {
5809                        sbox.restore(baseline.clone()).unwrap();
5810                        read_only.push(msr);
5811                        continue;
5812                    }
5813                    let planted = match sbox.call::<u64>("ReadMSR", msr) {
5814                        Ok(v) => v,
5815                        Err(_) => {
5816                            sbox.restore(baseline.clone()).unwrap();
5817                            masked_only.push(msr);
5818                            continue;
5819                        }
5820                    };
5821                    if planted < jump / 2 {
5822                        sbox.restore(baseline.clone()).unwrap();
5823                        masked_only.push(msr);
5824                        continue;
5825                    }
5826                    sbox.restore(baseline.clone()).unwrap();
5827                    let after: u64 = sbox.call("ReadMSR", msr).unwrap();
5828                    if after < jump / 2 {
5829                        exercised.push(msr);
5830                    } else {
5831                        free_running_leaked.push(msr);
5832                    }
5833                    continue;
5834                }
5835
5836                // Multiple candidates cover MSRs with restricted writable bits.
5837                let candidates = [
5838                    original ^ 0x55,
5839                    original ^ 0x1,
5840                    original ^ (1 << 12),
5841                    original ^ (1 << 20),
5842                    original ^ (1 << 32),
5843                    original.wrapping_add(1),
5844                    0,
5845                ];
5846                let mut planted = false;
5847                let mut saw_write = false;
5848                for cand in candidates {
5849                    if cand == original {
5850                        continue;
5851                    }
5852                    if sbox.call::<()>("WriteMSR", (msr, cand)).is_err() {
5853                        sbox.restore(baseline.clone()).unwrap();
5854                        continue;
5855                    }
5856                    saw_write = true;
5857                    match sbox.call::<u64>("ReadMSR", msr) {
5858                        Ok(v) if v != original => {
5859                            planted = true;
5860                            break;
5861                        }
5862                        _ => {
5863                            sbox.restore(baseline.clone()).unwrap();
5864                        }
5865                    }
5866                }
5867
5868                if planted {
5869                    sbox.restore(baseline.clone()).unwrap();
5870                    match sbox.call::<u64>("ReadMSR", msr) {
5871                        Ok(after) => assert_eq!(
5872                            after, original,
5873                            "0x{msr:X}: a guest MSR write leaked across restore \
5874                         (expected 0x{original:X}, got 0x{after:X})"
5875                        ),
5876                        Err(e) => panic!("0x{msr:X}: read-back after restore failed: {e:?}"),
5877                    }
5878                    exercised.push(msr);
5879                } else if saw_write {
5880                    masked_only.push(msr);
5881                } else {
5882                    read_only.push(msr);
5883                }
5884            }
5885
5886            let fmt = |v: &[u32]| {
5887                v.iter()
5888                    .map(|m| format!("0x{m:X}"))
5889                    .collect::<Vec<_>>()
5890                    .join(", ")
5891            };
5892            eprintln!(
5893                "full-window MSR sweep: readable={readable} exercised={} masked_only={} read_only={}",
5894                exercised.len(),
5895                masked_only.len(),
5896                read_only.len()
5897            );
5898            eprintln!("  exercised:   [{}]", fmt(&exercised));
5899            eprintln!("  masked_only: [{}]", fmt(&masked_only));
5900            eprintln!("  read_only:   [{}]", fmt(&read_only));
5901            eprintln!("  free_running_leaked: [{}]", fmt(&free_running_leaked));
5902            assert!(
5903                free_running_leaked.is_empty(),
5904                "free-running MSRs not reset across restore on this backend: [{}]",
5905                fmt(&free_running_leaked)
5906            );
5907            assert!(
5908                !exercised.is_empty(),
5909                "sweep was vacuous: no guest MSR write ever retained a value that restore \
5910             then rolled back, so the rollback path was never exercised"
5911            );
5912        }
5913
5914        /// Active SSP is guest-writable state the Hyper-V backends reset
5915        /// across restore. Skips where the guest cannot use CET shadow
5916        /// stacks, which includes every KVM host.
5917        #[test]
5918        #[cfg(all(any(mshv3, target_os = "windows"), target_arch = "x86_64"))]
5919        fn active_ssp_does_not_leak_across_restore() {
5920            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5921                .build()
5922                .unwrap();
5923
5924            if !sbox.call::<bool>("CetShadowStackSupported", ()).unwrap() {
5925                return;
5926            }
5927
5928            let baseline = sbox.snapshot().unwrap();
5929            let original: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
5930
5931            let mutated: u64 = sbox.call("IncrementActiveSsp", ()).unwrap();
5932            assert_ne!(mutated, original, "guest did not change active SSP");
5933            let seen: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
5934            assert_eq!(seen, mutated, "guest did not observe its own SSP mutation");
5935
5936            sbox.restore(baseline).unwrap();
5937
5938            let after: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
5939            assert_eq!(
5940                after, original,
5941                "active SSP leaked across restore (original=0x{original:X}, mutated=0x{mutated:X}, after=0x{after:X})"
5942            );
5943        }
5944
5945        /// Hyperlight hides CET from KVM guests, so shadow stacks cannot be
5946        /// enabled and active SSP cannot be moved. Active SSP has no
5947        /// architectural MSR, so it is absent from the KVM reset set and the
5948        /// backend never restores it. Hiding CET keeps that gap unreachable.
5949        #[test]
5950        #[cfg(all(kvm, target_arch = "x86_64"))]
5951        fn kvm_does_not_expose_cet_to_guest() {
5952            use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5953
5954            if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5955                return;
5956            }
5957
5958            let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5959                .build()
5960                .unwrap();
5961            assert!(
5962                !sbox.call::<bool>("CetShadowStackSupported", ()).unwrap(),
5963                "KVM guest CPUID exposes CET shadow stacks"
5964            );
5965
5966            // With CET hidden the host cannot read or write IA32_S_CET, so
5967            // allowing it is rejected at VM creation.
5968            let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5969                .guest_msrs(&[MSR_S_CET])
5970                .unwrap()
5971                .build()
5972                .expect_err("allowing IA32_S_CET must be rejected when CET is hidden");
5973            assert_msr_not_declarable(&err, MSR_S_CET);
5974        }
5975    }
5976
5977    /// Tests for [`Sandbox::from_snapshot`] in-memory.
5978    mod from_snapshot {
5979        use std::sync::Arc;
5980
5981        use hyperlight_common::layout;
5982        use hyperlight_testing::simple_guest_as_pathbuf;
5983
5984        use crate::func::Registerable;
5985        use crate::sandbox::SandboxConfiguration;
5986        use crate::sandbox::snapshot::Snapshot;
5987        use crate::{GuestBinary, HostFunctions, HyperlightError, Sandbox, SandboxBuilder};
5988
5989        fn make_sandbox() -> Sandbox {
5990            let path = simple_guest_as_pathbuf();
5991            SandboxBuilder::from_file(path).build().unwrap()
5992        }
5993
5994        /// Sandbox with an extra `Add(i32, i32) -> i32` host function.
5995        fn make_sandbox_with_add() -> Sandbox {
5996            let path = simple_guest_as_pathbuf();
5997            SandboxBuilder::from_file(path)
5998                .host_function("Add", |a: i32, b: i32| a + b)
5999                .build()
6000                .unwrap()
6001        }
6002
6003        fn host_funcs_with_matching_add() -> HostFunctions {
6004            let mut hf = HostFunctions::default();
6005            hf.register_host_function("Add", |a: i32, b: i32| Ok(a + b))
6006                .unwrap();
6007            hf
6008        }
6009
6010        #[test]
6011        fn round_trip_running_sandbox() {
6012            let mut sbox = make_sandbox();
6013            sbox.call::<i32>("AddToStatic", 11i32).unwrap();
6014            let snapshot = sbox.snapshot().unwrap();
6015            assert!(snapshot.virtq().is_some());
6016            let mut sbox2 = SandboxBuilder::from_snapshot(snapshot).build().unwrap();
6017            super::assert_virtq_attached(&sbox2);
6018            assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 11);
6019            let echoed: String = sbox2.call("Echo", "hi".to_string()).unwrap();
6020            assert_eq!(echoed, "hi");
6021        }
6022
6023        #[test]
6024        fn rejects_noncanonical_transport_snapshot() {
6025            let mut sbox = make_sandbox();
6026            sbox.call::<i32>("AddToStatic", 1i32).unwrap();
6027
6028            // Checkpointing repairs the rings, so inject corruption afterward.
6029            sbox.checkpoint_transport_for_snapshot().unwrap();
6030
6031            let layout = &sbox.mem_mgr.layout;
6032            let scratch_base = layout::scratch_base_gpa(layout.get_scratch_size());
6033
6034            let ring_offset =
6035                (layout.get_transport_arena().g2h_ring_addr() - scratch_base) as usize;
6036
6037            sbox.mem_mgr
6038                .scratch_mem
6039                .write::<u64>(ring_offset, 1)
6040                .unwrap();
6041
6042            let Err(err) = sbox.snapshot() else {
6043                panic!("noncanonical transport must fail snapshot creation");
6044            };
6045
6046            assert!(err.to_string().contains("invalid canonical G2H image"));
6047        }
6048
6049        #[test]
6050        fn round_trip_pre_init_snapshot() {
6051            let path = simple_guest_as_pathbuf();
6052            let snap =
6053                Snapshot::from_env(GuestBinary::FilePath(path), SandboxConfiguration::default())
6054                    .unwrap();
6055            assert!(snap.virtq().is_none());
6056            let mut sbox = SandboxBuilder::from_snapshot(Arc::new(snap))
6057                .build()
6058                .unwrap();
6059            assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 0);
6060        }
6061
6062        /// `max_guest_log_level` configured through the
6063        /// `SandboxConfiguration` passed to `from_snapshot` is honored for a
6064        /// pre-init (`NextAction::Initialise`) snapshot: the guest runs its
6065        /// entrypoint with the configured filter, so a higher level lets more
6066        /// guest log messages through than a lower one. Before this was
6067        /// plumbed, `from_snapshot` always passed `None` (falling back to
6068        /// `RUST_LOG`), so both counts below would be equal.
6069        ///
6070        /// Ignored because it installs a process-global `log` logger; run
6071        /// in isolation via the `test-isolated` Justfile recipe.
6072        #[test]
6073        #[ignore]
6074        fn max_guest_log_level_is_honored_from_snapshot() {
6075            use hyperlight_common::log_level::GuestLogFilter;
6076            use hyperlight_testing::logger::{LOGGER, Logger};
6077            use tracing_core::LevelFilter;
6078
6079            Logger::initialize_test_logger();
6080            LOGGER.set_max_level(log::LevelFilter::Trace);
6081
6082            // Build a fresh pre-init sandbox with the given guest log level,
6083            // emit one guest log message at each level, and count how many
6084            // reached the host (guest logs carry target "hyperlight_guest").
6085            let count_guest_logs = |max_level: LevelFilter| -> usize {
6086                let snap = Snapshot::from_env(
6087                    GuestBinary::FilePath(simple_guest_as_pathbuf()),
6088                    SandboxConfiguration::default(),
6089                )
6090                .unwrap();
6091                let mut config = SandboxConfiguration::default();
6092                config.set_max_guest_log_level(max_level);
6093                let mut sbox =
6094                    Sandbox::from_snapshot(Arc::new(snap), HostFunctions::default(), Some(config))
6095                        .unwrap();
6096
6097                // Drop any log records emitted while the guest initialised.
6098                LOGGER.clear_log_calls();
6099
6100                for level in [
6101                    LevelFilter::TRACE,
6102                    LevelFilter::DEBUG,
6103                    LevelFilter::INFO,
6104                    LevelFilter::WARN,
6105                    LevelFilter::ERROR,
6106                ] {
6107                    let encoded: u64 = GuestLogFilter::from(level).into();
6108                    sbox.call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6109                        .unwrap();
6110                }
6111
6112                let count = (0..LOGGER.num_log_calls())
6113                    .filter_map(|i| LOGGER.get_log_call(i))
6114                    .filter(|c| c.target == "hyperlight_guest")
6115                    .count();
6116                LOGGER.clear_log_calls();
6117                count
6118            };
6119
6120            let trace_count = count_guest_logs(LevelFilter::TRACE);
6121            let error_count = count_guest_logs(LevelFilter::ERROR);
6122
6123            assert!(
6124                error_count >= 1,
6125                "an ERROR-level guest log must reach the host, got {error_count}"
6126            );
6127            assert!(
6128                trace_count > error_count,
6129                "TRACE must let more guest logs through than ERROR (trace={trace_count}, \
6130                 error={error_count}); equal counts mean max_guest_log_level was ignored"
6131            );
6132        }
6133
6134        /// A configured log level overrides the level captured by an initialized snapshot.
6135        ///
6136        /// Ignored because it installs a process-global `log` logger; run
6137        /// in isolation via the `test-isolated` Justfile recipe.
6138        #[test]
6139        #[ignore]
6140        fn max_guest_log_level_overrides_initialized_snapshot() {
6141            use hyperlight_common::log_level::GuestLogFilter;
6142            use hyperlight_testing::logger::{LOGGER, Logger};
6143            use tracing_core::LevelFilter;
6144
6145            Logger::initialize_test_logger();
6146            LOGGER.set_max_level(log::LevelFilter::Trace);
6147
6148            let initialized_snapshot = |captured_level: LevelFilter| {
6149                SandboxBuilder::from_file(simple_guest_as_pathbuf())
6150                    .guest_log_level(captured_level)
6151                    .build()
6152                    .unwrap()
6153                    .snapshot()
6154                    .unwrap()
6155            };
6156
6157            let count_guest_logs =
6158                |snapshot: Arc<Snapshot>, override_level: Option<LevelFilter>| -> usize {
6159                    let config = override_level.map(|level| {
6160                        let mut config = SandboxConfiguration::default();
6161                        config.set_max_guest_log_level(level);
6162                        config
6163                    });
6164                    let mut sandbox =
6165                        Sandbox::from_snapshot(snapshot, HostFunctions::default(), config).unwrap();
6166
6167                    LOGGER.clear_log_calls();
6168                    for level in [
6169                        LevelFilter::TRACE,
6170                        LevelFilter::DEBUG,
6171                        LevelFilter::INFO,
6172                        LevelFilter::WARN,
6173                        LevelFilter::ERROR,
6174                    ] {
6175                        let encoded: u64 = GuestLogFilter::from(level).into();
6176                        sandbox
6177                            .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6178                            .unwrap();
6179                    }
6180
6181                    let count = (0..LOGGER.num_log_calls())
6182                        .filter_map(|i| LOGGER.get_log_call(i))
6183                        .filter(|call| call.target == "hyperlight_guest")
6184                        .count();
6185                    LOGGER.clear_log_calls();
6186                    count
6187                };
6188
6189            let trace_snapshot = initialized_snapshot(LevelFilter::TRACE);
6190            let error_snapshot = initialized_snapshot(LevelFilter::ERROR);
6191
6192            let captured_trace = count_guest_logs(trace_snapshot.clone(), None);
6193            let overridden_trace = count_guest_logs(trace_snapshot, Some(LevelFilter::ERROR));
6194            let captured_error = count_guest_logs(error_snapshot.clone(), None);
6195            let overridden_error = count_guest_logs(error_snapshot, Some(LevelFilter::TRACE));
6196
6197            assert!(
6198                captured_trace > overridden_trace,
6199                "ERROR override should reduce TRACE snapshot logs (trace={}, error={})",
6200                captured_trace,
6201                overridden_trace
6202            );
6203            assert!(
6204                overridden_error > captured_error,
6205                "TRACE override should increase ERROR snapshot logs (trace={}, error={})",
6206                overridden_error,
6207                captured_error
6208            );
6209        }
6210
6211        /// A runtime log-level override set on a Sandbox survives restore.
6212        ///
6213        /// Ignored because it installs a process-global `log` logger; run
6214        /// in isolation via the `test-isolated` Justfile recipe.
6215        #[test]
6216        #[ignore]
6217        fn max_guest_log_level_setter_survives_restore() {
6218            use hyperlight_common::log_level::GuestLogFilter;
6219            use hyperlight_testing::logger::{LOGGER, Logger};
6220            use tracing_core::LevelFilter;
6221
6222            Logger::initialize_test_logger();
6223            LOGGER.set_max_level(log::LevelFilter::Trace);
6224
6225            let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6226                .guest_log_level(LevelFilter::TRACE)
6227                .build()
6228                .unwrap();
6229            let snapshot = source.snapshot().unwrap();
6230            let mut sandbox = SandboxBuilder::from_snapshot(snapshot.clone())
6231                .build()
6232                .unwrap();
6233            sandbox.log_level(LevelFilter::ERROR).unwrap();
6234
6235            let count_guest_logs = |sandbox: &mut Sandbox| {
6236                LOGGER.clear_log_calls();
6237                for level in [
6238                    LevelFilter::TRACE,
6239                    LevelFilter::DEBUG,
6240                    LevelFilter::INFO,
6241                    LevelFilter::WARN,
6242                    LevelFilter::ERROR,
6243                ] {
6244                    let encoded: u64 = GuestLogFilter::from(level).into();
6245                    sandbox
6246                        .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6247                        .unwrap();
6248                }
6249                let count = (0..LOGGER.num_log_calls())
6250                    .filter_map(|i| LOGGER.get_log_call(i))
6251                    .filter(|call| call.target == "hyperlight_guest")
6252                    .count();
6253                LOGGER.clear_log_calls();
6254                count
6255            };
6256
6257            let before_restore = count_guest_logs(&mut sandbox);
6258            sandbox.restore(snapshot).unwrap();
6259            let after_restore = count_guest_logs(&mut sandbox);
6260
6261            assert_eq!(before_restore, 1);
6262            assert_eq!(before_restore, after_restore);
6263        }
6264
6265        /// Runtime log-level updates can disable and re-enable guest tracing.
6266        ///
6267        /// Ignored because it installs a process-global `log` logger. Run in
6268        /// isolation via the `test-isolated` Justfile recipe.
6269        #[test]
6270        #[ignore]
6271        fn max_guest_log_level_can_be_disabled_and_reenabled() {
6272            use hyperlight_common::log_level::GuestLogFilter;
6273            use hyperlight_testing::logger::{LOGGER, Logger};
6274            use tracing_core::LevelFilter;
6275
6276            Logger::initialize_test_logger();
6277            LOGGER.set_max_level(log::LevelFilter::Trace);
6278
6279            let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6280                .guest_log_level(LevelFilter::TRACE)
6281                .build()
6282                .unwrap();
6283            let encoded: u64 = GuestLogFilter::Trace.into();
6284            let count_guest_logs = |sandbox: &mut Sandbox| {
6285                LOGGER.clear_log_calls();
6286                sandbox
6287                    .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6288                    .unwrap();
6289                (0..LOGGER.num_log_calls())
6290                    .filter_map(|i| LOGGER.get_log_call(i))
6291                    .filter(|call| call.target == "hyperlight_guest")
6292                    .count()
6293            };
6294
6295            assert!(count_guest_logs(&mut sandbox) > 0);
6296            sandbox.log_level(LevelFilter::OFF).unwrap();
6297            assert_eq!(count_guest_logs(&mut sandbox), 0);
6298            sandbox.log_level(LevelFilter::TRACE).unwrap();
6299            assert!(count_guest_logs(&mut sandbox) > 0);
6300        }
6301
6302        /// Callsites reached while the guest runs at `OFF` still produce trace
6303        /// data once the level is raised, matching a guest started at `TRACE`.
6304        ///
6305        /// Ignored because it installs a process-global `log` logger. Run in
6306        /// isolation via the `test-isolated` Justfile recipe.
6307        #[test]
6308        #[ignore]
6309        fn max_guest_log_level_can_be_enabled_after_off_init() {
6310            use hyperlight_common::log_level::GuestLogFilter;
6311            use hyperlight_testing::logger::{LOGGER, Logger};
6312            use tracing_core::LevelFilter;
6313
6314            Logger::initialize_test_logger();
6315            LOGGER.set_max_level(log::LevelFilter::Trace);
6316
6317            let encoded: u64 = GuestLogFilter::Trace.into();
6318            let count_guest_logs = |sandbox: &mut Sandbox| {
6319                LOGGER.clear_log_calls();
6320                sandbox
6321                    .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6322                    .unwrap();
6323                (0..LOGGER.num_log_calls())
6324                    .filter_map(|i| LOGGER.get_log_call(i))
6325                    .filter(|call| call.target == "hyperlight_guest")
6326                    .count()
6327            };
6328
6329            let mut from_trace = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6330                .guest_log_level(LevelFilter::TRACE)
6331                .build()
6332                .unwrap();
6333            let _ = count_guest_logs(&mut from_trace);
6334            let expected = count_guest_logs(&mut from_trace);
6335
6336            let mut from_off = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6337                .guest_log_level(LevelFilter::OFF)
6338                .build()
6339                .unwrap();
6340            // Runs the guest at OFF so its callsites cache a disabled interest.
6341            assert_eq!(count_guest_logs(&mut from_off), 0);
6342
6343            from_off.log_level(LevelFilter::TRACE).unwrap();
6344            assert_eq!(count_guest_logs(&mut from_off), expected);
6345        }
6346
6347        /// Two sandboxes built from clones of one `Arc<Snapshot>` can
6348        /// each `restore` back to it, and stay memory-isolated from
6349        /// each other in between.
6350        #[test]
6351        fn arc_clone_isolation_and_restore_compat() {
6352            let mut sbox = make_sandbox();
6353            sbox.call::<i32>("AddToStatic", 3i32).unwrap();
6354            let snapshot = sbox.snapshot().unwrap();
6355
6356            let mut a = SandboxBuilder::from_snapshot(snapshot.clone())
6357                .build()
6358                .unwrap();
6359            let mut b = SandboxBuilder::from_snapshot(snapshot.clone())
6360                .build()
6361                .unwrap();
6362            super::assert_virtq_attached(&a);
6363            super::assert_virtq_attached(&b);
6364            assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 3);
6365            assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
6366
6367            a.call::<i32>("AddToStatic", 7i32).unwrap();
6368            assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 10);
6369            assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
6370
6371            a.restore(snapshot.clone()).unwrap();
6372            b.restore(snapshot).unwrap();
6373            super::assert_virtq_attached(&a);
6374            super::assert_virtq_attached(&b);
6375            assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 3);
6376            assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
6377        }
6378
6379        #[test]
6380        fn accepts_matching_host_functions() {
6381            let mut sbox = make_sandbox_with_add();
6382            sbox.call::<i32>("AddToStatic", 5i32).unwrap();
6383            let snap = sbox.snapshot().unwrap();
6384            let mut sbox2 = SandboxBuilder::from_snapshot(snap)
6385                .host_functions(host_funcs_with_matching_add())
6386                .build()
6387                .unwrap();
6388            assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 5);
6389        }
6390
6391        #[test]
6392        fn rejects_missing_host_function() {
6393            let mut sbox = make_sandbox_with_add();
6394            let snap = sbox.snapshot().unwrap();
6395            let err = SandboxBuilder::from_snapshot(snap)
6396                .build()
6397                .expect_err("missing `Add` must be rejected");
6398            assert!(
6399                matches!(
6400                    &err,
6401                    HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
6402                        if missing.iter().any(|n| n == "Add") && signature_mismatches.is_empty()
6403                ),
6404                "got: {:?}",
6405                err
6406            );
6407        }
6408
6409        /// `restore` must also reject a snapshot whose required host
6410        /// functions are not a subset of the target sandbox's. This
6411        /// matters across sandboxes: a snapshot taken from a sandbox
6412        /// with `Add` registered cannot be restored into a layout
6413        /// compatible sandbox that lacks `Add`.
6414        #[test]
6415        fn restore_rejects_missing_host_function() {
6416            let mut sbox_with_add = make_sandbox_with_add();
6417            let snap = sbox_with_add.snapshot().unwrap();
6418            let mut sbox_without_add = make_sandbox();
6419            let err = sbox_without_add
6420                .restore(snap)
6421                .expect_err("missing `Add` must be rejected on restore");
6422            assert!(
6423                matches!(
6424                    &err,
6425                    HyperlightError::SnapshotHostFunctionMismatch { missing, .. }
6426                        if missing.iter().any(|n| n == "Add")
6427                ),
6428                "got: {:?}",
6429                err
6430            );
6431        }
6432
6433        /// `restore` rejects a snapshot whose required host function
6434        /// shares a name with the target's but disagrees on signature.
6435        #[test]
6436        fn restore_rejects_signature_mismatch() {
6437            let mut sbox_with_add = make_sandbox_with_add();
6438            let snap = sbox_with_add.snapshot().unwrap();
6439            let path = simple_guest_as_pathbuf();
6440            let mut sbox_wrong_add = SandboxBuilder::from_file(path)
6441                .host_function("Add", |a: String, b: String| format!("{a}{b}"))
6442                .build()
6443                .unwrap();
6444            let err = sbox_wrong_add
6445                .restore(snap)
6446                .expect_err("signature mismatch on `Add` must be rejected on restore");
6447            assert!(
6448                matches!(
6449                    &err,
6450                    HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
6451                        if missing.is_empty() && signature_mismatches.iter().any(|s| s.contains("Add"))
6452                ),
6453                "got: {:?}",
6454                err
6455            );
6456        }
6457
6458        /// Cross-instance `restore` succeeds when the target registers
6459        /// a strict superset of the snapshot's host functions.
6460        #[test]
6461        fn restore_across_sandboxes_with_superset_host_funcs() {
6462            let mut source = make_sandbox_with_add();
6463            source.call::<i32>("AddToStatic", 17i32).unwrap();
6464            let snap = source.snapshot().unwrap();
6465
6466            let path = simple_guest_as_pathbuf();
6467            let mut target = SandboxBuilder::from_file(path)
6468                .host_function("Add", |a: i32, b: i32| a + b)
6469                .host_function("Mul", |a: i32, b: i32| a * b)
6470                .build()
6471                .unwrap();
6472
6473            target.restore(snap).unwrap();
6474            assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 17);
6475        }
6476
6477        #[test]
6478        fn rejects_signature_mismatch() {
6479            let mut sbox = make_sandbox_with_add();
6480            let snap = sbox.snapshot().unwrap();
6481            let mut hf = HostFunctions::default();
6482            hf.register_host_function("Add", |a: String, b: String| Ok(format!("{a}{b}")))
6483                .unwrap();
6484            let err = SandboxBuilder::from_snapshot(snap)
6485                .host_functions(hf)
6486                .build()
6487                .expect_err("signature mismatch on `Add` must be rejected");
6488            assert!(
6489                matches!(
6490                    &err,
6491                    HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
6492                        if missing.is_empty() && signature_mismatches.iter().any(|s| s.contains("Add"))
6493                ),
6494                "got: {:?}",
6495                err
6496            );
6497        }
6498
6499        /// Supplied host-function set may be a strict superset of the
6500        /// snapshot's required set.
6501        #[test]
6502        fn accepts_extra_host_functions() {
6503            let mut sbox = make_sandbox_with_add();
6504            sbox.call::<i32>("AddToStatic", 9i32).unwrap();
6505            let snap = sbox.snapshot().unwrap();
6506            let mut hf = host_funcs_with_matching_add();
6507            hf.register_host_function("Mul", |a: i32, b: i32| Ok(a * b))
6508                .unwrap();
6509            let mut sbox2 = SandboxBuilder::from_snapshot(snap)
6510                .host_functions(hf)
6511                .build()
6512                .unwrap();
6513            assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 9);
6514        }
6515
6516        /// A sandbox built via `from_snapshot` can itself be snapshotted
6517        /// and restored, and its snapshots are restore-compatible with it.
6518        #[test]
6519        fn re_snapshot_after_from_snapshot() {
6520            let mut sbox = make_sandbox();
6521            sbox.call::<i32>("AddToStatic", 4i32).unwrap();
6522            let snap1 = sbox.snapshot().unwrap();
6523
6524            let mut sbox2 = SandboxBuilder::from_snapshot(snap1).build().unwrap();
6525            sbox2.call::<i32>("AddToStatic", 6i32).unwrap();
6526            let snap2 = sbox2.snapshot().unwrap();
6527
6528            sbox2.call::<i32>("AddToStatic", 100i32).unwrap();
6529            assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 110);
6530
6531            sbox2.restore(snap2.clone()).unwrap();
6532            assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 10);
6533
6534            let mut sbox3 = SandboxBuilder::from_snapshot(snap2).build().unwrap();
6535            assert_eq!(sbox3.call::<i32>("GetStatic", ()).unwrap(), 10);
6536        }
6537
6538        /// The host function closure supplied to `from_snapshot` (not the
6539        /// original sandbox's closure) is the one invoked at runtime.
6540        #[test]
6541        fn supplied_host_function_is_callable() {
6542            let path = simple_guest_as_pathbuf();
6543            let mut sbox = SandboxBuilder::from_file(path)
6544                .host_function("Echo42", || 1i64)
6545                .build()
6546                .unwrap();
6547            let snap = sbox.snapshot().unwrap();
6548
6549            let mut hf = HostFunctions::default();
6550            hf.register_host_function("Echo42", || Ok(42i64)).unwrap();
6551            let mut sbox2 = SandboxBuilder::from_snapshot(snap)
6552                .host_functions(hf)
6553                .build()
6554                .unwrap();
6555
6556            let got: i64 = sbox2
6557                .call(
6558                    "CallGivenParamlessHostFuncThatReturnsI64",
6559                    "Echo42".to_string(),
6560                )
6561                .unwrap();
6562            assert_eq!(got, 42);
6563        }
6564
6565        /// Pre-init snapshots record no required host functions, so any
6566        /// `HostFunctions` set is accepted.
6567        #[test]
6568        fn pre_init_snapshot_accepts_arbitrary_host_functions() {
6569            let path = simple_guest_as_pathbuf();
6570            let snap =
6571                Snapshot::from_env(GuestBinary::FilePath(path), SandboxConfiguration::default())
6572                    .unwrap();
6573            let mut hf = HostFunctions::default();
6574            hf.register_host_function("Unrelated", |a: i32| Ok(a + 1))
6575                .unwrap();
6576            let mut sbox = SandboxBuilder::from_snapshot(Arc::new(snap))
6577                .host_functions(hf)
6578                .build()
6579                .unwrap();
6580            assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 0);
6581        }
6582
6583        /// Snapshots taken from a sandbox built via `from_snapshot`
6584        /// must continue the generation counter of the snapshot they
6585        /// were constructed from, matching `restore`.
6586        #[test]
6587        fn snapshot_generation_propagates() {
6588            let mut sbox = make_sandbox();
6589            sbox.call::<i32>("AddToStatic", 1i32).unwrap();
6590            let snap1 = sbox.snapshot().unwrap();
6591            let gen1 = snap1.snapshot_generation();
6592            sbox.call::<i32>("AddToStatic", 1i32).unwrap();
6593            let snap2 = sbox.snapshot().unwrap();
6594            let gen2 = snap2.snapshot_generation();
6595            assert_eq!(gen2, gen1 + 1);
6596
6597            let mut sbox2 = SandboxBuilder::from_snapshot(snap2).build().unwrap();
6598            sbox2.call::<i32>("AddToStatic", 1i32).unwrap();
6599            let snap3 = sbox2.snapshot().unwrap();
6600            assert_eq!(snap3.snapshot_generation(), gen2 + 1);
6601        }
6602
6603        /// Registering a host function on an already-evolved
6604        /// `Sandbox` must invalidate its cached snapshot, so
6605        /// that the next `snapshot()` reflects the new required
6606        /// host-function set.
6607        #[test]
6608        fn late_register_invalidates_snapshot_cache() {
6609            let mut sbox = make_sandbox();
6610            // Force a cached snapshot to exist.
6611            let _ = sbox.snapshot().unwrap();
6612
6613            sbox.register_host_function("Echo42", || Ok(42i64)).unwrap();
6614
6615            // The next snapshot must include `Echo42` as a required
6616            // host function, so building a sandbox from it without
6617            // `Echo42` must fail.
6618            let snap = sbox.snapshot().unwrap();
6619            let err = SandboxBuilder::from_snapshot(snap)
6620                .build()
6621                .expect_err("late-registered `Echo42` must be required by the new snapshot");
6622            let msg = format!("{}", err);
6623            assert!(msg.contains("Echo42"), "got: {}", msg);
6624        }
6625    }
6626}