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