1use std::collections::BTreeSet;
5use std::path::Path;
6#[cfg(crashdump)]
7use std::path::PathBuf;
8use std::sync::{Arc, Mutex};
9
10use hyperlight_common::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
11use hyperlight_common::flatbuffer_wrappers::function_types::{
12 ParameterValue, ReturnType, ReturnValue,
13};
14use tracing::{Span, instrument};
15use tracing_core::LevelFilter;
16
17use super::Callable;
18use super::file_mapping::prepare_file_cow;
19use super::host_funcs::FunctionRegistry;
20use super::snapshot::{Snapshot, SnapshotOptions};
21use crate::func::{ParameterTuple, SupportedReturnType};
22use crate::hypervisor::InterruptHandle;
23use crate::hypervisor::hyperlight_vm::{HyperlightVm, HyperlightVmError};
24use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags};
25use crate::mem::mgr::{ExecutionMode, SandboxMemoryManager};
26use crate::mem::shared_mem::{HostSharedMemory, SharedMemory as _};
27use crate::metrics::{
28 METRIC_GUEST_ERROR, METRIC_GUEST_ERROR_LABEL_CODE, maybe_time_and_emit_guest_call,
29};
30use crate::sandbox::snapshot::SnapshotMemoryBacking;
31use crate::{HyperlightError, Result, log_then_return};
32
33#[derive(Clone, Copy, Debug, Eq, PartialEq)]
35pub enum SandboxStatus {
36 Ready,
38 Poisoned,
40 Unrecoverable,
42}
43
44impl SandboxStatus {
45 pub const fn is_ready(self) -> bool {
47 matches!(self, Self::Ready)
48 }
49
50 pub const fn is_poisoned(self) -> bool {
52 matches!(self, Self::Poisoned)
53 }
54
55 pub const fn is_unrecoverable(self) -> bool {
57 matches!(self, Self::Unrecoverable)
58 }
59}
60
61pub struct Sandbox {
84 status: SandboxStatus,
85 pub(crate) host_funcs: Arc<Mutex<FunctionRegistry>>,
86 pub(crate) mem_mgr: SandboxMemoryManager<HostSharedMemory>,
87 vm: HyperlightVm,
88 pub(crate) snapshot: Option<Arc<Snapshot>>,
91 transport_dirty: bool,
93 pt_root_finder: Option<PtRootFinder>,
97 max_guest_log_level: Option<LevelFilter>,
99}
100
101#[deprecated(since = "0.18.0", note = "use Sandbox")]
103pub type MultiUseSandbox = Sandbox;
104
105pub struct SnapshotMemoryReader<'a> {
107 memory: &'a SnapshotMemoryBacking<HostSharedMemory>,
108}
109
110impl SnapshotMemoryReader<'_> {
111 pub fn read_exact(&self, gpa: u64, destination: &mut [u8]) -> Result<()> {
113 self.memory.read_snapshot_gpa(gpa, destination)
114 }
115}
116
117pub type PtRootFinder =
128 Box<dyn Fn(&SnapshotMemoryReader<'_>, &[u8], u64) -> Result<Vec<u64>> + Send>;
129
130fn normalize_page_table_roots(roots: Vec<u64>, active_root: u64) -> Vec<u64> {
131 let mut seen = BTreeSet::from([active_root]);
132 let mut normalized = vec![active_root];
133 normalized.extend(roots.into_iter().filter(|root| seen.insert(*root)));
134 normalized
135}
136
137impl Sandbox {
138 fn check_ready(&self) -> Result<()> {
139 match self.status {
140 SandboxStatus::Ready => Ok(()),
141 SandboxStatus::Poisoned => Err(HyperlightError::PoisonedSandbox),
142 SandboxStatus::Unrecoverable => Err(HyperlightError::UnrecoverableSandbox),
143 }
144 }
145
146 fn poison(&mut self) {
147 if self.status.is_ready() {
148 self.status = SandboxStatus::Poisoned;
149 }
150 }
151
152 #[instrument(skip_all, parent = Span::current(), level = "Trace")]
158 pub(super) fn from_uninit(
159 host_funcs: Arc<Mutex<FunctionRegistry>>,
160 mgr: SandboxMemoryManager<HostSharedMemory>,
161 vm: HyperlightVm,
162 ) -> Sandbox {
163 let transport_dirty = matches!(mgr.next_action, super::snapshot::NextAction::Initialise(_));
165
166 Self {
167 status: SandboxStatus::Ready,
168 host_funcs,
169 mem_mgr: mgr,
170 vm,
171 snapshot: None,
172 transport_dirty,
173 pt_root_finder: None,
174 max_guest_log_level: None,
175 }
176 }
177
178 pub fn log_level(&mut self, log_level: LevelFilter) -> Result<()> {
182 self.check_ready()?;
183 self.mem_mgr.request_guest_log_level_update(log_level)?;
184 self.max_guest_log_level = Some(log_level);
185 Ok(())
186 }
187
188 pub fn set_pt_root_finder(&mut self, finder: PtRootFinder) {
194 self.pt_root_finder = Some(finder);
195 }
196
197 #[instrument(err(Debug), skip_all, parent = Span::current(), level = "Trace")]
263 pub fn from_snapshot(
264 snapshot: Arc<Snapshot>,
265 host_funcs: crate::HostFunctions,
266 config: Option<crate::sandbox::SandboxConfiguration>,
267 ) -> Result<Self> {
268 use rand::RngExt;
269
270 use crate::mem::ptr::RawPtr;
271 use crate::sandbox::uninitialized_evolve::set_up_hypervisor_partition;
272
273 snapshot.validate_host_functions(host_funcs.inner())?;
276
277 let host_funcs = Arc::new(Mutex::new(host_funcs.into_inner()));
278
279 let stack_top_gva = snapshot.stack_top_gva();
280 let caller_supplied_config = config.is_some();
288 let mut config = config.unwrap_or_default();
289 if caller_supplied_config {
290 warn_on_layout_override(&config, snapshot.layout());
291 }
292 config.set_scratch_size(snapshot.layout().get_scratch_size());
293 config.set_g2h_queue_size(snapshot.layout().get_g2h_queue_size());
294 config.set_h2g_queue_size(snapshot.layout().get_h2g_queue_size());
295 config.set_g2h_buffer_size(snapshot.layout().get_g2h_buffer_size());
296 config.set_h2g_buffer_size(snapshot.layout().get_h2g_buffer_size());
297 config.set_g2h_pool_pages(snapshot.layout().get_g2h_pool_pages());
298 config.set_h2g_pool_pages(snapshot.layout().get_h2g_pool_pages());
299 let max_guest_log_level = config.get_max_guest_log_level();
300 let load_info = snapshot.load_info();
301
302 let mgr = crate::mem::mgr::SandboxMemoryManager::from_snapshot(&snapshot)?;
303 let (mut hshm, gshm) = mgr.build()?;
304 let restore_virtq = matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_));
305
306 let page_size = u32::try_from(page_size::get())? as usize;
307
308 #[cfg(target_os = "linux")]
309 crate::signal_handlers::setup_signal_handlers(&config)?;
310
311 let mut vm =
312 set_up_hypervisor_partition(gshm, &config, stack_top_gva, page_size, load_info)?;
313
314 let seed = {
315 let mut rng = rand::rng();
316 rng.random::<u64>()
317 };
318 let peb_addr = RawPtr::from(u64::try_from(hshm.layout.peb_address())?);
319
320 vm.initialise(peb_addr, seed, &mut hshm, &host_funcs, max_guest_log_level)
323 .map_err(crate::hypervisor::hyperlight_vm::HyperlightVmError::Initialize)?;
324 if matches!(
325 snapshot.next_action(),
326 super::snapshot::NextAction::Initialise(_)
327 ) {
328 hshm.finish_snapshot_checkpoint()?;
329 }
330
331 if matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_)) {
332 hshm.request_libc_rng_reseed(seed as u32)?;
333 }
334
335 if matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_)) {
339 let sregs = snapshot.sregs().ok_or_else(|| {
340 crate::new_error!("snapshot with NextAction::Call must have captured sregs")
341 })?;
342 #[cfg(target_arch = "x86_64")]
343 let msrs = snapshot.msrs().ok_or_else(|| {
344 crate::new_error!("snapshot with NextAction::Call must have captured MSRs")
345 })?;
346 vm.apply_sregs(hshm.layout.get_pt_base_gpa(), sregs)
347 .map_err(|e| {
348 crate::HyperlightError::HyperlightVmError(
349 crate::hypervisor::hyperlight_vm::HyperlightVmError::Restore(e.into()),
350 )
351 })?;
352
353 #[cfg(target_arch = "x86_64")]
355 vm.restore_msrs(msrs).map_err(|e| {
356 crate::HyperlightError::HyperlightVmError(
357 crate::hypervisor::hyperlight_vm::HyperlightVmError::Restore(e),
358 )
359 })?;
360 }
361
362 if restore_virtq {
363 let virtq = snapshot.virtq().ok_or_else(|| {
364 crate::new_error!("running snapshot has no canonical transport state")
365 })?;
366 hshm.restore_virtq(virtq)?;
367 }
368
369 let mut sbox = Sandbox::from_uninit(host_funcs, hshm, vm);
370
371 if let Some(log_level) = max_guest_log_level {
372 sbox.log_level(log_level)?;
373 }
374
375 Ok(sbox)
376 }
377
378 pub fn snapshot(&mut self) -> Result<Arc<Snapshot>> {
441 self.snapshot_with_options(&SnapshotOptions::default())
442 }
443
444 #[instrument(err(Debug), skip_all, parent = Span::current())]
466 pub fn snapshot_with_options(&mut self, options: &SnapshotOptions) -> Result<Arc<Snapshot>> {
467 self.check_ready()?;
468 let SnapshotOptions { scratch_size } = options;
471 let current = self.mem_mgr.layout.get_scratch_size();
472 let scratch_size = scratch_size.unwrap_or(current);
473
474 if scratch_size == current {
475 if let Some(snapshot) = &self.snapshot {
476 return Ok(snapshot.clone());
477 }
478 return self.capture_snapshot(scratch_size);
479 }
480
481 self.mem_mgr.layout.with_scratch_size(scratch_size)?;
483 self.capture_snapshot(scratch_size)
484 }
485
486 fn capture_snapshot(&mut self, scratch_size: usize) -> Result<Arc<Snapshot>> {
489 if self.transport_dirty {
490 self.checkpoint_transport_for_snapshot()?;
491 }
492
493 let mapped_regions_iter = self.vm.get_mapped_regions();
494 let mapped_regions_vec: Vec<MemoryRegion> = mapped_regions_iter.cloned().collect();
495 let cr3 = self
497 .vm
498 .get_root_pt()
499 .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
500 let root_pt_gpas = if let Some(finder) = &self.pt_root_finder {
502 let snapshot = SnapshotMemoryReader {
503 memory: &self.mem_mgr.shared_mem,
504 };
505 let roots = self
506 .mem_mgr
507 .scratch_mem
508 .with_contents(|scratch| finder(&snapshot, scratch, cr3))??;
509 normalize_page_table_roots(roots, cr3)
510 } else {
511 vec![cr3]
512 };
513
514 let stack_top_gpa = self.vm.get_stack_top();
515 let sregs = self
516 .vm
517 .get_snapshot_sregs()
518 .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
519 #[cfg(target_arch = "x86_64")]
520 let msrs = self
521 .vm
522 .get_msr_reset_state()
523 .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
524 let next_action = self.vm.get_next_action();
525 let host_functions = (&*self.host_funcs.try_lock().map_err(|e| {
526 crate::new_error!("Error locking host_funcs at {}:{}: {}", file!(), line!(), e)
527 })?)
528 .into();
529
530 let memory_snapshot = self.mem_mgr.snapshot(
531 mapped_regions_vec,
532 &root_pt_gpas,
533 stack_top_gpa,
534 sregs,
535 #[cfg(target_arch = "x86_64")]
536 msrs,
537 next_action,
538 host_functions,
539 scratch_size,
540 )?;
541 let snapshot = Arc::new(memory_snapshot);
542
543 if let Err(error) = self.remove_dynamic_mappings() {
544 self.status = SandboxStatus::Poisoned;
545 self.snapshot = None;
546 return Err(error);
547 }
548 let (snapshot_mem, scratch_mem) = match self.mem_mgr.install_captured_snapshot(&snapshot) {
549 Ok(memory) => memory,
550 Err(error) => {
551 self.status = SandboxStatus::Unrecoverable;
552 self.snapshot = None;
553 return Err(error);
554 }
555 };
556 if let Err(error) = self.vm.update_snapshot_mapping(snapshot_mem) {
557 self.status = SandboxStatus::Unrecoverable;
558 self.snapshot = None;
559 return Err(HyperlightVmError::UpdateRegion(error).into());
560 }
561 if let Some(scratch_mem) = scratch_mem
562 && let Err(error) = self.vm.update_scratch_mapping(scratch_mem)
563 {
564 self.status = SandboxStatus::Unrecoverable;
565 self.snapshot = None;
566 return Err(HyperlightVmError::UpdateRegion(error).into());
567 }
568 if let Err(error) = self.vm.apply_sregs(snapshot.root_pt_gpa(), &sregs) {
569 self.status = SandboxStatus::Poisoned;
570 self.snapshot = None;
571 return Err(HyperlightVmError::Restore(error.into()).into());
572 }
573
574 self.snapshot = Some(snapshot.clone());
575 Ok(snapshot)
576 }
577
578 fn checkpoint_transport_for_snapshot(&mut self) -> Result<()> {
579 self.with_guest_execution(|sbox| {
580 sbox.mem_mgr.begin_snapshot_checkpoint()?;
581 sbox.dispatch_guest_call_restricted()?;
582
583 sbox.mem_mgr.finish_snapshot_checkpoint()?;
584
585 sbox.transport_dirty = false;
586 Ok(())
587 })
588 }
589
590 fn remove_dynamic_mappings(&mut self) -> Result<()> {
591 let regions = self.vm.get_mapped_regions().cloned().collect::<Vec<_>>();
592 for region in ®ions {
593 self.vm
594 .unmap_region(region)
595 .map_err(HyperlightVmError::UnmapRegion)?;
596 }
597 Ok(())
598 }
599
600 fn restore_memory_and_mappings(&mut self, snapshot: &Snapshot) -> Result<()> {
601 let (snapshot_mem, scratch_mem) = self.mem_mgr.restore_snapshot(snapshot)?;
602 self.vm
603 .update_snapshot_mapping(snapshot_mem)
604 .map_err(HyperlightVmError::UpdateRegion)?;
605 if let Some(scratch_mem) = scratch_mem {
606 self.vm
607 .update_scratch_mapping(scratch_mem)
608 .map_err(HyperlightVmError::UpdateRegion)?;
609 }
610 Ok(())
611 }
612
613 #[instrument(err(Debug), skip_all, parent = Span::current())]
706 pub fn restore(&mut self, snapshot: Arc<Snapshot>) -> Result<()> {
707 if self.status.is_unrecoverable() {
708 return Err(HyperlightError::UnrecoverableSandbox);
709 }
710
711 {
735 let host_funcs = self
736 .host_funcs
737 .try_lock()
738 .map_err(|e| crate::new_error!("Error locking host_funcs: {}", e))?;
739 snapshot.validate_host_functions(&host_funcs)?;
740 }
741
742 let sregs = snapshot.sregs().ok_or_else(|| {
743 HyperlightError::Error("snapshot from running sandbox should have sregs".to_string())
744 })?;
745 #[cfg(target_arch = "x86_64")]
746 let msrs = snapshot.msrs().ok_or_else(|| {
747 HyperlightError::Error("snapshot from running sandbox should have MSRs".to_string())
748 })?;
749
750 if snapshot.virtq().is_none()
751 && matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_))
752 {
753 return Err(crate::new_error!(
754 "running snapshot has no canonical transport state"
755 ));
756 }
757
758 self.status = SandboxStatus::Poisoned;
760 self.snapshot = None;
761
762 self.remove_dynamic_mappings()?;
763
764 if let Err(error) = self.restore_memory_and_mappings(&snapshot) {
765 self.status = SandboxStatus::Unrecoverable;
766 return Err(error);
767 }
768
769 self.vm
771 .reset_vcpu(
772 snapshot.root_pt_gpa(),
773 sregs,
774 #[cfg(target_arch = "x86_64")]
775 msrs,
776 )
777 .map_err(HyperlightVmError::Restore)?;
778
779 self.vm.set_stack_top(snapshot.stack_top_gva());
780 self.vm.set_next_action(snapshot.next_action());
781
782 self.mem_mgr
783 .request_libc_rng_reseed(rand::random::<u32>())?;
784 if let Some(log_level) = self.max_guest_log_level {
785 self.mem_mgr.request_guest_log_level_update(log_level)?;
786 }
787
788 self.snapshot = Some(snapshot.clone());
790 self.transport_dirty = false;
791
792 self.status = SandboxStatus::Ready;
802
803 Ok(())
804 }
805
806 #[doc(hidden)]
840 #[deprecated(
841 since = "0.8.0",
842 note = "Deprecated in favour of call and snapshot/restore."
843 )]
844 #[instrument(err(Debug), skip(self, args), parent = Span::current())]
845 pub fn call_guest_function_by_name<Output: SupportedReturnType>(
846 &mut self,
847 func_name: &str,
848 args: impl ParameterTuple,
849 ) -> Result<Output> {
850 self.check_ready()?;
851 let snapshot = self.snapshot()?;
852 let res = self.call(func_name, args);
853 self.restore(snapshot)?;
854 res
855 }
856
857 #[instrument(err(Debug), skip(self, args), parent = Span::current())]
928 pub fn call<Output: SupportedReturnType>(
929 &mut self,
930 func_name: &str,
931 args: impl ParameterTuple,
932 ) -> Result<Output> {
933 self.check_ready()?;
934 self.snapshot = None;
936 maybe_time_and_emit_guest_call(func_name, || {
937 let ret = self.call_guest_function_by_name_no_reset(
938 func_name,
939 Output::TYPE,
940 args.into_value(),
941 );
942 let ret = Output::from_value(ret?)?;
945 Ok(ret)
946 })
947 }
948
949 #[instrument(err(Debug), skip(self, rgn), parent = Span::current())]
969 pub unsafe fn map_region(&mut self, rgn: &MemoryRegion) -> Result<()> {
970 self.check_ready()?;
971 if rgn.flags.contains(MemoryRegionFlags::WRITE) {
972 log_then_return!("TODO: Writable mappings not yet supported");
976 }
977
978 unsafe { self.vm.map_region(rgn) }.map_err(HyperlightVmError::MapRegion)?;
980 self.snapshot = None;
981 Ok(())
982 }
983
984 #[instrument(err(Debug), skip(self, file_path, guest_base), parent = Span::current())]
997 pub fn map_file_cow(&mut self, file_path: &Path, guest_base: u64) -> Result<u64> {
998 self.check_ready()?;
999
1000 let mut prepared = prepare_file_cow(file_path, guest_base)?;
1002
1003 let shared_size = self.mem_mgr.shared_mem.gpa_span_len() as u64;
1006 let base_addr = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
1007 let shared_end = base_addr.checked_add(shared_size).ok_or_else(|| {
1008 crate::HyperlightError::Error("shared memory end overflow".to_string())
1009 })?;
1010 let mapping_end = guest_base
1011 .checked_add(prepared.size as u64)
1012 .ok_or_else(|| {
1013 crate::HyperlightError::Error(format!(
1014 "map_file_cow: guest address overflow: {:#x} + {:#x}",
1015 guest_base, prepared.size
1016 ))
1017 })?;
1018 if guest_base < shared_end && mapping_end > base_addr {
1019 return Err(crate::HyperlightError::Error(format!(
1020 "map_file_cow: mapping [{:#x}..{:#x}) overlaps sandbox shared memory [{:#x}..{:#x})",
1021 guest_base, mapping_end, base_addr, shared_end,
1022 )));
1023 }
1024
1025 let region = prepared.to_memory_region()?;
1027
1028 unsafe { self.vm.map_region(®ion) }
1029 .map_err(HyperlightVmError::MapRegion)
1030 .map_err(crate::HyperlightError::HyperlightVmError)?;
1031
1032 self.snapshot = None;
1033
1034 let size = prepared.size as u64;
1035
1036 prepared.mark_consumed();
1044
1045 Ok(size)
1046 }
1047
1048 #[cfg(feature = "fuzzing")]
1057 #[instrument(err(Debug), skip(self, args), parent = Span::current())]
1058 pub fn call_type_erased_guest_function_by_name(
1059 &mut self,
1060 func_name: &str,
1061 ret_type: ReturnType,
1062 args: Vec<ParameterValue>,
1063 ) -> Result<ReturnValue> {
1064 self.check_ready()?;
1065 self.snapshot = None;
1067 maybe_time_and_emit_guest_call(func_name, || {
1068 self.call_guest_function_by_name_no_reset(func_name, ret_type, args)
1069 })
1070 }
1071
1072 fn call_guest_function_by_name_no_reset(
1073 &mut self,
1074 function_name: &str,
1075 return_type: ReturnType,
1076 args: Vec<ParameterValue>,
1077 ) -> Result<ReturnValue> {
1078 self.check_ready()?;
1079 self.with_guest_execution(|sbox| {
1080 sbox.transport_dirty = true;
1081
1082 let fc = FunctionCall::new(
1083 function_name.to_string(),
1084 Some(args),
1085 FunctionCallType::Guest,
1086 return_type,
1087 );
1088
1089 let cid = sbox.mem_mgr.write_guest_function_call(&fc)?;
1090 sbox.dispatch_guest_call()?;
1091
1092 let guest_result = sbox.mem_mgr.read_h2g_result_from_g2h(cid)?.into_inner();
1093
1094 match guest_result {
1095 Ok(val) => Ok(val),
1096 Err(guest_error) => {
1097 metrics::counter!(
1098 METRIC_GUEST_ERROR,
1099 METRIC_GUEST_ERROR_LABEL_CODE => (guest_error.code as u64).to_string()
1100 )
1101 .increment(1);
1102
1103 Err(HyperlightError::GuestError(
1104 guest_error.code,
1105 guest_error.message,
1106 ))
1107 }
1108 }
1109 })
1110 }
1111
1112 fn with_guest_execution<T>(&mut self, op: impl FnOnce(&mut Self) -> Result<T>) -> Result<T> {
1113 self.vm.clear_cancel();
1117 let result = op(self);
1118 self.mem_mgr.abort_buffer.clear();
1119
1120 if result.as_ref().is_err_and(HyperlightError::is_poison_error) {
1121 self.poison();
1122 }
1123
1124 result
1125 }
1126
1127 fn dispatch_guest_call(&mut self) -> Result<()> {
1128 self.vm
1129 .dispatch_call_from_host(&mut self.mem_mgr, &self.host_funcs)
1130 .map_err(|error| {
1131 let (error, should_poison) = error.promote();
1132 if should_poison {
1133 self.poison();
1134 }
1135 error
1136 })
1137 }
1138
1139 fn dispatch_guest_call_restricted(&mut self) -> Result<()> {
1141 let mode = std::mem::replace(&mut self.mem_mgr.execution_mode, ExecutionMode::Restricted);
1142 let res = self.dispatch_guest_call();
1143 self.mem_mgr.execution_mode = mode;
1144
1145 res
1146 }
1147
1148 pub fn interrupt_handle(&self) -> Arc<dyn InterruptHandle> {
1175 self.vm.interrupt_handle()
1176 }
1177
1178 #[cfg(crashdump)]
1214 #[instrument(err(Debug), skip_all, parent = Span::current())]
1215 pub fn generate_crashdump(&mut self) -> Result<()> {
1216 crate::hypervisor::crashdump::generate_crashdump(&self.vm, &mut self.mem_mgr, None)
1217 }
1218
1219 #[cfg(crashdump)]
1226 #[instrument(err(Debug), skip_all, parent = Span::current())]
1227 pub fn generate_crashdump_to_dir(&mut self, dir: impl Into<PathBuf>) -> Result<()> {
1228 crate::hypervisor::crashdump::generate_crashdump(
1229 &self.vm,
1230 &mut self.mem_mgr,
1231 Some(dir.into()),
1232 )
1233 }
1234
1235 #[deprecated(since = "0.17.0", note = "use status().is_poisoned()")]
1267 pub fn poisoned(&self) -> bool {
1268 self.status.is_poisoned()
1269 }
1270
1271 pub fn status(&self) -> SandboxStatus {
1279 self.status
1280 }
1281
1282 pub fn scratch_allocated_bytes(&self) -> Result<u64> {
1308 self.mem_mgr.scratch_allocated_bytes()
1309 }
1310}
1311
1312impl Callable for Sandbox {
1313 fn call<Output: SupportedReturnType>(
1314 &mut self,
1315 func_name: &str,
1316 args: impl ParameterTuple,
1317 ) -> Result<Output> {
1318 self.check_ready()?;
1319 self.call(func_name, args)
1320 }
1321}
1322
1323impl std::fmt::Debug for Sandbox {
1324 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1325 f.debug_struct("Sandbox").finish()
1326 }
1327}
1328
1329fn warn_on_layout_override(
1334 caller: &crate::sandbox::SandboxConfiguration,
1335 snapshot: &crate::mem::layout::SandboxMemoryLayout,
1336) {
1337 let mismatches: &[(&str, u64, u64)] = &[
1338 (
1339 "scratch_size",
1340 caller.get_scratch_size() as u64,
1341 snapshot.get_scratch_size() as u64,
1342 ),
1343 (
1344 "g2h_queue_size",
1345 caller.get_g2h_queue_size() as u64,
1346 snapshot.get_g2h_queue_size() as u64,
1347 ),
1348 (
1349 "h2g_queue_size",
1350 caller.get_h2g_queue_size() as u64,
1351 snapshot.get_h2g_queue_size() as u64,
1352 ),
1353 (
1354 "g2h_buffer_size",
1355 caller.get_g2h_buffer_size() as u64,
1356 snapshot.get_g2h_buffer_size() as u64,
1357 ),
1358 (
1359 "h2g_buffer_size",
1360 caller.get_h2g_buffer_size() as u64,
1361 snapshot.get_h2g_buffer_size() as u64,
1362 ),
1363 (
1364 "g2h_pool_pages",
1365 caller.get_g2h_pool_pages() as u64,
1366 snapshot.get_g2h_pool_pages() as u64,
1367 ),
1368 (
1369 "h2g_pool_pages",
1370 caller.get_h2g_pool_pages() as u64,
1371 snapshot.get_h2g_pool_pages() as u64,
1372 ),
1373 ];
1374 for (name, supplied, snap) in mismatches {
1375 if supplied != snap {
1376 tracing::warn!(
1377 "from_snapshot ignoring caller-supplied {} ({}); using snapshot value ({})",
1378 name,
1379 supplied,
1380 snap
1381 );
1382 }
1383 }
1384}
1385
1386#[cfg(test)]
1387mod tests {
1388 use std::sync::{Arc, Barrier};
1389 use std::thread;
1390
1391 use hyperlight_common::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
1392 use hyperlight_common::flatbuffer_wrappers::function_types::ParameterValue;
1393 use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
1394 use hyperlight_common::func::{Bytes, SupportedReturnType};
1395 use hyperlight_testing::sandbox_sizes::{
1396 LARGE_SCRATCH_SIZE, MEDIUM_SCRATCH_SIZE, SMALL_SCRATCH_SIZE,
1397 };
1398 use hyperlight_testing::{c_simple_guest_as_pathbuf, simple_guest_as_pathbuf};
1399
1400 use super::normalize_page_table_roots;
1401 use crate::func::host_functions::Registerable;
1402 #[cfg(not(gdb))]
1403 use crate::hypervisor::hyperlight_vm::test_support::VmOperation;
1404 use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags, MemoryRegionType};
1405 use crate::mem::mgr::ExecutionMode;
1406 use crate::mem::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, SharedMemory as _};
1407 use crate::sandbox::SandboxConfiguration;
1408 use crate::sandbox::snapshot::SnapshotOptions;
1409 use crate::sandbox::uninitialized::{GuestBlob, GuestEnvironment};
1410 use crate::{
1411 GuestBinary, HyperlightError, Result, Sandbox, SandboxBuilder, SandboxStatus,
1412 UninitializedSandbox,
1413 };
1414
1415 #[test]
1416 fn sandbox_status_predicates() {
1417 assert!(SandboxStatus::Ready.is_ready());
1418 assert!(!SandboxStatus::Ready.is_poisoned());
1419 assert!(!SandboxStatus::Ready.is_unrecoverable());
1420
1421 assert!(!SandboxStatus::Poisoned.is_ready());
1422 assert!(SandboxStatus::Poisoned.is_poisoned());
1423 assert!(!SandboxStatus::Poisoned.is_unrecoverable());
1424
1425 assert!(!SandboxStatus::Unrecoverable.is_ready());
1426 assert!(!SandboxStatus::Unrecoverable.is_poisoned());
1427 assert!(SandboxStatus::Unrecoverable.is_unrecoverable());
1428 }
1429
1430 fn scratch(scratch_size: usize) -> SnapshotOptions {
1431 SnapshotOptions::default().scratch_size(scratch_size)
1432 }
1433
1434 fn assert_virtq_attached(sbox: &Sandbox) {
1435 assert!(sbox.mem_mgr.g2h_consumer.is_some());
1436 assert!(sbox.mem_mgr.h2g_consumer.is_some());
1437 }
1438
1439 #[test]
1443 fn transport_guard_page_is_unmapped() {
1444 use hyperlight_common::layout::{scratch_reserved_top_gva, scratch_transport_end_gva};
1445
1446 fn assert_guarded(sbox: &mut Sandbox) {
1447 let guard = scratch_transport_end_gva();
1448 let mut mapped = |gva: u64| sbox.call::<bool>("CheckMapped", gva).unwrap();
1449 assert!(mapped(guard - hyperlight_common::vmem::PAGE_SIZE as u64));
1450 assert!(!mapped(guard));
1451 assert!(mapped(scratch_reserved_top_gva()));
1452 }
1453
1454 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1455 .scratch_size(8 << 20)
1456 .build()
1457 .unwrap();
1458 assert_guarded(&mut sbox);
1459 let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1460 assert_guarded(&mut sbox);
1461 sbox.restore(small).unwrap();
1462 assert_guarded(&mut sbox);
1463 }
1464
1465 #[test]
1469 fn snapshot_scratch_size_resizes_on_restore() {
1470 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1471 .scratch_size(8 << 20)
1472 .build()
1473 .unwrap();
1474 let full = sbox.snapshot().unwrap();
1475 let default = sbox
1478 .snapshot_with_options(&SnapshotOptions::default())
1479 .unwrap();
1480 assert!(Arc::ptr_eq(&default, &full));
1481 let same = sbox.snapshot_with_options(&scratch(8 << 20)).unwrap();
1482 assert!(Arc::ptr_eq(&same, &full));
1483 let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1484 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1485 assert!(Arc::ptr_eq(&sbox.snapshot().unwrap(), &small));
1486 assert!(matches!(
1487 sbox.snapshot_with_options(&scratch(4096)),
1488 Err(HyperlightError::MemoryRequestTooSmall(..))
1489 ));
1490 assert!(matches!(
1491 sbox.snapshot_with_options(&scratch(32 << 30)),
1492 Err(HyperlightError::MemoryRequestTooBig(..))
1493 ));
1494 let echo: String = sbox.call("Echo", "still".to_string()).unwrap();
1497 assert_eq!(echo, "still");
1498 assert!(sbox.transport_dirty);
1499 assert!(sbox.snapshot_with_options(&scratch(4096)).is_err());
1500 assert!(sbox.snapshot_with_options(&scratch(32 << 30)).is_err());
1501 assert!(sbox.transport_dirty);
1502
1503 let page = crate::mem::layout::SandboxMemoryLayout::host_page_size();
1506 let no_pt_room = sbox.mem_mgr.layout.min_scratch().next_multiple_of(page);
1507 assert!(matches!(
1508 sbox.snapshot_with_options(&scratch(no_pt_room)),
1509 Err(HyperlightError::MemoryRequestTooSmall(..))
1510 ));
1511 let echo: String = sbox.call("Echo", "usable".to_string()).unwrap();
1512 assert_eq!(echo, "usable");
1513
1514 for _ in 0..3 {
1515 sbox.restore(small.clone()).unwrap();
1516 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1517 let echo: String = sbox.call("Echo", "hello".to_string()).unwrap();
1518 assert_eq!(echo, "hello");
1519 sbox.call::<()>("AllocAndWritePattern", 32u64 << 10)
1520 .unwrap();
1521 }
1522 let again = sbox.snapshot().unwrap();
1524 assert_eq!(again.layout().get_scratch_size(), 2 << 20);
1525
1526 let dir = tempfile::tempdir().unwrap();
1528 let tag = crate::sandbox::snapshot::OciTag::new("small").unwrap();
1529 small.save(dir.path(), &tag).unwrap();
1530 let loaded = crate::sandbox::snapshot::Snapshot::checked_load(dir.path(), tag).unwrap();
1531 sbox.restore(Arc::new(loaded)).unwrap();
1532 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1533 let echo: String = sbox.call("Echo", "loaded".to_string()).unwrap();
1534 assert_eq!(echo, "loaded");
1535
1536 sbox.restore(full).unwrap();
1537 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 8 << 20);
1538 let echo: String = sbox.call("Echo", "back".to_string()).unwrap();
1539 assert_eq!(echo, "back");
1540 }
1541
1542 #[test]
1545 fn snapshot_scratch_size_grows_on_restore() {
1546 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1547 .scratch_size(4 << 20)
1548 .build()
1549 .unwrap();
1550 let booted = sbox.snapshot().unwrap();
1551 assert!(sbox.call::<()>("AllocAndWritePattern", 8u64 << 20).is_err());
1553 sbox.restore(booted).unwrap();
1554
1555 let large = sbox.snapshot_with_options(&scratch(16 << 20)).unwrap();
1556 assert_eq!(large.layout().get_scratch_size(), 16 << 20);
1557 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 16 << 20);
1558 sbox.call::<()>("AllocAndWritePattern", 8u64 << 20).unwrap();
1559
1560 for _ in 0..2 {
1561 sbox.restore(large.clone()).unwrap();
1562 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 16 << 20);
1563 sbox.call::<()>("AllocAndWritePattern", 8u64 << 20).unwrap();
1564 let echo: String = sbox.call("Echo", "grown".to_string()).unwrap();
1565 assert_eq!(echo, "grown");
1566 }
1567 }
1568
1569 #[test]
1574 fn held_buffers_survive_resized_snapshots() {
1575 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1576 .scratch_size(8 << 20)
1577 .h2g_pool_pages(8)
1579 .g2h_pool_pages(12)
1580 .host_function("HostEchoByteChunks", |v: Vec<Bytes>| v)
1581 .host_function("HostNoOp", || {})
1582 .build()
1583 .unwrap();
1584 let chunks = |seed: u8| {
1587 let mut first: Bytes = (0..11 * 1024usize)
1588 .map(|i| (i ^ (i >> 8)) as u8 ^ seed)
1589 .collect();
1590 let second = first.split_off(6 * 1024);
1591 vec![first, second]
1592 };
1593 let read_back =
1595 |sbox: &mut Sandbox, read: &str| sbox.call::<Vec<Bytes>>(read, ()).unwrap().concat();
1596 let base = sbox.snapshot().unwrap();
1597
1598 for (seed, hold, read, release) in [
1599 (
1600 0x00,
1601 "RetainGuestByteChunks",
1602 "ReadRetainedGuestByteChunks",
1603 "ReleaseGuestByteChunks",
1604 ),
1605 (
1606 0x40,
1607 "RetainHostByteChunks",
1608 "ReadRetainedHostByteChunks",
1609 "ReleaseHostByteChunks",
1610 ),
1611 ] {
1612 sbox.restore(base.clone()).unwrap();
1613 let held = chunks(seed);
1614 let len: i32 = sbox.call(hold, held.clone()).unwrap();
1615 assert_eq!(len, 11 * 1024);
1616 assert_eq!(read_back(&mut sbox, read), held.concat());
1617
1618 for size in [2 << 20, 16 << 20] {
1621 let snapshot = sbox.snapshot_with_options(&scratch(size)).unwrap();
1622 assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1626 assert_eq!(sbox.call::<i32>(hold, chunks(!seed)).unwrap(), len);
1627 sbox.restore(snapshot).unwrap();
1628 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), size);
1629
1630 let other = chunks(seed ^ 0x80);
1634 let echoed: Vec<Bytes> =
1635 sbox.call("RoundTripHostByteChunks", other.clone()).unwrap();
1636 assert_eq!(echoed.concat(), other.concat());
1637 assert_eq!(read_back(&mut sbox, read), held.concat());
1638 }
1639 assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1640 assert!(read_back(&mut sbox, read).is_empty());
1642
1643 for round in 1..=32 {
1646 let next = chunks(seed + round);
1647 assert_eq!(sbox.call::<i32>(hold, next.clone()).unwrap(), len);
1648 assert_eq!(read_back(&mut sbox, read), next.concat());
1649 assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1650 }
1651
1652 let back = sbox.snapshot_with_options(&scratch(8 << 20)).unwrap();
1655 assert!(!sbox.transport_dirty);
1656 sbox.restore(back).unwrap();
1657 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 8 << 20);
1658 let last = chunks(seed + 0x21);
1659 assert_eq!(sbox.call::<i32>(hold, last.clone()).unwrap(), len);
1660 assert_eq!(read_back(&mut sbox, read), last.concat());
1661 assert_eq!(sbox.call::<i32>(release, ()).unwrap(), len);
1662 }
1663 }
1664
1665 #[test]
1669 fn running_out_of_scratch_stops_at_the_transport_arena() {
1670 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1671 .scratch_size(8 << 20)
1672 .build()
1673 .unwrap();
1674 let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1675 sbox.restore(small.clone()).unwrap();
1676 let err = sbox
1678 .call::<()>("AllocAndWritePattern", 4u64 << 20)
1679 .unwrap_err();
1680 assert!(
1681 matches!(&err, HyperlightError::GuestAborted(code, msg)
1682 if *code == ErrorCode::MallocFailed as u8 && msg.contains("Out of physical memory")),
1683 "{err:?}"
1684 );
1685 let size = sbox.mem_mgr.scratch_mem.mem_size();
1686 let offset = size - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
1687 let allocator = sbox.mem_mgr.scratch_mem.read::<u64>(offset).unwrap();
1688 let arena = sbox.mem_mgr.layout.get_transport_arena();
1689 assert!(allocator > arena.base_addr(), "{allocator:#x}");
1692 assert!(allocator < arena.base_addr() + 0x4000, "{allocator:#x}");
1693
1694 sbox.restore(small).unwrap();
1695 let echo: String = sbox.call("Echo", "recovered".to_string()).unwrap();
1696 assert_eq!(echo, "recovered");
1697 }
1698
1699 #[test]
1703 fn scratch_allocated_bytes_counts_written_pages() {
1704 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1705 .scratch_size(16 << 20)
1706 .build()
1707 .unwrap();
1708 let snapshot = sbox.snapshot().unwrap();
1709 assert_eq!(sbox.scratch_allocated_bytes().unwrap(), 0);
1710
1711 sbox.call::<()>("AllocAndWritePattern", 1u64 << 20).unwrap();
1712 let one = sbox.scratch_allocated_bytes().unwrap();
1713 assert!(one >= 1 << 20, "{one}");
1714 sbox.call::<()>("AllocAndWritePattern", 2u64 << 20).unwrap();
1716 let three = sbox.scratch_allocated_bytes().unwrap();
1717 assert!(three >= 3 << 20, "{three}");
1718
1719 sbox.restore(snapshot).unwrap();
1720 assert_eq!(sbox.scratch_allocated_bytes().unwrap(), 0);
1721 sbox.call::<()>("AllocAndWritePattern", 1u64 << 20).unwrap();
1722 assert_eq!(sbox.scratch_allocated_bytes().unwrap(), one);
1723 sbox.snapshot().unwrap();
1724 assert_eq!(sbox.scratch_allocated_bytes().unwrap(), 0);
1725 }
1726
1727 #[test]
1730 fn resized_capture_installs_the_snapshot() {
1731 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1732 .scratch_size(8 << 20)
1733 .build()
1734 .unwrap();
1735 sbox.call::<i32>("AddToStatic", 42i32).unwrap();
1736 let map_mem = allocate_guest_memory();
1737 let guest_base = 0x200000000_u64;
1738 let region = region_for_memory(&map_mem, guest_base as usize, MemoryRegionFlags::READ);
1739 unsafe { sbox.map_region(®ion).unwrap() };
1741 let len = hyperlight_common::vmem::PAGE_SIZE as u64;
1742 let mapped = sbox
1743 .call::<Vec<u8>>("ReadMappedBuffer", (guest_base, len, true))
1744 .unwrap();
1745
1746 let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1747
1748 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1749 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
1750 assert!(Arc::ptr_eq(&sbox.snapshot().unwrap(), &small));
1751 assert_virtq_attached(&sbox);
1752 assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 42);
1753 let read = sbox
1754 .call::<Vec<u8>>("ReadMappedBuffer", (guest_base, len, false))
1755 .unwrap();
1756 assert_eq!(read, mapped);
1757 }
1758
1759 #[test]
1762 fn resized_capture_keeps_pending_guest_requests() {
1763 use hyperlight_common::layout::{
1764 SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET, SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
1765 };
1766
1767 fn requests(sbox: &Sandbox) -> [u64; 2] {
1768 let scratch = &sbox.mem_mgr.scratch_mem;
1769 [
1770 SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
1771 SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
1772 ]
1773 .map(|offset| {
1774 scratch
1775 .read::<u64>(scratch.mem_size() - offset as usize)
1776 .unwrap()
1777 })
1778 }
1779
1780 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1781 .scratch_size(8 << 20)
1782 .build()
1783 .unwrap();
1784 let snapshot = sbox.snapshot().unwrap();
1785 sbox.restore(snapshot).unwrap();
1786 sbox.log_level(tracing_core::LevelFilter::INFO).unwrap();
1787 let pending = requests(&sbox);
1788 assert!(pending.iter().all(|&request| request != 0));
1789
1790 sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1791
1792 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), 2 << 20);
1793 assert_eq!(requests(&sbox), pending);
1794 }
1795
1796 #[test]
1799 #[cfg(not(unshared_snapshot_mem))]
1800 fn capture_after_resized_capture_reuses_its_layers() {
1801 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1802 .scratch_size(8 << 20)
1803 .build()
1804 .unwrap();
1805 let small = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1806 let map_mem = allocate_guest_memory();
1807 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
1808 unsafe { sbox.map_region(®ion).unwrap() };
1810
1811 let next = sbox.snapshot().unwrap();
1812
1813 assert!(!Arc::ptr_eq(&small, &next));
1814 assert_eq!(next.layout().get_scratch_size(), 2 << 20);
1815 let small_layers = small.snapshot_memory().layers();
1816 let next_layers = next.snapshot_memory().layers();
1817 assert_eq!(next_layers.len(), small_layers.len());
1818 for layer in next_layers.iter() {
1819 assert!(small_layers.iter().any(|kept| Arc::ptr_eq(kept, layer)));
1820 }
1821 }
1822
1823 #[test]
1826 fn snapshots_of_different_scratch_sizes_restore_their_state() {
1827 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1828 .scratch_size(4 << 20)
1829 .build()
1830 .unwrap();
1831 sbox.call::<i32>("AddToStatic", 1i32).unwrap();
1832 let grown = sbox.snapshot_with_options(&scratch(8 << 20)).unwrap();
1833 sbox.call::<i32>("AddToStatic", 2i32).unwrap();
1834 let shrunk = sbox.snapshot_with_options(&scratch(2 << 20)).unwrap();
1835 sbox.call::<i32>("AddToStatic", 3i32).unwrap();
1836 let unchanged = sbox.snapshot().unwrap();
1837
1838 sbox.restore(grown.clone()).unwrap();
1839 sbox.call::<i32>("AddToStatic", 10i32).unwrap();
1840 let branch = sbox.snapshot_with_options(&scratch(4 << 20)).unwrap();
1841
1842 for (snapshot, size, value) in [
1843 (&grown, 8 << 20, 1),
1844 (&shrunk, 2 << 20, 3),
1845 (&unchanged, 2 << 20, 6),
1846 (&branch, 4 << 20, 11),
1847 ] {
1848 sbox.restore(snapshot.clone()).unwrap();
1849 assert_eq!(sbox.mem_mgr.scratch_mem.mem_size(), size);
1850 assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), value);
1851 }
1852
1853 let dir = tempfile::tempdir().unwrap();
1854 let tag = crate::sandbox::snapshot::OciTag::new("branch").unwrap();
1855 branch.save(dir.path(), &tag).unwrap();
1856 let loaded = crate::sandbox::snapshot::Snapshot::checked_load(dir.path(), tag).unwrap();
1857 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1858 .build()
1859 .unwrap();
1860 target.restore(Arc::new(loaded)).unwrap();
1861 assert_eq!(target.mem_mgr.scratch_mem.mem_size(), 4 << 20);
1862 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
1863 }
1864
1865 #[test]
1866 #[cfg(not(gdb))]
1867 fn resized_capture_scratch_mapping_failure_is_unrecoverable() {
1868 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1869 .scratch_size(8 << 20)
1870 .build()
1871 .unwrap();
1872 let fault_plan = sandbox
1873 .vm
1874 .inject_vm_faults([VmOperation::Map(MemoryRegionType::Scratch)]);
1875
1876 let error = sandbox
1877 .snapshot_with_options(&scratch(2 << 20))
1878 .err()
1879 .unwrap();
1880
1881 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
1882 assert!(fault_plan.is_consumed());
1883 assert_eq!(sandbox.status(), SandboxStatus::Unrecoverable);
1884 }
1885
1886 #[test]
1887 fn poison() {
1888 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1889 .build()
1890 .unwrap();
1891 let snapshot = sbox.snapshot().unwrap();
1892
1893 let res = sbox
1895 .call::<()>("guest_panic", "hello".to_string())
1896 .unwrap_err();
1897 assert!(
1898 matches!(res, HyperlightError::GuestAborted(code, context) if code == ErrorCode::UnknownError as u8 && context.contains("hello"))
1899 );
1900 assert!(sbox.status().is_poisoned());
1901
1902 let res = sbox
1904 .call::<()>("guest_panic", "hello2".to_string())
1905 .unwrap_err();
1906 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1907
1908 if let Err(e) = sbox.snapshot() {
1910 assert!(sbox.status().is_poisoned());
1911 assert!(matches!(e, HyperlightError::PoisonedSandbox));
1912 } else {
1913 panic!("Snapshot should fail");
1914 }
1915
1916 {
1918 let map_mem = allocate_guest_memory();
1919 let guest_base = 0x0;
1920 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
1921 let res = unsafe { sbox.map_region(®ion) }.unwrap_err();
1922 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1923 }
1924
1925 {
1927 let temp_file = std::env::temp_dir().join("test_poison_map_file.bin");
1928 let res = sbox.map_file_cow(&temp_file, 0x0).unwrap_err();
1929 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1930 std::fs::remove_file(&temp_file).ok(); }
1932
1933 #[allow(deprecated)]
1935 let res = sbox
1936 .call_guest_function_by_name::<String>("Echo", "test".to_string())
1937 .unwrap_err();
1938 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1939
1940 sbox.restore(snapshot.clone()).unwrap();
1942 assert_eq!(sbox.status(), SandboxStatus::Ready);
1943
1944 let res = sbox.call::<String>("Echo", "hello2".to_string()).unwrap();
1946 assert_eq!(res, "hello2".to_string());
1947 assert_eq!(sbox.status(), SandboxStatus::Ready);
1948
1949 let res = sbox
1951 .call::<()>("guest_panic", "hello".to_string())
1952 .unwrap_err();
1953 assert!(
1954 matches!(res, HyperlightError::GuestAborted(code, context) if code == ErrorCode::UnknownError as u8 && context.contains("hello"))
1955 );
1956 assert!(sbox.status().is_poisoned());
1957
1958 sbox.restore(snapshot.clone()).unwrap();
1960 assert_eq!(sbox.status(), SandboxStatus::Ready);
1961
1962 let res = sbox.call::<String>("Echo", "hello3".to_string()).unwrap();
1964 assert_eq!(res, "hello3".to_string());
1965 assert_eq!(sbox.status(), SandboxStatus::Ready);
1966
1967 let _ = sbox.snapshot().unwrap();
1969 }
1970
1971 #[test]
1973 fn host_func_error() {
1974 let path = simple_guest_as_pathbuf();
1975 let mut sandbox = SandboxBuilder::from_file(path)
1976 .host_function("HostError", || -> Result<()> {
1977 Err(HyperlightError::Error("hi".to_string()))
1978 })
1979 .build()
1980 .unwrap();
1981
1982 for _ in 0..1000 {
1984 let result = sandbox
1985 .call::<i64>(
1986 "CallGivenParamlessHostFuncThatReturnsI64",
1987 "HostError".to_string(),
1988 )
1989 .unwrap_err();
1990
1991 assert!(
1992 matches!(result, HyperlightError::GuestError(code, msg) if code == ErrorCode::HostFunctionError && msg == "hi"),
1993 );
1994 }
1995 }
1996
1997 #[test]
1998 fn call_host_func_expect_error() {
1999 let path = simple_guest_as_pathbuf();
2000 let mut sandbox = SandboxBuilder::from_file(path).build().unwrap();
2001 sandbox
2002 .call::<()>("CallHostExpectError", "SomeUnknownHostFunc".to_string())
2003 .unwrap();
2004 }
2005
2006 #[test]
2008 fn transport_buffers_are_reclaimed() {
2009 let path = simple_guest_as_pathbuf();
2010 let mut sandbox = SandboxBuilder::from_file(path)
2011 .host_function("HostAdd", |a: i32, b: i32| a + b)
2012 .build()
2013 .unwrap();
2014
2015 for _ in 0..1000 {
2017 let result = sandbox.call::<i32>("Add", (5i32, 10i32)).unwrap();
2018 assert_eq!(result, 15);
2019 let result = sandbox.call::<i32>("AddToStaticAndFail", ()).unwrap_err();
2020 assert!(
2021 matches!(result, HyperlightError::GuestError (code, msg ) if code == ErrorCode::GuestError && msg == "Crash on purpose")
2022 );
2023 }
2024 }
2025
2026 #[test]
2028 fn test_call_guest_function_by_name() {
2029 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2030 .build()
2031 .unwrap();
2032
2033 let snapshot = sbox.snapshot().unwrap();
2034
2035 let _ = sbox.call::<i32>("AddToStatic", 5i32).unwrap();
2036 let res: i32 = sbox.call("GetStatic", ()).unwrap();
2037 assert_eq!(res, 5);
2038
2039 sbox.restore(snapshot).unwrap();
2040 #[allow(deprecated)]
2041 let _ = sbox
2042 .call_guest_function_by_name::<i32>("AddToStatic", 5i32)
2043 .unwrap();
2044 #[allow(deprecated)]
2045 let res: i32 = sbox.call_guest_function_by_name("GetStatic", ()).unwrap();
2046 assert_eq!(res, 0);
2047 }
2048
2049 #[test]
2052 fn test_with_small_scratch() {
2053 let scratch_size = {
2055 let defaults = SandboxConfiguration::default();
2056 let layout =
2057 crate::mem::layout::SandboxMemoryLayout::new(defaults, 0, 0, None).unwrap();
2058 layout.min_scratch().next_multiple_of(page_size::get())
2059 } + 0x40000;
2060
2061 let mut sbox1 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2062 .scratch_size(scratch_size)
2063 .build()
2064 .unwrap();
2065
2066 for _ in 0..1000 {
2067 sbox1.call::<String>("Echo", "hello".to_string()).unwrap();
2068 }
2069
2070 let mut sbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2071 .scratch_size(scratch_size)
2072 .build()
2073 .unwrap();
2074
2075 for i in 0..1000 {
2076 sbox2
2077 .call::<i32>(
2078 "PrintUsingPrintf",
2079 format!("Hello World {}\n", i).to_string(),
2080 )
2081 .unwrap();
2082 }
2083 }
2084
2085 #[test]
2088 fn snapshot_evolve_restore_handles_state_correctly() {
2089 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2090 .build()
2091 .unwrap();
2092
2093 let snapshot = sbox.snapshot().unwrap();
2094
2095 let _ = sbox.call::<i32>("AddToStatic", 5i32).unwrap();
2096
2097 let res: i32 = sbox.call("GetStatic", ()).unwrap();
2098 assert_eq!(res, 5);
2099
2100 sbox.restore(snapshot).unwrap();
2101 let res: i32 = sbox.call("GetStatic", ()).unwrap();
2102 assert_eq!(res, 0);
2103 }
2104
2105 #[test]
2106 fn snapshots_checkpoint_only_dirty_transport() {
2107 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2108 .build()
2109 .unwrap();
2110
2111 assert!(sandbox.transport_dirty);
2112 let initial = sandbox.snapshot().unwrap();
2113 assert!(!sandbox.transport_dirty);
2114
2115 let restored = SandboxBuilder::from_snapshot(initial).build().unwrap();
2116 assert!(!restored.transport_dirty);
2117
2118 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2119 assert!(sandbox.transport_dirty);
2120
2121 let first = sandbox.snapshot().unwrap();
2122 assert!(!sandbox.transport_dirty);
2123 let cached = sandbox.snapshot().unwrap();
2124 assert!(Arc::ptr_eq(&first, &cached));
2125 assert!(!sandbox.transport_dirty);
2126
2127 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2128 assert!(sandbox.transport_dirty);
2129 sandbox.snapshot().unwrap();
2130 assert!(!sandbox.transport_dirty);
2131 }
2132
2133 #[test]
2134 fn snapshots_reject_noncanonical_transport_after_checkpoint() {
2135 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2136 .build()
2137 .unwrap();
2138
2139 sandbox.checkpoint_transport_for_snapshot().unwrap();
2140 sandbox.snapshot = None;
2141
2142 let generation = sandbox.mem_mgr.snapshot_count;
2143 let ring = sandbox.mem_mgr.layout.get_transport_arena().g2h_ring_addr();
2144 let scratch_base =
2145 hyperlight_common::layout::scratch_base_gpa(sandbox.mem_mgr.layout.get_scratch_size());
2146 let offset = usize::try_from(ring - scratch_base).unwrap();
2147
2148 sandbox.mem_mgr.scratch_mem.write::<u64>(offset, 1).unwrap();
2149
2150 let Err(error) = sandbox.snapshot() else {
2151 panic!("expected invalid canonical transport");
2152 };
2153
2154 assert!(
2155 error.to_string().contains("invalid canonical G2H image"),
2156 "{error}"
2157 );
2158 assert_eq!(sandbox.mem_mgr.snapshot_count, generation);
2159 assert!(sandbox.snapshot.is_none());
2160
2161 sandbox.mem_mgr.scratch_mem.write::<u64>(offset, 0).unwrap();
2163 let expected = vec![0x5a; 2 * hyperlight_common::vmem::PAGE_SIZE + 137];
2164 let actual: Vec<u8> = sandbox.call("EchoGuestVecBytes", expected.clone()).unwrap();
2165 assert_eq!(actual, expected);
2166 }
2167
2168 #[test]
2169 fn snapshot_checkpoint_ignores_idle_cancellation() {
2170 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2171 .build()
2172 .unwrap();
2173
2174 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2175 assert!(!sandbox.interrupt_handle().kill());
2176
2177 sandbox.snapshot().unwrap();
2178 assert_eq!(sandbox.status(), SandboxStatus::Ready);
2179 assert!(!sandbox.transport_dirty);
2180 assert!(!sandbox.interrupt_handle().kill());
2181 assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 5);
2182 }
2183
2184 #[test]
2185 fn snapshot_checkpoint_clears_partial_abort_bytes() {
2186 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2187 .build()
2188 .unwrap();
2189
2190 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2191 sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
2192
2193 sandbox.snapshot().unwrap();
2194
2195 assert!(sandbox.mem_mgr.abort_buffer.is_empty());
2196 assert_eq!(sandbox.status(), SandboxStatus::Ready);
2197 }
2198
2199 #[test]
2200 fn restricted_dispatch_rejects_host_calls() {
2201 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2202 .build()
2203 .unwrap();
2204
2205 let call = FunctionCall::new(
2206 "PrintOutput".into(),
2207 Some(vec![ParameterValue::String("checkpoint".into())]),
2208 FunctionCallType::Guest,
2209 i32::TYPE,
2210 );
2211 sandbox.mem_mgr.write_guest_function_call(&call).unwrap();
2212
2213 let error = sandbox.dispatch_guest_call_restricted().unwrap_err();
2214
2215 assert!(
2216 error.to_string().contains("during a snapshot checkpoint"),
2217 "{error}"
2218 );
2219 assert_eq!(sandbox.status(), SandboxStatus::Poisoned);
2220 assert_eq!(sandbox.mem_mgr.execution_mode, ExecutionMode::Unrestricted);
2221 }
2222
2223 #[test]
2224 fn restore_resets_execution_mode() {
2225 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2226 .build()
2227 .unwrap();
2228
2229 let snapshot = sandbox.snapshot().unwrap();
2230 sandbox.mem_mgr.execution_mode = ExecutionMode::Restricted;
2231 sandbox.restore(snapshot).unwrap();
2232
2233 sandbox
2234 .call::<i32>("PrintOutput", "restored".to_string())
2235 .unwrap();
2236 }
2237
2238 #[test]
2239 fn guest_execution_preserves_pre_entry_cancellation() {
2240 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2241 .build()
2242 .unwrap();
2243 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
2244 sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
2245
2246 let error = sandbox
2247 .with_guest_execution(|sandbox| {
2248 sandbox.mem_mgr.begin_snapshot_checkpoint()?;
2249 assert!(!sandbox.interrupt_handle().kill());
2250 sandbox.dispatch_guest_call()
2251 })
2252 .unwrap_err();
2253
2254 assert!(matches!(error, HyperlightError::ExecutionCanceledByHost()));
2255 assert_eq!(sandbox.status(), SandboxStatus::Poisoned);
2256 assert!(sandbox.mem_mgr.abort_buffer.is_empty());
2257 }
2258
2259 #[test]
2260 fn snapshots_preserve_retained_transport_and_clear_abort_state() {
2261 let path = simple_guest_as_pathbuf();
2262 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
2263 sandbox
2264 .register("HostEchoByteChunks", |value: Vec<Bytes>| value)
2265 .unwrap();
2266
2267 let mut sandbox = sandbox.evolve().unwrap();
2268 let retained = vec![Bytes::from(vec![0xa5; 6 * 1024])];
2269
2270 for (retain, release) in [
2271 ("RetainGuestByteChunks", "ReleaseGuestByteChunks"),
2272 ("RetainHostByteChunks", "ReleaseHostByteChunks"),
2273 ] {
2274 let retained_len: i32 = sandbox.call(retain, retained.clone()).unwrap();
2275 assert_eq!(retained_len, 6 * 1024);
2276 sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
2277
2278 let snapshot = sandbox.snapshot().unwrap();
2279 assert!(!sandbox.status().is_poisoned());
2280 assert!(!sandbox.transport_dirty);
2281 assert!(sandbox.mem_mgr.abort_buffer.is_empty());
2282
2283 assert_eq!(sandbox.call::<i32>(release, ()).unwrap(), retained_len);
2284
2285 sandbox.restore(snapshot).unwrap();
2286 assert_eq!(sandbox.call::<i32>(release, ()).unwrap(), retained_len);
2287 sandbox.snapshot().unwrap();
2288 assert!(!sandbox.transport_dirty);
2289 }
2290 }
2291
2292 #[test]
2293 fn retained_restore_is_ready_for_first_request() {
2294 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2295 .build()
2296 .unwrap();
2297 sandbox
2298 .call::<i32>(
2299 "RetainGuestByteChunks",
2300 vec![Bytes::from(vec![0x5a; 6 * 1024])],
2301 )
2302 .unwrap();
2303 sandbox.checkpoint_transport_for_snapshot().unwrap();
2304 let source_root = sandbox.vm.get_root_pt().unwrap();
2305 let snapshot = sandbox.snapshot().unwrap();
2306 assert_eq!(sandbox.vm.get_root_pt().unwrap(), source_root);
2307
2308 sandbox.restore(snapshot.clone()).unwrap();
2309 let mut clone =
2310 Sandbox::from_snapshot(snapshot, crate::HostFunctions::default(), None).unwrap();
2311 let expected = vec![0x3c; 3 * hyperlight_common::vmem::PAGE_SIZE + 117];
2312 let call = FunctionCall::new(
2313 "EchoGuestVecBytes".into(),
2314 Some(vec![ParameterValue::VecBytes(expected.clone())]),
2315 FunctionCallType::Guest,
2316 Vec::<u8>::TYPE,
2317 );
2318
2319 for restored in [&mut sandbox, &mut clone] {
2320 restored.transport_dirty = true;
2321 let cid = restored.mem_mgr.write_guest_function_call(&call).unwrap();
2322 restored.dispatch_guest_call().unwrap();
2323 let value = restored
2324 .mem_mgr
2325 .read_h2g_result_from_g2h(cid)
2326 .unwrap()
2327 .into_inner()
2328 .unwrap();
2329 assert_eq!(Vec::<u8>::from_value(value).unwrap(), expected);
2330 }
2331
2332 assert_eq!(
2333 clone.call::<i32>("ReleaseGuestByteChunks", ()).unwrap(),
2334 6 * 1024
2335 );
2336 }
2337
2338 #[test]
2339 fn test_trigger_exception_on_guest() {
2340 let mut multi_use_sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2341 .build()
2342 .unwrap();
2343
2344 let res: Result<()> = multi_use_sandbox.call("TriggerException", ());
2345
2346 assert!(res.is_err());
2347
2348 match res.unwrap_err() {
2349 HyperlightError::GuestAborted(_, msg) => {
2350 #[cfg(target_arch = "x86_64")]
2352 assert!(msg.contains("InvalidOpcode"));
2353 #[cfg(target_arch = "aarch64")]
2354 assert!(msg.contains("0x2000000"));
2355 }
2356 e => panic!("Expected HyperlightError::GuestAborted but got {:?}", e),
2357 }
2358 }
2359
2360 fn create_many_on_threads_test<const NUM_THREADS: usize, const SANDBOXES_PER_THREAD: usize>() {
2361 let start_barrier = Arc::new(Barrier::new(NUM_THREADS + 1));
2363 let mut thread_handles = vec![];
2364
2365 for _ in 0..NUM_THREADS {
2366 let barrier = start_barrier.clone();
2367
2368 let handle = thread::spawn(move || {
2369 barrier.wait();
2370
2371 for _ in 0..SANDBOXES_PER_THREAD {
2372 let guest_path = simple_guest_as_pathbuf();
2373 let mut sandbox = SandboxBuilder::from_file(guest_path).build().unwrap();
2374
2375 let result: i32 = sandbox.call("GetStatic", ()).unwrap();
2376 assert_eq!(result, 0);
2377 }
2378 });
2379
2380 thread_handles.push(handle);
2381 }
2382
2383 start_barrier.wait();
2384
2385 for handle in thread_handles {
2386 handle.join().unwrap();
2387 }
2388 }
2389
2390 #[test]
2391 fn create_200_sandboxes() {
2392 create_many_on_threads_test::<20, 10>();
2393 }
2394
2395 #[test]
2396 fn create_200_threads() {
2397 #[cfg(target_arch = "aarch64")]
2398 create_many_on_threads_test::<32, 1>();
2399 #[cfg(not(target_arch = "aarch64"))]
2400 create_many_on_threads_test::<200, 1>();
2401 }
2402
2403 #[test]
2404 fn create_2000_sandboxes() {
2405 #[cfg(target_arch = "aarch64")]
2406 create_many_on_threads_test::<20, 100>();
2407 #[cfg(not(target_arch = "aarch64"))]
2408 create_many_on_threads_test::<200, 10>();
2409 }
2410
2411 #[test]
2412 fn test_mmap() {
2413 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2414 .build()
2415 .unwrap();
2416
2417 let expected = b"hello world";
2418 let map_mem = page_aligned_memory(expected);
2419 let guest_base = 0x1_0000_0000; unsafe {
2422 sbox.map_region(®ion_for_memory(
2423 &map_mem,
2424 guest_base,
2425 MemoryRegionFlags::READ,
2426 ))
2427 .unwrap();
2428 }
2429
2430 let _guard = map_mem.lock.try_read().unwrap();
2431 let actual: Vec<u8> = sbox
2432 .call(
2433 "ReadMappedBuffer",
2434 (guest_base as u64, expected.len() as u64, true),
2435 )
2436 .unwrap();
2437
2438 assert_eq!(actual, expected);
2439 }
2440
2441 #[test]
2443 fn test_mmap_write_exec() {
2444 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2445 .build()
2446 .unwrap();
2447
2448 #[cfg(target_arch = "x86_64")]
2449 let expected = &[0x90, 0x90, 0x90, 0xC3]; #[cfg(target_arch = "aarch64")]
2451 let expected = &[0x1f, 0x20, 0x03, 0xd5, 0xc0, 0x03, 0x5f, 0xd6];
2452 let map_mem = page_aligned_memory(expected);
2453 let guest_base = 0x1_0000_0000; unsafe {
2456 sbox.map_region(®ion_for_memory(
2457 &map_mem,
2458 guest_base,
2459 MemoryRegionFlags::READ | MemoryRegionFlags::EXECUTE,
2460 ))
2461 .unwrap();
2462 }
2463
2464 let _guard = map_mem.lock.try_read().unwrap();
2465
2466 let succeed = sbox
2468 .call::<bool>(
2469 "ExecMappedBuffer",
2470 (guest_base as u64, expected.len() as u64),
2471 )
2472 .unwrap();
2473 assert!(succeed, "Expected execution of mapped buffer to succeed");
2474
2475 let err = sbox
2477 .call::<bool>(
2478 "WriteMappedBuffer",
2479 (guest_base as u64, expected.len() as u64),
2480 )
2481 .unwrap_err();
2482
2483 match err {
2484 HyperlightError::MemoryAccessViolation(addr, ..) if addr == guest_base as u64 => {}
2485 _ => panic!("Expected MemoryAccessViolation error"),
2486 };
2487 }
2488
2489 fn page_aligned_memory(src: &[u8]) -> GuestSharedMemory {
2490 let page_size = page_size::get();
2491 let len = src.len().div_ceil(page_size) * page_size;
2492
2493 let mut mem = ExclusiveSharedMemory::new(len).unwrap();
2494 mem.copy_from_slice(src, 0).unwrap();
2495
2496 let (_, guest_mem) = mem.build();
2497
2498 guest_mem
2499 }
2500
2501 fn region_for_memory(
2502 mem: &GuestSharedMemory,
2503 guest_base: usize,
2504 flags: MemoryRegionFlags,
2505 ) -> MemoryRegion {
2506 let len = mem.mem_size();
2507 MemoryRegion {
2508 host_region: mem.host_region_base()..mem.host_region_end(),
2509 guest_region: guest_base..(guest_base + len),
2510 flags,
2511 region_type: MemoryRegionType::Heap,
2512 }
2513 }
2514
2515 fn allocate_guest_memory() -> GuestSharedMemory {
2516 let mut data = vec![0; 2 * page_size::get()];
2517 data[..b"test data for snapshot".len()].copy_from_slice(b"test data for snapshot");
2518 page_aligned_memory(&data)
2519 }
2520
2521 #[test]
2522 fn snapshot_restore_handles_remapping_correctly() {
2523 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2524 .build()
2525 .unwrap();
2526
2527 let snapshot1 = sbox.snapshot().unwrap();
2529 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2530
2531 let map_mem = allocate_guest_memory();
2533 let guest_base = 0x200000000_usize;
2534 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2535
2536 unsafe { sbox.map_region(®ion).unwrap() };
2537 assert_eq!(sbox.vm.get_mapped_regions().count(), 1);
2538 let orig_read = sbox
2539 .call::<Vec<u8>>(
2540 "ReadMappedBuffer",
2541 (
2542 guest_base as u64,
2543 hyperlight_common::vmem::PAGE_SIZE as u64,
2544 true,
2545 ),
2546 )
2547 .unwrap();
2548
2549 let snapshot2 = sbox.snapshot().unwrap();
2551 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2552
2553 sbox.restore(snapshot1.clone()).unwrap();
2555 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2556 let is_mapped = sbox
2557 .call::<bool>("CheckMapped", (guest_base as u64,))
2558 .unwrap();
2559 assert!(!is_mapped);
2560
2561 sbox.restore(snapshot2.clone()).unwrap();
2564 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2565 let is_mapped = sbox
2566 .call::<bool>("CheckMapped", (guest_base as u64,))
2567 .unwrap();
2568 assert!(is_mapped);
2569
2570 let new_read = sbox
2572 .call::<Vec<u8>>(
2573 "ReadMappedBuffer",
2574 (
2575 guest_base as u64,
2576 hyperlight_common::vmem::PAGE_SIZE as u64,
2577 false,
2578 ),
2579 )
2580 .unwrap();
2581 assert_eq!(new_read, orig_read);
2582 }
2583
2584 #[test]
2589 #[cfg(not(unshared_snapshot_mem))]
2590 fn capture_without_guest_progress_reuses_every_layer() {
2591 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2592 .build()
2593 .unwrap();
2594
2595 let first = sbox.snapshot().unwrap();
2596 assert!(
2597 !first.snapshot_memory().layers().is_empty(),
2598 "the first capture materializes the initialization delta"
2599 );
2600
2601 let map_mem = allocate_guest_memory();
2602 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2603 unsafe { sbox.map_region(®ion).unwrap() };
2605
2606 let second = sbox.snapshot().unwrap();
2607 assert!(
2608 !Arc::ptr_eq(&first, &second),
2609 "map_region must invalidate the cached snapshot"
2610 );
2611 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
2612
2613 for layer in second.snapshot_memory().layers().iter() {
2615 assert!(
2616 first
2617 .snapshot_memory()
2618 .layers()
2619 .iter()
2620 .any(|previous| Arc::ptr_eq(previous, layer)),
2621 "capture copied a page it could have shared"
2622 );
2623 }
2624
2625 assert_eq!(
2626 second.snapshot_memory().layers().len(),
2627 first.snapshot_memory().layers().len()
2628 );
2629
2630 sbox.restore(second).unwrap();
2631 assert_eq!(
2632 sbox.call::<String>("Echo", "hello".to_string()).unwrap(),
2633 "hello"
2634 );
2635 }
2636
2637 #[test]
2641 fn snapshot_restore_across_sandboxes_preserves_mapped_region_contents() {
2642 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2643 .build()
2644 .unwrap();
2645
2646 let map_mem = allocate_guest_memory();
2647 let guest_base = 0x200000000_usize;
2648 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2649 unsafe { source.map_region(®ion).unwrap() };
2650
2651 let orig_read = source
2653 .call::<Vec<u8>>(
2654 "ReadMappedBuffer",
2655 (
2656 guest_base as u64,
2657 hyperlight_common::vmem::PAGE_SIZE as u64,
2658 true,
2659 ),
2660 )
2661 .unwrap();
2662
2663 let snapshot = source.snapshot().unwrap();
2664
2665 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2666 .build()
2667 .unwrap();
2668 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2669
2670 target.restore(snapshot).unwrap();
2671 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2672
2673 let new_read = target
2676 .call::<Vec<u8>>(
2677 "ReadMappedBuffer",
2678 (
2679 guest_base as u64,
2680 hyperlight_common::vmem::PAGE_SIZE as u64,
2681 false,
2682 ),
2683 )
2684 .unwrap();
2685 assert_eq!(new_read, orig_read);
2686 }
2687
2688 #[test]
2689 fn snapshot_restore_across_sandboxes() {
2690 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2691 .build()
2692 .unwrap();
2693
2694 let mut sandbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2695 .build()
2696 .unwrap();
2697
2698 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2699 assert_eq!(sandbox2.call::<i32>("GetStatic", ()).unwrap(), 0);
2700
2701 let snapshot = sandbox.snapshot().unwrap();
2702 sandbox2.restore(snapshot).unwrap();
2703 assert_virtq_attached(&sandbox2);
2704 assert_eq!(sandbox2.call::<i32>("GetStatic", ()).unwrap(), 42);
2705 }
2706
2707 #[test]
2708 #[cfg(not(gdb))]
2709 fn snapshot_restore_keeps_current_base_mappings() {
2710 let path = simple_guest_as_pathbuf();
2711 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2712 .unwrap()
2713 .evolve()
2714 .unwrap();
2715 let snapshot = sandbox.snapshot().unwrap();
2716 sandbox.restore(snapshot.clone()).unwrap();
2717 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2718 let mappings = sandbox.vm.base_mapping_state();
2719 let fault_plan = sandbox
2720 .vm
2721 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Snapshot)]);
2722
2723 sandbox.restore(snapshot).unwrap();
2724
2725 assert_eq!(sandbox.status(), SandboxStatus::Ready);
2726 let new_mappings = sandbox.vm.base_mapping_state();
2727 assert_eq!(new_mappings.0, mappings.0);
2729 assert_eq!(new_mappings.1.map(|m| m.1), mappings.1.map(|m| m.1));
2732 assert!(!fault_plan.is_consumed());
2733 assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 0);
2734 }
2735
2736 #[test]
2737 #[cfg(not(gdb))]
2738 fn snapshot_capture_mapping_failure_is_unrecoverable() {
2739 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2740 .build()
2741 .unwrap();
2742 let recovery_snapshot = sandbox.snapshot().unwrap();
2743 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2744 let fault_plan = sandbox
2745 .vm
2746 .inject_vm_faults([VmOperation::Map(MemoryRegionType::Snapshot)]);
2747
2748 let error = sandbox.snapshot().err().unwrap();
2749
2750 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2751 assert!(fault_plan.is_consumed());
2752 assert_eq!(sandbox.status(), SandboxStatus::Unrecoverable);
2753 assert!(matches!(
2754 sandbox.restore(recovery_snapshot),
2755 Err(HyperlightError::UnrecoverableSandbox)
2756 ));
2757 assert!(matches!(
2758 sandbox.call::<i32>("GetStatic", ()),
2759 Err(HyperlightError::UnrecoverableSandbox)
2760 ));
2761 assert!(matches!(
2762 sandbox.snapshot(),
2763 Err(HyperlightError::UnrecoverableSandbox)
2764 ));
2765 }
2766
2767 #[test]
2768 #[cfg(not(gdb))]
2769 fn snapshot_restore_mapping_failure_is_unrecoverable() {
2770 let path = simple_guest_as_pathbuf();
2771 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2772 .unwrap()
2773 .evolve()
2774 .unwrap();
2775 source.call::<i32>("AddToStatic", 42i32).unwrap();
2776 let snapshot = source.snapshot().unwrap();
2777
2778 let path = simple_guest_as_pathbuf();
2779 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2780 .unwrap()
2781 .evolve()
2782 .unwrap();
2783 let mappings = target.vm.base_mapping_state();
2784 let fault_plan = target
2785 .vm
2786 .inject_vm_faults([VmOperation::Map(MemoryRegionType::Snapshot)]);
2787
2788 let error = target.restore(snapshot.clone()).unwrap_err();
2789 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2790 assert_eq!(target.status(), SandboxStatus::Unrecoverable);
2791 assert_eq!(target.vm.base_mapping_state(), (Vec::new(), mappings.1));
2792 assert!(fault_plan.is_consumed());
2793
2794 assert!(matches!(
2795 target.restore(snapshot),
2796 Err(HyperlightError::UnrecoverableSandbox)
2797 ));
2798 assert!(matches!(
2799 target.call::<i32>("GetStatic", ()),
2800 Err(HyperlightError::UnrecoverableSandbox)
2801 ));
2802 assert!(matches!(
2803 target.snapshot(),
2804 Err(HyperlightError::UnrecoverableSandbox)
2805 ));
2806
2807 let map_mem = allocate_guest_memory();
2808 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2809 assert!(matches!(
2810 unsafe { target.map_region(®ion) },
2811 Err(HyperlightError::UnrecoverableSandbox)
2812 ));
2813 }
2814
2815 #[test]
2816 #[cfg(not(gdb))]
2817 fn scratch_mapping_failure_clears_mapping_state() {
2818 let path = simple_guest_as_pathbuf();
2819 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2820 .unwrap()
2821 .evolve()
2822 .unwrap();
2823 let snapshot_mapping = target.vm.base_mapping_state().0;
2824 let scratch = ExclusiveSharedMemory::new(target.mem_mgr.scratch_mem.mem_size()).unwrap();
2825 let (_, scratch) = scratch.build();
2826 let fault_plan = target
2827 .vm
2828 .inject_vm_faults([VmOperation::Map(MemoryRegionType::Scratch)]);
2829
2830 target.vm.update_scratch_mapping(scratch).unwrap_err();
2831 assert_eq!(target.vm.base_mapping_state(), (snapshot_mapping, None));
2832 assert!(fault_plan.is_consumed());
2833 }
2834
2835 #[test]
2836 #[cfg(not(gdb))]
2837 fn snapshot_restore_unmapping_failure_is_unrecoverable() {
2838 let path = simple_guest_as_pathbuf();
2839 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2840 .unwrap()
2841 .evolve()
2842 .unwrap();
2843 source.call::<i32>("AddToStatic", 42i32).unwrap();
2844 let snapshot = source.snapshot().unwrap();
2845
2846 let path = simple_guest_as_pathbuf();
2847 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2848 .unwrap()
2849 .evolve()
2850 .unwrap();
2851 let mappings = target.vm.base_mapping_state();
2852 let fault_plan = target
2853 .vm
2854 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Snapshot)]);
2855
2856 let error = target.restore(snapshot).unwrap_err();
2857 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2858 assert_eq!(target.status(), SandboxStatus::Unrecoverable);
2859 assert_eq!(target.vm.base_mapping_state(), mappings);
2860 assert!(fault_plan.is_consumed());
2861 }
2862
2863 #[test]
2864 #[cfg(not(gdb))]
2865 fn snapshot_restore_dynamic_unmapping_failure_is_recoverable() {
2866 let path = simple_guest_as_pathbuf();
2867 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2868 .unwrap()
2869 .evolve()
2870 .unwrap();
2871 source.call::<i32>("AddToStatic", 42i32).unwrap();
2872 let snapshot = source.snapshot().unwrap();
2873
2874 let path = simple_guest_as_pathbuf();
2875 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2876 .unwrap()
2877 .evolve()
2878 .unwrap();
2879 let map_mem = allocate_guest_memory();
2880 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2881 unsafe { target.map_region(®ion).unwrap() };
2882 let fault_plan = target
2883 .vm
2884 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Heap)]);
2885
2886 let error = target.restore(snapshot.clone()).unwrap_err();
2887 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2888 assert!(target.status().is_poisoned());
2889 assert_eq!(target.vm.get_mapped_regions().count(), 1);
2890 assert!(fault_plan.is_consumed());
2891
2892 target.restore(snapshot).unwrap();
2893 assert_eq!(target.status(), SandboxStatus::Ready);
2894 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2895 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2896 }
2897
2898 #[test]
2899 #[cfg(not(gdb))]
2900 fn snapshot_restore_partial_dynamic_unmapping_failure_is_recoverable() {
2901 let path = simple_guest_as_pathbuf();
2902 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2903 .unwrap()
2904 .evolve()
2905 .unwrap();
2906 source.call::<i32>("AddToStatic", 42i32).unwrap();
2907 let snapshot = source.snapshot().unwrap();
2908
2909 let path = simple_guest_as_pathbuf();
2910 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2911 .unwrap()
2912 .evolve()
2913 .unwrap();
2914 let first_mem = allocate_guest_memory();
2915 let first_region =
2916 region_for_memory(&first_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2917 unsafe { target.map_region(&first_region).unwrap() };
2918 let (mapped_path, _) =
2919 create_test_file("hyperlight_test_partial_dynamic_unmapping.bin", &[0; 4096]);
2920 target.map_file_cow(&mapped_path, 0x300000000).unwrap();
2921 let second_region = target.vm.get_mapped_regions().last().unwrap().clone();
2922 let fault_plan = target
2923 .vm
2924 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::MappedFile)]);
2925
2926 let error = target.restore(snapshot.clone()).unwrap_err();
2927 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2928 assert!(target.status().is_poisoned());
2929 assert_eq!(
2930 target.vm.get_mapped_regions().collect::<Vec<_>>(),
2931 vec![&second_region]
2932 );
2933 assert!(fault_plan.is_consumed());
2934
2935 target.restore(snapshot).unwrap();
2936 assert_eq!(target.status(), SandboxStatus::Ready);
2937 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2938 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2939 std::fs::remove_file(mapped_path).unwrap();
2940 }
2941
2942 #[test]
2943 #[cfg(not(gdb))]
2944 fn snapshot_capture_dynamic_unmapping_failure_is_recoverable() {
2945 let path = simple_guest_as_pathbuf();
2946 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2947 .unwrap()
2948 .evolve()
2949 .unwrap();
2950 let recovery_snapshot = sandbox.snapshot().unwrap();
2951 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2952
2953 let map_mem = allocate_guest_memory();
2954 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2955 unsafe { sandbox.map_region(®ion).unwrap() };
2957 let fault_plan = sandbox
2958 .vm
2959 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Heap)]);
2960
2961 let error = sandbox.snapshot().err().unwrap();
2962 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2963 assert!(sandbox.status().is_poisoned());
2964 assert!(fault_plan.is_consumed());
2965
2966 sandbox.restore(recovery_snapshot).unwrap();
2967 assert_eq!(sandbox.status(), SandboxStatus::Ready);
2968 assert_eq!(sandbox.vm.get_mapped_regions().count(), 0);
2969 assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 0);
2970 }
2971
2972 #[test]
2973 #[cfg(not(gdb))]
2974 fn snapshot_restore_vcpu_reset_failure_is_recoverable() {
2975 let path = simple_guest_as_pathbuf();
2976 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2977 .unwrap()
2978 .evolve()
2979 .unwrap();
2980 source.call::<i32>("AddToStatic", 42i32).unwrap();
2981 let snapshot = source.snapshot().unwrap();
2982
2983 #[cfg(target_arch = "x86_64")]
2984 let reset_operations = [
2985 VmOperation::SetRegs,
2986 VmOperation::SetDebugRegs,
2987 VmOperation::ResetXsave,
2988 VmOperation::SetSregs,
2989 ];
2990 #[cfg(target_arch = "aarch64")]
2991 let reset_operations = [VmOperation::ResetVcpu];
2992
2993 for reset_operation in reset_operations {
2994 let path = simple_guest_as_pathbuf();
2995 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2996 .unwrap()
2997 .evolve()
2998 .unwrap();
2999 let fault_plan = target.vm.inject_vm_faults([reset_operation]);
3000
3001 let error = target.restore(snapshot.clone()).unwrap_err();
3002 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
3003 assert!(target.status().is_poisoned());
3004 assert!(fault_plan.is_consumed());
3005 let (snapshot_mappings, scratch_mapping) = target.vm.base_mapping_state();
3006 assert!(!snapshot_mappings.is_empty());
3007 assert_eq!(
3008 scratch_mapping,
3009 Some((
3010 target.mem_mgr.scratch_mem.base_addr(),
3011 target.mem_mgr.scratch_mem.mem_size(),
3012 ))
3013 );
3014
3015 target.restore(snapshot.clone()).unwrap();
3016 assert_eq!(target.status(), SandboxStatus::Ready);
3017 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3018 }
3019 }
3020
3021 #[test]
3022 #[cfg(not(gdb))]
3023 fn snapshot_capture_page_table_switch_failure_is_recoverable() {
3024 let path = simple_guest_as_pathbuf();
3025 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3026 .unwrap()
3027 .evolve()
3028 .unwrap();
3029 let recovery_snapshot = sandbox.snapshot().unwrap();
3030 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
3031
3032 let fault_plan = sandbox.vm.inject_vm_faults([VmOperation::SetSregs]);
3033
3034 let error = sandbox.snapshot().err().unwrap();
3035 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
3036 assert!(sandbox.status().is_poisoned());
3037 assert!(fault_plan.is_consumed());
3038
3039 sandbox.restore(recovery_snapshot).unwrap();
3040 assert_eq!(sandbox.status(), SandboxStatus::Ready);
3041 assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 0);
3042 }
3043
3044 #[test]
3045 #[cfg(not(gdb))]
3046 fn snapshot_capture_does_not_reset_vcpu() {
3047 #[cfg(target_arch = "x86_64")]
3048 let reset_operations = [
3049 VmOperation::SetRegs,
3050 VmOperation::SetDebugRegs,
3051 VmOperation::ResetXsave,
3052 VmOperation::SetMsrs,
3053 ];
3054 #[cfg(target_arch = "aarch64")]
3055 let reset_operations = [VmOperation::ResetVcpu];
3056
3057 for resize in [false, true] {
3058 for reset_operation in reset_operations {
3059 let path = simple_guest_as_pathbuf();
3060 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3061 .unwrap()
3062 .evolve()
3063 .unwrap();
3064 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
3065 sandbox.checkpoint_transport_for_snapshot().unwrap();
3066 let mut options = SnapshotOptions::default();
3067 if resize {
3068 options = scratch(sandbox.mem_mgr.layout.get_scratch_size() * 2);
3069 }
3070 let fault_plan = sandbox.vm.inject_vm_faults([reset_operation]);
3071
3072 sandbox.snapshot_with_options(&options).unwrap();
3073
3074 assert!(!fault_plan.is_consumed());
3075 assert_eq!(sandbox.status(), SandboxStatus::Ready);
3076 }
3077 }
3078 }
3079
3080 #[test]
3081 fn snapshot_capture_reclaims_internal_scratch_pages() {
3082 let path = simple_guest_as_pathbuf();
3083 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3084 .unwrap()
3085 .evolve()
3086 .unwrap();
3087 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
3088
3089 sandbox.snapshot().unwrap();
3090
3091 let allocator_offset = sandbox.mem_mgr.scratch_mem.mem_size()
3092 - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
3093 assert_eq!(
3094 sandbox
3095 .mem_mgr
3096 .scratch_mem
3097 .read::<u64>(allocator_offset)
3098 .unwrap(),
3099 sandbox.mem_mgr.first_free_scratch_gpa()
3100 );
3101 }
3102
3103 #[test]
3104 fn snapshot_capture_zeroes_reclaimed_scratch() {
3105 let path = simple_guest_as_pathbuf();
3106 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3107 .unwrap()
3108 .evolve()
3109 .unwrap();
3110 let page_gva = 0x4000_0000_u64;
3111 let page_size = hyperlight_common::vmem::PAGE_SIZE;
3112 assert!(sandbox.call::<bool>("MapZeroInitPage", page_gva).unwrap());
3113 let allocator_offset = sandbox.mem_mgr.scratch_mem.mem_size()
3114 - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
3115 let used_end = sandbox
3116 .mem_mgr
3117 .scratch_mem
3118 .read::<u64>(allocator_offset)
3119 .unwrap();
3120 let before = sandbox
3121 .mem_mgr
3122 .scratch_mem
3123 .with_contents(|scratch| scratch.to_vec())
3124 .unwrap();
3125 sandbox.snapshot().unwrap();
3126
3127 let scratch_base =
3128 hyperlight_common::layout::scratch_base_gpa(sandbox.mem_mgr.scratch_mem.mem_size());
3129 let free_start =
3130 usize::try_from(sandbox.mem_mgr.first_free_scratch_gpa() - scratch_base).unwrap();
3131 let free_end = usize::try_from(used_end - scratch_base).unwrap();
3132 let after = sandbox
3133 .mem_mgr
3134 .scratch_mem
3135 .with_contents(|scratch| scratch.to_vec())
3136 .unwrap();
3137 assert!(before[free_start..free_end].iter().any(|&byte| byte != 0));
3138 assert!(after[free_start..free_end].iter().all(|&byte| byte == 0));
3139
3140 let page = sandbox
3141 .call::<Vec<u8>>("ReadMappedBuffer", (page_gva, page_size as u64, false))
3142 .unwrap();
3143 assert_eq!(page, vec![0; page_size]);
3144 }
3145
3146 #[test]
3149 fn snapshot_capture_clamps_guest_allocator_value() {
3150 use hyperlight_common::layout::{
3151 SCRATCH_TOP_ALLOCATOR_OFFSET, SCRATCH_TOP_SIZE_OFFSET, scratch_base_gpa,
3152 };
3153
3154 for allocator in [0, u64::MAX] {
3155 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3156 .build()
3157 .unwrap();
3158 sbox.snapshot().unwrap();
3159 let scratch_size = sbox.mem_mgr.scratch_mem.mem_size();
3160 let first_free = sbox.mem_mgr.first_free_scratch_gpa();
3161 let marker_offset =
3162 usize::try_from(first_free - scratch_base_gpa(scratch_size)).unwrap();
3163 let marker = 0x1234_5678_9abc_def0_u64;
3164 let scratch = &sbox.mem_mgr.scratch_mem;
3165 scratch.write(marker_offset, marker).unwrap();
3166 scratch
3167 .write(
3168 scratch_size - SCRATCH_TOP_ALLOCATOR_OFFSET as usize,
3169 allocator,
3170 )
3171 .unwrap();
3172 let arena = sbox.mem_mgr.layout.get_transport_arena().base_addr();
3175 let allocated = if allocator == 0 {
3176 0
3177 } else {
3178 arena - first_free
3179 };
3180 assert_eq!(sbox.scratch_allocated_bytes().unwrap(), allocated);
3181
3182 let map_mem = allocate_guest_memory();
3184 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
3185 unsafe { sbox.map_region(®ion).unwrap() };
3187 sbox.snapshot().unwrap();
3188
3189 let scratch = &sbox.mem_mgr.scratch_mem;
3190 assert_eq!(sbox.mem_mgr.first_free_scratch_gpa(), first_free);
3191 let expected = if allocator == 0 { marker } else { 0 };
3192 assert_eq!(scratch.read::<u64>(marker_offset).unwrap(), expected);
3193 assert_eq!(
3194 scratch
3195 .read::<u64>(scratch_size - SCRATCH_TOP_SIZE_OFFSET as usize)
3196 .unwrap(),
3197 scratch_size as u64
3198 );
3199 assert_eq!(
3200 sbox.call::<String>("Echo", "hello\n".to_string()).unwrap(),
3201 "hello\n"
3202 );
3203 }
3204 }
3205
3206 #[test]
3207 #[cfg(all(target_arch = "x86_64", not(gdb)))]
3208 fn snapshot_restore_msr_failure_is_recoverable() {
3209 let path = simple_guest_as_pathbuf();
3210 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3211 .unwrap()
3212 .evolve()
3213 .unwrap();
3214 source.call::<i32>("AddToStatic", 42i32).unwrap();
3215 let snapshot = source.snapshot().unwrap();
3216
3217 let path = simple_guest_as_pathbuf();
3218 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3219 .unwrap()
3220 .evolve()
3221 .unwrap();
3222 let fault_plan = target.vm.inject_vm_faults([VmOperation::SetMsrs]);
3223
3224 let error = target.restore(snapshot.clone()).unwrap_err();
3225 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
3226 assert!(target.status().is_poisoned());
3227 assert!(fault_plan.is_consumed());
3228 let (snapshot_mappings, scratch_mapping) = target.vm.base_mapping_state();
3229 assert!(!snapshot_mappings.is_empty());
3230 assert_eq!(
3231 scratch_mapping,
3232 Some((
3233 target.mem_mgr.scratch_mem.base_addr(),
3234 target.mem_mgr.scratch_mem.mem_size(),
3235 ))
3236 );
3237
3238 target.restore(snapshot).unwrap();
3239 assert_eq!(target.status(), SandboxStatus::Ready);
3240 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3241 }
3242
3243 #[test]
3244 fn snapshot_restore_accepts_different_configured_layout() {
3245 type Configure = fn(&mut SandboxConfiguration);
3246 type LayoutValue = fn(&crate::mem::layout::SandboxMemoryLayout) -> usize;
3247 let cases: &[(&str, Configure, LayoutValue)] = &[
3248 (
3249 "G2H queue size",
3250 |cfg| cfg.set_g2h_queue_size(128),
3251 |layout| layout.get_g2h_queue_size(),
3252 ),
3253 (
3254 "H2G queue size",
3255 |cfg| cfg.set_h2g_queue_size(64),
3256 |layout| layout.get_h2g_queue_size(),
3257 ),
3258 (
3259 "G2H buffer size",
3260 |cfg| cfg.set_g2h_buffer_size(0x2000),
3261 |layout| layout.get_g2h_buffer_size(),
3262 ),
3263 (
3264 "H2G buffer size",
3265 |cfg| cfg.set_h2g_buffer_size(0x2000),
3266 |layout| layout.get_h2g_buffer_size(),
3267 ),
3268 (
3269 "G2H pool pages",
3270 |cfg| cfg.set_g2h_pool_pages(16),
3271 |layout| layout.get_g2h_pool_pages(),
3272 ),
3273 (
3274 "H2G pool pages",
3275 |cfg| cfg.set_h2g_pool_pages(16),
3276 |layout| layout.get_h2g_pool_pages(),
3277 ),
3278 (
3279 "scratch",
3280 |cfg| cfg.set_scratch_size(0x90_000),
3281 |layout| layout.get_scratch_size(),
3282 ),
3283 ];
3284
3285 for (name, configure, layout_value) in cases {
3286 for incoming_is_larger in [true, false] {
3287 let mut custom_cfg = SandboxConfiguration::default();
3288 configure(&mut custom_cfg);
3289 let (source_cfg, target_cfg) = if incoming_is_larger {
3290 (custom_cfg, SandboxConfiguration::default())
3291 } else {
3292 (SandboxConfiguration::default(), custom_cfg)
3293 };
3294
3295 let path = simple_guest_as_pathbuf();
3296 let mut source =
3297 UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3298 .unwrap()
3299 .evolve()
3300 .unwrap();
3301
3302 let path = simple_guest_as_pathbuf();
3303 let mut target =
3304 UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
3305 .unwrap()
3306 .evolve()
3307 .unwrap();
3308
3309 let source_value = layout_value(&source.mem_mgr.layout);
3310 assert_ne!(source_value, layout_value(&target.mem_mgr.layout));
3311
3312 source.call::<i32>("AddToStatic", 42i32).unwrap();
3313 target
3314 .restore(source.snapshot().unwrap())
3315 .unwrap_or_else(|err| panic!("restore with different {name} layout: {err}"));
3316 assert_eq!(layout_value(&target.mem_mgr.layout), source_value);
3317 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3318 }
3319 }
3320 }
3321
3322 #[test]
3323 fn snapshot_restore_recovers_oom_with_larger_scratch() {
3324 let mut source_cfg = SandboxConfiguration::default();
3325 source_cfg.set_scratch_size(0x200_000);
3326 let path = simple_guest_as_pathbuf();
3327 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3328 .unwrap()
3329 .evolve()
3330 .unwrap();
3331 let snapshot = source.snapshot().unwrap();
3332
3333 let path = simple_guest_as_pathbuf();
3334 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3335 .unwrap()
3336 .evolve()
3337 .unwrap();
3338
3339 assert!(target.call::<()>("ExhaustHeap", ()).is_err());
3340 assert!(target.status().is_poisoned());
3341
3342 target.restore(snapshot).unwrap();
3343 assert!(!target.status().is_poisoned());
3344 target
3345 .call::<()>("AllocAndWritePattern", 0x100_000u64)
3346 .unwrap();
3347 }
3348
3349 #[test]
3350 fn snapshot_restore_applies_smaller_scratch_limit() {
3351 let path = simple_guest_as_pathbuf();
3352 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3353 .unwrap()
3354 .evolve()
3355 .unwrap();
3356 let snapshot = source.snapshot().unwrap();
3357
3358 let mut target_cfg = SandboxConfiguration::default();
3359 target_cfg.set_scratch_size(0x200_000);
3360 let path = simple_guest_as_pathbuf();
3361 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
3362 .unwrap()
3363 .evolve()
3364 .unwrap();
3365
3366 target
3367 .call::<()>("AllocAndWritePattern", 0x100_000u64)
3368 .unwrap();
3369 target.restore(snapshot).unwrap();
3370 assert_eq!(
3371 target.mem_mgr.layout.get_scratch_size(),
3372 SandboxConfiguration::DEFAULT_SCRATCH_SIZE
3373 );
3374 assert!(
3375 target
3376 .call::<()>("AllocAndWritePattern", 0x100_000u64)
3377 .is_err()
3378 );
3379 assert!(target.status().is_poisoned());
3380 }
3381
3382 #[test]
3383 fn snapshot_restore_applies_smaller_h2g_capacity() {
3384 let mut source_cfg = SandboxConfiguration::default();
3385 source_cfg.set_scratch_size(1024 * 1024);
3386 source_cfg.set_h2g_pool_pages(4);
3387 let path = simple_guest_as_pathbuf();
3388 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3389 .unwrap()
3390 .evolve()
3391 .unwrap();
3392 let snapshot = source.snapshot().unwrap();
3393 let mut target_cfg = SandboxConfiguration::default();
3394 target_cfg.set_scratch_size(1024 * 1024);
3395 target_cfg.set_h2g_pool_pages(8);
3396 let path = simple_guest_as_pathbuf();
3397 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
3398 .unwrap()
3399 .evolve()
3400 .unwrap();
3401 let large = "x".repeat(4 * hyperlight_common::vmem::PAGE_SIZE);
3402
3403 assert_eq!(target.call::<String>("Echo", large.clone()).unwrap(), large);
3404 target.restore(snapshot).unwrap();
3405 assert_eq!(target.mem_mgr.layout.get_h2g_pool_pages(), 4);
3406 let error = target.call::<String>("Echo", large).unwrap_err();
3407 assert!(error.to_string().contains("H2G capacity"));
3408 assert!(!target.status().is_poisoned());
3409 assert_eq!(
3410 target.call::<String>("Echo", "small".to_string()).unwrap(),
3411 "small"
3412 );
3413 }
3414
3415 #[test]
3416 fn snapshot_restore_alternates_different_layouts() {
3417 let mut small_cfg = SandboxConfiguration::default();
3418 small_cfg.set_scratch_size(0x70_000);
3419 let path = simple_guest_as_pathbuf();
3420 let mut small = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(small_cfg))
3421 .unwrap()
3422 .evolve()
3423 .unwrap();
3424 small.call::<i32>("AddToStatic", 11i32).unwrap();
3425 let small_snapshot = small.snapshot().unwrap();
3426
3427 let mut large_cfg = SandboxConfiguration::default();
3428 large_cfg.set_scratch_size(0x90_000);
3429 let path = simple_guest_as_pathbuf();
3430 let mut large = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(large_cfg))
3431 .unwrap()
3432 .evolve()
3433 .unwrap();
3434 large.call::<i32>("AddToStatic", 22i32).unwrap();
3435 let large_snapshot = large.snapshot().unwrap();
3436
3437 let path = simple_guest_as_pathbuf();
3438 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3439 .unwrap()
3440 .evolve()
3441 .unwrap();
3442
3443 target.restore(small_snapshot.clone()).unwrap();
3444 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
3445 assert_eq!(target.mem_mgr.layout.get_scratch_size(), 0x70_000);
3446
3447 target.restore(large_snapshot).unwrap();
3448 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 22);
3449 assert_eq!(target.mem_mgr.layout.get_scratch_size(), 0x90_000);
3450
3451 target.restore(small_snapshot).unwrap();
3452 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
3453 assert_eq!(target.mem_mgr.layout.get_scratch_size(), 0x70_000);
3454 }
3455
3456 #[test]
3457 fn snapshot_restore_replaces_rust_guest_with_c_guest() {
3458 let init_data = b"cross-layout-init-data";
3459 let source_env = GuestEnvironment {
3460 guest_binary: GuestBinary::FilePath(c_simple_guest_as_pathbuf()),
3461 init_data: Some(GuestBlob {
3462 data: init_data,
3463 permissions: MemoryRegionFlags::READ | MemoryRegionFlags::WRITE,
3464 }),
3465 };
3466 let mut source = UninitializedSandbox::new(source_env, None)
3467 .unwrap()
3468 .evolve()
3469 .unwrap();
3470 let mut target =
3471 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3472 .unwrap()
3473 .evolve()
3474 .unwrap();
3475
3476 assert_eq!(source.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3477 assert_eq!(target.call::<i32>("AddToStatic", 17i32).unwrap(), 17);
3478 target.set_pt_root_finder(Box::new(|_, _, root| Ok(vec![root])));
3479 assert!(target.pt_root_finder.is_some());
3480
3481 assert_ne!(
3482 source.mem_mgr.layout.code_size(),
3483 target.mem_mgr.layout.code_size()
3484 );
3485 assert_ne!(
3486 source.mem_mgr.layout.init_data_size(),
3487 target.mem_mgr.layout.init_data_size()
3488 );
3489 assert_ne!(
3490 source.mem_mgr.layout.init_data_permissions(),
3491 target.mem_mgr.layout.init_data_permissions()
3492 );
3493
3494 let snapshot = source.snapshot().unwrap();
3495 target.restore(snapshot).unwrap();
3496 assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
3497 assert!(matches!(
3498 target.call::<i32>("GetStatic", ()),
3499 Err(HyperlightError::GuestError(
3500 ErrorCode::GuestFunctionNotFound,
3501 name
3502 )) if name == "GetStatic"
3503 ));
3504 }
3505
3506 #[test]
3507 fn active_page_table_root_is_first() {
3508 const ACTIVE: u64 = 0x1000;
3509 const OTHER: u64 = 0x2000;
3510
3511 assert_eq!(
3512 normalize_page_table_roots(vec![OTHER, ACTIVE, ACTIVE], ACTIVE),
3513 vec![ACTIVE, OTHER]
3514 );
3515 assert_eq!(
3516 normalize_page_table_roots(vec![OTHER, OTHER], ACTIVE),
3517 vec![ACTIVE, OTHER]
3518 );
3519 assert_eq!(
3520 normalize_page_table_roots(vec![OTHER], ACTIVE),
3521 vec![ACTIVE, OTHER]
3522 );
3523 assert_eq!(normalize_page_table_roots(Vec::new(), ACTIVE), vec![ACTIVE]);
3524 }
3525
3526 #[test]
3527 fn page_table_root_finder_reads_snapshot_memory() {
3528 use std::sync::atomic::{AtomicBool, Ordering};
3529
3530 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3531 .build()
3532 .unwrap();
3533 let base = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
3534 let mut expected = [0; 16];
3535 sandbox
3536 .mem_mgr
3537 .shared_mem
3538 .read_snapshot_gpa(base, &mut expected)
3539 .unwrap();
3540 let invoked = Arc::new(AtomicBool::new(false));
3541 let callback_invoked = invoked.clone();
3542 sandbox.set_pt_root_finder(Box::new(move |snapshot, _, root| {
3543 let mut bytes = [0; 16];
3544 snapshot.read_exact(base, &mut bytes)?;
3545 assert_eq!(bytes, expected);
3546 callback_invoked.store(true, Ordering::Relaxed);
3547 Ok(vec![root])
3548 }));
3549
3550 sandbox.snapshot().unwrap();
3551 assert!(invoked.load(Ordering::Relaxed));
3552 }
3553
3554 #[test]
3555 fn page_table_root_finder_error_aborts_snapshot() {
3556 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3557 .build()
3558 .unwrap();
3559 sandbox.set_pt_root_finder(Box::new(|_, _, _| {
3560 Err(crate::new_error!("failed to discover page-table roots"))
3561 }));
3562
3563 let error = sandbox.snapshot().err().unwrap();
3564
3565 assert!(
3566 error
3567 .to_string()
3568 .contains("failed to discover page-table roots")
3569 );
3570 assert_eq!(sandbox.status(), SandboxStatus::Ready);
3571 assert!(sandbox.snapshot.is_none());
3572 }
3573
3574 #[test]
3575 fn snapshot_restore_replaces_c_guest_with_rust_guest() {
3576 let mut source =
3577 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3578 .unwrap()
3579 .evolve()
3580 .unwrap();
3581 assert_eq!(source.call::<i32>("AddToStatic", 42i32).unwrap(), 42);
3582 let snapshot = source.snapshot().unwrap();
3583
3584 let mut target =
3585 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3586 .unwrap()
3587 .evolve()
3588 .unwrap();
3589 assert_eq!(target.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3590
3591 target.restore(snapshot).unwrap();
3592 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3593 assert!(matches!(
3594 target.call::<i32>("StackAllocate", 512i32),
3595 Err(HyperlightError::GuestError(
3596 ErrorCode::GuestFunctionNotFound,
3597 name
3598 )) if name == "StackAllocate"
3599 ));
3600 }
3601
3602 #[test]
3603 fn snapshot_restore_alternates_c_and_rust_guests() {
3604 let mut c_source =
3605 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3606 .unwrap()
3607 .evolve()
3608 .unwrap();
3609 assert_eq!(c_source.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3610 let c_snapshot = c_source.snapshot().unwrap();
3611
3612 let mut rust_source =
3613 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3614 .unwrap()
3615 .evolve()
3616 .unwrap();
3617 rust_source.call::<i32>("AddToStatic", 42i32).unwrap();
3618 let rust_snapshot = rust_source.snapshot().unwrap();
3619
3620 let mut target =
3621 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3622 .unwrap()
3623 .evolve()
3624 .unwrap();
3625 assert_eq!(target.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
3626
3627 target.restore(rust_snapshot).unwrap();
3628 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
3629 assert!(matches!(
3630 target.call::<i32>("StackAllocate", 512i32),
3631 Err(HyperlightError::GuestError(
3632 ErrorCode::GuestFunctionNotFound,
3633 name
3634 )) if name == "StackAllocate"
3635 ));
3636
3637 target.restore(c_snapshot).unwrap();
3638 assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
3639 assert!(matches!(
3640 target.call::<i32>("GetStatic", ()),
3641 Err(HyperlightError::GuestError(
3642 ErrorCode::GuestFunctionNotFound,
3643 name
3644 )) if name == "GetStatic"
3645 ));
3646 }
3647
3648 #[test]
3649 fn snapshot_restore_keeps_target_host_function_implementation() {
3650 let path = simple_guest_as_pathbuf();
3651 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3652 source
3653 .register_host_function("Echo42", || Ok(1i64))
3654 .unwrap();
3655 let mut source = source.evolve().unwrap();
3656 let snapshot = source.snapshot().unwrap();
3657
3658 let path = simple_guest_as_pathbuf();
3659 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3660 target
3661 .register_host_function("Echo42", || Ok(42i64))
3662 .unwrap();
3663 let mut target = target.evolve().unwrap();
3664
3665 target.restore(snapshot).unwrap();
3666 assert_eq!(
3667 target
3668 .call::<i64>(
3669 "CallGivenParamlessHostFuncThatReturnsI64",
3670 "Echo42".to_string(),
3671 )
3672 .unwrap(),
3673 42
3674 );
3675 }
3676
3677 #[test]
3678 fn snapshot_restore_recovers_poison_with_different_guest() {
3679 let mut source =
3680 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
3681 .unwrap()
3682 .evolve()
3683 .unwrap();
3684 let snapshot = source.snapshot().unwrap();
3685
3686 let path = simple_guest_as_pathbuf();
3687 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3688 .unwrap()
3689 .evolve()
3690 .unwrap();
3691 assert!(target.call::<()>("ExhaustHeap", ()).is_err());
3692 assert!(target.status().is_poisoned());
3693
3694 target.restore(snapshot).unwrap();
3695 assert!(!target.status().is_poisoned());
3696 assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
3697 assert!(matches!(
3698 target.call::<i32>("GetStatic", ()),
3699 Err(HyperlightError::GuestError(
3700 ErrorCode::GuestFunctionNotFound,
3701 name
3702 )) if name == "GetStatic"
3703 ));
3704 }
3705
3706 #[test]
3709 fn snapshot_restore_failure_leaves_target_usable() {
3710 let path = simple_guest_as_pathbuf();
3711 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3712 source
3713 .register_host_function("Add", |a: i32, b: i32| Ok(a + b))
3714 .unwrap();
3715 let mut source = source.evolve().unwrap();
3716
3717 let map_mem = allocate_guest_memory();
3718 let path = simple_guest_as_pathbuf();
3719 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3720 .unwrap()
3721 .evolve()
3722 .unwrap();
3723
3724 target.call::<i32>("AddToStatic", 5i32).unwrap();
3725 let guest_base = 0x200000000_usize;
3726 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3727 unsafe { target.map_region(®ion).unwrap() };
3729 target
3730 .call::<Vec<u8>>(
3731 "ReadMappedBuffer",
3732 (
3733 guest_base as u64,
3734 hyperlight_common::vmem::PAGE_SIZE as u64,
3735 true,
3736 ),
3737 )
3738 .unwrap();
3739 let cached_snapshot = target.snapshot().unwrap();
3740 let bad_snapshot = source.snapshot().unwrap();
3741 let err = target.restore(bad_snapshot);
3742 assert!(matches!(
3743 err,
3744 Err(HyperlightError::SnapshotHostFunctionMismatch { missing, .. })
3745 if missing.iter().any(|name| name == "Add")
3746 ));
3747
3748 assert!(Arc::ptr_eq(&target.snapshot().unwrap(), &cached_snapshot));
3749 assert_eq!(target.vm.get_mapped_regions().count(), 0);
3750 assert!(
3751 target
3752 .call::<bool>("CheckMapped", guest_base as u64)
3753 .unwrap()
3754 );
3755 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 5);
3756 target.call::<i32>("AddToStatic", 3i32).unwrap();
3757 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 8);
3758
3759 let good_snapshot = target.snapshot().unwrap();
3760 target.call::<i32>("AddToStatic", 100i32).unwrap();
3761 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 108);
3762 target.restore(good_snapshot).unwrap();
3763 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 8);
3764 }
3765
3766 #[test]
3769 fn snapshot_restore_across_sandboxes_target_has_mapped_regions() {
3770 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3771 .build()
3772 .unwrap();
3773 source.call::<i32>("AddToStatic", 23i32).unwrap();
3774 let snapshot = source.snapshot().unwrap();
3775
3776 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3777 .build()
3778 .unwrap();
3779 let map_mem = allocate_guest_memory();
3780 let guest_base = 0x200000000_usize;
3781 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3782 unsafe { target.map_region(®ion).unwrap() };
3783 assert_eq!(target.vm.get_mapped_regions().count(), 1);
3784
3785 target.restore(snapshot).unwrap();
3786 assert_eq!(target.vm.get_mapped_regions().count(), 0);
3787 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
3788 }
3789
3790 #[test]
3791 fn snapshot_restore_unmaps_regions_overlapping_incoming_layout() {
3792 let mut source_cfg = SandboxConfiguration::default();
3793 source_cfg.set_scratch_size(0x90_000);
3794 let path = simple_guest_as_pathbuf();
3795 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3796 .unwrap()
3797 .evolve()
3798 .unwrap();
3799 source.call::<i32>("AddToStatic", 23i32).unwrap();
3800 let snapshot = source.snapshot().unwrap();
3801
3802 let path = simple_guest_as_pathbuf();
3803 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3804 .unwrap()
3805 .evolve()
3806 .unwrap();
3807 assert!(
3808 snapshot.snapshot_memory().gpa_span_len() > target.mem_mgr.shared_mem.gpa_span_len()
3809 );
3810
3811 let map_mem = allocate_guest_memory();
3812 let guest_base = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS
3813 + target.mem_mgr.shared_mem.gpa_span_len();
3814 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3815 unsafe { target.map_region(®ion).unwrap() };
3817
3818 target.restore(snapshot).unwrap();
3819 assert_eq!(target.vm.get_mapped_regions().count(), 0);
3820 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
3821 }
3822
3823 #[test]
3824 fn snapshot_restore_unmaps_region_overlapping_incoming_scratch() {
3825 let incoming_scratch_size = 0x90_000;
3826 let mut source_cfg = SandboxConfiguration::default();
3827 source_cfg.set_scratch_size(incoming_scratch_size);
3828 let path = simple_guest_as_pathbuf();
3829 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
3830 .unwrap()
3831 .evolve()
3832 .unwrap();
3833 source.call::<i32>("AddToStatic", 23i32).unwrap();
3834 let snapshot = source.snapshot().unwrap();
3835
3836 let path = simple_guest_as_pathbuf();
3837 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
3838 .unwrap()
3839 .evolve()
3840 .unwrap();
3841 let guest_base =
3842 hyperlight_common::layout::scratch_base_gpa(incoming_scratch_size) as usize;
3843 let target_scratch_base =
3844 hyperlight_common::layout::scratch_base_gpa(SandboxConfiguration::DEFAULT_SCRATCH_SIZE)
3845 as usize;
3846 let map_mem = allocate_guest_memory();
3847 assert!(guest_base + map_mem.mem_size() <= target_scratch_base);
3848 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
3849 unsafe { target.map_region(®ion).unwrap() };
3851
3852 target.restore(snapshot).unwrap();
3853 assert_eq!(target.vm.get_mapped_regions().count(), 0);
3854 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
3855 }
3856
3857 #[test]
3861 fn snapshot_restore_across_sandboxes_both_have_different_mapped_regions() {
3862 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3863 .build()
3864 .unwrap();
3865 let source_mem = allocate_guest_memory();
3866 let source_base = 0x200000000_usize;
3867 let source_region = region_for_memory(&source_mem, source_base, MemoryRegionFlags::READ);
3868 unsafe { source.map_region(&source_region).unwrap() };
3869 let orig_read = source
3870 .call::<Vec<u8>>(
3871 "ReadMappedBuffer",
3872 (
3873 source_base as u64,
3874 hyperlight_common::vmem::PAGE_SIZE as u64,
3875 true,
3876 ),
3877 )
3878 .unwrap();
3879 source.call::<i32>("AddToStatic", 9i32).unwrap();
3880 let snapshot = source.snapshot().unwrap();
3881
3882 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3883 .build()
3884 .unwrap();
3885 let target_mem = allocate_guest_memory();
3886 let target_base = 0x300000000_usize;
3887 let target_region = region_for_memory(&target_mem, target_base, MemoryRegionFlags::READ);
3888 unsafe { target.map_region(&target_region).unwrap() };
3889 assert_eq!(target.vm.get_mapped_regions().count(), 1);
3890
3891 target.restore(snapshot).unwrap();
3892
3893 assert_eq!(target.vm.get_mapped_regions().count(), 0);
3894 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 9);
3895
3896 let new_read = target
3897 .call::<Vec<u8>>(
3898 "ReadMappedBuffer",
3899 (
3900 source_base as u64,
3901 hyperlight_common::vmem::PAGE_SIZE as u64,
3902 false,
3903 ),
3904 )
3905 .unwrap();
3906 assert_eq!(new_read, orig_read);
3907 }
3908
3909 #[test]
3911 fn snapshot_restore_across_sandboxes_repeated() {
3912 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3913 .build()
3914 .unwrap();
3915 source.call::<i32>("AddToStatic", 7i32).unwrap();
3916 let snapshot = source.snapshot().unwrap();
3917
3918 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3919 .build()
3920 .unwrap();
3921
3922 target.restore(snapshot.clone()).unwrap();
3923 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 7);
3924
3925 target.call::<i32>("AddToStatic", 1000i32).unwrap();
3926 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 1007);
3927
3928 target.restore(snapshot).unwrap();
3929 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 7);
3930 }
3931
3932 #[test]
3935 fn snapshot_restore_resets_debug_registers() {
3936 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3937 .build()
3938 .unwrap();
3939
3940 let snapshot = sandbox.snapshot().unwrap();
3941
3942 let dr0_initial: u64 = sandbox.call("GetDr0", ()).unwrap();
3944 assert_eq!(dr0_initial, 0, "DR0 should initially be 0");
3945
3946 const DIRTY_VALUE: u64 = 0xFFFF_FEDC_7654_3210;
3949 sandbox.call::<()>("SetDr0", DIRTY_VALUE).unwrap();
3950
3951 #[cfg(not(hvf))]
3953 {
3954 let dr0_dirty: u64 = sandbox.call("GetDr0", ()).unwrap();
3966 assert_eq!(
3967 dr0_dirty, DIRTY_VALUE,
3968 "DR0 should be dirty after SetDr0 call"
3969 );
3970 }
3971
3972 sandbox.restore(snapshot).unwrap();
3974
3975 let dr0_after_restore: u64 = sandbox.call("GetDr0", ()).unwrap();
3976 assert_eq!(
3977 dr0_after_restore, 0,
3978 "DR0 should be 0 after restore (reset_vcpu should have been called)"
3979 );
3980 }
3981
3982 #[test]
3983 #[cfg(target_arch = "x86_64")]
3984 fn snapshot_restore_resets_xcr0() {
3985 let mut sandbox: Sandbox = {
3986 let path = simple_guest_as_pathbuf();
3987 let u_sbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3988 u_sbox.evolve().unwrap()
3989 };
3990
3991 assert_eq!(sandbox.call::<u64>("ReadXcr0", ()).unwrap(), 1);
3992 let snapshot = sandbox.snapshot().unwrap();
3993
3994 sandbox.call::<()>("WriteXcr0", 3u64).unwrap();
3995 assert_eq!(sandbox.call::<u64>("ReadXcr0", ()).unwrap(), 3);
3996
3997 sandbox.restore(snapshot).unwrap();
3998
3999 assert_eq!(
4000 sandbox.call::<u64>("ReadXcr0", ()).unwrap(),
4001 1,
4002 "restore must reset XCR0"
4003 );
4004 }
4005
4006 #[test]
4009 fn stale_abort_buffer_does_not_leak_across_calls() {
4010 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4011 .build()
4012 .unwrap();
4013
4014 sbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 1020]);
4016
4017 let res = sbox.call::<String>("Echo", "hello".to_string());
4018 assert!(
4019 res.is_ok(),
4020 "Expected Ok after stale abort buffer, got: {:?}",
4021 res.unwrap_err()
4022 );
4023
4024 assert!(
4026 sbox.mem_mgr.abort_buffer.is_empty(),
4027 "abort_buffer should be empty after a guest call"
4028 );
4029 }
4030
4031 #[test]
4032 fn test_sandbox_creation_various_sizes() {
4033 let test_cases: [(&str, usize); 3] = [
4034 ("small (8MiB scratch)", SMALL_SCRATCH_SIZE),
4035 ("medium (64MiB scratch)", MEDIUM_SCRATCH_SIZE),
4036 ("large (256MiB scratch)", LARGE_SCRATCH_SIZE),
4037 ];
4038
4039 for (name, scratch_size) in test_cases {
4040 let path = simple_guest_as_pathbuf();
4041 let sbox = SandboxBuilder::from_file(path)
4042 .scratch_size(scratch_size)
4043 .build()
4044 .unwrap_or_else(|e| panic!("Failed to create {} sandbox: {}", name, e));
4045
4046 drop(sbox);
4047 }
4048 }
4049
4050 #[cfg(feature = "trace_guest")]
4052 fn sandbox_for_gva_tests() -> Sandbox {
4053 let path = simple_guest_as_pathbuf();
4054 SandboxBuilder::from_file(path).build().unwrap()
4055 }
4056
4057 #[cfg(feature = "trace_guest")]
4061 fn assert_gva_read_matches(sbox: &mut Sandbox, gva: u64, len: usize) {
4062 let expected: Vec<u8> = sbox
4064 .call("ReadMappedBuffer", (gva, len as u64, true))
4065 .unwrap();
4066 assert_eq!(expected.len(), len);
4067
4068 let root_pt = sbox.vm.get_root_pt().unwrap();
4070 let actual = sbox
4071 .mem_mgr
4072 .read_guest_memory_by_gva(gva, len, root_pt)
4073 .unwrap();
4074
4075 assert_eq!(
4076 actual, expected,
4077 "read_guest_memory_by_gva at GVA {:#x} (len {}) differs from guest ReadMappedBuffer",
4078 gva, len,
4079 );
4080 }
4081
4082 #[test]
4085 #[cfg(feature = "trace_guest")]
4086 fn read_guest_memory_by_gva_single_page() {
4087 let mut sbox = sandbox_for_gva_tests();
4088 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4089 assert_gva_read_matches(&mut sbox, code_gva, 128);
4090 }
4091
4092 #[test]
4095 #[cfg(feature = "trace_guest")]
4096 fn read_guest_memory_by_gva_full_page() {
4097 let mut sbox = sandbox_for_gva_tests();
4098 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4099 assert_gva_read_matches(&mut sbox, code_gva, 4096);
4100 }
4101
4102 #[test]
4105 #[cfg(feature = "trace_guest")]
4106 fn read_guest_memory_by_gva_unaligned_cross_page() {
4107 let mut sbox = sandbox_for_gva_tests();
4108 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4109 let start = code_gva + 4096 - 1;
4112 println!(
4113 "Testing unaligned cross-page read starting at {:#x} spanning 4097 bytes",
4114 start
4115 );
4116 assert_gva_read_matches(&mut sbox, start, 4097);
4117 }
4118
4119 #[test]
4121 #[cfg(feature = "trace_guest")]
4122 fn read_guest_memory_by_gva_two_full_pages() {
4123 let mut sbox = sandbox_for_gva_tests();
4124 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4125 assert_gva_read_matches(&mut sbox, code_gva, 4096 * 2);
4126 }
4127
4128 #[test]
4132 #[cfg(feature = "trace_guest")]
4133 fn read_guest_memory_by_gva_cross_page_boundary() {
4134 let mut sbox = sandbox_for_gva_tests();
4135 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
4136 let start = code_gva + 4096 - 100;
4138 assert_gva_read_matches(&mut sbox, start, 200);
4139 }
4140
4141 fn create_test_file(name: &str, content: &[u8]) -> (std::path::PathBuf, Vec<u8>) {
4145 use std::io::Write;
4146
4147 let page_size = page_size::get();
4148 let padded_len = content.len().max(page_size).div_ceil(page_size) * page_size + page_size;
4149 let mut padded = vec![0u8; padded_len];
4150 padded[..content.len()].copy_from_slice(content);
4151
4152 let temp_dir = std::env::temp_dir();
4153 let path = temp_dir.join(name);
4154 let _ = std::fs::remove_file(&path); let mut f = std::fs::File::create(&path).unwrap();
4156 f.write_all(&padded).unwrap();
4157 (path, content.to_vec())
4158 }
4159
4160 #[test]
4163 fn test_map_file_cow_basic() {
4164 let expected = b"hello world from map_file_cow";
4165 let (path, expected_bytes) =
4166 create_test_file("hyperlight_test_map_file_cow_basic.bin", expected);
4167
4168 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4169 .build()
4170 .unwrap();
4171
4172 let guest_base: u64 = 0x1_0000_0000;
4173 let mapped_size = sbox.map_file_cow(&path, guest_base).unwrap();
4174 assert!(mapped_size > 0, "mapped_size should be positive");
4175 assert!(
4176 mapped_size >= expected.len() as u64,
4177 "mapped_size should be >= file content length"
4178 );
4179
4180 let actual: Vec<u8> = sbox
4182 .call(
4183 "ReadMappedBuffer",
4184 (guest_base, expected_bytes.len() as u64, true),
4185 )
4186 .unwrap();
4187
4188 assert_eq!(
4189 actual, expected_bytes,
4190 "Guest should read back the exact file content"
4191 );
4192
4193 let _ = std::fs::remove_file(&path);
4195 }
4196
4197 #[test]
4200 fn test_map_file_cow_read_only_enforcement() {
4201 let content = &[0xBB; 4096];
4202 let (path, _) = create_test_file("hyperlight_test_map_file_cow_readonly.bin", content);
4203
4204 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4205 .build()
4206 .unwrap();
4207
4208 let guest_base: u64 = 0x1_0000_0000;
4209 sbox.map_file_cow(&path, guest_base).unwrap();
4210
4211 let err = sbox
4213 .call::<bool>("WriteMappedBuffer", (guest_base, content.len() as u64))
4214 .unwrap_err();
4215
4216 match err {
4217 HyperlightError::MemoryAccessViolation(addr, ..) if addr == guest_base => {}
4218 _ => panic!(
4219 "Expected MemoryAccessViolation at guest_base, got: {:?}",
4220 err
4221 ),
4222 };
4223
4224 let _ = std::fs::remove_file(&path);
4226 }
4227
4228 #[test]
4231 fn test_map_file_cow_poisoned() {
4232 let (path, _) = create_test_file("hyperlight_test_map_file_cow_poison.bin", &[0xCC; 4096]);
4233
4234 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4235 .build()
4236 .unwrap();
4237 let snapshot = sbox.snapshot().unwrap();
4238
4239 let _ = sbox
4241 .call::<()>("guest_panic", "hello".to_string())
4242 .unwrap_err();
4243 assert!(sbox.status().is_poisoned());
4244
4245 let err = sbox.map_file_cow(&path, 0x1_0000_0000).unwrap_err();
4247 assert!(matches!(err, HyperlightError::PoisonedSandbox));
4248
4249 sbox.restore(snapshot).unwrap();
4251 assert_eq!(sbox.status(), SandboxStatus::Ready);
4252 let result = sbox.map_file_cow(&path, 0x1_0000_0000);
4253 assert!(result.is_ok());
4254
4255 let _ = std::fs::remove_file(&path);
4256 }
4257
4258 #[test]
4261 fn test_map_file_cow_multi_vm_same_file() {
4262 let expected = b"shared file content across VMs";
4263 let (path, expected_bytes) =
4264 create_test_file("hyperlight_test_map_file_cow_multi_vm.bin", expected);
4265
4266 let guest_base: u64 = 0x1_0000_0000;
4267
4268 let mut sbox1 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4269 .build()
4270 .unwrap();
4271
4272 let mut sbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4273 .build()
4274 .unwrap();
4275
4276 sbox1.map_file_cow(&path, guest_base).unwrap();
4278 sbox2.map_file_cow(&path, guest_base).unwrap();
4279
4280 let actual1: Vec<u8> = sbox1
4282 .call(
4283 "ReadMappedBuffer",
4284 (guest_base, expected_bytes.len() as u64, true),
4285 )
4286 .unwrap();
4287 let actual2: Vec<u8> = sbox2
4288 .call(
4289 "ReadMappedBuffer",
4290 (guest_base, expected_bytes.len() as u64, true),
4291 )
4292 .unwrap();
4293
4294 assert_eq!(
4295 actual1, expected_bytes,
4296 "Sandbox 1 should read correct content"
4297 );
4298 assert_eq!(
4299 actual2, expected_bytes,
4300 "Sandbox 2 should read correct content"
4301 );
4302
4303 let _ = std::fs::remove_file(&path);
4304 }
4305
4306 #[test]
4309 fn test_map_file_cow_multi_vm_threaded() {
4310 let expected = b"threaded file mapping test data";
4311 let (path, expected_bytes) =
4312 create_test_file("hyperlight_test_map_file_cow_threaded.bin", expected);
4313
4314 const NUM_THREADS: usize = 5;
4315 let path = Arc::new(path);
4316 let expected_bytes = Arc::new(expected_bytes);
4317 let barrier = Arc::new(Barrier::new(NUM_THREADS));
4318 let mut handles = vec![];
4319
4320 for _ in 0..NUM_THREADS {
4321 let path = path.clone();
4322 let expected_bytes = expected_bytes.clone();
4323 let barrier = barrier.clone();
4324
4325 handles.push(thread::spawn(move || {
4326 barrier.wait();
4327
4328 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4329 .build()
4330 .unwrap();
4331
4332 let guest_base: u64 = 0x1_0000_0000;
4333 sbox.map_file_cow(&path, guest_base).unwrap();
4334
4335 let actual: Vec<u8> = sbox
4336 .call(
4337 "ReadMappedBuffer",
4338 (guest_base, expected_bytes.len() as u64, true),
4339 )
4340 .unwrap();
4341
4342 assert_eq!(actual, *expected_bytes);
4343 }));
4344 }
4345
4346 for h in handles {
4347 h.join().unwrap();
4348 }
4349
4350 let _ = std::fs::remove_file(&*path);
4351 }
4352
4353 #[test]
4356 #[cfg(target_os = "windows")]
4357 fn test_map_file_cow_cleanup_no_handle_leak() {
4358 let (path, _) = create_test_file("hyperlight_test_map_file_cow_cleanup.bin", &[0xDD; 4096]);
4359
4360 {
4361 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4362 .build()
4363 .unwrap();
4364
4365 sbox.map_file_cow(&path, 0x1_0000_0000).unwrap();
4366 }
4368
4369 std::fs::remove_file(&path)
4370 .expect("File should be deletable after sandbox with map_file_cow is dropped");
4371 }
4372
4373 #[test]
4377 fn test_map_file_cow_snapshot_remapping_cycle() {
4378 let expected = b"snapshot remapping cycle test!";
4379 let (path, expected_bytes) =
4380 create_test_file("hyperlight_test_map_file_cow_snapshot_remap.bin", expected);
4381
4382 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4383 .build()
4384 .unwrap();
4385
4386 let guest_base: u64 = 0x1_0000_0000;
4387
4388 let snapshot1 = sbox.snapshot().unwrap();
4390
4391 sbox.map_file_cow(&path, guest_base).unwrap();
4393
4394 let actual: Vec<u8> = sbox
4396 .call(
4397 "ReadMappedBuffer",
4398 (guest_base, expected_bytes.len() as u64, true),
4399 )
4400 .unwrap();
4401 assert_eq!(actual, expected_bytes);
4402
4403 let snapshot2 = sbox.snapshot().unwrap();
4405
4406 sbox.restore(snapshot1.clone()).unwrap();
4408 let is_mapped: bool = sbox.call("CheckMapped", (guest_base,)).unwrap();
4409 assert!(
4410 !is_mapped,
4411 "Region should be unmapped after restoring to snapshot₁"
4412 );
4413
4414 sbox.restore(snapshot2).unwrap();
4417 let is_mapped: bool = sbox.call("CheckMapped", (guest_base,)).unwrap();
4418 assert!(
4419 is_mapped,
4420 "Region should be mapped after restoring to snapshot₂"
4421 );
4422 let actual2: Vec<u8> = sbox
4423 .call(
4424 "ReadMappedBuffer",
4425 (guest_base, expected_bytes.len() as u64, false),
4426 )
4427 .unwrap();
4428 assert_eq!(
4429 actual2, expected_bytes,
4430 "Data should be intact after snapshot₂ restore"
4431 );
4432
4433 let _ = std::fs::remove_file(&path);
4434 }
4435
4436 #[test]
4439 fn test_map_file_cow_snapshot_restore() {
4440 let expected = b"snapshot restore basic test!!";
4441 let (path, expected_bytes) =
4442 create_test_file("hyperlight_test_map_file_cow_snap_restore.bin", expected);
4443
4444 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4445 .build()
4446 .unwrap();
4447
4448 let guest_base: u64 = 0x1_0000_0000;
4449 sbox.map_file_cow(&path, guest_base).unwrap();
4450
4451 let actual: Vec<u8> = sbox
4453 .call(
4454 "ReadMappedBuffer",
4455 (guest_base, expected_bytes.len() as u64, true),
4456 )
4457 .unwrap();
4458 assert_eq!(actual, expected_bytes);
4459
4460 let snapshot = sbox.snapshot().unwrap();
4462
4463 sbox.restore(snapshot).unwrap();
4465
4466 let actual2: Vec<u8> = sbox
4468 .call(
4469 "ReadMappedBuffer",
4470 (guest_base, expected_bytes.len() as u64, false),
4471 )
4472 .unwrap();
4473 assert_eq!(
4474 actual2, expected_bytes,
4475 "Data should be readable after restore from snapshot"
4476 );
4477
4478 let _ = std::fs::remove_file(&path);
4479 }
4480
4481 #[test]
4485 fn test_map_file_cow_deferred_basic() {
4486 let expected = b"deferred map_file_cow test data";
4487 let (path, expected_bytes) =
4488 create_test_file("hyperlight_test_map_file_cow_deferred.bin", expected);
4489
4490 let guest_base: u64 = 0x1_0000_0000;
4491
4492 let mut u_sbox =
4493 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4494 .unwrap();
4495
4496 let mapped_size = u_sbox.map_file_cow(&path, guest_base).unwrap();
4498 assert!(mapped_size > 0, "mapped_size should be positive");
4499 assert!(
4500 mapped_size >= expected.len() as u64,
4501 "mapped_size should be >= file content length"
4502 );
4503
4504 let mut sbox = u_sbox.evolve().unwrap();
4506
4507 let actual: Vec<u8> = sbox
4509 .call(
4510 "ReadMappedBuffer",
4511 (guest_base, expected_bytes.len() as u64, true),
4512 )
4513 .unwrap();
4514
4515 assert_eq!(
4516 actual, expected_bytes,
4517 "Guest should read back the exact file content after deferred mapping"
4518 );
4519
4520 let _ = std::fs::remove_file(&path);
4521 }
4522
4523 #[test]
4527 fn test_map_file_cow_deferred_drop_without_evolve() {
4528 let (path, _) = create_test_file(
4529 "hyperlight_test_map_file_cow_deferred_drop.bin",
4530 &[0xAA; 4096],
4531 );
4532
4533 let guest_base: u64 = 0x1_0000_0000;
4534
4535 {
4536 let mut u_sbox =
4537 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4538 .unwrap();
4539
4540 u_sbox.map_file_cow(&path, guest_base).unwrap();
4541 }
4544
4545 #[cfg(target_os = "windows")]
4548 std::fs::remove_file(&path)
4549 .expect("File should be deletable after dropping UninitializedSandbox");
4550 #[cfg(not(target_os = "windows"))]
4551 let _ = std::fs::remove_file(&path);
4552 }
4553
4554 #[test]
4557 fn test_map_file_cow_unaligned_guest_base() {
4558 let (path, _) =
4559 create_test_file("hyperlight_test_map_file_cow_unaligned.bin", &[0xBB; 4096]);
4560
4561 let mut u_sbox =
4562 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4563 .unwrap();
4564
4565 let unaligned_base: u64 = (page_size::get() + 1) as u64;
4567 let result = u_sbox.map_file_cow(&path, unaligned_base);
4568 assert!(
4569 result.is_err(),
4570 "map_file_cow should reject unaligned guest_base"
4571 );
4572
4573 let _ = std::fs::remove_file(&path);
4574 }
4575
4576 #[test]
4578 fn test_map_file_cow_empty_file() {
4579 let temp_dir = std::env::temp_dir();
4580 let path = temp_dir.join("hyperlight_test_map_file_cow_empty.bin");
4581 let _ = std::fs::remove_file(&path);
4582 std::fs::File::create(&path).unwrap(); let mut u_sbox =
4585 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4586 .unwrap();
4587
4588 let guest_base: u64 = 0x1_0000_0000;
4589 let result = u_sbox.map_file_cow(&path, guest_base);
4590 assert!(result.is_err(), "map_file_cow should reject empty files");
4591
4592 let _ = std::fs::remove_file(&path);
4593 }
4594
4595 #[test]
4597 fn test_map_file_cow_overlapping_mappings() {
4598 let (path1, _) =
4599 create_test_file("hyperlight_test_map_file_cow_overlap1.bin", &[0xAA; 4096]);
4600 let (path2, _) =
4601 create_test_file("hyperlight_test_map_file_cow_overlap2.bin", &[0xBB; 4096]);
4602
4603 let guest_base: u64 = 0x1_0000_0000;
4604
4605 let mut u_sbox =
4606 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4607 .unwrap();
4608
4609 u_sbox.map_file_cow(&path1, guest_base).unwrap();
4611
4612 let result = u_sbox.map_file_cow(&path2, guest_base);
4614 assert!(
4615 result.is_err(),
4616 "map_file_cow should reject overlapping guest address ranges"
4617 );
4618
4619 let _ = std::fs::remove_file(&path1);
4620 let _ = std::fs::remove_file(&path2);
4621 }
4622
4623 #[test]
4626 fn test_map_file_cow_shared_mem_overlap() {
4627 let (path, _) = create_test_file(
4628 "hyperlight_test_map_file_cow_overlap_shm.bin",
4629 &[0xCC; 4096],
4630 );
4631
4632 let mut u_sbox =
4633 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
4634 .unwrap();
4635
4636 let base_addr = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
4638 let result = u_sbox.map_file_cow(&path, base_addr);
4640 assert!(
4641 result.is_err(),
4642 "map_file_cow should reject guest_base inside shared memory"
4643 );
4644
4645 let _ = std::fs::remove_file(&path);
4646 }
4647
4648 #[test]
4649 fn map_region_rejects_overlapping_regions() {
4650 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4651 .build()
4652 .unwrap();
4653
4654 let mem1 = allocate_guest_memory();
4655 let mem2 = allocate_guest_memory();
4656 let guest_base: usize = 0x200000000;
4657 let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
4658
4659 unsafe { sbox.map_region(®ion1).unwrap() };
4661
4662 let region2 = region_for_memory(&mem2, guest_base, MemoryRegionFlags::READ);
4664 let err = unsafe { sbox.map_region(®ion2) }.unwrap_err();
4665 assert!(
4666 format!("{err:?}").contains("Overlapping"),
4667 "Expected Overlapping error, got: {err:?}"
4668 );
4669 }
4670
4671 #[test]
4672 fn map_region_rejects_partial_overlap() {
4673 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4674 .build()
4675 .unwrap();
4676
4677 let ps = page_size::get();
4679 let mem1 = page_aligned_memory(&vec![0xAA; ps * 2]); let mem2 = page_aligned_memory(&vec![0xBB; ps * 2]); let guest_base: usize = 0x200000000;
4682 let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
4683
4684 unsafe { sbox.map_region(®ion1).unwrap() };
4685
4686 let overlap_base = guest_base - ps;
4688 let region2 = region_for_memory(&mem2, overlap_base, MemoryRegionFlags::READ);
4689 let err = unsafe { sbox.map_region(®ion2) }.unwrap_err();
4690 assert!(
4691 format!("{err:?}").contains("verlap"),
4692 "Expected overlap error for partial overlap, got: {err:?}"
4693 );
4694 }
4695
4696 #[test]
4697 fn map_region_allows_adjacent_non_overlapping() {
4698 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4699 .build()
4700 .unwrap();
4701
4702 let mem1 = allocate_guest_memory();
4703 let mem2 = allocate_guest_memory();
4704 let guest_base: usize = 0x200000000;
4705 let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
4706 let region_size = mem1.mem_size();
4707
4708 unsafe { sbox.map_region(®ion1).unwrap() };
4709
4710 let adjacent_base = guest_base + region_size;
4712 let region2 = region_for_memory(&mem2, adjacent_base, MemoryRegionFlags::READ);
4713 unsafe { sbox.map_region(®ion2).unwrap() };
4714 }
4715
4716 #[test]
4717 fn map_region_rejects_overlap_with_snapshot() {
4718 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4719 .build()
4720 .unwrap();
4721
4722 let mem = allocate_guest_memory();
4724 let region = region_for_memory(
4725 &mem,
4726 crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS,
4727 MemoryRegionFlags::READ,
4728 );
4729 let err = unsafe { sbox.map_region(®ion) }.unwrap_err();
4730 assert!(
4731 format!("{err:?}").contains("Overlapping"),
4732 "Expected Overlapping error for snapshot overlap, got: {err:?}"
4733 );
4734 }
4735
4736 #[test]
4737 fn map_region_rejects_overlap_with_scratch() {
4738 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4739 .build()
4740 .unwrap();
4741
4742 let scratch_addr = hyperlight_common::layout::scratch_base_gpa(
4744 crate::sandbox::SandboxConfiguration::DEFAULT_SCRATCH_SIZE,
4745 ) as usize;
4746 let mem = allocate_guest_memory();
4747 let region = region_for_memory(&mem, scratch_addr, MemoryRegionFlags::READ);
4748 let err = unsafe { sbox.map_region(®ion) }.unwrap_err();
4749 assert!(
4750 format!("{err:?}").contains("verlap"),
4751 "Expected overlap error for scratch region, got: {err:?}"
4752 );
4753 }
4754
4755 #[cfg(target_arch = "x86_64")]
4756 mod msr_tests {
4757 use super::*;
4758 use crate::hypervisor::hyperlight_vm::{CreateHyperlightVmError, HyperlightVmError};
4759 use crate::hypervisor::regs::{
4760 MSR_APERF, MSR_BNDCFGS, MSR_CSTAR, MSR_DEBUGCTL, MSR_IA32_SSP,
4761 MSR_INTERRUPT_SSP_TABLE_ADDR, MSR_KERNEL_GS_BASE as KERNEL_GS_BASE, MSR_LSTAR,
4762 MSR_MPERF, MSR_MTRR_DEF_TYPE, MSR_MTRR_FIX64K_00000, MSR_PAT, MSR_PL0_SSP, MSR_PL1_SSP,
4763 MSR_PL2_SSP, MSR_PL3_SSP, MSR_S_CET, MSR_SFMASK, MSR_SPEC_CTRL, MSR_STAR,
4764 MSR_SYSENTER_CS as SYSENTER_CS, MSR_SYSENTER_EIP, MSR_SYSENTER_ESP, MSR_TSC,
4765 MSR_TSC_ADJUST, MSR_TSC_AUX, MSR_TSC_DEADLINE, MSR_TSX_CTRL, MSR_U_CET,
4766 MSR_UMWAIT_CONTROL, MSR_VIRT_SPEC_CTRL, MSR_XFD, MSR_XFD_ERR, MSR_XSS,
4767 };
4768 use crate::hypervisor::virtual_machine::{
4769 CreateVmError, RegisterError, ResetVcpuError, VmError,
4770 };
4771 use crate::sandbox::snapshot::Snapshot;
4772
4773 fn assert_msr_not_declarable(error: &HyperlightError, expected: u32) {
4774 assert!(
4775 matches!(
4776 error,
4777 HyperlightError::HyperlightVmError(HyperlightVmError::Create(
4778 CreateHyperlightVmError::Vm(VmError::CreateVm(
4779 CreateVmError::MsrNotDeclarable { msr, .. }
4780 ))
4781 )) if *msr == expected
4782 ),
4783 "expected MsrNotAllowable for {expected:#x}, got: {error:?}"
4784 );
4785 }
4786
4787 fn assert_snapshot_msr_index_invalid(error: &HyperlightError) {
4788 assert!(
4789 matches!(
4790 error,
4791 HyperlightError::HyperlightVmError(HyperlightVmError::Restore(
4792 ResetVcpuError::Register(RegisterError::InvalidSnapshotMsrIndex { .. })
4793 ))
4794 ),
4795 "expected InvalidSnapshotMsrIndex, got: {error:?}"
4796 );
4797 }
4798
4799 #[test]
4800 fn kernel_gs_base_does_not_leak_through_swapgs() {
4801 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4802 .build()
4803 .unwrap();
4804
4805 let original: u64 = sandbox.call("ReadKernelGsBaseViaSwapgs", ()).unwrap();
4806 let sentinel = if original == 0x0000_7AAA_5555_AAAA {
4807 0x0000_6BBB_4444_BBBB
4808 } else {
4809 0x0000_7AAA_5555_AAAA
4810 };
4811 let snapshot = sandbox.snapshot().unwrap();
4812
4813 sandbox
4814 .call::<()>("WriteKernelGsBaseViaSwapgs", sentinel)
4815 .unwrap();
4816 assert_eq!(
4817 sandbox
4818 .call::<u64>("ReadKernelGsBaseViaSwapgs", ())
4819 .unwrap(),
4820 sentinel
4821 );
4822
4823 sandbox.restore(snapshot).unwrap();
4824 assert_eq!(
4825 sandbox
4826 .call::<u64>("ReadKernelGsBaseViaSwapgs", ())
4827 .unwrap(),
4828 original,
4829 "KERNEL_GS_BASE leaked across restore"
4830 );
4831 }
4832
4833 #[test]
4838 #[cfg(any(kvm, mshv3))]
4839 fn restore_rewinds_tsc() {
4840 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4841 .build()
4842 .unwrap();
4843 let snapshot = sbox.snapshot().unwrap();
4844
4845 for restore in 0..3 {
4846 std::thread::sleep(std::time::Duration::from_millis(500));
4847 let before: u64 = sbox.call("ReadTsc", ()).unwrap();
4848 sbox.restore(snapshot.clone()).unwrap();
4849 let after: u64 = sbox.call("ReadTsc", ()).unwrap();
4850 assert!(
4851 after < before,
4852 "restore {restore} did not rewind TSC (before={before}, after={after})"
4853 );
4854 }
4855 }
4856
4857 #[test]
4859 #[cfg(kvm)]
4860 fn restore_handles_zero_tsc() {
4861 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4862 .build()
4863 .unwrap();
4864 sbox.vm
4865 .restore_msrs(&[crate::hypervisor::regs::MsrEntry {
4866 index: MSR_TSC,
4867 value: 0,
4868 }])
4869 .unwrap();
4870 let tsc: u64 = sbox.call("ReadTsc", ()).unwrap();
4871 assert!(tsc < 1 << 62, "TSC jumped to {tsc:#x} after restoring zero");
4872 }
4873
4874 #[test]
4875 fn snapshot_msr_values_survive_full_in_memory_lifecycle() {
4876 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4877 .guest_msrs(&[KERNEL_GS_BASE])
4878 .unwrap()
4879 .build()
4880 .unwrap();
4881 let first = 0x1111;
4882 let second = 0x2222;
4883 let third = 0x3333;
4884
4885 source
4886 .call::<()>("WriteMSR", (KERNEL_GS_BASE, first))
4887 .unwrap();
4888 assert_eq!(
4889 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4890 first
4891 );
4892 let first_snapshot = source.snapshot().unwrap();
4893
4894 source
4895 .call::<()>("WriteMSR", (KERNEL_GS_BASE, second))
4896 .unwrap();
4897 assert_eq!(
4898 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4899 second
4900 );
4901 source.restore(first_snapshot.clone()).unwrap();
4902 assert_eq!(
4903 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4904 first
4905 );
4906
4907 let mut clone = SandboxBuilder::from_snapshot(first_snapshot.clone())
4908 .guest_msrs(&[KERNEL_GS_BASE])
4909 .unwrap()
4910 .build()
4911 .unwrap();
4912 assert_eq!(clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(), first);
4913
4914 clone
4915 .call::<()>("WriteMSR", (KERNEL_GS_BASE, third))
4916 .unwrap();
4917 assert_eq!(clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(), third);
4918 let third_snapshot = clone.snapshot().unwrap();
4919 source.restore(third_snapshot.clone()).unwrap();
4920 assert_eq!(
4921 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4922 third
4923 );
4924
4925 let mut second_clone = SandboxBuilder::from_snapshot(third_snapshot)
4926 .guest_msrs(&[KERNEL_GS_BASE])
4927 .unwrap()
4928 .build()
4929 .unwrap();
4930 assert_eq!(
4931 second_clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4932 third
4933 );
4934 second_clone.restore(first_snapshot).unwrap();
4935 assert_eq!(
4936 second_clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4937 first
4938 );
4939 }
4940
4941 #[test]
4942 fn equivalent_msr_configs_are_order_independent_across_sandboxes() {
4943 let source_order = [KERNEL_GS_BASE, SYSENTER_CS];
4944 let target_order = [SYSENTER_CS, KERNEL_GS_BASE];
4945 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4946 .guest_msrs(&source_order)
4947 .unwrap()
4948 .build()
4949 .unwrap();
4950 source
4951 .call::<()>("WriteMSR", (KERNEL_GS_BASE, 0x4444u64))
4952 .unwrap();
4953 assert_eq!(
4954 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4955 0x4444
4956 );
4957 source
4958 .call::<()>("WriteMSR", (SYSENTER_CS, 0x5555u64))
4959 .unwrap();
4960 assert_eq!(source.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4961 let snapshot = source.snapshot().unwrap();
4962
4963 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4964 .guest_msrs(&target_order)
4965 .unwrap()
4966 .build()
4967 .unwrap();
4968 target
4969 .call::<()>("WriteMSR", (KERNEL_GS_BASE, 0xAAAAu64))
4970 .unwrap();
4971 assert_eq!(
4972 target.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4973 0xAAAA
4974 );
4975 target
4976 .call::<()>("WriteMSR", (SYSENTER_CS, 0xBBBBu64))
4977 .unwrap();
4978 assert_eq!(target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0xBBBB);
4979 target.restore(snapshot.clone()).unwrap();
4980 assert_eq!(
4981 target.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4982 0x4444
4983 );
4984 assert_eq!(target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4985
4986 let mut clone = SandboxBuilder::from_snapshot(snapshot)
4987 .guest_msrs(&target_order)
4988 .unwrap()
4989 .build()
4990 .unwrap();
4991 assert_eq!(
4992 clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4993 0x4444
4994 );
4995 assert_eq!(clone.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4996 }
4997
4998 #[test]
5002 fn snapshot_restores_into_superset_guest_msrs() {
5003 const SYSENTER_ESP: u32 = 0x175;
5004 let sentinel: u64 = 0x1234;
5005 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5006 .guest_msrs(&[SYSENTER_CS])
5007 .unwrap()
5008 .build()
5009 .unwrap();
5010 source
5011 .call::<()>("WriteMSR", (SYSENTER_CS, sentinel))
5012 .unwrap();
5013 let snapshot = source.snapshot().unwrap();
5014
5015 let mut clone = SandboxBuilder::from_snapshot(snapshot.clone())
5016 .guest_msrs(&[SYSENTER_CS, SYSENTER_ESP])
5017 .unwrap()
5018 .build()
5019 .unwrap();
5020 assert_eq!(clone.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), sentinel);
5021 let baseline: u64 = clone.call("ReadMSR", SYSENTER_ESP).unwrap();
5022
5023 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5024 .guest_msrs(&[SYSENTER_CS, SYSENTER_ESP])
5025 .unwrap()
5026 .build()
5027 .unwrap();
5028 target
5029 .call::<()>("WriteMSR", (SYSENTER_ESP, baseline ^ 0x55))
5030 .unwrap();
5031 target.restore(snapshot).unwrap();
5032 assert_eq!(
5033 target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(),
5034 sentinel
5035 );
5036 assert_eq!(
5038 target.call::<u64>("ReadMSR", SYSENTER_ESP).unwrap(),
5039 baseline
5040 );
5041 }
5042
5043 #[test]
5048 fn snapshot_rejects_non_superset_guest_msrs() {
5049 const SYSENTER_ESP: u32 = 0x175;
5050 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5051 .guest_msrs(&[SYSENTER_CS])
5052 .unwrap()
5053 .build()
5054 .unwrap();
5055 source
5056 .call::<()>("WriteMSR", (SYSENTER_CS, 0x1234u64))
5057 .unwrap();
5058 let snapshot = source.snapshot().unwrap();
5059
5060 for dest in [&[][..], &[SYSENTER_ESP][..]] {
5064 let err = SandboxBuilder::from_snapshot(snapshot.clone())
5065 .guest_msrs(dest)
5066 .unwrap()
5067 .build()
5068 .expect_err("from_snapshot must reject an unrestorable snapshot MSR");
5069 assert_snapshot_msr_index_invalid(&err);
5070
5071 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5072 .guest_msrs(dest)
5073 .unwrap()
5074 .build()
5075 .unwrap();
5076 let err = target
5077 .restore(snapshot.clone())
5078 .expect_err("restore must reject an unrestorable snapshot MSR");
5079 assert_snapshot_msr_index_invalid(&err);
5080 assert!(target.status().is_poisoned());
5081 assert!(matches!(
5082 target.call::<String>("Echo", "hi".to_string()),
5083 Err(HyperlightError::PoisonedSandbox)
5084 ));
5085 }
5086 }
5087
5088 #[test]
5089 fn from_pre_init_snapshot_uses_local_msr_reset_set() {
5090 let mut config = SandboxConfiguration::default();
5091 config.guest_msrs(&[KERNEL_GS_BASE]).unwrap();
5092 let snapshot = Arc::new(
5093 Snapshot::from_env(GuestBinary::FilePath(simple_guest_as_pathbuf()), config)
5094 .unwrap(),
5095 );
5096 assert!(snapshot.msrs().is_none());
5097
5098 let mut sandbox = SandboxBuilder::from_snapshot(snapshot.clone())
5099 .guest_msrs(&[KERNEL_GS_BASE])
5100 .unwrap()
5101 .build()
5102 .unwrap();
5103 let baseline: u64 = sandbox.call("ReadMSR", KERNEL_GS_BASE).unwrap();
5104 sandbox
5105 .call::<()>("WriteMSR", (KERNEL_GS_BASE, baseline ^ 0x55))
5106 .unwrap();
5107 assert_eq!(
5108 sandbox.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
5109 baseline ^ 0x55
5110 );
5111 }
5112
5113 #[test]
5114 #[cfg(kvm)]
5115 fn guest_cannot_enable_x2apic_through_apic_base() {
5116 use crate::hypervisor::regs::APIC_BASE_X2APIC_ENABLE;
5117 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5118
5119 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5120 return;
5121 }
5122
5123 const MSR_IA32_APIC_BASE: u32 = 0x1B;
5124 const MSR_X2APIC_BASE: u32 = 0x800;
5125 const APIC_BASE_DEFAULT: u64 = 0xFEE0_0900;
5126
5127 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5128 .build()
5129 .unwrap();
5130 let snapshot = sandbox.snapshot().unwrap();
5131
5132 let x2apic_base = APIC_BASE_DEFAULT | APIC_BASE_X2APIC_ENABLE;
5133 let result = sandbox.call::<()>("WriteMSR", (MSR_IA32_APIC_BASE, x2apic_base));
5134 assert!(
5135 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5136 "guest enabled x2APIC through APIC_BASE: {result:?}"
5137 );
5138 assert!(sandbox.status().is_poisoned());
5139 sandbox.restore(snapshot).unwrap();
5140 assert!(!sandbox.status().is_poisoned());
5141
5142 let result = sandbox.call::<()>("WriteMSR", (MSR_X2APIC_BASE, 1u64));
5143 assert!(
5144 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5145 "x2APIC MSR access succeeded after restore: {result:?}"
5146 );
5147 assert!(sandbox.status().is_poisoned());
5148 }
5149
5150 #[test]
5151 #[cfg(kvm)]
5152 fn denied_msr_access_poisons_sandbox() {
5153 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5154
5155 match get_available_hypervisor() {
5156 Some(HypervisorType::Kvm) => {}
5157 _ => {
5158 return;
5159 }
5160 }
5161
5162 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5163 .build()
5164 .unwrap();
5165
5166 let snapshot = sbox.snapshot().unwrap();
5167 let msr_index: u32 = 0xC000_0102; let result = sbox.call::<u64>("ReadMSR", msr_index);
5170 assert!(
5171 matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
5172 "RDMSR 0x{:X}: expected direct #GP, got: {:?}",
5173 msr_index,
5174 result
5175 );
5176 assert!(sbox.status().is_poisoned());
5177
5178 sbox.restore(snapshot.clone()).unwrap();
5179
5180 let result = sbox.call::<()>("WriteMSR", (msr_index, 0x5u64));
5181 assert!(
5182 matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
5183 "WRMSR 0x{:X}: expected direct #GP, got: {:?}",
5184 msr_index,
5185 result
5186 );
5187 assert!(sbox.status().is_poisoned());
5188 }
5189
5190 #[test]
5191 #[cfg(kvm)]
5192 fn batched_msr_probe_recovers_from_denied_reads() {
5193 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5194
5195 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5196 return;
5197 }
5198
5199 const KVM_CUSTOM_MSR: u32 = 0x4B56_4D00;
5200 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5201 .guest_msrs(&[KERNEL_GS_BASE])
5202 .unwrap()
5203 .build()
5204 .unwrap();
5205
5206 assert_eq!(
5207 sbox.call::<Vec<u8>>("ProbeReadableMSRs", (0u32, 4096u32))
5208 .unwrap()
5209 .len(),
5210 512
5211 );
5212 assert_eq!(
5213 sbox.call::<Vec<u8>>("ProbeReadableMSRs", (KERNEL_GS_BASE, 1u32))
5214 .unwrap(),
5215 vec![1]
5216 );
5217 assert_eq!(
5218 sbox.call::<Vec<u8>>("ProbeReadableMSRs", (KVM_CUSTOM_MSR, 1u32))
5219 .unwrap(),
5220 vec![0]
5221 );
5222 assert!(!sbox.status().is_poisoned());
5223 sbox.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap();
5224 }
5225
5226 #[test]
5227 #[cfg(target_arch = "x86_64")]
5228 fn nested_virtualization_is_hidden_from_guest() {
5229 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5230 .build()
5231 .unwrap();
5232
5233 let features: u32 = sandbox.call("NestedVirtualizationCpuid", ()).unwrap();
5234 assert_eq!(features & 0b11, 0, "guest CPUID exposes VMX or SVM");
5235 }
5236
5237 #[test]
5238 #[cfg(kvm)]
5239 fn nested_vmx_setup_msrs_are_denied() {
5240 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5241
5242 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5243 return;
5244 }
5245
5246 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5247 .build()
5248 .unwrap();
5249
5250 let snapshot = sandbox.snapshot().unwrap();
5251 let vmx_basic: u32 = 0x480;
5252 let result = sandbox.call::<u64>("ReadMSR", vmx_basic);
5253 assert!(
5254 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5255 "RDMSR 0x{vmx_basic:X}: expected direct #GP, got: {result:?}"
5256 );
5257
5258 sandbox.restore(snapshot).unwrap();
5259 let feature_control: u32 = 0x3A;
5260 let result = sandbox.call::<()>("WriteMSR", (feature_control, 0x5u64));
5261 assert!(
5262 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5263 "WRMSR 0x{feature_control:X}: expected direct #GP, got: {result:?}"
5264 );
5265 }
5266
5267 #[test]
5272 #[cfg(target_arch = "x86_64")]
5273 fn guest_cannot_enter_vmx_operation() {
5274 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5275 .build()
5276 .unwrap();
5277
5278 let result = sandbox.call::<()>("EnableVmxOperation", ());
5279 assert!(
5280 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5281 "guest entered VMX operation via CR4.VMXE: {result:?}"
5282 );
5283 assert!(sandbox.status().is_poisoned());
5284 }
5285
5286 #[test]
5291 #[cfg(target_arch = "x86_64")]
5292 fn guest_vmlaunch_faults() {
5293 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5294 .build()
5295 .unwrap();
5296
5297 let result = sandbox.call::<()>("ExecuteVmlaunch", ());
5298 assert!(
5299 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5300 "guest executed VMLAUNCH without faulting: {result:?}"
5301 );
5302 assert!(sandbox.status().is_poisoned());
5303 }
5304
5305 #[test]
5308 #[cfg(kvm)]
5309 fn x2apic_is_hidden_from_guest_cpuid() {
5310 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5311
5312 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5313 return;
5314 }
5315
5316 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5317 .build()
5318 .unwrap();
5319
5320 assert!(
5321 !sandbox.call::<bool>("X2apicSupported", ()).unwrap(),
5322 "guest CPUID advertises x2APIC"
5323 );
5324 }
5325
5326 #[test]
5328 #[cfg(target_arch = "x86_64")]
5329 fn test_allow_non_resettable_msr_fails_creation() {
5330 let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5332 .guest_msrs(&[0x49])
5333 .unwrap()
5334 .build()
5335 .unwrap_err();
5336
5337 assert_msr_not_declarable(&err, 0x49);
5338 }
5339
5340 #[test]
5342 #[cfg(kvm)]
5343 fn unclassified_declared_msr_rejected_at_creation() {
5344 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5345
5346 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5347 return;
5348 }
5349
5350 let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5352 .guest_msrs(&[0x1A0])
5353 .unwrap()
5354 .build()
5355 .expect_err("an unclassified declared MSR must be rejected at creation");
5356
5357 assert_msr_not_declarable(&err, 0x1A0);
5358 }
5359
5360 #[test]
5361 #[cfg(target_arch = "x86_64")]
5362 fn test_multiple_guest_msrs_reset_across_restore() {
5363 let msrs: [u32; 4] = [0x174, 0x175, 0x176, 0xC000_0102];
5365
5366 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5367 .guest_msrs(&msrs)
5368 .unwrap()
5369 .build()
5370 .unwrap();
5371
5372 let baseline_snapshot = sbox.snapshot().unwrap();
5373
5374 let value: u64 = 0x1000;
5375 for &msr in &msrs {
5376 sbox.call::<()>("WriteMSR", (msr, value)).unwrap();
5377 let read_value: u64 = sbox.call("ReadMSR", msr).unwrap();
5378 assert_eq!(read_value, value, "MSR 0x{msr:X} should be writable");
5379 }
5380
5381 sbox.restore(baseline_snapshot).unwrap();
5382 for &msr in &msrs {
5383 let read_value: u64 = sbox.call("ReadMSR", msr).unwrap();
5384 assert_ne!(
5385 read_value, value,
5386 "MSR 0x{msr:X} should be reset to baseline across restore"
5387 );
5388 }
5389 }
5390
5391 #[test]
5393 #[cfg(target_arch = "x86_64")]
5394 fn test_declared_msr_does_not_leak_across_restore() {
5395 let msr_index: u32 = 0xC000_0102; let sentinel: u64 = 0xCAFE_F00D;
5397
5398 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5399 .guest_msrs(&[msr_index])
5400 .unwrap()
5401 .build()
5402 .unwrap();
5403
5404 let baseline = sbox.snapshot().unwrap();
5405 let original: u64 = sbox.call("ReadMSR", msr_index).unwrap();
5406 assert_ne!(
5407 original, sentinel,
5408 "test sentinel must differ from the baseline value"
5409 );
5410
5411 sbox.call::<()>("WriteMSR", (msr_index, sentinel)).unwrap();
5412 assert_eq!(
5413 sbox.call::<u64>("ReadMSR", msr_index).unwrap(),
5414 sentinel,
5415 "sentinel should be observable before restore"
5416 );
5417 sbox.restore(baseline).unwrap();
5418
5419 let after: u64 = sbox.call("ReadMSR", msr_index).unwrap();
5420 assert_ne!(after, sentinel, "sentinel leaked across restore");
5421 assert_eq!(after, original, "MSR not reset to its baseline value");
5422 }
5423
5424 #[test]
5426 #[cfg(all(kvm, target_arch = "x86_64"))]
5427 fn test_debugctl_and_x2apic_msr_denied_by_default() {
5428 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5429
5430 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5431 return;
5432 }
5433
5434 for msr_index in [0x1D9_u32, 0x800] {
5435 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5436 .build()
5437 .unwrap();
5438
5439 let result = sbox.call::<()>("WriteMSR", (msr_index, 0x1u64));
5440 assert!(
5441 matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
5442 "WRMSR 0x{msr_index:X}: expected direct #GP, got: {result:?}"
5443 );
5444 assert!(
5445 sbox.status().is_poisoned(),
5446 "sandbox should be poisoned after a denied WRMSR to 0x{msr_index:X}"
5447 );
5448 }
5449 }
5450
5451 #[test]
5452 #[cfg(all(kvm, target_arch = "x86_64"))]
5453 fn all_kvm_custom_msrs_are_denied() {
5454 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5455
5456 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5457 return;
5458 }
5459
5460 const KVM_CUSTOM_MSR_START: u32 = 0x4B56_4D00;
5461 const KVM_CUSTOM_MSR_END: u32 = 0x4B56_4DFF;
5462
5463 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5464 .build()
5465 .unwrap();
5466 let snapshot = sandbox.snapshot().unwrap();
5467
5468 for index in KVM_CUSTOM_MSR_START..=KVM_CUSTOM_MSR_END {
5469 let result = sandbox.call::<u64>("ReadMSR", index);
5470 assert!(
5471 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5472 "RDMSR {index:#x} was not denied: {result:?}"
5473 );
5474 sandbox.restore(snapshot.clone()).unwrap();
5475
5476 let result = sandbox.call::<()>("WriteMSR", (index, 1u64));
5477 assert!(
5478 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
5479 "WRMSR {index:#x} was not denied: {result:?}"
5480 );
5481 sandbox.restore(snapshot.clone()).unwrap();
5482 }
5483 }
5484
5485 #[test]
5489 #[cfg(target_arch = "x86_64")]
5490 fn unresettable_msr_classes_do_not_leak() {
5491 let cases: &[(u32, &str)] = &[
5492 (0xC1, "PMU IA32_PMC0"),
5493 (0x186, "PMU IA32_PERFEVTSEL0"),
5494 (0x38F, "PMU IA32_PERF_GLOBAL_CTRL"),
5495 (0x1C8, "LBR_SELECT"),
5496 (0x14CE, "arch-LBR IA32_LBR_CTL"),
5497 (0x1D4, "FRED IA32_FRED_CONFIG"),
5498 (0xC001_0114, "AMD VM_CR"),
5499 (0xC001_0117, "AMD VM_HSAVE_PA"),
5500 ];
5501
5502 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5503 .build()
5504 .unwrap();
5505
5506 for &(msr, _name) in cases {
5507 assert_msr_write_does_not_survive_restore(&mut sbox, msr, 0x1);
5508 }
5509 }
5510
5511 #[test]
5514 #[cfg(target_arch = "x86_64")]
5515 fn misc_enable_guest_write_does_not_survive_restore() {
5516 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5517 .build()
5518 .unwrap();
5519 assert_msr_write_does_not_survive_restore(&mut sbox, 0x1A0, 1u64 << 40);
5520 }
5521
5522 #[test]
5524 #[cfg(target_arch = "x86_64")]
5525 fn runtime_msr_table_entries_are_justified() {
5526 use crate::hypervisor::regs::resettable_msr_indices;
5527
5528 #[cfg(kvm)]
5529 let is_kvm = matches!(
5530 crate::hypervisor::virtual_machine::get_available_hypervisor(),
5531 Some(crate::hypervisor::virtual_machine::HypervisorType::Kvm)
5532 );
5533 #[cfg(not(kvm))]
5534 let is_kvm = false;
5535
5536 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5537 .build()
5538 .unwrap();
5539
5540 let reset_indices: Vec<u32> = sbox.vm.reset_set_indices();
5541
5542 for index in resettable_msr_indices() {
5543 if !reset_indices.contains(&index) {
5544 assert_omitted_msr_does_not_retain(&mut sbox, index);
5545 } else if is_kvm && index == KERNEL_GS_BASE {
5546 } else if (index == MSR_TSC && !is_kvm) || matches!(index, MSR_MPERF | MSR_APERF) {
5549 assert_guest_counter_is_writable_and_restored(&mut sbox, index);
5550 } else if let Some(test_value) = guest_write_test_value(index) {
5551 assert_guest_msr_is_writable_and_restored(&mut sbox, index, test_value);
5552 } else {
5553 assert!(
5554 reset_exception_reason(index).is_some(),
5555 "MSR 0x{index:X} is in the reset set without positive guest-write coverage or an explicit reason"
5556 );
5557 }
5558 }
5559 }
5560
5561 fn assert_omitted_msr_does_not_retain(sbox: &mut Sandbox, index: u32) {
5562 let baseline = sbox.snapshot().unwrap();
5563 let original: u64 = match sbox.call("ReadMSR", index) {
5564 Ok(value) => value,
5565 Err(_) => {
5566 assert!(
5567 sbox.status().is_poisoned(),
5568 "0x{index:X}: fault did not poison sandbox"
5569 );
5570 sbox.restore(baseline).unwrap();
5571 return;
5572 }
5573 };
5574 let preferred = guest_write_test_value(index).unwrap_or(original ^ 1);
5575 let candidates = [preferred, original ^ 1, original ^ 2, 0, 1, 0x1000];
5576
5577 for candidate in candidates {
5578 if candidate == original {
5579 continue;
5580 }
5581 if sbox.call::<()>("WriteMSR", (index, candidate)).is_err() {
5582 assert!(
5583 sbox.status().is_poisoned(),
5584 "0x{index:X}: fault did not poison sandbox"
5585 );
5586 sbox.restore(baseline.clone()).unwrap();
5587 continue;
5588 }
5589 let written: u64 = sbox.call("ReadMSR", index).unwrap_or_else(|error| {
5590 panic!("0x{index:X}: read after successful write failed: {error:?}")
5591 });
5592 if written != original {
5593 sbox.restore(baseline).unwrap();
5594 let after: u64 = sbox.call("ReadMSR", index).unwrap();
5595 assert_eq!(
5596 after, original,
5597 "0x{index:X}: guest retained a write but the MSR is absent from the reset set"
5598 );
5599 return;
5600 }
5601 sbox.restore(baseline.clone()).unwrap();
5602 }
5603 }
5604
5605 fn guest_write_test_value(index: u32) -> Option<u64> {
5606 match index {
5607 SYSENTER_CS => Some(0x10),
5608 MSR_SYSENTER_ESP | MSR_SYSENTER_EIP => Some(0x1000),
5609 MSR_PAT => Some(0x0007_0406_0007_0406),
5610 MSR_STAR => Some(0x001B_0008_0000_0000),
5611 MSR_LSTAR | MSR_CSTAR => Some(0x1000),
5612 MSR_SFMASK => Some(0x200),
5613 KERNEL_GS_BASE => Some(0x1000),
5614 MSR_TSC_ADJUST => Some(0x1000),
5615 MSR_TSC_AUX => Some(0x5),
5616 MSR_MTRR_DEF_TYPE => Some(0xC00),
5617 0x200..=0x21F if index & 1 == 0 => Some(0x6), 0x200..=0x21F => Some(0x800), MSR_MTRR_FIX64K_00000 | 0x258 | 0x259 | 0x268..=0x26F => {
5620 Some(0x0606_0606_0606_0606)
5621 }
5622 _ => None,
5623 }
5624 }
5625
5626 fn reset_exception_reason(index: u32) -> Option<&'static str> {
5627 match index {
5628 MSR_TSC => Some("KVM denies direct guest TSC MSR access"),
5629 MSR_IA32_SSP => Some(
5630 "active SSP has no architectural RDMSR/WRMSR; covered by active_ssp_does_not_leak_across_restore",
5631 ),
5632 MSR_DEBUGCTL => Some("DEBUGCTL support depends on exposed debug features"),
5633 MSR_SPEC_CTRL => Some("SPEC_CTRL writable bits depend on mitigation features"),
5634 MSR_U_CET
5635 | MSR_S_CET
5636 | MSR_PL0_SSP
5637 | MSR_PL1_SSP
5638 | MSR_PL2_SSP
5639 | MSR_PL3_SSP
5640 | MSR_INTERRUPT_SSP_TABLE_ADDR => {
5641 Some("CET writable state depends on exposed CET features")
5642 }
5643 MSR_TSX_CTRL => Some("TSX_CTRL writable bits depend on exposed TSX features"),
5644 MSR_XFD | MSR_XFD_ERR => Some("XFD writable bits depend on exposed XSAVE features"),
5645 MSR_UMWAIT_CONTROL => {
5646 Some("UMWAIT_CONTROL writable bits depend on exposed WAITPKG features")
5647 }
5648 MSR_TSC_DEADLINE => {
5649 Some("TSC_DEADLINE writable bits depend on exposed APIC-timer features")
5650 }
5651 MSR_BNDCFGS => Some("BNDCFGS writable bits depend on exposed MPX features"),
5652 MSR_XSS => Some("XSS writable bits depend on exposed XSAVE features"),
5653 MSR_VIRT_SPEC_CTRL => {
5654 Some("VIRT_SPEC_CTRL writable bits depend on exposed AMD SSBD virtualization")
5655 }
5656 _ => None,
5657 }
5658 }
5659
5660 fn assert_guest_msr_is_writable_and_restored(
5661 sbox: &mut Sandbox,
5662 index: u32,
5663 sentinel: u64,
5664 ) {
5665 let baseline = sbox.snapshot().unwrap();
5666 let original: u64 = sbox
5667 .call("ReadMSR", index)
5668 .unwrap_or_else(|error| panic!("0x{index:X}: guest RDMSR failed: {error:?}"));
5669 let value = if original == sentinel { 0 } else { sentinel };
5670
5671 sbox.call::<()>("WriteMSR", (index, value))
5672 .unwrap_or_else(|error| panic!("0x{index:X}: guest WRMSR failed: {error:?}"));
5673 let written: u64 = sbox
5674 .call("ReadMSR", index)
5675 .unwrap_or_else(|error| panic!("0x{index:X}: guest read-back failed: {error:?}"));
5676 assert_eq!(written, value, "0x{index:X}: guest write did not stick");
5677
5678 sbox.restore(baseline).unwrap();
5679 let restored: u64 = sbox.call("ReadMSR", index).unwrap();
5680 assert_eq!(
5681 restored, original,
5682 "0x{index:X}: restore did not recover the baseline"
5683 );
5684 }
5685
5686 fn assert_guest_counter_is_writable_and_restored(sbox: &mut Sandbox, index: u32) {
5687 let baseline = sbox.snapshot().unwrap();
5688 let original: u64 = sbox.call("ReadMSR", index).unwrap();
5689 let jump = original.wrapping_add(1 << 60);
5690
5691 sbox.call::<()>("WriteMSR", (index, jump)).unwrap();
5692 let written: u64 = sbox.call("ReadMSR", index).unwrap();
5693 assert!(
5694 written >= jump / 2,
5695 "0x{index:X}: guest write did not stick"
5696 );
5697
5698 sbox.restore(baseline).unwrap();
5699 let restored: u64 = sbox.call("ReadMSR", index).unwrap();
5700 assert!(
5701 restored < jump / 2,
5702 "0x{index:X}: restore did not pull the counter below the guest-written jump"
5703 );
5704 }
5705
5706 #[cfg(target_arch = "x86_64")]
5708 fn assert_msr_write_does_not_survive_restore(sbox: &mut Sandbox, msr: u32, sentinel: u64) {
5709 let baseline = sbox.snapshot().unwrap();
5710 let original: u64 = match sbox.call("ReadMSR", msr) {
5711 Ok(v) => v,
5712 Err(_) => {
5713 assert!(
5714 sbox.status().is_poisoned(),
5715 "0x{msr:X}: a faulting RDMSR should poison the sandbox"
5716 );
5717 sbox.restore(baseline).unwrap();
5718 return;
5719 }
5720 };
5721 assert_ne!(
5722 original, sentinel,
5723 "0x{msr:X}: sentinel must differ from baseline"
5724 );
5725
5726 if sbox.call::<()>("WriteMSR", (msr, sentinel)).is_err() {
5727 assert!(
5728 sbox.status().is_poisoned(),
5729 "0x{msr:X}: a faulting WRMSR should poison the sandbox"
5730 );
5731 sbox.restore(baseline).unwrap();
5732 return;
5733 }
5734
5735 sbox.restore(baseline).unwrap();
5736 let after: u64 = sbox.call("ReadMSR", msr).unwrap();
5737 assert_eq!(
5738 after, original,
5739 "0x{msr:X}: MSR leaked across restore (expected 0x{original:X}, got 0x{after:X})"
5740 );
5741 }
5742
5743 #[test]
5745 #[ignore = "slow host-dependent hardware MSR audit"]
5746 #[cfg(target_arch = "x86_64")]
5747 fn test_no_msr_leaks_across_restore_full_window_sweep() {
5748 const FREE_RUNNING: &[u32] = &[
5750 0x10, 0xE7, 0xE8, ];
5754
5755 #[cfg(kvm)]
5756 if matches!(
5757 crate::hypervisor::virtual_machine::get_available_hypervisor(),
5758 Some(crate::hypervisor::virtual_machine::HypervisorType::Kvm)
5759 ) {
5760 return;
5761 }
5762
5763 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5764 .build()
5765 .unwrap();
5766
5767 let baseline = sbox.snapshot().unwrap();
5768
5769 let mut readable = 0usize;
5771 let mut exercised: Vec<u32> = Vec::new();
5772 let mut read_only: Vec<u32> = Vec::new();
5773 let mut masked_only: Vec<u32> = Vec::new();
5774 let mut free_running_leaked: Vec<u32> = Vec::new();
5776
5777 const PROBE_CHUNK_SIZE: u32 = 4096;
5778 let low = 0x0000_0000u32..=0x0000_1FFF;
5780 let hyperv_synthetic = 0x4000_0000u32..=0x4000_1FFF;
5782 let extended = 0xC000_0000u32..=0xC001_FFFF;
5784
5785 let mut readable_msrs = Vec::new();
5786 for window in [low, hyperv_synthetic, extended] {
5787 let window_end = *window.end();
5788 for chunk_start in window.step_by(PROBE_CHUNK_SIZE as usize) {
5789 let chunk_len = PROBE_CHUNK_SIZE.min(window_end - chunk_start + 1);
5790 let bitmap: Vec<u8> = sbox
5791 .call("ProbeReadableMSRs", (chunk_start, chunk_len))
5792 .unwrap();
5793 assert_eq!(bitmap.len(), chunk_len.div_ceil(8) as usize);
5794 readable_msrs.extend((0..chunk_len).filter_map(|offset| {
5795 let byte = bitmap[offset as usize / 8];
5796 (byte & (1 << (offset % 8)) != 0).then_some(chunk_start + offset)
5797 }));
5798 }
5799 }
5800
5801 for msr in readable_msrs {
5802 let original: u64 = sbox.call("ReadMSR", msr).unwrap();
5803 readable += 1;
5804
5805 if FREE_RUNNING.contains(&msr) {
5807 let jump = original.wrapping_add(1 << 60);
5808 if sbox.call::<()>("WriteMSR", (msr, jump)).is_err() {
5809 sbox.restore(baseline.clone()).unwrap();
5810 read_only.push(msr);
5811 continue;
5812 }
5813 let planted = match sbox.call::<u64>("ReadMSR", msr) {
5814 Ok(v) => v,
5815 Err(_) => {
5816 sbox.restore(baseline.clone()).unwrap();
5817 masked_only.push(msr);
5818 continue;
5819 }
5820 };
5821 if planted < jump / 2 {
5822 sbox.restore(baseline.clone()).unwrap();
5823 masked_only.push(msr);
5824 continue;
5825 }
5826 sbox.restore(baseline.clone()).unwrap();
5827 let after: u64 = sbox.call("ReadMSR", msr).unwrap();
5828 if after < jump / 2 {
5829 exercised.push(msr);
5830 } else {
5831 free_running_leaked.push(msr);
5832 }
5833 continue;
5834 }
5835
5836 let candidates = [
5838 original ^ 0x55,
5839 original ^ 0x1,
5840 original ^ (1 << 12),
5841 original ^ (1 << 20),
5842 original ^ (1 << 32),
5843 original.wrapping_add(1),
5844 0,
5845 ];
5846 let mut planted = false;
5847 let mut saw_write = false;
5848 for cand in candidates {
5849 if cand == original {
5850 continue;
5851 }
5852 if sbox.call::<()>("WriteMSR", (msr, cand)).is_err() {
5853 sbox.restore(baseline.clone()).unwrap();
5854 continue;
5855 }
5856 saw_write = true;
5857 match sbox.call::<u64>("ReadMSR", msr) {
5858 Ok(v) if v != original => {
5859 planted = true;
5860 break;
5861 }
5862 _ => {
5863 sbox.restore(baseline.clone()).unwrap();
5864 }
5865 }
5866 }
5867
5868 if planted {
5869 sbox.restore(baseline.clone()).unwrap();
5870 match sbox.call::<u64>("ReadMSR", msr) {
5871 Ok(after) => assert_eq!(
5872 after, original,
5873 "0x{msr:X}: a guest MSR write leaked across restore \
5874 (expected 0x{original:X}, got 0x{after:X})"
5875 ),
5876 Err(e) => panic!("0x{msr:X}: read-back after restore failed: {e:?}"),
5877 }
5878 exercised.push(msr);
5879 } else if saw_write {
5880 masked_only.push(msr);
5881 } else {
5882 read_only.push(msr);
5883 }
5884 }
5885
5886 let fmt = |v: &[u32]| {
5887 v.iter()
5888 .map(|m| format!("0x{m:X}"))
5889 .collect::<Vec<_>>()
5890 .join(", ")
5891 };
5892 eprintln!(
5893 "full-window MSR sweep: readable={readable} exercised={} masked_only={} read_only={}",
5894 exercised.len(),
5895 masked_only.len(),
5896 read_only.len()
5897 );
5898 eprintln!(" exercised: [{}]", fmt(&exercised));
5899 eprintln!(" masked_only: [{}]", fmt(&masked_only));
5900 eprintln!(" read_only: [{}]", fmt(&read_only));
5901 eprintln!(" free_running_leaked: [{}]", fmt(&free_running_leaked));
5902 assert!(
5903 free_running_leaked.is_empty(),
5904 "free-running MSRs not reset across restore on this backend: [{}]",
5905 fmt(&free_running_leaked)
5906 );
5907 assert!(
5908 !exercised.is_empty(),
5909 "sweep was vacuous: no guest MSR write ever retained a value that restore \
5910 then rolled back, so the rollback path was never exercised"
5911 );
5912 }
5913
5914 #[test]
5918 #[cfg(all(any(mshv3, target_os = "windows"), target_arch = "x86_64"))]
5919 fn active_ssp_does_not_leak_across_restore() {
5920 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5921 .build()
5922 .unwrap();
5923
5924 if !sbox.call::<bool>("CetShadowStackSupported", ()).unwrap() {
5925 return;
5926 }
5927
5928 let baseline = sbox.snapshot().unwrap();
5929 let original: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
5930
5931 let mutated: u64 = sbox.call("IncrementActiveSsp", ()).unwrap();
5932 assert_ne!(mutated, original, "guest did not change active SSP");
5933 let seen: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
5934 assert_eq!(seen, mutated, "guest did not observe its own SSP mutation");
5935
5936 sbox.restore(baseline).unwrap();
5937
5938 let after: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
5939 assert_eq!(
5940 after, original,
5941 "active SSP leaked across restore (original=0x{original:X}, mutated=0x{mutated:X}, after=0x{after:X})"
5942 );
5943 }
5944
5945 #[test]
5950 #[cfg(all(kvm, target_arch = "x86_64"))]
5951 fn kvm_does_not_expose_cet_to_guest() {
5952 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
5953
5954 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
5955 return;
5956 }
5957
5958 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5959 .build()
5960 .unwrap();
5961 assert!(
5962 !sbox.call::<bool>("CetShadowStackSupported", ()).unwrap(),
5963 "KVM guest CPUID exposes CET shadow stacks"
5964 );
5965
5966 let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5969 .guest_msrs(&[MSR_S_CET])
5970 .unwrap()
5971 .build()
5972 .expect_err("allowing IA32_S_CET must be rejected when CET is hidden");
5973 assert_msr_not_declarable(&err, MSR_S_CET);
5974 }
5975 }
5976
5977 mod from_snapshot {
5979 use std::sync::Arc;
5980
5981 use hyperlight_common::layout;
5982 use hyperlight_testing::simple_guest_as_pathbuf;
5983
5984 use crate::func::Registerable;
5985 use crate::sandbox::SandboxConfiguration;
5986 use crate::sandbox::snapshot::Snapshot;
5987 use crate::{GuestBinary, HostFunctions, HyperlightError, Sandbox, SandboxBuilder};
5988
5989 fn make_sandbox() -> Sandbox {
5990 let path = simple_guest_as_pathbuf();
5991 SandboxBuilder::from_file(path).build().unwrap()
5992 }
5993
5994 fn make_sandbox_with_add() -> Sandbox {
5996 let path = simple_guest_as_pathbuf();
5997 SandboxBuilder::from_file(path)
5998 .host_function("Add", |a: i32, b: i32| a + b)
5999 .build()
6000 .unwrap()
6001 }
6002
6003 fn host_funcs_with_matching_add() -> HostFunctions {
6004 let mut hf = HostFunctions::default();
6005 hf.register_host_function("Add", |a: i32, b: i32| Ok(a + b))
6006 .unwrap();
6007 hf
6008 }
6009
6010 #[test]
6011 fn round_trip_running_sandbox() {
6012 let mut sbox = make_sandbox();
6013 sbox.call::<i32>("AddToStatic", 11i32).unwrap();
6014 let snapshot = sbox.snapshot().unwrap();
6015 assert!(snapshot.virtq().is_some());
6016 let mut sbox2 = SandboxBuilder::from_snapshot(snapshot).build().unwrap();
6017 super::assert_virtq_attached(&sbox2);
6018 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 11);
6019 let echoed: String = sbox2.call("Echo", "hi".to_string()).unwrap();
6020 assert_eq!(echoed, "hi");
6021 }
6022
6023 #[test]
6024 fn rejects_noncanonical_transport_snapshot() {
6025 let mut sbox = make_sandbox();
6026 sbox.call::<i32>("AddToStatic", 1i32).unwrap();
6027
6028 sbox.checkpoint_transport_for_snapshot().unwrap();
6030
6031 let layout = &sbox.mem_mgr.layout;
6032 let scratch_base = layout::scratch_base_gpa(layout.get_scratch_size());
6033
6034 let ring_offset =
6035 (layout.get_transport_arena().g2h_ring_addr() - scratch_base) as usize;
6036
6037 sbox.mem_mgr
6038 .scratch_mem
6039 .write::<u64>(ring_offset, 1)
6040 .unwrap();
6041
6042 let Err(err) = sbox.snapshot() else {
6043 panic!("noncanonical transport must fail snapshot creation");
6044 };
6045
6046 assert!(err.to_string().contains("invalid canonical G2H image"));
6047 }
6048
6049 #[test]
6050 fn round_trip_pre_init_snapshot() {
6051 let path = simple_guest_as_pathbuf();
6052 let snap =
6053 Snapshot::from_env(GuestBinary::FilePath(path), SandboxConfiguration::default())
6054 .unwrap();
6055 assert!(snap.virtq().is_none());
6056 let mut sbox = SandboxBuilder::from_snapshot(Arc::new(snap))
6057 .build()
6058 .unwrap();
6059 assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 0);
6060 }
6061
6062 #[test]
6073 #[ignore]
6074 fn max_guest_log_level_is_honored_from_snapshot() {
6075 use hyperlight_common::log_level::GuestLogFilter;
6076 use hyperlight_testing::logger::{LOGGER, Logger};
6077 use tracing_core::LevelFilter;
6078
6079 Logger::initialize_test_logger();
6080 LOGGER.set_max_level(log::LevelFilter::Trace);
6081
6082 let count_guest_logs = |max_level: LevelFilter| -> usize {
6086 let snap = Snapshot::from_env(
6087 GuestBinary::FilePath(simple_guest_as_pathbuf()),
6088 SandboxConfiguration::default(),
6089 )
6090 .unwrap();
6091 let mut config = SandboxConfiguration::default();
6092 config.set_max_guest_log_level(max_level);
6093 let mut sbox =
6094 Sandbox::from_snapshot(Arc::new(snap), HostFunctions::default(), Some(config))
6095 .unwrap();
6096
6097 LOGGER.clear_log_calls();
6099
6100 for level in [
6101 LevelFilter::TRACE,
6102 LevelFilter::DEBUG,
6103 LevelFilter::INFO,
6104 LevelFilter::WARN,
6105 LevelFilter::ERROR,
6106 ] {
6107 let encoded: u64 = GuestLogFilter::from(level).into();
6108 sbox.call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6109 .unwrap();
6110 }
6111
6112 let count = (0..LOGGER.num_log_calls())
6113 .filter_map(|i| LOGGER.get_log_call(i))
6114 .filter(|c| c.target == "hyperlight_guest")
6115 .count();
6116 LOGGER.clear_log_calls();
6117 count
6118 };
6119
6120 let trace_count = count_guest_logs(LevelFilter::TRACE);
6121 let error_count = count_guest_logs(LevelFilter::ERROR);
6122
6123 assert!(
6124 error_count >= 1,
6125 "an ERROR-level guest log must reach the host, got {error_count}"
6126 );
6127 assert!(
6128 trace_count > error_count,
6129 "TRACE must let more guest logs through than ERROR (trace={trace_count}, \
6130 error={error_count}); equal counts mean max_guest_log_level was ignored"
6131 );
6132 }
6133
6134 #[test]
6139 #[ignore]
6140 fn max_guest_log_level_overrides_initialized_snapshot() {
6141 use hyperlight_common::log_level::GuestLogFilter;
6142 use hyperlight_testing::logger::{LOGGER, Logger};
6143 use tracing_core::LevelFilter;
6144
6145 Logger::initialize_test_logger();
6146 LOGGER.set_max_level(log::LevelFilter::Trace);
6147
6148 let initialized_snapshot = |captured_level: LevelFilter| {
6149 SandboxBuilder::from_file(simple_guest_as_pathbuf())
6150 .guest_log_level(captured_level)
6151 .build()
6152 .unwrap()
6153 .snapshot()
6154 .unwrap()
6155 };
6156
6157 let count_guest_logs =
6158 |snapshot: Arc<Snapshot>, override_level: Option<LevelFilter>| -> usize {
6159 let config = override_level.map(|level| {
6160 let mut config = SandboxConfiguration::default();
6161 config.set_max_guest_log_level(level);
6162 config
6163 });
6164 let mut sandbox =
6165 Sandbox::from_snapshot(snapshot, HostFunctions::default(), config).unwrap();
6166
6167 LOGGER.clear_log_calls();
6168 for level in [
6169 LevelFilter::TRACE,
6170 LevelFilter::DEBUG,
6171 LevelFilter::INFO,
6172 LevelFilter::WARN,
6173 LevelFilter::ERROR,
6174 ] {
6175 let encoded: u64 = GuestLogFilter::from(level).into();
6176 sandbox
6177 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6178 .unwrap();
6179 }
6180
6181 let count = (0..LOGGER.num_log_calls())
6182 .filter_map(|i| LOGGER.get_log_call(i))
6183 .filter(|call| call.target == "hyperlight_guest")
6184 .count();
6185 LOGGER.clear_log_calls();
6186 count
6187 };
6188
6189 let trace_snapshot = initialized_snapshot(LevelFilter::TRACE);
6190 let error_snapshot = initialized_snapshot(LevelFilter::ERROR);
6191
6192 let captured_trace = count_guest_logs(trace_snapshot.clone(), None);
6193 let overridden_trace = count_guest_logs(trace_snapshot, Some(LevelFilter::ERROR));
6194 let captured_error = count_guest_logs(error_snapshot.clone(), None);
6195 let overridden_error = count_guest_logs(error_snapshot, Some(LevelFilter::TRACE));
6196
6197 assert!(
6198 captured_trace > overridden_trace,
6199 "ERROR override should reduce TRACE snapshot logs (trace={}, error={})",
6200 captured_trace,
6201 overridden_trace
6202 );
6203 assert!(
6204 overridden_error > captured_error,
6205 "TRACE override should increase ERROR snapshot logs (trace={}, error={})",
6206 overridden_error,
6207 captured_error
6208 );
6209 }
6210
6211 #[test]
6216 #[ignore]
6217 fn max_guest_log_level_setter_survives_restore() {
6218 use hyperlight_common::log_level::GuestLogFilter;
6219 use hyperlight_testing::logger::{LOGGER, Logger};
6220 use tracing_core::LevelFilter;
6221
6222 Logger::initialize_test_logger();
6223 LOGGER.set_max_level(log::LevelFilter::Trace);
6224
6225 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6226 .guest_log_level(LevelFilter::TRACE)
6227 .build()
6228 .unwrap();
6229 let snapshot = source.snapshot().unwrap();
6230 let mut sandbox = SandboxBuilder::from_snapshot(snapshot.clone())
6231 .build()
6232 .unwrap();
6233 sandbox.log_level(LevelFilter::ERROR).unwrap();
6234
6235 let count_guest_logs = |sandbox: &mut Sandbox| {
6236 LOGGER.clear_log_calls();
6237 for level in [
6238 LevelFilter::TRACE,
6239 LevelFilter::DEBUG,
6240 LevelFilter::INFO,
6241 LevelFilter::WARN,
6242 LevelFilter::ERROR,
6243 ] {
6244 let encoded: u64 = GuestLogFilter::from(level).into();
6245 sandbox
6246 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6247 .unwrap();
6248 }
6249 let count = (0..LOGGER.num_log_calls())
6250 .filter_map(|i| LOGGER.get_log_call(i))
6251 .filter(|call| call.target == "hyperlight_guest")
6252 .count();
6253 LOGGER.clear_log_calls();
6254 count
6255 };
6256
6257 let before_restore = count_guest_logs(&mut sandbox);
6258 sandbox.restore(snapshot).unwrap();
6259 let after_restore = count_guest_logs(&mut sandbox);
6260
6261 assert_eq!(before_restore, 1);
6262 assert_eq!(before_restore, after_restore);
6263 }
6264
6265 #[test]
6270 #[ignore]
6271 fn max_guest_log_level_can_be_disabled_and_reenabled() {
6272 use hyperlight_common::log_level::GuestLogFilter;
6273 use hyperlight_testing::logger::{LOGGER, Logger};
6274 use tracing_core::LevelFilter;
6275
6276 Logger::initialize_test_logger();
6277 LOGGER.set_max_level(log::LevelFilter::Trace);
6278
6279 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6280 .guest_log_level(LevelFilter::TRACE)
6281 .build()
6282 .unwrap();
6283 let encoded: u64 = GuestLogFilter::Trace.into();
6284 let count_guest_logs = |sandbox: &mut Sandbox| {
6285 LOGGER.clear_log_calls();
6286 sandbox
6287 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6288 .unwrap();
6289 (0..LOGGER.num_log_calls())
6290 .filter_map(|i| LOGGER.get_log_call(i))
6291 .filter(|call| call.target == "hyperlight_guest")
6292 .count()
6293 };
6294
6295 assert!(count_guest_logs(&mut sandbox) > 0);
6296 sandbox.log_level(LevelFilter::OFF).unwrap();
6297 assert_eq!(count_guest_logs(&mut sandbox), 0);
6298 sandbox.log_level(LevelFilter::TRACE).unwrap();
6299 assert!(count_guest_logs(&mut sandbox) > 0);
6300 }
6301
6302 #[test]
6308 #[ignore]
6309 fn max_guest_log_level_can_be_enabled_after_off_init() {
6310 use hyperlight_common::log_level::GuestLogFilter;
6311 use hyperlight_testing::logger::{LOGGER, Logger};
6312 use tracing_core::LevelFilter;
6313
6314 Logger::initialize_test_logger();
6315 LOGGER.set_max_level(log::LevelFilter::Trace);
6316
6317 let encoded: u64 = GuestLogFilter::Trace.into();
6318 let count_guest_logs = |sandbox: &mut Sandbox| {
6319 LOGGER.clear_log_calls();
6320 sandbox
6321 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
6322 .unwrap();
6323 (0..LOGGER.num_log_calls())
6324 .filter_map(|i| LOGGER.get_log_call(i))
6325 .filter(|call| call.target == "hyperlight_guest")
6326 .count()
6327 };
6328
6329 let mut from_trace = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6330 .guest_log_level(LevelFilter::TRACE)
6331 .build()
6332 .unwrap();
6333 let _ = count_guest_logs(&mut from_trace);
6334 let expected = count_guest_logs(&mut from_trace);
6335
6336 let mut from_off = SandboxBuilder::from_file(simple_guest_as_pathbuf())
6337 .guest_log_level(LevelFilter::OFF)
6338 .build()
6339 .unwrap();
6340 assert_eq!(count_guest_logs(&mut from_off), 0);
6342
6343 from_off.log_level(LevelFilter::TRACE).unwrap();
6344 assert_eq!(count_guest_logs(&mut from_off), expected);
6345 }
6346
6347 #[test]
6351 fn arc_clone_isolation_and_restore_compat() {
6352 let mut sbox = make_sandbox();
6353 sbox.call::<i32>("AddToStatic", 3i32).unwrap();
6354 let snapshot = sbox.snapshot().unwrap();
6355
6356 let mut a = SandboxBuilder::from_snapshot(snapshot.clone())
6357 .build()
6358 .unwrap();
6359 let mut b = SandboxBuilder::from_snapshot(snapshot.clone())
6360 .build()
6361 .unwrap();
6362 super::assert_virtq_attached(&a);
6363 super::assert_virtq_attached(&b);
6364 assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 3);
6365 assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
6366
6367 a.call::<i32>("AddToStatic", 7i32).unwrap();
6368 assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 10);
6369 assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
6370
6371 a.restore(snapshot.clone()).unwrap();
6372 b.restore(snapshot).unwrap();
6373 super::assert_virtq_attached(&a);
6374 super::assert_virtq_attached(&b);
6375 assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 3);
6376 assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
6377 }
6378
6379 #[test]
6380 fn accepts_matching_host_functions() {
6381 let mut sbox = make_sandbox_with_add();
6382 sbox.call::<i32>("AddToStatic", 5i32).unwrap();
6383 let snap = sbox.snapshot().unwrap();
6384 let mut sbox2 = SandboxBuilder::from_snapshot(snap)
6385 .host_functions(host_funcs_with_matching_add())
6386 .build()
6387 .unwrap();
6388 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 5);
6389 }
6390
6391 #[test]
6392 fn rejects_missing_host_function() {
6393 let mut sbox = make_sandbox_with_add();
6394 let snap = sbox.snapshot().unwrap();
6395 let err = SandboxBuilder::from_snapshot(snap)
6396 .build()
6397 .expect_err("missing `Add` must be rejected");
6398 assert!(
6399 matches!(
6400 &err,
6401 HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
6402 if missing.iter().any(|n| n == "Add") && signature_mismatches.is_empty()
6403 ),
6404 "got: {:?}",
6405 err
6406 );
6407 }
6408
6409 #[test]
6415 fn restore_rejects_missing_host_function() {
6416 let mut sbox_with_add = make_sandbox_with_add();
6417 let snap = sbox_with_add.snapshot().unwrap();
6418 let mut sbox_without_add = make_sandbox();
6419 let err = sbox_without_add
6420 .restore(snap)
6421 .expect_err("missing `Add` must be rejected on restore");
6422 assert!(
6423 matches!(
6424 &err,
6425 HyperlightError::SnapshotHostFunctionMismatch { missing, .. }
6426 if missing.iter().any(|n| n == "Add")
6427 ),
6428 "got: {:?}",
6429 err
6430 );
6431 }
6432
6433 #[test]
6436 fn restore_rejects_signature_mismatch() {
6437 let mut sbox_with_add = make_sandbox_with_add();
6438 let snap = sbox_with_add.snapshot().unwrap();
6439 let path = simple_guest_as_pathbuf();
6440 let mut sbox_wrong_add = SandboxBuilder::from_file(path)
6441 .host_function("Add", |a: String, b: String| format!("{a}{b}"))
6442 .build()
6443 .unwrap();
6444 let err = sbox_wrong_add
6445 .restore(snap)
6446 .expect_err("signature mismatch on `Add` must be rejected on restore");
6447 assert!(
6448 matches!(
6449 &err,
6450 HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
6451 if missing.is_empty() && signature_mismatches.iter().any(|s| s.contains("Add"))
6452 ),
6453 "got: {:?}",
6454 err
6455 );
6456 }
6457
6458 #[test]
6461 fn restore_across_sandboxes_with_superset_host_funcs() {
6462 let mut source = make_sandbox_with_add();
6463 source.call::<i32>("AddToStatic", 17i32).unwrap();
6464 let snap = source.snapshot().unwrap();
6465
6466 let path = simple_guest_as_pathbuf();
6467 let mut target = SandboxBuilder::from_file(path)
6468 .host_function("Add", |a: i32, b: i32| a + b)
6469 .host_function("Mul", |a: i32, b: i32| a * b)
6470 .build()
6471 .unwrap();
6472
6473 target.restore(snap).unwrap();
6474 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 17);
6475 }
6476
6477 #[test]
6478 fn rejects_signature_mismatch() {
6479 let mut sbox = make_sandbox_with_add();
6480 let snap = sbox.snapshot().unwrap();
6481 let mut hf = HostFunctions::default();
6482 hf.register_host_function("Add", |a: String, b: String| Ok(format!("{a}{b}")))
6483 .unwrap();
6484 let err = SandboxBuilder::from_snapshot(snap)
6485 .host_functions(hf)
6486 .build()
6487 .expect_err("signature mismatch on `Add` must be rejected");
6488 assert!(
6489 matches!(
6490 &err,
6491 HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
6492 if missing.is_empty() && signature_mismatches.iter().any(|s| s.contains("Add"))
6493 ),
6494 "got: {:?}",
6495 err
6496 );
6497 }
6498
6499 #[test]
6502 fn accepts_extra_host_functions() {
6503 let mut sbox = make_sandbox_with_add();
6504 sbox.call::<i32>("AddToStatic", 9i32).unwrap();
6505 let snap = sbox.snapshot().unwrap();
6506 let mut hf = host_funcs_with_matching_add();
6507 hf.register_host_function("Mul", |a: i32, b: i32| Ok(a * b))
6508 .unwrap();
6509 let mut sbox2 = SandboxBuilder::from_snapshot(snap)
6510 .host_functions(hf)
6511 .build()
6512 .unwrap();
6513 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 9);
6514 }
6515
6516 #[test]
6519 fn re_snapshot_after_from_snapshot() {
6520 let mut sbox = make_sandbox();
6521 sbox.call::<i32>("AddToStatic", 4i32).unwrap();
6522 let snap1 = sbox.snapshot().unwrap();
6523
6524 let mut sbox2 = SandboxBuilder::from_snapshot(snap1).build().unwrap();
6525 sbox2.call::<i32>("AddToStatic", 6i32).unwrap();
6526 let snap2 = sbox2.snapshot().unwrap();
6527
6528 sbox2.call::<i32>("AddToStatic", 100i32).unwrap();
6529 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 110);
6530
6531 sbox2.restore(snap2.clone()).unwrap();
6532 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 10);
6533
6534 let mut sbox3 = SandboxBuilder::from_snapshot(snap2).build().unwrap();
6535 assert_eq!(sbox3.call::<i32>("GetStatic", ()).unwrap(), 10);
6536 }
6537
6538 #[test]
6541 fn supplied_host_function_is_callable() {
6542 let path = simple_guest_as_pathbuf();
6543 let mut sbox = SandboxBuilder::from_file(path)
6544 .host_function("Echo42", || 1i64)
6545 .build()
6546 .unwrap();
6547 let snap = sbox.snapshot().unwrap();
6548
6549 let mut hf = HostFunctions::default();
6550 hf.register_host_function("Echo42", || Ok(42i64)).unwrap();
6551 let mut sbox2 = SandboxBuilder::from_snapshot(snap)
6552 .host_functions(hf)
6553 .build()
6554 .unwrap();
6555
6556 let got: i64 = sbox2
6557 .call(
6558 "CallGivenParamlessHostFuncThatReturnsI64",
6559 "Echo42".to_string(),
6560 )
6561 .unwrap();
6562 assert_eq!(got, 42);
6563 }
6564
6565 #[test]
6568 fn pre_init_snapshot_accepts_arbitrary_host_functions() {
6569 let path = simple_guest_as_pathbuf();
6570 let snap =
6571 Snapshot::from_env(GuestBinary::FilePath(path), SandboxConfiguration::default())
6572 .unwrap();
6573 let mut hf = HostFunctions::default();
6574 hf.register_host_function("Unrelated", |a: i32| Ok(a + 1))
6575 .unwrap();
6576 let mut sbox = SandboxBuilder::from_snapshot(Arc::new(snap))
6577 .host_functions(hf)
6578 .build()
6579 .unwrap();
6580 assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 0);
6581 }
6582
6583 #[test]
6587 fn snapshot_generation_propagates() {
6588 let mut sbox = make_sandbox();
6589 sbox.call::<i32>("AddToStatic", 1i32).unwrap();
6590 let snap1 = sbox.snapshot().unwrap();
6591 let gen1 = snap1.snapshot_generation();
6592 sbox.call::<i32>("AddToStatic", 1i32).unwrap();
6593 let snap2 = sbox.snapshot().unwrap();
6594 let gen2 = snap2.snapshot_generation();
6595 assert_eq!(gen2, gen1 + 1);
6596
6597 let mut sbox2 = SandboxBuilder::from_snapshot(snap2).build().unwrap();
6598 sbox2.call::<i32>("AddToStatic", 1i32).unwrap();
6599 let snap3 = sbox2.snapshot().unwrap();
6600 assert_eq!(snap3.snapshot_generation(), gen2 + 1);
6601 }
6602
6603 #[test]
6608 fn late_register_invalidates_snapshot_cache() {
6609 let mut sbox = make_sandbox();
6610 let _ = sbox.snapshot().unwrap();
6612
6613 sbox.register_host_function("Echo42", || Ok(42i64)).unwrap();
6614
6615 let snap = sbox.snapshot().unwrap();
6619 let err = SandboxBuilder::from_snapshot(snap)
6620 .build()
6621 .expect_err("late-registered `Echo42` must be required by the new snapshot");
6622 let msg = format!("{}", err);
6623 assert!(msg.contains("Echo42"), "got: {}", msg);
6624 }
6625 }
6626}