1use std::path::Path;
5#[cfg(crashdump)]
6use std::path::PathBuf;
7use std::sync::{Arc, Mutex};
8
9use hyperlight_common::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
10use hyperlight_common::flatbuffer_wrappers::function_types::{
11 ParameterValue, ReturnType, ReturnValue,
12};
13use tracing::{Span, instrument};
14use tracing_core::LevelFilter;
15
16use super::Callable;
17use super::file_mapping::prepare_file_cow;
18use super::host_funcs::FunctionRegistry;
19use super::snapshot::Snapshot;
20use crate::func::{ParameterTuple, SupportedReturnType};
21use crate::hypervisor::InterruptHandle;
22use crate::hypervisor::hyperlight_vm::{HyperlightVm, HyperlightVmError};
23use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags};
24use crate::mem::mgr::{ExecutionMode, SandboxMemoryManager};
25use crate::mem::shared_mem::{HostSharedMemory, SharedMemory as _};
26use crate::metrics::{
27 METRIC_GUEST_ERROR, METRIC_GUEST_ERROR_LABEL_CODE, maybe_time_and_emit_guest_call,
28};
29use crate::{HyperlightError, Result, log_then_return};
30
31#[derive(Clone, Copy, Debug, Eq, PartialEq)]
33pub enum SandboxStatus {
34 Ready,
36 Poisoned,
38 Unrecoverable,
40}
41
42impl SandboxStatus {
43 pub const fn is_ready(self) -> bool {
45 matches!(self, Self::Ready)
46 }
47
48 pub const fn is_poisoned(self) -> bool {
50 matches!(self, Self::Poisoned)
51 }
52
53 pub const fn is_unrecoverable(self) -> bool {
55 matches!(self, Self::Unrecoverable)
56 }
57}
58
59pub struct Sandbox {
82 status: SandboxStatus,
83 pub(crate) host_funcs: Arc<Mutex<FunctionRegistry>>,
84 pub(crate) mem_mgr: SandboxMemoryManager<HostSharedMemory>,
85 vm: HyperlightVm,
86 pub(crate) snapshot: Option<Arc<Snapshot>>,
89 transport_dirty: bool,
91 pt_root_finder: Option<PtRootFinder>,
95 max_guest_log_level: Option<LevelFilter>,
97}
98
99#[deprecated(since = "0.18.0", note = "use Sandbox")]
101pub type MultiUseSandbox = Sandbox;
102
103pub type PtRootFinder = Box<dyn Fn(&[u8], &[u8], u64) -> Vec<u64> + Send>;
114
115impl Sandbox {
116 fn check_ready(&self) -> Result<()> {
117 match self.status {
118 SandboxStatus::Ready => Ok(()),
119 SandboxStatus::Poisoned => Err(HyperlightError::PoisonedSandbox),
120 SandboxStatus::Unrecoverable => Err(HyperlightError::UnrecoverableSandbox),
121 }
122 }
123
124 fn poison(&mut self) {
125 if self.status.is_ready() {
126 self.status = SandboxStatus::Poisoned;
127 }
128 }
129
130 #[instrument(skip_all, parent = Span::current(), level = "Trace")]
136 pub(super) fn from_uninit(
137 host_funcs: Arc<Mutex<FunctionRegistry>>,
138 mgr: SandboxMemoryManager<HostSharedMemory>,
139 vm: HyperlightVm,
140 ) -> Sandbox {
141 let transport_dirty = matches!(mgr.next_action, super::snapshot::NextAction::Initialise(_));
143
144 Self {
145 status: SandboxStatus::Ready,
146 host_funcs,
147 mem_mgr: mgr,
148 vm,
149 snapshot: None,
150 transport_dirty,
151 pt_root_finder: None,
152 max_guest_log_level: None,
153 }
154 }
155
156 pub fn log_level(&mut self, log_level: LevelFilter) -> Result<()> {
160 self.check_ready()?;
161 self.mem_mgr.request_guest_log_level_update(log_level)?;
162 self.max_guest_log_level = Some(log_level);
163 Ok(())
164 }
165
166 pub fn set_pt_root_finder(&mut self, finder: PtRootFinder) {
172 self.pt_root_finder = Some(finder);
173 }
174
175 #[instrument(err(Debug), skip_all, parent = Span::current(), level = "Trace")]
241 pub fn from_snapshot(
242 snapshot: Arc<Snapshot>,
243 host_funcs: crate::HostFunctions,
244 config: Option<crate::sandbox::SandboxConfiguration>,
245 ) -> Result<Self> {
246 use rand::RngExt;
247
248 use crate::mem::ptr::RawPtr;
249 use crate::sandbox::uninitialized_evolve::set_up_hypervisor_partition;
250
251 snapshot.validate_host_functions(host_funcs.inner())?;
254
255 let host_funcs = Arc::new(Mutex::new(host_funcs.into_inner()));
256
257 let stack_top_gva = snapshot.stack_top_gva();
258 let caller_supplied_config = config.is_some();
266 let mut config = config.unwrap_or_default();
267 if caller_supplied_config {
268 warn_on_layout_override(&config, snapshot.layout());
269 }
270 config.set_heap_size(snapshot.layout().heap_size() as u64);
271 config.set_scratch_size(snapshot.layout().get_scratch_size());
272 config.set_g2h_queue_size(snapshot.layout().get_g2h_queue_size());
273 config.set_h2g_queue_size(snapshot.layout().get_h2g_queue_size());
274 config.set_g2h_buffer_size(snapshot.layout().get_g2h_buffer_size());
275 config.set_h2g_buffer_size(snapshot.layout().get_h2g_buffer_size());
276 config.set_g2h_pool_pages(snapshot.layout().get_g2h_pool_pages());
277 config.set_h2g_pool_pages(snapshot.layout().get_h2g_pool_pages());
278 let max_guest_log_level = config.get_max_guest_log_level();
279 let load_info = snapshot.load_info();
280
281 let mgr = crate::mem::mgr::SandboxMemoryManager::from_snapshot(&snapshot)?;
282 let (mut hshm, gshm) = mgr.build()?;
283 let restore_virtq = matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_));
284
285 let page_size = u32::try_from(page_size::get())? as usize;
286
287 #[cfg(target_os = "linux")]
288 crate::signal_handlers::setup_signal_handlers(&config)?;
289
290 #[cfg(any(crashdump, gdb))]
296 let rt_cfg = crate::sandbox::uninitialized::SandboxRuntimeConfig {
297 #[cfg(crashdump)]
298 binary_path: None,
299 #[cfg(gdb)]
300 debug_info: config.get_guest_debug_info(),
301 #[cfg(crashdump)]
302 guest_core_dump: config.get_guest_core_dump(),
303 #[cfg(crashdump)]
304 entry_point: None,
305 };
306
307 let mut vm = set_up_hypervisor_partition(
308 gshm,
309 &config,
310 stack_top_gva,
311 page_size,
312 #[cfg(any(crashdump, gdb))]
313 rt_cfg,
314 load_info,
315 )?;
316
317 let seed = {
318 let mut rng = rand::rng();
319 rng.random::<u64>()
320 };
321 let peb_addr = RawPtr::from(u64::try_from(hshm.layout.peb_address())?);
322
323 vm.initialise(peb_addr, seed, &mut hshm, &host_funcs, max_guest_log_level)
326 .map_err(crate::hypervisor::hyperlight_vm::HyperlightVmError::Initialize)?;
327 if matches!(
328 snapshot.next_action(),
329 super::snapshot::NextAction::Initialise(_)
330 ) {
331 hshm.finish_snapshot_checkpoint()?;
332 }
333
334 if matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_)) {
335 hshm.request_libc_rng_reseed(seed as u32)?;
336 }
337
338 if matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_)) {
342 let sregs = snapshot.sregs().ok_or_else(|| {
343 crate::new_error!("snapshot with NextAction::Call must have captured sregs")
344 })?;
345 #[cfg(target_arch = "x86_64")]
346 let msrs = snapshot.msrs().ok_or_else(|| {
347 crate::new_error!("snapshot with NextAction::Call must have captured MSRs")
348 })?;
349 vm.apply_sregs(hshm.layout.get_pt_base_gpa(), sregs)
350 .map_err(|e| {
351 crate::HyperlightError::HyperlightVmError(
352 crate::hypervisor::hyperlight_vm::HyperlightVmError::Restore(e.into()),
353 )
354 })?;
355
356 #[cfg(target_arch = "x86_64")]
358 vm.restore_msrs(msrs).map_err(|e| {
359 crate::HyperlightError::HyperlightVmError(
360 crate::hypervisor::hyperlight_vm::HyperlightVmError::Restore(e),
361 )
362 })?;
363 }
364
365 if restore_virtq {
366 let virtq = snapshot.virtq().ok_or_else(|| {
367 crate::new_error!("running snapshot has no canonical transport state")
368 })?;
369 hshm.restore_virtq(virtq)?;
370 }
371
372 let mut sbox = Sandbox::from_uninit(host_funcs, hshm, vm);
373
374 if let Some(log_level) = max_guest_log_level {
375 sbox.log_level(log_level)?;
376 }
377
378 Ok(sbox)
379 }
380
381 #[instrument(err(Debug), skip_all, parent = Span::current())]
416 pub fn snapshot(&mut self) -> Result<Arc<Snapshot>> {
417 self.check_ready()?;
418
419 if let Some(snapshot) = &self.snapshot {
420 return Ok(snapshot.clone());
421 }
422
423 if self.transport_dirty {
424 self.checkpoint_transport_for_snapshot()?;
425 }
426
427 let mapped_regions_iter = self.vm.get_mapped_regions();
428 let mapped_regions_vec: Vec<MemoryRegion> = mapped_regions_iter.cloned().collect();
429 let cr3 = self
431 .vm
432 .get_root_pt()
433 .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
434 let root_pt_gpas = if let Some(finder) = &self.pt_root_finder {
436 let roots = self.mem_mgr.shared_mem.with_contents(|snap| {
437 self.mem_mgr
438 .scratch_mem
439 .with_contents(|scratch| finder(snap, scratch, cr3))
440 })??;
441 if roots.is_empty() { vec![cr3] } else { roots }
442 } else {
443 vec![cr3]
444 };
445
446 let stack_top_gpa = self.vm.get_stack_top();
447 let sregs = self
448 .vm
449 .get_snapshot_sregs()
450 .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
451 #[cfg(target_arch = "x86_64")]
452 let msrs = self
453 .vm
454 .get_msr_reset_state()
455 .map_err(|e| HyperlightError::HyperlightVmError(e.into()))?;
456 let next_action = self.vm.get_next_action();
457 let host_functions = (&*self.host_funcs.try_lock().map_err(|e| {
458 crate::new_error!("Error locking host_funcs at {}:{}: {}", file!(), line!(), e)
459 })?)
460 .into();
461
462 let memory_snapshot = self.mem_mgr.snapshot(
463 mapped_regions_vec,
464 &root_pt_gpas,
465 stack_top_gpa,
466 sregs,
467 #[cfg(target_arch = "x86_64")]
468 msrs,
469 next_action,
470 host_functions,
471 )?;
472 let snapshot = Arc::new(memory_snapshot);
473 self.snapshot = Some(snapshot.clone());
474 Ok(snapshot)
475 }
476
477 fn checkpoint_transport_for_snapshot(&mut self) -> Result<()> {
478 self.with_guest_execution(|sbox| {
479 sbox.mem_mgr.begin_snapshot_checkpoint()?;
480 sbox.dispatch_guest_call_restricted()?;
481
482 sbox.mem_mgr.finish_snapshot_checkpoint()?;
483
484 sbox.transport_dirty = false;
485 Ok(())
486 })
487 }
488
489 fn restore_memory_and_mappings(&mut self, snapshot: &Snapshot) -> Result<()> {
490 let (snapshot_mem, scratch_mem) = self.mem_mgr.restore_snapshot(snapshot)?;
491 if let Some(snapshot_mem) = snapshot_mem {
492 self.vm
493 .update_snapshot_mapping(snapshot_mem)
494 .map_err(HyperlightVmError::UpdateRegion)?;
495 }
496 if let Some(scratch_mem) = scratch_mem {
497 self.vm
498 .update_scratch_mapping(scratch_mem)
499 .map_err(HyperlightVmError::UpdateRegion)?;
500 }
501 Ok(())
502 }
503
504 #[instrument(err(Debug), skip_all, parent = Span::current())]
593 pub fn restore(&mut self, snapshot: Arc<Snapshot>) -> Result<()> {
594 if self.status.is_unrecoverable() {
595 return Err(HyperlightError::UnrecoverableSandbox);
596 }
597
598 {
622 let host_funcs = self
623 .host_funcs
624 .try_lock()
625 .map_err(|e| crate::new_error!("Error locking host_funcs: {}", e))?;
626 snapshot.validate_host_functions(&host_funcs)?;
627 }
628
629 let sregs = snapshot.sregs().ok_or_else(|| {
630 HyperlightError::Error("snapshot from running sandbox should have sregs".to_string())
631 })?;
632 #[cfg(target_arch = "x86_64")]
633 let msrs = snapshot.msrs().ok_or_else(|| {
634 HyperlightError::Error("snapshot from running sandbox should have MSRs".to_string())
635 })?;
636
637 if snapshot.virtq().is_none()
638 && matches!(snapshot.next_action(), super::snapshot::NextAction::Call(_))
639 {
640 return Err(crate::new_error!(
641 "running snapshot has no canonical transport state"
642 ));
643 }
644
645 self.status = SandboxStatus::Poisoned;
647 self.snapshot = None;
648
649 let current_regions: Vec<MemoryRegion> = self.vm.get_mapped_regions().cloned().collect();
650 for region in ¤t_regions {
651 self.vm
652 .unmap_region(region)
653 .map_err(HyperlightVmError::UnmapRegion)?;
654 }
655
656 if let Err(error) = self.restore_memory_and_mappings(&snapshot) {
657 self.status = SandboxStatus::Unrecoverable;
658 return Err(error);
659 }
660
661 self.vm
663 .reset_vcpu(
664 snapshot.root_pt_gpa(),
665 sregs,
666 #[cfg(target_arch = "x86_64")]
667 msrs,
668 )
669 .map_err(HyperlightVmError::Restore)?;
670
671 self.vm.set_stack_top(snapshot.stack_top_gva());
672 self.vm.set_next_action(snapshot.next_action());
673 #[cfg(crashdump)]
676 {
677 self.vm
678 .set_crashdump_entry_point(snapshot.original_entrypoint());
679 self.vm.clear_crashdump_binary_path();
680 }
681
682 self.mem_mgr
683 .request_libc_rng_reseed(rand::random::<u32>())?;
684 if let Some(log_level) = self.max_guest_log_level {
685 self.mem_mgr.request_guest_log_level_update(log_level)?;
686 }
687
688 self.snapshot = Some(snapshot.clone());
690 self.transport_dirty = false;
691
692 self.status = SandboxStatus::Ready;
702
703 Ok(())
704 }
705
706 #[doc(hidden)]
740 #[deprecated(
741 since = "0.8.0",
742 note = "Deprecated in favour of call and snapshot/restore."
743 )]
744 #[instrument(err(Debug), skip(self, args), parent = Span::current())]
745 pub fn call_guest_function_by_name<Output: SupportedReturnType>(
746 &mut self,
747 func_name: &str,
748 args: impl ParameterTuple,
749 ) -> Result<Output> {
750 self.check_ready()?;
751 let snapshot = self.snapshot()?;
752 let res = self.call(func_name, args);
753 self.restore(snapshot)?;
754 res
755 }
756
757 #[instrument(err(Debug), skip(self, args), parent = Span::current())]
828 pub fn call<Output: SupportedReturnType>(
829 &mut self,
830 func_name: &str,
831 args: impl ParameterTuple,
832 ) -> Result<Output> {
833 self.check_ready()?;
834 self.snapshot = None;
836 maybe_time_and_emit_guest_call(func_name, || {
837 let ret = self.call_guest_function_by_name_no_reset(
838 func_name,
839 Output::TYPE,
840 args.into_value(),
841 );
842 let ret = Output::from_value(ret?)?;
845 Ok(ret)
846 })
847 }
848
849 #[instrument(err(Debug), skip(self, rgn), parent = Span::current())]
865 pub unsafe fn map_region(&mut self, rgn: &MemoryRegion) -> Result<()> {
866 self.check_ready()?;
867 if rgn.flags.contains(MemoryRegionFlags::WRITE) {
868 log_then_return!("TODO: Writable mappings not yet supported");
872 }
873
874 unsafe { self.vm.map_region(rgn) }.map_err(HyperlightVmError::MapRegion)?;
876 self.snapshot = None;
877 Ok(())
878 }
879
880 #[instrument(err(Debug), skip(self, file_path, guest_base), parent = Span::current())]
889 pub fn map_file_cow(&mut self, file_path: &Path, guest_base: u64) -> Result<u64> {
890 self.check_ready()?;
891
892 let mut prepared = prepare_file_cow(file_path, guest_base)?;
894
895 let shared_size = self.mem_mgr.shared_mem.mem_size() as u64;
898 let base_addr = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
899 let shared_end = base_addr.checked_add(shared_size).ok_or_else(|| {
900 crate::HyperlightError::Error("shared memory end overflow".to_string())
901 })?;
902 let mapping_end = guest_base
903 .checked_add(prepared.size as u64)
904 .ok_or_else(|| {
905 crate::HyperlightError::Error(format!(
906 "map_file_cow: guest address overflow: {:#x} + {:#x}",
907 guest_base, prepared.size
908 ))
909 })?;
910 if guest_base < shared_end && mapping_end > base_addr {
911 return Err(crate::HyperlightError::Error(format!(
912 "map_file_cow: mapping [{:#x}..{:#x}) overlaps sandbox shared memory [{:#x}..{:#x})",
913 guest_base, mapping_end, base_addr, shared_end,
914 )));
915 }
916
917 let region = prepared.to_memory_region()?;
919
920 unsafe { self.vm.map_region(®ion) }
921 .map_err(HyperlightVmError::MapRegion)
922 .map_err(crate::HyperlightError::HyperlightVmError)?;
923
924 self.snapshot = None;
925
926 let size = prepared.size as u64;
927
928 prepared.mark_consumed();
936
937 Ok(size)
938 }
939
940 #[cfg(feature = "fuzzing")]
949 #[instrument(err(Debug), skip(self, args), parent = Span::current())]
950 pub fn call_type_erased_guest_function_by_name(
951 &mut self,
952 func_name: &str,
953 ret_type: ReturnType,
954 args: Vec<ParameterValue>,
955 ) -> Result<ReturnValue> {
956 self.check_ready()?;
957 self.snapshot = None;
959 maybe_time_and_emit_guest_call(func_name, || {
960 self.call_guest_function_by_name_no_reset(func_name, ret_type, args)
961 })
962 }
963
964 fn call_guest_function_by_name_no_reset(
965 &mut self,
966 function_name: &str,
967 return_type: ReturnType,
968 args: Vec<ParameterValue>,
969 ) -> Result<ReturnValue> {
970 self.check_ready()?;
971 self.with_guest_execution(|sbox| {
972 sbox.transport_dirty = true;
973
974 let fc = FunctionCall::new(
975 function_name.to_string(),
976 Some(args),
977 FunctionCallType::Guest,
978 return_type,
979 );
980
981 let cid = sbox.mem_mgr.write_guest_function_call(&fc)?;
982 sbox.dispatch_guest_call()?;
983
984 let guest_result = sbox.mem_mgr.read_h2g_result_from_g2h(cid)?.into_inner();
985
986 match guest_result {
987 Ok(val) => Ok(val),
988 Err(guest_error) => {
989 metrics::counter!(
990 METRIC_GUEST_ERROR,
991 METRIC_GUEST_ERROR_LABEL_CODE => (guest_error.code as u64).to_string()
992 )
993 .increment(1);
994
995 Err(HyperlightError::GuestError(
996 guest_error.code,
997 guest_error.message,
998 ))
999 }
1000 }
1001 })
1002 }
1003
1004 fn with_guest_execution<T>(&mut self, op: impl FnOnce(&mut Self) -> Result<T>) -> Result<T> {
1005 self.vm.clear_cancel();
1009 let result = op(self);
1010 self.mem_mgr.abort_buffer.clear();
1011
1012 if result.as_ref().is_err_and(HyperlightError::is_poison_error) {
1013 self.poison();
1014 }
1015
1016 result
1017 }
1018
1019 fn dispatch_guest_call(&mut self) -> Result<()> {
1020 self.vm
1021 .dispatch_call_from_host(&mut self.mem_mgr, &self.host_funcs)
1022 .map_err(|error| {
1023 let (error, should_poison) = error.promote();
1024 if should_poison {
1025 self.poison();
1026 }
1027 error
1028 })
1029 }
1030
1031 fn dispatch_guest_call_restricted(&mut self) -> Result<()> {
1033 let mode = std::mem::replace(&mut self.mem_mgr.execution_mode, ExecutionMode::Restricted);
1034 let res = self.dispatch_guest_call();
1035 self.mem_mgr.execution_mode = mode;
1036
1037 res
1038 }
1039
1040 pub fn interrupt_handle(&self) -> Arc<dyn InterruptHandle> {
1067 self.vm.interrupt_handle()
1068 }
1069
1070 #[cfg(crashdump)]
1106 #[instrument(err(Debug), skip_all, parent = Span::current())]
1107 pub fn generate_crashdump(&mut self) -> Result<()> {
1108 crate::hypervisor::crashdump::generate_crashdump(&self.vm, &mut self.mem_mgr, None)
1109 }
1110
1111 #[cfg(crashdump)]
1118 #[instrument(err(Debug), skip_all, parent = Span::current())]
1119 pub fn generate_crashdump_to_dir(&mut self, dir: impl Into<PathBuf>) -> Result<()> {
1120 crate::hypervisor::crashdump::generate_crashdump(
1121 &self.vm,
1122 &mut self.mem_mgr,
1123 Some(dir.into()),
1124 )
1125 }
1126
1127 #[deprecated(since = "0.17.0", note = "use status().is_poisoned()")]
1159 pub fn poisoned(&self) -> bool {
1160 self.status.is_poisoned()
1161 }
1162
1163 pub fn status(&self) -> SandboxStatus {
1171 self.status
1172 }
1173}
1174
1175impl Callable for Sandbox {
1176 fn call<Output: SupportedReturnType>(
1177 &mut self,
1178 func_name: &str,
1179 args: impl ParameterTuple,
1180 ) -> Result<Output> {
1181 self.check_ready()?;
1182 self.call(func_name, args)
1183 }
1184}
1185
1186impl std::fmt::Debug for Sandbox {
1187 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1188 f.debug_struct("Sandbox").finish()
1189 }
1190}
1191
1192fn warn_on_layout_override(
1197 caller: &crate::sandbox::SandboxConfiguration,
1198 snapshot: &crate::mem::layout::SandboxMemoryLayout,
1199) {
1200 let mismatches: &[(&str, u64, u64)] = &[
1201 (
1202 "heap_size",
1203 caller.get_heap_size(),
1204 snapshot.heap_size() as u64,
1205 ),
1206 (
1207 "scratch_size",
1208 caller.get_scratch_size() as u64,
1209 snapshot.get_scratch_size() as u64,
1210 ),
1211 (
1212 "g2h_queue_size",
1213 caller.get_g2h_queue_size() as u64,
1214 snapshot.get_g2h_queue_size() as u64,
1215 ),
1216 (
1217 "h2g_queue_size",
1218 caller.get_h2g_queue_size() as u64,
1219 snapshot.get_h2g_queue_size() as u64,
1220 ),
1221 (
1222 "g2h_buffer_size",
1223 caller.get_g2h_buffer_size() as u64,
1224 snapshot.get_g2h_buffer_size() as u64,
1225 ),
1226 (
1227 "h2g_buffer_size",
1228 caller.get_h2g_buffer_size() as u64,
1229 snapshot.get_h2g_buffer_size() as u64,
1230 ),
1231 (
1232 "g2h_pool_pages",
1233 caller.get_g2h_pool_pages() as u64,
1234 snapshot.get_g2h_pool_pages() as u64,
1235 ),
1236 (
1237 "h2g_pool_pages",
1238 caller.get_h2g_pool_pages() as u64,
1239 snapshot.get_h2g_pool_pages() as u64,
1240 ),
1241 ];
1242 for (name, supplied, snap) in mismatches {
1243 if supplied != snap {
1244 tracing::warn!(
1245 "from_snapshot ignoring caller-supplied {} ({}); using snapshot value ({})",
1246 name,
1247 supplied,
1248 snap
1249 );
1250 }
1251 }
1252}
1253
1254#[cfg(test)]
1255mod tests {
1256 use std::sync::{Arc, Barrier};
1257 use std::thread;
1258
1259 use hyperlight_common::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
1260 use hyperlight_common::flatbuffer_wrappers::function_types::ParameterValue;
1261 use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
1262 use hyperlight_common::func::{Bytes, SupportedReturnType};
1263 use hyperlight_testing::sandbox_sizes::{LARGE_HEAP_SIZE, MEDIUM_HEAP_SIZE, SMALL_HEAP_SIZE};
1264 use hyperlight_testing::{c_simple_guest_as_pathbuf, simple_guest_as_pathbuf};
1265
1266 use crate::func::host_functions::Registerable;
1267 #[cfg(not(gdb))]
1268 use crate::hypervisor::hyperlight_vm::test_support::VmOperation;
1269 use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags, MemoryRegionType};
1270 use crate::mem::mgr::ExecutionMode;
1271 use crate::mem::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, SharedMemory as _};
1272 use crate::sandbox::SandboxConfiguration;
1273 use crate::sandbox::uninitialized::{GuestBlob, GuestEnvironment};
1274 use crate::{
1275 GuestBinary, HyperlightError, Result, Sandbox, SandboxBuilder, SandboxStatus,
1276 UninitializedSandbox,
1277 };
1278
1279 #[test]
1280 fn sandbox_status_predicates() {
1281 assert!(SandboxStatus::Ready.is_ready());
1282 assert!(!SandboxStatus::Ready.is_poisoned());
1283 assert!(!SandboxStatus::Ready.is_unrecoverable());
1284
1285 assert!(!SandboxStatus::Poisoned.is_ready());
1286 assert!(SandboxStatus::Poisoned.is_poisoned());
1287 assert!(!SandboxStatus::Poisoned.is_unrecoverable());
1288
1289 assert!(!SandboxStatus::Unrecoverable.is_ready());
1290 assert!(!SandboxStatus::Unrecoverable.is_poisoned());
1291 assert!(SandboxStatus::Unrecoverable.is_unrecoverable());
1292 }
1293
1294 fn assert_virtq_attached(sbox: &Sandbox) {
1295 assert!(sbox.mem_mgr.g2h_consumer.is_some());
1296 assert!(sbox.mem_mgr.h2g_consumer.is_some());
1297 }
1298
1299 #[test]
1300 fn poison() {
1301 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1302 .build()
1303 .unwrap();
1304 let snapshot = sbox.snapshot().unwrap();
1305
1306 let res = sbox
1308 .call::<()>("guest_panic", "hello".to_string())
1309 .unwrap_err();
1310 assert!(
1311 matches!(res, HyperlightError::GuestAborted(code, context) if code == ErrorCode::UnknownError as u8 && context.contains("hello"))
1312 );
1313 assert!(sbox.status().is_poisoned());
1314
1315 let res = sbox
1317 .call::<()>("guest_panic", "hello2".to_string())
1318 .unwrap_err();
1319 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1320
1321 if let Err(e) = sbox.snapshot() {
1323 assert!(sbox.status().is_poisoned());
1324 assert!(matches!(e, HyperlightError::PoisonedSandbox));
1325 } else {
1326 panic!("Snapshot should fail");
1327 }
1328
1329 {
1331 let map_mem = allocate_guest_memory();
1332 let guest_base = 0x0;
1333 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
1334 let res = unsafe { sbox.map_region(®ion) }.unwrap_err();
1335 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1336 }
1337
1338 {
1340 let temp_file = std::env::temp_dir().join("test_poison_map_file.bin");
1341 let res = sbox.map_file_cow(&temp_file, 0x0).unwrap_err();
1342 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1343 std::fs::remove_file(&temp_file).ok(); }
1345
1346 #[allow(deprecated)]
1348 let res = sbox
1349 .call_guest_function_by_name::<String>("Echo", "test".to_string())
1350 .unwrap_err();
1351 assert!(matches!(res, HyperlightError::PoisonedSandbox));
1352
1353 sbox.restore(snapshot.clone()).unwrap();
1355 assert_eq!(sbox.status(), SandboxStatus::Ready);
1356
1357 let res = sbox.call::<String>("Echo", "hello2".to_string()).unwrap();
1359 assert_eq!(res, "hello2".to_string());
1360 assert_eq!(sbox.status(), SandboxStatus::Ready);
1361
1362 let res = sbox
1364 .call::<()>("guest_panic", "hello".to_string())
1365 .unwrap_err();
1366 assert!(
1367 matches!(res, HyperlightError::GuestAborted(code, context) if code == ErrorCode::UnknownError as u8 && context.contains("hello"))
1368 );
1369 assert!(sbox.status().is_poisoned());
1370
1371 sbox.restore(snapshot.clone()).unwrap();
1373 assert_eq!(sbox.status(), SandboxStatus::Ready);
1374
1375 let res = sbox.call::<String>("Echo", "hello3".to_string()).unwrap();
1377 assert_eq!(res, "hello3".to_string());
1378 assert_eq!(sbox.status(), SandboxStatus::Ready);
1379
1380 let _ = sbox.snapshot().unwrap();
1382 }
1383
1384 #[test]
1386 fn host_func_error() {
1387 let path = simple_guest_as_pathbuf();
1388 let mut sandbox = SandboxBuilder::from_file(path)
1389 .host_function("HostError", || -> Result<()> {
1390 Err(HyperlightError::Error("hi".to_string()))
1391 })
1392 .build()
1393 .unwrap();
1394
1395 for _ in 0..1000 {
1397 let result = sandbox
1398 .call::<i64>(
1399 "CallGivenParamlessHostFuncThatReturnsI64",
1400 "HostError".to_string(),
1401 )
1402 .unwrap_err();
1403
1404 assert!(
1405 matches!(result, HyperlightError::GuestError(code, msg) if code == ErrorCode::HostFunctionError && msg == "hi"),
1406 );
1407 }
1408 }
1409
1410 #[test]
1411 fn call_host_func_expect_error() {
1412 let path = simple_guest_as_pathbuf();
1413 let mut sandbox = SandboxBuilder::from_file(path).build().unwrap();
1414 sandbox
1415 .call::<()>("CallHostExpectError", "SomeUnknownHostFunc".to_string())
1416 .unwrap();
1417 }
1418
1419 #[test]
1421 fn transport_buffers_are_reclaimed() {
1422 let path = simple_guest_as_pathbuf();
1423 let mut sandbox = SandboxBuilder::from_file(path)
1424 .host_function("HostAdd", |a: i32, b: i32| a + b)
1425 .build()
1426 .unwrap();
1427
1428 for _ in 0..1000 {
1430 let result = sandbox.call::<i32>("Add", (5i32, 10i32)).unwrap();
1431 assert_eq!(result, 15);
1432 let result = sandbox.call::<i32>("AddToStaticAndFail", ()).unwrap_err();
1433 assert!(
1434 matches!(result, HyperlightError::GuestError (code, msg ) if code == ErrorCode::GuestError && msg == "Crash on purpose")
1435 );
1436 }
1437 }
1438
1439 #[test]
1441 fn test_call_guest_function_by_name() {
1442 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1443 .build()
1444 .unwrap();
1445
1446 let snapshot = sbox.snapshot().unwrap();
1447
1448 let _ = sbox.call::<i32>("AddToStatic", 5i32).unwrap();
1449 let res: i32 = sbox.call("GetStatic", ()).unwrap();
1450 assert_eq!(res, 5);
1451
1452 sbox.restore(snapshot).unwrap();
1453 #[allow(deprecated)]
1454 let _ = sbox
1455 .call_guest_function_by_name::<i32>("AddToStatic", 5i32)
1456 .unwrap();
1457 #[allow(deprecated)]
1458 let res: i32 = sbox.call_guest_function_by_name("GetStatic", ()).unwrap();
1459 assert_eq!(res, 0);
1460 }
1461
1462 #[test]
1465 fn test_with_small_stack_and_heap() {
1466 const HEAP_SIZE: u64 = 128 * 1024;
1467 let scratch_size = {
1469 let defaults = SandboxConfiguration::default();
1470 let layout =
1471 crate::mem::layout::SandboxMemoryLayout::new(defaults, 0, 0, None).unwrap();
1472 hyperlight_common::layout::min_scratch_size(layout.get_transport_arena().size())
1473 .next_multiple_of(page_size::get())
1474 } + 0x40000;
1475
1476 let mut sbox1 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1477 .heap_size(HEAP_SIZE)
1478 .scratch_size(scratch_size)
1479 .build()
1480 .unwrap();
1481
1482 for _ in 0..1000 {
1483 sbox1.call::<String>("Echo", "hello".to_string()).unwrap();
1484 }
1485
1486 let mut sbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1487 .heap_size(HEAP_SIZE)
1488 .scratch_size(scratch_size)
1489 .build()
1490 .unwrap();
1491
1492 for i in 0..1000 {
1493 sbox2
1494 .call::<i32>(
1495 "PrintUsingPrintf",
1496 format!("Hello World {}\n", i).to_string(),
1497 )
1498 .unwrap();
1499 }
1500 }
1501
1502 #[test]
1505 fn snapshot_evolve_restore_handles_state_correctly() {
1506 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1507 .build()
1508 .unwrap();
1509
1510 let snapshot = sbox.snapshot().unwrap();
1511
1512 let _ = sbox.call::<i32>("AddToStatic", 5i32).unwrap();
1513
1514 let res: i32 = sbox.call("GetStatic", ()).unwrap();
1515 assert_eq!(res, 5);
1516
1517 sbox.restore(snapshot).unwrap();
1518 let res: i32 = sbox.call("GetStatic", ()).unwrap();
1519 assert_eq!(res, 0);
1520 }
1521
1522 #[test]
1523 fn snapshots_checkpoint_only_dirty_transport() {
1524 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1525 .build()
1526 .unwrap();
1527
1528 assert!(sandbox.transport_dirty);
1529 let initial = sandbox.snapshot().unwrap();
1530 assert!(!sandbox.transport_dirty);
1531
1532 let restored = SandboxBuilder::from_snapshot(initial).build().unwrap();
1533 assert!(!restored.transport_dirty);
1534
1535 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
1536 assert!(sandbox.transport_dirty);
1537
1538 let first = sandbox.snapshot().unwrap();
1539 assert!(!sandbox.transport_dirty);
1540 let cached = sandbox.snapshot().unwrap();
1541 assert!(Arc::ptr_eq(&first, &cached));
1542 assert!(!sandbox.transport_dirty);
1543
1544 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
1545 assert!(sandbox.transport_dirty);
1546 sandbox.snapshot().unwrap();
1547 assert!(!sandbox.transport_dirty);
1548 }
1549
1550 #[test]
1551 fn snapshots_reject_noncanonical_transport_after_checkpoint() {
1552 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1553 .build()
1554 .unwrap();
1555
1556 sandbox.checkpoint_transport_for_snapshot().unwrap();
1557 sandbox.snapshot = None;
1558
1559 let generation = sandbox.mem_mgr.snapshot_count;
1560 let ring = sandbox.mem_mgr.layout.get_transport_arena().g2h_ring_addr();
1561 let offset = sandbox
1562 .mem_mgr
1563 .layout
1564 .resolve_gpa(ring, &[])
1565 .unwrap()
1566 .offset;
1567
1568 sandbox.mem_mgr.scratch_mem.write::<u64>(offset, 1).unwrap();
1569
1570 let Err(error) = sandbox.snapshot() else {
1571 panic!("expected invalid canonical transport");
1572 };
1573
1574 assert!(
1575 error.to_string().contains("invalid canonical G2H image"),
1576 "{error}"
1577 );
1578 assert_eq!(sandbox.mem_mgr.snapshot_count, generation);
1579 assert!(sandbox.snapshot.is_none());
1580
1581 sandbox.mem_mgr.scratch_mem.write::<u64>(offset, 0).unwrap();
1583 let expected = vec![0x5a; 2 * hyperlight_common::vmem::PAGE_SIZE + 137];
1584 let actual: Vec<u8> = sandbox.call("EchoGuestVecBytes", expected.clone()).unwrap();
1585 assert_eq!(actual, expected);
1586 }
1587
1588 #[test]
1589 fn snapshot_checkpoint_ignores_idle_cancellation() {
1590 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1591 .build()
1592 .unwrap();
1593
1594 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
1595 assert!(!sandbox.interrupt_handle().kill());
1596
1597 sandbox.snapshot().unwrap();
1598 assert_eq!(sandbox.status(), SandboxStatus::Ready);
1599 assert!(!sandbox.transport_dirty);
1600 assert!(!sandbox.interrupt_handle().kill());
1601 assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 5);
1602 }
1603
1604 #[test]
1605 fn snapshot_checkpoint_clears_partial_abort_bytes() {
1606 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1607 .build()
1608 .unwrap();
1609
1610 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
1611 sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
1612
1613 sandbox.snapshot().unwrap();
1614
1615 assert!(sandbox.mem_mgr.abort_buffer.is_empty());
1616 assert_eq!(sandbox.status(), SandboxStatus::Ready);
1617 }
1618
1619 #[test]
1620 fn restricted_dispatch_rejects_host_calls() {
1621 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1622 .build()
1623 .unwrap();
1624
1625 let call = FunctionCall::new(
1626 "PrintOutput".into(),
1627 Some(vec![ParameterValue::String("checkpoint".into())]),
1628 FunctionCallType::Guest,
1629 i32::TYPE,
1630 );
1631 sandbox.mem_mgr.write_guest_function_call(&call).unwrap();
1632
1633 let error = sandbox.dispatch_guest_call_restricted().unwrap_err();
1634
1635 assert!(
1636 error.to_string().contains("during a snapshot checkpoint"),
1637 "{error}"
1638 );
1639 assert_eq!(sandbox.status(), SandboxStatus::Poisoned);
1640 assert_eq!(sandbox.mem_mgr.execution_mode, ExecutionMode::Unrestricted);
1641 }
1642
1643 #[test]
1644 fn restore_resets_execution_mode() {
1645 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1646 .build()
1647 .unwrap();
1648
1649 let snapshot = sandbox.snapshot().unwrap();
1650 sandbox.mem_mgr.execution_mode = ExecutionMode::Restricted;
1651 sandbox.restore(snapshot).unwrap();
1652
1653 sandbox
1654 .call::<i32>("PrintOutput", "restored".to_string())
1655 .unwrap();
1656 }
1657
1658 #[test]
1659 fn guest_execution_preserves_pre_entry_cancellation() {
1660 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1661 .build()
1662 .unwrap();
1663 sandbox.call::<i32>("AddToStatic", 5i32).unwrap();
1664 sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
1665
1666 let error = sandbox
1667 .with_guest_execution(|sandbox| {
1668 sandbox.mem_mgr.begin_snapshot_checkpoint()?;
1669 assert!(!sandbox.interrupt_handle().kill());
1670 sandbox.dispatch_guest_call()
1671 })
1672 .unwrap_err();
1673
1674 assert!(matches!(error, HyperlightError::ExecutionCanceledByHost()));
1675 assert_eq!(sandbox.status(), SandboxStatus::Poisoned);
1676 assert!(sandbox.mem_mgr.abort_buffer.is_empty());
1677 }
1678
1679 #[test]
1680 fn snapshots_preserve_retained_transport_and_clear_abort_state() {
1681 let path = simple_guest_as_pathbuf();
1682 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
1683 sandbox
1684 .register("HostEchoByteChunks", |value: Vec<Bytes>| value)
1685 .unwrap();
1686
1687 let mut sandbox = sandbox.evolve().unwrap();
1688 let retained = vec![Bytes::from(vec![0xa5; 6 * 1024])];
1689
1690 for (retain, release) in [
1691 ("RetainGuestByteChunks", "ReleaseGuestByteChunks"),
1692 ("RetainHostByteChunks", "ReleaseHostByteChunks"),
1693 ] {
1694 let retained_len: i32 = sandbox.call(retain, retained.clone()).unwrap();
1695 assert_eq!(retained_len, 6 * 1024);
1696 sandbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 8]);
1697
1698 let snapshot = sandbox.snapshot().unwrap();
1699 assert!(!sandbox.status().is_poisoned());
1700 assert!(!sandbox.transport_dirty);
1701 assert!(sandbox.mem_mgr.abort_buffer.is_empty());
1702
1703 assert_eq!(sandbox.call::<i32>(release, ()).unwrap(), retained_len);
1704
1705 sandbox.restore(snapshot).unwrap();
1706 assert_eq!(sandbox.call::<i32>(release, ()).unwrap(), retained_len);
1707 sandbox.snapshot().unwrap();
1708 assert!(!sandbox.transport_dirty);
1709 }
1710 }
1711
1712 #[test]
1713 fn retained_restore_is_ready_for_first_request() {
1714 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1715 .build()
1716 .unwrap();
1717 sandbox
1718 .call::<i32>(
1719 "RetainGuestByteChunks",
1720 vec![Bytes::from(vec![0x5a; 6 * 1024])],
1721 )
1722 .unwrap();
1723 sandbox.checkpoint_transport_for_snapshot().unwrap();
1724 let source_root = sandbox.vm.get_root_pt().unwrap();
1725 let snapshot = sandbox.snapshot().unwrap();
1726 assert_eq!(sandbox.vm.get_root_pt().unwrap(), source_root);
1727
1728 sandbox.restore(snapshot.clone()).unwrap();
1729 let mut clone =
1730 Sandbox::from_snapshot(snapshot, crate::HostFunctions::default(), None).unwrap();
1731 let expected = vec![0x3c; 3 * hyperlight_common::vmem::PAGE_SIZE + 117];
1732 let call = FunctionCall::new(
1733 "EchoGuestVecBytes".into(),
1734 Some(vec![ParameterValue::VecBytes(expected.clone())]),
1735 FunctionCallType::Guest,
1736 Vec::<u8>::TYPE,
1737 );
1738
1739 for restored in [&mut sandbox, &mut clone] {
1740 restored.transport_dirty = true;
1741 let cid = restored.mem_mgr.write_guest_function_call(&call).unwrap();
1742 restored.dispatch_guest_call().unwrap();
1743 let value = restored
1744 .mem_mgr
1745 .read_h2g_result_from_g2h(cid)
1746 .unwrap()
1747 .into_inner()
1748 .unwrap();
1749 assert_eq!(Vec::<u8>::from_value(value).unwrap(), expected);
1750 }
1751
1752 assert_eq!(
1753 clone.call::<i32>("ReleaseGuestByteChunks", ()).unwrap(),
1754 6 * 1024
1755 );
1756 }
1757
1758 #[test]
1759 fn test_trigger_exception_on_guest() {
1760 let mut multi_use_sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1761 .build()
1762 .unwrap();
1763
1764 let res: Result<()> = multi_use_sandbox.call("TriggerException", ());
1765
1766 assert!(res.is_err());
1767
1768 match res.unwrap_err() {
1769 HyperlightError::GuestAborted(_, msg) => {
1770 #[cfg(target_arch = "x86_64")]
1772 assert!(msg.contains("InvalidOpcode"));
1773 #[cfg(target_arch = "aarch64")]
1774 assert!(msg.contains("0x2000000"));
1775 }
1776 e => panic!("Expected HyperlightError::GuestAborted but got {:?}", e),
1777 }
1778 }
1779
1780 fn create_many_on_threads_test<const NUM_THREADS: usize, const SANDBOXES_PER_THREAD: usize>() {
1781 let start_barrier = Arc::new(Barrier::new(NUM_THREADS + 1));
1783 let mut thread_handles = vec![];
1784
1785 for _ in 0..NUM_THREADS {
1786 let barrier = start_barrier.clone();
1787
1788 let handle = thread::spawn(move || {
1789 barrier.wait();
1790
1791 for _ in 0..SANDBOXES_PER_THREAD {
1792 let guest_path = simple_guest_as_pathbuf();
1793 let mut sandbox = SandboxBuilder::from_file(guest_path).build().unwrap();
1794
1795 let result: i32 = sandbox.call("GetStatic", ()).unwrap();
1796 assert_eq!(result, 0);
1797 }
1798 });
1799
1800 thread_handles.push(handle);
1801 }
1802
1803 start_barrier.wait();
1804
1805 for handle in thread_handles {
1806 handle.join().unwrap();
1807 }
1808 }
1809
1810 #[test]
1811 fn create_200_sandboxes() {
1812 create_many_on_threads_test::<20, 10>();
1813 }
1814
1815 #[test]
1816 fn create_200_threads() {
1817 #[cfg(target_arch = "aarch64")]
1818 create_many_on_threads_test::<32, 1>();
1819 #[cfg(not(target_arch = "aarch64"))]
1820 create_many_on_threads_test::<200, 1>();
1821 }
1822
1823 #[test]
1824 fn create_2000_sandboxes() {
1825 #[cfg(target_arch = "aarch64")]
1826 create_many_on_threads_test::<20, 100>();
1827 #[cfg(not(target_arch = "aarch64"))]
1828 create_many_on_threads_test::<200, 10>();
1829 }
1830
1831 #[test]
1832 fn test_mmap() {
1833 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1834 .build()
1835 .unwrap();
1836
1837 let expected = b"hello world";
1838 let map_mem = page_aligned_memory(expected);
1839 let guest_base = 0x1_0000_0000; unsafe {
1842 sbox.map_region(®ion_for_memory(
1843 &map_mem,
1844 guest_base,
1845 MemoryRegionFlags::READ,
1846 ))
1847 .unwrap();
1848 }
1849
1850 let _guard = map_mem.lock.try_read().unwrap();
1851 let actual: Vec<u8> = sbox
1852 .call(
1853 "ReadMappedBuffer",
1854 (guest_base as u64, expected.len() as u64, true),
1855 )
1856 .unwrap();
1857
1858 assert_eq!(actual, expected);
1859 }
1860
1861 #[test]
1863 fn test_mmap_write_exec() {
1864 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1865 .build()
1866 .unwrap();
1867
1868 #[cfg(target_arch = "x86_64")]
1869 let expected = &[0x90, 0x90, 0x90, 0xC3]; #[cfg(target_arch = "aarch64")]
1871 let expected = &[0x1f, 0x20, 0x03, 0xd5, 0xc0, 0x03, 0x5f, 0xd6];
1872 let map_mem = page_aligned_memory(expected);
1873 let guest_base = 0x1_0000_0000; unsafe {
1876 sbox.map_region(®ion_for_memory(
1877 &map_mem,
1878 guest_base,
1879 MemoryRegionFlags::READ | MemoryRegionFlags::EXECUTE,
1880 ))
1881 .unwrap();
1882 }
1883
1884 let _guard = map_mem.lock.try_read().unwrap();
1885
1886 let succeed = sbox
1888 .call::<bool>(
1889 "ExecMappedBuffer",
1890 (guest_base as u64, expected.len() as u64),
1891 )
1892 .unwrap();
1893 assert!(succeed, "Expected execution of mapped buffer to succeed");
1894
1895 let err = sbox
1897 .call::<bool>(
1898 "WriteMappedBuffer",
1899 (guest_base as u64, expected.len() as u64),
1900 )
1901 .unwrap_err();
1902
1903 match err {
1904 HyperlightError::MemoryAccessViolation(addr, ..) if addr == guest_base as u64 => {}
1905 _ => panic!("Expected MemoryAccessViolation error"),
1906 };
1907 }
1908
1909 fn page_aligned_memory(src: &[u8]) -> GuestSharedMemory {
1910 let page_size = page_size::get();
1911 let len = src.len().div_ceil(page_size) * page_size;
1912
1913 let mut mem = ExclusiveSharedMemory::new(len).unwrap();
1914 mem.copy_from_slice(src, 0).unwrap();
1915
1916 let (_, guest_mem) = mem.build();
1917
1918 guest_mem
1919 }
1920
1921 fn region_for_memory(
1922 mem: &GuestSharedMemory,
1923 guest_base: usize,
1924 flags: MemoryRegionFlags,
1925 ) -> MemoryRegion {
1926 let len = mem.mem_size();
1927 MemoryRegion {
1928 host_region: mem.host_region_base()..mem.host_region_end(),
1929 guest_region: guest_base..(guest_base + len),
1930 flags,
1931 region_type: MemoryRegionType::Heap,
1932 }
1933 }
1934
1935 fn allocate_guest_memory() -> GuestSharedMemory {
1936 page_aligned_memory(b"test data for snapshot")
1937 }
1938
1939 #[test]
1940 fn snapshot_restore_handles_remapping_correctly() {
1941 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
1942 .build()
1943 .unwrap();
1944
1945 let snapshot1 = sbox.snapshot().unwrap();
1947 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
1948
1949 let map_mem = allocate_guest_memory();
1951 let guest_base = 0x200000000_usize;
1952 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
1953
1954 unsafe { sbox.map_region(®ion).unwrap() };
1955 assert_eq!(sbox.vm.get_mapped_regions().count(), 1);
1956 let orig_read = sbox
1957 .call::<Vec<u8>>(
1958 "ReadMappedBuffer",
1959 (
1960 guest_base as u64,
1961 hyperlight_common::vmem::PAGE_SIZE as u64,
1962 true,
1963 ),
1964 )
1965 .unwrap();
1966
1967 let snapshot2 = sbox.snapshot().unwrap();
1969 assert_eq!(sbox.vm.get_mapped_regions().count(), 1);
1970
1971 sbox.restore(snapshot1.clone()).unwrap();
1973 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
1974 let is_mapped = sbox
1975 .call::<bool>("CheckMapped", (guest_base as u64,))
1976 .unwrap();
1977 assert!(!is_mapped);
1978
1979 sbox.restore(snapshot2.clone()).unwrap();
1982 assert_eq!(sbox.vm.get_mapped_regions().count(), 0);
1983 let is_mapped = sbox
1984 .call::<bool>("CheckMapped", (guest_base as u64,))
1985 .unwrap();
1986 assert!(is_mapped);
1987
1988 let new_read = sbox
1990 .call::<Vec<u8>>(
1991 "ReadMappedBuffer",
1992 (
1993 guest_base as u64,
1994 hyperlight_common::vmem::PAGE_SIZE as u64,
1995 false,
1996 ),
1997 )
1998 .unwrap();
1999 assert_eq!(new_read, orig_read);
2000 }
2001
2002 #[test]
2006 fn snapshot_restore_across_sandboxes_preserves_mapped_region_contents() {
2007 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2008 .build()
2009 .unwrap();
2010
2011 let map_mem = allocate_guest_memory();
2012 let guest_base = 0x200000000_usize;
2013 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2014 unsafe { source.map_region(®ion).unwrap() };
2015
2016 let orig_read = source
2018 .call::<Vec<u8>>(
2019 "ReadMappedBuffer",
2020 (
2021 guest_base as u64,
2022 hyperlight_common::vmem::PAGE_SIZE as u64,
2023 true,
2024 ),
2025 )
2026 .unwrap();
2027
2028 let snapshot = source.snapshot().unwrap();
2029
2030 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2031 .build()
2032 .unwrap();
2033 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2034
2035 target.restore(snapshot).unwrap();
2036 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2037
2038 let new_read = target
2041 .call::<Vec<u8>>(
2042 "ReadMappedBuffer",
2043 (
2044 guest_base as u64,
2045 hyperlight_common::vmem::PAGE_SIZE as u64,
2046 false,
2047 ),
2048 )
2049 .unwrap();
2050 assert_eq!(new_read, orig_read);
2051 }
2052
2053 #[test]
2054 fn snapshot_restore_across_sandboxes() {
2055 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2056 .build()
2057 .unwrap();
2058
2059 let mut sandbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2060 .build()
2061 .unwrap();
2062
2063 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2064 assert_eq!(sandbox2.call::<i32>("GetStatic", ()).unwrap(), 0);
2065
2066 let snapshot = sandbox.snapshot().unwrap();
2067 sandbox2.restore(snapshot).unwrap();
2068 assert_virtq_attached(&sandbox2);
2069 assert_eq!(sandbox2.call::<i32>("GetStatic", ()).unwrap(), 42);
2070 }
2071
2072 #[test]
2073 #[cfg(not(gdb))]
2074 fn snapshot_restore_keeps_current_base_mappings() {
2075 let path = simple_guest_as_pathbuf();
2076 let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2077 .unwrap()
2078 .evolve()
2079 .unwrap();
2080 let snapshot = sandbox.snapshot().unwrap();
2081 sandbox.restore(snapshot.clone()).unwrap();
2082 sandbox.call::<i32>("AddToStatic", 42i32).unwrap();
2083 let mappings = sandbox.vm.base_mapping_state();
2084 let fault_plan = sandbox
2085 .vm
2086 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Snapshot)]);
2087
2088 sandbox.restore(snapshot).unwrap();
2089
2090 assert_eq!(sandbox.status(), SandboxStatus::Ready);
2091 let new_mappings = sandbox.vm.base_mapping_state();
2092 assert_eq!(new_mappings.0, mappings.0);
2094 assert_eq!(new_mappings.1.map(|m| m.1), mappings.1.map(|m| m.1));
2097 assert!(!fault_plan.is_consumed());
2098 assert_eq!(sandbox.call::<i32>("GetStatic", ()).unwrap(), 0);
2099 }
2100
2101 #[test]
2102 #[cfg(not(gdb))]
2103 fn snapshot_restore_mapping_failure_is_unrecoverable() {
2104 let path = simple_guest_as_pathbuf();
2105 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2106 .unwrap()
2107 .evolve()
2108 .unwrap();
2109 source.call::<i32>("AddToStatic", 42i32).unwrap();
2110 let snapshot = source.snapshot().unwrap();
2111
2112 let path = simple_guest_as_pathbuf();
2113 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2114 .unwrap()
2115 .evolve()
2116 .unwrap();
2117 let mappings = target.vm.base_mapping_state();
2118 let fault_plan = target
2119 .vm
2120 .inject_vm_faults([VmOperation::Map(MemoryRegionType::Snapshot)]);
2121
2122 let error = target.restore(snapshot.clone()).unwrap_err();
2123 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2124 assert_eq!(target.status(), SandboxStatus::Unrecoverable);
2125 assert_eq!(target.vm.base_mapping_state(), (None, mappings.1));
2126 assert!(fault_plan.is_consumed());
2127
2128 assert!(matches!(
2129 target.restore(snapshot),
2130 Err(HyperlightError::UnrecoverableSandbox)
2131 ));
2132 assert!(matches!(
2133 target.call::<i32>("GetStatic", ()),
2134 Err(HyperlightError::UnrecoverableSandbox)
2135 ));
2136 assert!(matches!(
2137 target.snapshot(),
2138 Err(HyperlightError::UnrecoverableSandbox)
2139 ));
2140
2141 let map_mem = allocate_guest_memory();
2142 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2143 assert!(matches!(
2144 unsafe { target.map_region(®ion) },
2145 Err(HyperlightError::UnrecoverableSandbox)
2146 ));
2147 }
2148
2149 #[test]
2150 #[cfg(not(gdb))]
2151 fn scratch_mapping_failure_clears_mapping_state() {
2152 let path = simple_guest_as_pathbuf();
2153 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2154 .unwrap()
2155 .evolve()
2156 .unwrap();
2157 let snapshot_mapping = target.vm.base_mapping_state().0;
2158 let scratch = ExclusiveSharedMemory::new(target.mem_mgr.scratch_mem.mem_size()).unwrap();
2159 let (_, scratch) = scratch.build();
2160 let fault_plan = target
2161 .vm
2162 .inject_vm_faults([VmOperation::Map(MemoryRegionType::Scratch)]);
2163
2164 target.vm.update_scratch_mapping(scratch).unwrap_err();
2165 assert_eq!(target.vm.base_mapping_state(), (snapshot_mapping, None));
2166 assert!(fault_plan.is_consumed());
2167 }
2168
2169 #[test]
2170 #[cfg(not(gdb))]
2171 fn snapshot_restore_unmapping_failure_is_unrecoverable() {
2172 let path = simple_guest_as_pathbuf();
2173 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2174 .unwrap()
2175 .evolve()
2176 .unwrap();
2177 source.call::<i32>("AddToStatic", 42i32).unwrap();
2178 let snapshot = source.snapshot().unwrap();
2179
2180 let path = simple_guest_as_pathbuf();
2181 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2182 .unwrap()
2183 .evolve()
2184 .unwrap();
2185 let mappings = target.vm.base_mapping_state();
2186 let fault_plan = target
2187 .vm
2188 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Snapshot)]);
2189
2190 let error = target.restore(snapshot).unwrap_err();
2191 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2192 assert_eq!(target.status(), SandboxStatus::Unrecoverable);
2193 assert_eq!(target.vm.base_mapping_state(), mappings);
2194 assert!(fault_plan.is_consumed());
2195 }
2196
2197 #[test]
2198 #[cfg(not(gdb))]
2199 fn snapshot_restore_dynamic_unmapping_failure_is_recoverable() {
2200 let path = simple_guest_as_pathbuf();
2201 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2202 .unwrap()
2203 .evolve()
2204 .unwrap();
2205 source.call::<i32>("AddToStatic", 42i32).unwrap();
2206 let snapshot = source.snapshot().unwrap();
2207
2208 let path = simple_guest_as_pathbuf();
2209 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2210 .unwrap()
2211 .evolve()
2212 .unwrap();
2213 let map_mem = allocate_guest_memory();
2214 let region = region_for_memory(&map_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2215 unsafe { target.map_region(®ion).unwrap() };
2216 let fault_plan = target
2217 .vm
2218 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::Heap)]);
2219
2220 let error = target.restore(snapshot.clone()).unwrap_err();
2221 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2222 assert!(target.status().is_poisoned());
2223 assert_eq!(target.vm.get_mapped_regions().count(), 1);
2224 assert!(fault_plan.is_consumed());
2225
2226 target.restore(snapshot).unwrap();
2227 assert_eq!(target.status(), SandboxStatus::Ready);
2228 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2229 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2230 }
2231
2232 #[test]
2233 #[cfg(not(gdb))]
2234 fn snapshot_restore_partial_dynamic_unmapping_failure_is_recoverable() {
2235 let path = simple_guest_as_pathbuf();
2236 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2237 .unwrap()
2238 .evolve()
2239 .unwrap();
2240 source.call::<i32>("AddToStatic", 42i32).unwrap();
2241 let snapshot = source.snapshot().unwrap();
2242
2243 let path = simple_guest_as_pathbuf();
2244 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2245 .unwrap()
2246 .evolve()
2247 .unwrap();
2248 let first_mem = allocate_guest_memory();
2249 let first_region =
2250 region_for_memory(&first_mem, 0x200000000_usize, MemoryRegionFlags::READ);
2251 unsafe { target.map_region(&first_region).unwrap() };
2252 let (mapped_path, _) =
2253 create_test_file("hyperlight_test_partial_dynamic_unmapping.bin", &[0; 4096]);
2254 target.map_file_cow(&mapped_path, 0x300000000).unwrap();
2255 let second_region = target.vm.get_mapped_regions().last().unwrap().clone();
2256 let fault_plan = target
2257 .vm
2258 .inject_vm_faults([VmOperation::Unmap(MemoryRegionType::MappedFile)]);
2259
2260 let error = target.restore(snapshot.clone()).unwrap_err();
2261 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2262 assert!(target.status().is_poisoned());
2263 assert_eq!(
2264 target.vm.get_mapped_regions().collect::<Vec<_>>(),
2265 vec![&second_region]
2266 );
2267 assert!(fault_plan.is_consumed());
2268
2269 target.restore(snapshot).unwrap();
2270 assert_eq!(target.status(), SandboxStatus::Ready);
2271 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2272 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2273 std::fs::remove_file(mapped_path).unwrap();
2274 }
2275
2276 #[test]
2277 #[cfg(not(gdb))]
2278 fn snapshot_restore_vcpu_reset_failure_is_recoverable() {
2279 let path = simple_guest_as_pathbuf();
2280 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2281 .unwrap()
2282 .evolve()
2283 .unwrap();
2284 source.call::<i32>("AddToStatic", 42i32).unwrap();
2285 let snapshot = source.snapshot().unwrap();
2286
2287 #[cfg(target_arch = "x86_64")]
2288 let reset_operations = [
2289 VmOperation::SetRegs,
2290 VmOperation::SetDebugRegs,
2291 VmOperation::ResetXsave,
2292 VmOperation::SetSregs,
2293 ];
2294 #[cfg(target_arch = "aarch64")]
2295 let reset_operations = [VmOperation::ResetVcpu];
2296
2297 for reset_operation in reset_operations {
2298 let path = simple_guest_as_pathbuf();
2299 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2300 .unwrap()
2301 .evolve()
2302 .unwrap();
2303 let fault_plan = target.vm.inject_vm_faults([reset_operation]);
2304
2305 let error = target.restore(snapshot.clone()).unwrap_err();
2306 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2307 assert!(target.status().is_poisoned());
2308 assert!(fault_plan.is_consumed());
2309 assert_eq!(
2310 target.vm.base_mapping_state(),
2311 (
2312 Some((
2313 target.mem_mgr.shared_mem.base_addr(),
2314 target.mem_mgr.shared_mem.mem_size(),
2315 )),
2316 Some((
2317 target.mem_mgr.scratch_mem.base_addr(),
2318 target.mem_mgr.scratch_mem.mem_size(),
2319 )),
2320 )
2321 );
2322
2323 target.restore(snapshot.clone()).unwrap();
2324 assert_eq!(target.status(), SandboxStatus::Ready);
2325 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2326 }
2327 }
2328
2329 #[test]
2330 #[cfg(all(target_arch = "x86_64", not(gdb)))]
2331 fn snapshot_restore_msr_failure_is_recoverable() {
2332 let path = simple_guest_as_pathbuf();
2333 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2334 .unwrap()
2335 .evolve()
2336 .unwrap();
2337 source.call::<i32>("AddToStatic", 42i32).unwrap();
2338 let snapshot = source.snapshot().unwrap();
2339
2340 let path = simple_guest_as_pathbuf();
2341 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2342 .unwrap()
2343 .evolve()
2344 .unwrap();
2345 let fault_plan = target.vm.inject_vm_faults([VmOperation::SetMsrs]);
2346
2347 let error = target.restore(snapshot.clone()).unwrap_err();
2348 assert!(matches!(error, HyperlightError::HyperlightVmError(_)));
2349 assert!(target.status().is_poisoned());
2350 assert!(fault_plan.is_consumed());
2351 assert_eq!(
2352 target.vm.base_mapping_state(),
2353 (
2354 Some((
2355 target.mem_mgr.shared_mem.base_addr(),
2356 target.mem_mgr.shared_mem.mem_size(),
2357 )),
2358 Some((
2359 target.mem_mgr.scratch_mem.base_addr(),
2360 target.mem_mgr.scratch_mem.mem_size(),
2361 )),
2362 )
2363 );
2364
2365 target.restore(snapshot).unwrap();
2366 assert_eq!(target.status(), SandboxStatus::Ready);
2367 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2368 }
2369
2370 #[test]
2371 fn snapshot_restore_accepts_different_configured_layout() {
2372 type Configure = fn(&mut SandboxConfiguration);
2373 type LayoutValue = fn(&crate::mem::layout::SandboxMemoryLayout) -> usize;
2374 let cases: &[(&str, Configure, LayoutValue)] = &[
2375 (
2376 "G2H queue size",
2377 |cfg| cfg.set_g2h_queue_size(128),
2378 |layout| layout.get_g2h_queue_size(),
2379 ),
2380 (
2381 "H2G queue size",
2382 |cfg| cfg.set_h2g_queue_size(64),
2383 |layout| layout.get_h2g_queue_size(),
2384 ),
2385 (
2386 "G2H buffer size",
2387 |cfg| cfg.set_g2h_buffer_size(0x2000),
2388 |layout| layout.get_g2h_buffer_size(),
2389 ),
2390 (
2391 "H2G buffer size",
2392 |cfg| cfg.set_h2g_buffer_size(0x2000),
2393 |layout| layout.get_h2g_buffer_size(),
2394 ),
2395 (
2396 "G2H pool pages",
2397 |cfg| cfg.set_g2h_pool_pages(16),
2398 |layout| layout.get_g2h_pool_pages(),
2399 ),
2400 (
2401 "H2G pool pages",
2402 |cfg| cfg.set_h2g_pool_pages(16),
2403 |layout| layout.get_h2g_pool_pages(),
2404 ),
2405 (
2406 "heap",
2407 |cfg| cfg.set_heap_size(0x40_000),
2408 |layout| layout.heap_size(),
2409 ),
2410 (
2411 "scratch",
2412 |cfg| cfg.set_scratch_size(0x90_000),
2413 |layout| layout.get_scratch_size(),
2414 ),
2415 ];
2416
2417 for (name, configure, layout_value) in cases {
2418 for incoming_is_larger in [true, false] {
2419 let mut custom_cfg = SandboxConfiguration::default();
2420 configure(&mut custom_cfg);
2421 let (source_cfg, target_cfg) = if incoming_is_larger {
2422 (custom_cfg, SandboxConfiguration::default())
2423 } else {
2424 (SandboxConfiguration::default(), custom_cfg)
2425 };
2426
2427 let path = simple_guest_as_pathbuf();
2428 let mut source =
2429 UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
2430 .unwrap()
2431 .evolve()
2432 .unwrap();
2433
2434 let path = simple_guest_as_pathbuf();
2435 let mut target =
2436 UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
2437 .unwrap()
2438 .evolve()
2439 .unwrap();
2440
2441 let source_value = layout_value(&source.mem_mgr.layout);
2442 assert_ne!(source_value, layout_value(&target.mem_mgr.layout));
2443
2444 source.call::<i32>("AddToStatic", 42i32).unwrap();
2445 target
2446 .restore(source.snapshot().unwrap())
2447 .unwrap_or_else(|err| panic!("restore with different {name} layout: {err}"));
2448 assert_eq!(layout_value(&target.mem_mgr.layout), source_value);
2449 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2450 }
2451 }
2452 }
2453
2454 #[test]
2455 fn snapshot_restore_recovers_oom_with_larger_heap() {
2456 let mut source_cfg = SandboxConfiguration::default();
2457 source_cfg.set_heap_size(0x20_000);
2458 let path = simple_guest_as_pathbuf();
2459 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
2460 .unwrap()
2461 .evolve()
2462 .unwrap();
2463 let snapshot = source.snapshot().unwrap();
2464
2465 let mut target_cfg = SandboxConfiguration::default();
2466 target_cfg.set_heap_size(40 * 1024);
2467 let path = simple_guest_as_pathbuf();
2468 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
2469 .unwrap()
2470 .evolve()
2471 .unwrap();
2472
2473 assert!(target.call::<()>("ExhaustHeap", ()).is_err());
2474 assert!(target.status().is_poisoned());
2475
2476 target.restore(snapshot).unwrap();
2477 assert!(!target.status().is_poisoned());
2478 assert_eq!(
2479 target.call::<i32>("CallMalloc", 0x10_000i32).unwrap(),
2480 0x10_000
2481 );
2482 }
2483
2484 #[test]
2485 fn snapshot_restore_applies_smaller_heap_limit() {
2486 let mut source_cfg = SandboxConfiguration::default();
2487 source_cfg.set_heap_size(40 * 1024);
2488 let path = simple_guest_as_pathbuf();
2489 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
2490 .unwrap()
2491 .evolve()
2492 .unwrap();
2493 let snapshot = source.snapshot().unwrap();
2494
2495 let mut target_cfg = SandboxConfiguration::default();
2496 target_cfg.set_heap_size(0x20_000);
2497 let path = simple_guest_as_pathbuf();
2498 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
2499 .unwrap()
2500 .evolve()
2501 .unwrap();
2502
2503 assert_eq!(
2504 target.call::<i32>("CallMalloc", 0x10_000i32).unwrap(),
2505 0x10_000
2506 );
2507 target.restore(snapshot).unwrap();
2508 assert_eq!(target.mem_mgr.layout.heap_size(), 40 * 1024);
2509 assert!(target.call::<i32>("CallMalloc", 0x10_000i32).is_err());
2510 assert!(target.status().is_poisoned());
2511 }
2512
2513 #[test]
2514 fn snapshot_restore_applies_smaller_h2g_capacity() {
2515 let mut source_cfg = SandboxConfiguration::default();
2516 source_cfg.set_scratch_size(1024 * 1024);
2517 source_cfg.set_h2g_pool_pages(4);
2518 let path = simple_guest_as_pathbuf();
2519 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
2520 .unwrap()
2521 .evolve()
2522 .unwrap();
2523 let snapshot = source.snapshot().unwrap();
2524 let mut target_cfg = SandboxConfiguration::default();
2525 target_cfg.set_scratch_size(1024 * 1024);
2526 target_cfg.set_h2g_pool_pages(8);
2527 let path = simple_guest_as_pathbuf();
2528 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(target_cfg))
2529 .unwrap()
2530 .evolve()
2531 .unwrap();
2532 let large = "x".repeat(4 * hyperlight_common::vmem::PAGE_SIZE);
2533
2534 assert_eq!(target.call::<String>("Echo", large.clone()).unwrap(), large);
2535 target.restore(snapshot).unwrap();
2536 assert_eq!(target.mem_mgr.layout.get_h2g_pool_pages(), 4);
2537 let error = target.call::<String>("Echo", large).unwrap_err();
2538 assert!(error.to_string().contains("H2G capacity"));
2539 assert!(!target.status().is_poisoned());
2540 assert_eq!(
2541 target.call::<String>("Echo", "small".to_string()).unwrap(),
2542 "small"
2543 );
2544 }
2545
2546 #[test]
2547 fn snapshot_restore_alternates_different_layouts() {
2548 let mut small_cfg = SandboxConfiguration::default();
2549 small_cfg.set_heap_size(40 * 1024);
2550 let path = simple_guest_as_pathbuf();
2551 let mut small = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(small_cfg))
2552 .unwrap()
2553 .evolve()
2554 .unwrap();
2555 small.call::<i32>("AddToStatic", 11i32).unwrap();
2556 let small_snapshot = small.snapshot().unwrap();
2557
2558 let mut large_cfg = SandboxConfiguration::default();
2559 large_cfg.set_heap_size(0x40_000);
2560 large_cfg.set_scratch_size(0x90_000);
2561 let path = simple_guest_as_pathbuf();
2562 let mut large = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(large_cfg))
2563 .unwrap()
2564 .evolve()
2565 .unwrap();
2566 large.call::<i32>("AddToStatic", 22i32).unwrap();
2567 let large_snapshot = large.snapshot().unwrap();
2568
2569 let path = simple_guest_as_pathbuf();
2570 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2571 .unwrap()
2572 .evolve()
2573 .unwrap();
2574
2575 target.restore(small_snapshot.clone()).unwrap();
2576 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
2577 assert_eq!(target.mem_mgr.layout.heap_size(), 40 * 1024);
2578
2579 target.restore(large_snapshot).unwrap();
2580 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 22);
2581 assert_eq!(target.mem_mgr.layout.heap_size(), 0x40_000);
2582
2583 target.restore(small_snapshot).unwrap();
2584 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 11);
2585 assert_eq!(target.mem_mgr.layout.heap_size(), 40 * 1024);
2586 }
2587
2588 #[test]
2589 fn snapshot_restore_replaces_rust_guest_with_c_guest() {
2590 let init_data = b"cross-layout-init-data";
2591 let source_env = GuestEnvironment {
2592 guest_binary: GuestBinary::FilePath(c_simple_guest_as_pathbuf()),
2593 init_data: Some(GuestBlob {
2594 data: init_data,
2595 permissions: MemoryRegionFlags::READ | MemoryRegionFlags::WRITE,
2596 }),
2597 };
2598 let mut source = UninitializedSandbox::new(source_env, None)
2599 .unwrap()
2600 .evolve()
2601 .unwrap();
2602 let mut target =
2603 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
2604 .unwrap()
2605 .evolve()
2606 .unwrap();
2607
2608 assert_eq!(source.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
2609 assert_eq!(target.call::<i32>("AddToStatic", 17i32).unwrap(), 17);
2610 target.set_pt_root_finder(Box::new(|_, _, root| vec![root]));
2611 assert!(target.pt_root_finder.is_some());
2612
2613 assert_ne!(
2614 source.mem_mgr.layout.code_size(),
2615 target.mem_mgr.layout.code_size()
2616 );
2617 assert_ne!(
2618 source.mem_mgr.layout.init_data_size(),
2619 target.mem_mgr.layout.init_data_size()
2620 );
2621 assert_ne!(
2622 source.mem_mgr.layout.init_data_permissions(),
2623 target.mem_mgr.layout.init_data_permissions()
2624 );
2625
2626 let snapshot = source.snapshot().unwrap();
2627 target.restore(snapshot).unwrap();
2628 assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
2629 assert!(matches!(
2630 target.call::<i32>("GetStatic", ()),
2631 Err(HyperlightError::GuestError(
2632 ErrorCode::GuestFunctionNotFound,
2633 name
2634 )) if name == "GetStatic"
2635 ));
2636 }
2637
2638 #[test]
2639 fn snapshot_restore_replaces_c_guest_with_rust_guest() {
2640 let mut source =
2641 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
2642 .unwrap()
2643 .evolve()
2644 .unwrap();
2645 assert_eq!(source.call::<i32>("AddToStatic", 42i32).unwrap(), 42);
2646 let snapshot = source.snapshot().unwrap();
2647
2648 let mut target =
2649 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
2650 .unwrap()
2651 .evolve()
2652 .unwrap();
2653 assert_eq!(target.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
2654
2655 target.restore(snapshot).unwrap();
2656 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2657 assert!(matches!(
2658 target.call::<i32>("StackAllocate", 512i32),
2659 Err(HyperlightError::GuestError(
2660 ErrorCode::GuestFunctionNotFound,
2661 name
2662 )) if name == "StackAllocate"
2663 ));
2664 }
2665
2666 #[test]
2667 fn snapshot_restore_alternates_c_and_rust_guests() {
2668 let mut c_source =
2669 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
2670 .unwrap()
2671 .evolve()
2672 .unwrap();
2673 assert_eq!(c_source.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
2674 let c_snapshot = c_source.snapshot().unwrap();
2675
2676 let mut rust_source =
2677 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
2678 .unwrap()
2679 .evolve()
2680 .unwrap();
2681 rust_source.call::<i32>("AddToStatic", 42i32).unwrap();
2682 let rust_snapshot = rust_source.snapshot().unwrap();
2683
2684 let mut target =
2685 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
2686 .unwrap()
2687 .evolve()
2688 .unwrap();
2689 assert_eq!(target.call::<i32>("StackAllocate", 256i32).unwrap(), 256);
2690
2691 target.restore(rust_snapshot).unwrap();
2692 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 42);
2693 assert!(matches!(
2694 target.call::<i32>("StackAllocate", 512i32),
2695 Err(HyperlightError::GuestError(
2696 ErrorCode::GuestFunctionNotFound,
2697 name
2698 )) if name == "StackAllocate"
2699 ));
2700
2701 target.restore(c_snapshot).unwrap();
2702 assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
2703 assert!(matches!(
2704 target.call::<i32>("GetStatic", ()),
2705 Err(HyperlightError::GuestError(
2706 ErrorCode::GuestFunctionNotFound,
2707 name
2708 )) if name == "GetStatic"
2709 ));
2710 }
2711
2712 #[test]
2713 fn snapshot_restore_keeps_target_host_function_implementation() {
2714 let path = simple_guest_as_pathbuf();
2715 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
2716 source
2717 .register_host_function("Echo42", || Ok(1i64))
2718 .unwrap();
2719 let mut source = source.evolve().unwrap();
2720 let snapshot = source.snapshot().unwrap();
2721
2722 let path = simple_guest_as_pathbuf();
2723 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
2724 target
2725 .register_host_function("Echo42", || Ok(42i64))
2726 .unwrap();
2727 let mut target = target.evolve().unwrap();
2728
2729 target.restore(snapshot).unwrap();
2730 assert_eq!(
2731 target
2732 .call::<i64>(
2733 "CallGivenParamlessHostFuncThatReturnsI64",
2734 "Echo42".to_string(),
2735 )
2736 .unwrap(),
2737 42
2738 );
2739 }
2740
2741 #[test]
2742 fn snapshot_restore_recovers_poison_with_different_guest() {
2743 let mut source =
2744 UninitializedSandbox::new(GuestBinary::FilePath(c_simple_guest_as_pathbuf()), None)
2745 .unwrap()
2746 .evolve()
2747 .unwrap();
2748 let snapshot = source.snapshot().unwrap();
2749
2750 let path = simple_guest_as_pathbuf();
2751 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2752 .unwrap()
2753 .evolve()
2754 .unwrap();
2755 assert!(target.call::<()>("ExhaustHeap", ()).is_err());
2756 assert!(target.status().is_poisoned());
2757
2758 target.restore(snapshot).unwrap();
2759 assert!(!target.status().is_poisoned());
2760 assert_eq!(target.call::<i32>("StackAllocate", 512i32).unwrap(), 512);
2761 assert!(matches!(
2762 target.call::<i32>("GetStatic", ()),
2763 Err(HyperlightError::GuestError(
2764 ErrorCode::GuestFunctionNotFound,
2765 name
2766 )) if name == "GetStatic"
2767 ));
2768 }
2769
2770 #[test]
2773 fn snapshot_restore_failure_leaves_target_usable() {
2774 let path = simple_guest_as_pathbuf();
2775 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
2776 source
2777 .register_host_function("Add", |a: i32, b: i32| Ok(a + b))
2778 .unwrap();
2779 let mut source = source.evolve().unwrap();
2780
2781 let map_mem = allocate_guest_memory();
2782 let path = simple_guest_as_pathbuf();
2783 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2784 .unwrap()
2785 .evolve()
2786 .unwrap();
2787
2788 target.call::<i32>("AddToStatic", 5i32).unwrap();
2789 let guest_base = 0x200000000_usize;
2790 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2791 unsafe { target.map_region(®ion).unwrap() };
2793 target
2794 .call::<Vec<u8>>(
2795 "ReadMappedBuffer",
2796 (
2797 guest_base as u64,
2798 hyperlight_common::vmem::PAGE_SIZE as u64,
2799 true,
2800 ),
2801 )
2802 .unwrap();
2803 let cached_snapshot = target.snapshot().unwrap();
2804 let bad_snapshot = source.snapshot().unwrap();
2805 let err = target.restore(bad_snapshot);
2806 assert!(matches!(
2807 err,
2808 Err(HyperlightError::SnapshotHostFunctionMismatch { missing, .. })
2809 if missing.iter().any(|name| name == "Add")
2810 ));
2811
2812 assert!(Arc::ptr_eq(&target.snapshot().unwrap(), &cached_snapshot));
2813 assert_eq!(target.vm.get_mapped_regions().count(), 1);
2814 assert!(
2815 target
2816 .call::<bool>("CheckMapped", guest_base as u64)
2817 .unwrap()
2818 );
2819 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 5);
2820 target.call::<i32>("AddToStatic", 3i32).unwrap();
2821 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 8);
2822
2823 let good_snapshot = target.snapshot().unwrap();
2824 target.call::<i32>("AddToStatic", 100i32).unwrap();
2825 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 108);
2826 target.restore(good_snapshot).unwrap();
2827 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 8);
2828 }
2829
2830 #[test]
2833 fn snapshot_restore_across_sandboxes_target_has_mapped_regions() {
2834 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2835 .build()
2836 .unwrap();
2837 source.call::<i32>("AddToStatic", 23i32).unwrap();
2838 let snapshot = source.snapshot().unwrap();
2839
2840 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2841 .build()
2842 .unwrap();
2843 let map_mem = allocate_guest_memory();
2844 let guest_base = 0x200000000_usize;
2845 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2846 unsafe { target.map_region(®ion).unwrap() };
2847 assert_eq!(target.vm.get_mapped_regions().count(), 1);
2848
2849 target.restore(snapshot).unwrap();
2850 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2851 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
2852 }
2853
2854 #[test]
2855 fn snapshot_restore_unmaps_regions_overlapping_incoming_layout() {
2856 let mut source_cfg = SandboxConfiguration::default();
2857 source_cfg.set_scratch_size(0x90_000);
2858 let path = simple_guest_as_pathbuf();
2859 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
2860 .unwrap()
2861 .evolve()
2862 .unwrap();
2863 source.call::<i32>("AddToStatic", 23i32).unwrap();
2864 let snapshot = source.snapshot().unwrap();
2865
2866 let path = simple_guest_as_pathbuf();
2867 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2868 .unwrap()
2869 .evolve()
2870 .unwrap();
2871 assert!(snapshot.memory().mem_size() > target.mem_mgr.shared_mem.mem_size());
2872
2873 let map_mem = allocate_guest_memory();
2874 let guest_base = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS
2875 + target.mem_mgr.shared_mem.mem_size();
2876 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2877 unsafe { target.map_region(®ion).unwrap() };
2879
2880 target.restore(snapshot).unwrap();
2881 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2882 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
2883 }
2884
2885 #[test]
2886 fn snapshot_restore_unmaps_region_overlapping_incoming_scratch() {
2887 let incoming_scratch_size = 0x90_000;
2888 let mut source_cfg = SandboxConfiguration::default();
2889 source_cfg.set_scratch_size(incoming_scratch_size);
2890 let path = simple_guest_as_pathbuf();
2891 let mut source = UninitializedSandbox::new(GuestBinary::FilePath(path), Some(source_cfg))
2892 .unwrap()
2893 .evolve()
2894 .unwrap();
2895 source.call::<i32>("AddToStatic", 23i32).unwrap();
2896 let snapshot = source.snapshot().unwrap();
2897
2898 let path = simple_guest_as_pathbuf();
2899 let mut target = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
2900 .unwrap()
2901 .evolve()
2902 .unwrap();
2903 let guest_base =
2904 hyperlight_common::layout::scratch_base_gpa(incoming_scratch_size) as usize;
2905 let target_scratch_base =
2906 hyperlight_common::layout::scratch_base_gpa(SandboxConfiguration::DEFAULT_SCRATCH_SIZE)
2907 as usize;
2908 let map_mem = allocate_guest_memory();
2909 assert!(guest_base + map_mem.mem_size() <= target_scratch_base);
2910 let region = region_for_memory(&map_mem, guest_base, MemoryRegionFlags::READ);
2911 unsafe { target.map_region(®ion).unwrap() };
2913
2914 target.restore(snapshot).unwrap();
2915 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2916 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 23);
2917 }
2918
2919 #[test]
2923 fn snapshot_restore_across_sandboxes_both_have_different_mapped_regions() {
2924 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2925 .build()
2926 .unwrap();
2927 let source_mem = allocate_guest_memory();
2928 let source_base = 0x200000000_usize;
2929 let source_region = region_for_memory(&source_mem, source_base, MemoryRegionFlags::READ);
2930 unsafe { source.map_region(&source_region).unwrap() };
2931 let orig_read = source
2932 .call::<Vec<u8>>(
2933 "ReadMappedBuffer",
2934 (
2935 source_base as u64,
2936 hyperlight_common::vmem::PAGE_SIZE as u64,
2937 true,
2938 ),
2939 )
2940 .unwrap();
2941 source.call::<i32>("AddToStatic", 9i32).unwrap();
2942 let snapshot = source.snapshot().unwrap();
2943
2944 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2945 .build()
2946 .unwrap();
2947 let target_mem = allocate_guest_memory();
2948 let target_base = 0x300000000_usize;
2949 let target_region = region_for_memory(&target_mem, target_base, MemoryRegionFlags::READ);
2950 unsafe { target.map_region(&target_region).unwrap() };
2951 assert_eq!(target.vm.get_mapped_regions().count(), 1);
2952
2953 target.restore(snapshot).unwrap();
2954
2955 assert_eq!(target.vm.get_mapped_regions().count(), 0);
2956 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 9);
2957
2958 let new_read = target
2959 .call::<Vec<u8>>(
2960 "ReadMappedBuffer",
2961 (
2962 source_base as u64,
2963 hyperlight_common::vmem::PAGE_SIZE as u64,
2964 false,
2965 ),
2966 )
2967 .unwrap();
2968 assert_eq!(new_read, orig_read);
2969 }
2970
2971 #[test]
2973 fn snapshot_restore_across_sandboxes_repeated() {
2974 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2975 .build()
2976 .unwrap();
2977 source.call::<i32>("AddToStatic", 7i32).unwrap();
2978 let snapshot = source.snapshot().unwrap();
2979
2980 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2981 .build()
2982 .unwrap();
2983
2984 target.restore(snapshot.clone()).unwrap();
2985 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 7);
2986
2987 target.call::<i32>("AddToStatic", 1000i32).unwrap();
2988 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 1007);
2989
2990 target.restore(snapshot).unwrap();
2991 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 7);
2992 }
2993
2994 #[test]
2997 fn snapshot_restore_resets_debug_registers() {
2998 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
2999 .build()
3000 .unwrap();
3001
3002 let snapshot = sandbox.snapshot().unwrap();
3003
3004 let dr0_initial: u64 = sandbox.call("GetDr0", ()).unwrap();
3006 assert_eq!(dr0_initial, 0, "DR0 should initially be 0");
3007
3008 const DIRTY_VALUE: u64 = 0xFFFF_FEDC_7654_3210;
3011 sandbox.call::<()>("SetDr0", DIRTY_VALUE).unwrap();
3012
3013 #[cfg(not(hvf))]
3015 {
3016 let dr0_dirty: u64 = sandbox.call("GetDr0", ()).unwrap();
3028 assert_eq!(
3029 dr0_dirty, DIRTY_VALUE,
3030 "DR0 should be dirty after SetDr0 call"
3031 );
3032 }
3033
3034 sandbox.restore(snapshot).unwrap();
3036
3037 let dr0_after_restore: u64 = sandbox.call("GetDr0", ()).unwrap();
3038 assert_eq!(
3039 dr0_after_restore, 0,
3040 "DR0 should be 0 after restore (reset_vcpu should have been called)"
3041 );
3042 }
3043
3044 #[test]
3045 #[cfg(target_arch = "x86_64")]
3046 fn snapshot_restore_resets_xcr0() {
3047 let mut sandbox: Sandbox = {
3048 let path = simple_guest_as_pathbuf();
3049 let u_sbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
3050 u_sbox.evolve().unwrap()
3051 };
3052
3053 assert_eq!(sandbox.call::<u64>("ReadXcr0", ()).unwrap(), 1);
3054 let snapshot = sandbox.snapshot().unwrap();
3055
3056 sandbox.call::<()>("WriteXcr0", 3u64).unwrap();
3057 assert_eq!(sandbox.call::<u64>("ReadXcr0", ()).unwrap(), 3);
3058
3059 sandbox.restore(snapshot).unwrap();
3060
3061 assert_eq!(
3062 sandbox.call::<u64>("ReadXcr0", ()).unwrap(),
3063 1,
3064 "restore must reset XCR0"
3065 );
3066 }
3067
3068 #[test]
3071 fn stale_abort_buffer_does_not_leak_across_calls() {
3072 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3073 .build()
3074 .unwrap();
3075
3076 sbox.mem_mgr.abort_buffer.extend_from_slice(&[0xAA; 1020]);
3078
3079 let res = sbox.call::<String>("Echo", "hello".to_string());
3080 assert!(
3081 res.is_ok(),
3082 "Expected Ok after stale abort buffer, got: {:?}",
3083 res.unwrap_err()
3084 );
3085
3086 assert!(
3088 sbox.mem_mgr.abort_buffer.is_empty(),
3089 "abort_buffer should be empty after a guest call"
3090 );
3091 }
3092
3093 #[test]
3095 fn test_sandbox_creation_various_sizes() {
3096 let test_cases: [(&str, u64); 3] = [
3097 ("small (8MB heap)", SMALL_HEAP_SIZE),
3098 ("medium (64MB heap)", MEDIUM_HEAP_SIZE),
3099 ("large (256MB heap)", LARGE_HEAP_SIZE),
3100 ];
3101
3102 for (name, heap_size) in test_cases {
3103 let path = simple_guest_as_pathbuf();
3104 let sbox = SandboxBuilder::from_file(path)
3105 .heap_size(heap_size)
3106 .scratch_size(0x100000)
3107 .build()
3108 .unwrap_or_else(|e| panic!("Failed to create {} sandbox: {}", name, e));
3109
3110 drop(sbox);
3111 }
3112 }
3113
3114 #[cfg(feature = "trace_guest")]
3116 fn sandbox_for_gva_tests() -> Sandbox {
3117 let path = simple_guest_as_pathbuf();
3118 SandboxBuilder::from_file(path).build().unwrap()
3119 }
3120
3121 #[cfg(feature = "trace_guest")]
3125 fn assert_gva_read_matches(sbox: &mut Sandbox, gva: u64, len: usize) {
3126 let expected: Vec<u8> = sbox
3128 .call("ReadMappedBuffer", (gva, len as u64, true))
3129 .unwrap();
3130 assert_eq!(expected.len(), len);
3131
3132 let root_pt = sbox.vm.get_root_pt().unwrap();
3134 let actual = sbox
3135 .mem_mgr
3136 .read_guest_memory_by_gva(gva, len, root_pt)
3137 .unwrap();
3138
3139 assert_eq!(
3140 actual, expected,
3141 "read_guest_memory_by_gva at GVA {:#x} (len {}) differs from guest ReadMappedBuffer",
3142 gva, len,
3143 );
3144 }
3145
3146 #[test]
3149 #[cfg(feature = "trace_guest")]
3150 fn read_guest_memory_by_gva_single_page() {
3151 let mut sbox = sandbox_for_gva_tests();
3152 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
3153 assert_gva_read_matches(&mut sbox, code_gva, 128);
3154 }
3155
3156 #[test]
3159 #[cfg(feature = "trace_guest")]
3160 fn read_guest_memory_by_gva_full_page() {
3161 let mut sbox = sandbox_for_gva_tests();
3162 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
3163 assert_gva_read_matches(&mut sbox, code_gva, 4096);
3164 }
3165
3166 #[test]
3169 #[cfg(feature = "trace_guest")]
3170 fn read_guest_memory_by_gva_unaligned_cross_page() {
3171 let mut sbox = sandbox_for_gva_tests();
3172 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
3173 let start = code_gva + 4096 - 1;
3176 println!(
3177 "Testing unaligned cross-page read starting at {:#x} spanning 4097 bytes",
3178 start
3179 );
3180 assert_gva_read_matches(&mut sbox, start, 4097);
3181 }
3182
3183 #[test]
3185 #[cfg(feature = "trace_guest")]
3186 fn read_guest_memory_by_gva_two_full_pages() {
3187 let mut sbox = sandbox_for_gva_tests();
3188 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
3189 assert_gva_read_matches(&mut sbox, code_gva, 4096 * 2);
3190 }
3191
3192 #[test]
3196 #[cfg(feature = "trace_guest")]
3197 fn read_guest_memory_by_gva_cross_page_boundary() {
3198 let mut sbox = sandbox_for_gva_tests();
3199 let code_gva = sbox.mem_mgr.layout.get_guest_code_gva() as u64;
3200 let start = code_gva + 4096 - 100;
3202 assert_gva_read_matches(&mut sbox, start, 200);
3203 }
3204
3205 fn create_test_file(name: &str, content: &[u8]) -> (std::path::PathBuf, Vec<u8>) {
3209 use std::io::Write;
3210
3211 let page_size = page_size::get();
3212 let padded_len = content.len().max(page_size).div_ceil(page_size) * page_size;
3213 let mut padded = vec![0u8; padded_len];
3214 padded[..content.len()].copy_from_slice(content);
3215
3216 let temp_dir = std::env::temp_dir();
3217 let path = temp_dir.join(name);
3218 let _ = std::fs::remove_file(&path); let mut f = std::fs::File::create(&path).unwrap();
3220 f.write_all(&padded).unwrap();
3221 (path, content.to_vec())
3222 }
3223
3224 #[test]
3227 fn test_map_file_cow_basic() {
3228 let expected = b"hello world from map_file_cow";
3229 let (path, expected_bytes) =
3230 create_test_file("hyperlight_test_map_file_cow_basic.bin", expected);
3231
3232 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3233 .build()
3234 .unwrap();
3235
3236 let guest_base: u64 = 0x1_0000_0000;
3237 let mapped_size = sbox.map_file_cow(&path, guest_base).unwrap();
3238 assert!(mapped_size > 0, "mapped_size should be positive");
3239 assert!(
3240 mapped_size >= expected.len() as u64,
3241 "mapped_size should be >= file content length"
3242 );
3243
3244 let actual: Vec<u8> = sbox
3246 .call(
3247 "ReadMappedBuffer",
3248 (guest_base, expected_bytes.len() as u64, true),
3249 )
3250 .unwrap();
3251
3252 assert_eq!(
3253 actual, expected_bytes,
3254 "Guest should read back the exact file content"
3255 );
3256
3257 let _ = std::fs::remove_file(&path);
3259 }
3260
3261 #[test]
3264 fn test_map_file_cow_read_only_enforcement() {
3265 let content = &[0xBB; 4096];
3266 let (path, _) = create_test_file("hyperlight_test_map_file_cow_readonly.bin", content);
3267
3268 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3269 .build()
3270 .unwrap();
3271
3272 let guest_base: u64 = 0x1_0000_0000;
3273 sbox.map_file_cow(&path, guest_base).unwrap();
3274
3275 let err = sbox
3277 .call::<bool>("WriteMappedBuffer", (guest_base, content.len() as u64))
3278 .unwrap_err();
3279
3280 match err {
3281 HyperlightError::MemoryAccessViolation(addr, ..) if addr == guest_base => {}
3282 _ => panic!(
3283 "Expected MemoryAccessViolation at guest_base, got: {:?}",
3284 err
3285 ),
3286 };
3287
3288 let _ = std::fs::remove_file(&path);
3290 }
3291
3292 #[test]
3295 fn test_map_file_cow_poisoned() {
3296 let (path, _) = create_test_file("hyperlight_test_map_file_cow_poison.bin", &[0xCC; 4096]);
3297
3298 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3299 .build()
3300 .unwrap();
3301 let snapshot = sbox.snapshot().unwrap();
3302
3303 let _ = sbox
3305 .call::<()>("guest_panic", "hello".to_string())
3306 .unwrap_err();
3307 assert!(sbox.status().is_poisoned());
3308
3309 let err = sbox.map_file_cow(&path, 0x1_0000_0000).unwrap_err();
3311 assert!(matches!(err, HyperlightError::PoisonedSandbox));
3312
3313 sbox.restore(snapshot).unwrap();
3315 assert_eq!(sbox.status(), SandboxStatus::Ready);
3316 let result = sbox.map_file_cow(&path, 0x1_0000_0000);
3317 assert!(result.is_ok());
3318
3319 let _ = std::fs::remove_file(&path);
3320 }
3321
3322 #[test]
3325 fn test_map_file_cow_multi_vm_same_file() {
3326 let expected = b"shared file content across VMs";
3327 let (path, expected_bytes) =
3328 create_test_file("hyperlight_test_map_file_cow_multi_vm.bin", expected);
3329
3330 let guest_base: u64 = 0x1_0000_0000;
3331
3332 let mut sbox1 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3333 .build()
3334 .unwrap();
3335
3336 let mut sbox2 = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3337 .build()
3338 .unwrap();
3339
3340 sbox1.map_file_cow(&path, guest_base).unwrap();
3342 sbox2.map_file_cow(&path, guest_base).unwrap();
3343
3344 let actual1: Vec<u8> = sbox1
3346 .call(
3347 "ReadMappedBuffer",
3348 (guest_base, expected_bytes.len() as u64, true),
3349 )
3350 .unwrap();
3351 let actual2: Vec<u8> = sbox2
3352 .call(
3353 "ReadMappedBuffer",
3354 (guest_base, expected_bytes.len() as u64, true),
3355 )
3356 .unwrap();
3357
3358 assert_eq!(
3359 actual1, expected_bytes,
3360 "Sandbox 1 should read correct content"
3361 );
3362 assert_eq!(
3363 actual2, expected_bytes,
3364 "Sandbox 2 should read correct content"
3365 );
3366
3367 let _ = std::fs::remove_file(&path);
3368 }
3369
3370 #[test]
3373 fn test_map_file_cow_multi_vm_threaded() {
3374 let expected = b"threaded file mapping test data";
3375 let (path, expected_bytes) =
3376 create_test_file("hyperlight_test_map_file_cow_threaded.bin", expected);
3377
3378 const NUM_THREADS: usize = 5;
3379 let path = Arc::new(path);
3380 let expected_bytes = Arc::new(expected_bytes);
3381 let barrier = Arc::new(Barrier::new(NUM_THREADS));
3382 let mut handles = vec![];
3383
3384 for _ in 0..NUM_THREADS {
3385 let path = path.clone();
3386 let expected_bytes = expected_bytes.clone();
3387 let barrier = barrier.clone();
3388
3389 handles.push(thread::spawn(move || {
3390 barrier.wait();
3391
3392 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3393 .build()
3394 .unwrap();
3395
3396 let guest_base: u64 = 0x1_0000_0000;
3397 sbox.map_file_cow(&path, guest_base).unwrap();
3398
3399 let actual: Vec<u8> = sbox
3400 .call(
3401 "ReadMappedBuffer",
3402 (guest_base, expected_bytes.len() as u64, true),
3403 )
3404 .unwrap();
3405
3406 assert_eq!(actual, *expected_bytes);
3407 }));
3408 }
3409
3410 for h in handles {
3411 h.join().unwrap();
3412 }
3413
3414 let _ = std::fs::remove_file(&*path);
3415 }
3416
3417 #[test]
3420 #[cfg(target_os = "windows")]
3421 fn test_map_file_cow_cleanup_no_handle_leak() {
3422 let (path, _) = create_test_file("hyperlight_test_map_file_cow_cleanup.bin", &[0xDD; 4096]);
3423
3424 {
3425 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3426 .build()
3427 .unwrap();
3428
3429 sbox.map_file_cow(&path, 0x1_0000_0000).unwrap();
3430 }
3432
3433 std::fs::remove_file(&path)
3434 .expect("File should be deletable after sandbox with map_file_cow is dropped");
3435 }
3436
3437 #[test]
3441 fn test_map_file_cow_snapshot_remapping_cycle() {
3442 let expected = b"snapshot remapping cycle test!";
3443 let (path, expected_bytes) =
3444 create_test_file("hyperlight_test_map_file_cow_snapshot_remap.bin", expected);
3445
3446 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3447 .build()
3448 .unwrap();
3449
3450 let guest_base: u64 = 0x1_0000_0000;
3451
3452 let snapshot1 = sbox.snapshot().unwrap();
3454
3455 sbox.map_file_cow(&path, guest_base).unwrap();
3457
3458 let actual: Vec<u8> = sbox
3460 .call(
3461 "ReadMappedBuffer",
3462 (guest_base, expected_bytes.len() as u64, true),
3463 )
3464 .unwrap();
3465 assert_eq!(actual, expected_bytes);
3466
3467 let snapshot2 = sbox.snapshot().unwrap();
3469
3470 sbox.restore(snapshot1.clone()).unwrap();
3472 let is_mapped: bool = sbox.call("CheckMapped", (guest_base,)).unwrap();
3473 assert!(
3474 !is_mapped,
3475 "Region should be unmapped after restoring to snapshot₁"
3476 );
3477
3478 sbox.restore(snapshot2).unwrap();
3481 let is_mapped: bool = sbox.call("CheckMapped", (guest_base,)).unwrap();
3482 assert!(
3483 is_mapped,
3484 "Region should be mapped after restoring to snapshot₂"
3485 );
3486 let actual2: Vec<u8> = sbox
3487 .call(
3488 "ReadMappedBuffer",
3489 (guest_base, expected_bytes.len() as u64, false),
3490 )
3491 .unwrap();
3492 assert_eq!(
3493 actual2, expected_bytes,
3494 "Data should be intact after snapshot₂ restore"
3495 );
3496
3497 let _ = std::fs::remove_file(&path);
3498 }
3499
3500 #[test]
3503 fn test_map_file_cow_snapshot_restore() {
3504 let expected = b"snapshot restore basic test!!";
3505 let (path, expected_bytes) =
3506 create_test_file("hyperlight_test_map_file_cow_snap_restore.bin", expected);
3507
3508 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3509 .build()
3510 .unwrap();
3511
3512 let guest_base: u64 = 0x1_0000_0000;
3513 sbox.map_file_cow(&path, guest_base).unwrap();
3514
3515 let actual: Vec<u8> = sbox
3517 .call(
3518 "ReadMappedBuffer",
3519 (guest_base, expected_bytes.len() as u64, true),
3520 )
3521 .unwrap();
3522 assert_eq!(actual, expected_bytes);
3523
3524 let snapshot = sbox.snapshot().unwrap();
3526
3527 sbox.restore(snapshot).unwrap();
3529
3530 let actual2: Vec<u8> = sbox
3532 .call(
3533 "ReadMappedBuffer",
3534 (guest_base, expected_bytes.len() as u64, false),
3535 )
3536 .unwrap();
3537 assert_eq!(
3538 actual2, expected_bytes,
3539 "Data should be readable after restore from snapshot"
3540 );
3541
3542 let _ = std::fs::remove_file(&path);
3543 }
3544
3545 #[test]
3549 fn test_map_file_cow_deferred_basic() {
3550 let expected = b"deferred map_file_cow test data";
3551 let (path, expected_bytes) =
3552 create_test_file("hyperlight_test_map_file_cow_deferred.bin", expected);
3553
3554 let guest_base: u64 = 0x1_0000_0000;
3555
3556 let mut u_sbox =
3557 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3558 .unwrap();
3559
3560 let mapped_size = u_sbox.map_file_cow(&path, guest_base).unwrap();
3562 assert!(mapped_size > 0, "mapped_size should be positive");
3563 assert!(
3564 mapped_size >= expected.len() as u64,
3565 "mapped_size should be >= file content length"
3566 );
3567
3568 let mut sbox = u_sbox.evolve().unwrap();
3570
3571 let actual: Vec<u8> = sbox
3573 .call(
3574 "ReadMappedBuffer",
3575 (guest_base, expected_bytes.len() as u64, true),
3576 )
3577 .unwrap();
3578
3579 assert_eq!(
3580 actual, expected_bytes,
3581 "Guest should read back the exact file content after deferred mapping"
3582 );
3583
3584 let _ = std::fs::remove_file(&path);
3585 }
3586
3587 #[test]
3591 fn test_map_file_cow_deferred_drop_without_evolve() {
3592 let (path, _) = create_test_file(
3593 "hyperlight_test_map_file_cow_deferred_drop.bin",
3594 &[0xAA; 4096],
3595 );
3596
3597 let guest_base: u64 = 0x1_0000_0000;
3598
3599 {
3600 let mut u_sbox =
3601 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3602 .unwrap();
3603
3604 u_sbox.map_file_cow(&path, guest_base).unwrap();
3605 }
3608
3609 #[cfg(target_os = "windows")]
3612 std::fs::remove_file(&path)
3613 .expect("File should be deletable after dropping UninitializedSandbox");
3614 #[cfg(not(target_os = "windows"))]
3615 let _ = std::fs::remove_file(&path);
3616 }
3617
3618 #[test]
3621 fn test_map_file_cow_unaligned_guest_base() {
3622 let (path, _) =
3623 create_test_file("hyperlight_test_map_file_cow_unaligned.bin", &[0xBB; 4096]);
3624
3625 let mut u_sbox =
3626 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3627 .unwrap();
3628
3629 let unaligned_base: u64 = (page_size::get() + 1) as u64;
3631 let result = u_sbox.map_file_cow(&path, unaligned_base);
3632 assert!(
3633 result.is_err(),
3634 "map_file_cow should reject unaligned guest_base"
3635 );
3636
3637 let _ = std::fs::remove_file(&path);
3638 }
3639
3640 #[test]
3642 fn test_map_file_cow_empty_file() {
3643 let temp_dir = std::env::temp_dir();
3644 let path = temp_dir.join("hyperlight_test_map_file_cow_empty.bin");
3645 let _ = std::fs::remove_file(&path);
3646 std::fs::File::create(&path).unwrap(); let mut u_sbox =
3649 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3650 .unwrap();
3651
3652 let guest_base: u64 = 0x1_0000_0000;
3653 let result = u_sbox.map_file_cow(&path, guest_base);
3654 assert!(result.is_err(), "map_file_cow should reject empty files");
3655
3656 let _ = std::fs::remove_file(&path);
3657 }
3658
3659 #[test]
3661 fn test_map_file_cow_overlapping_mappings() {
3662 let (path1, _) =
3663 create_test_file("hyperlight_test_map_file_cow_overlap1.bin", &[0xAA; 4096]);
3664 let (path2, _) =
3665 create_test_file("hyperlight_test_map_file_cow_overlap2.bin", &[0xBB; 4096]);
3666
3667 let guest_base: u64 = 0x1_0000_0000;
3668
3669 let mut u_sbox =
3670 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3671 .unwrap();
3672
3673 u_sbox.map_file_cow(&path1, guest_base).unwrap();
3675
3676 let result = u_sbox.map_file_cow(&path2, guest_base);
3678 assert!(
3679 result.is_err(),
3680 "map_file_cow should reject overlapping guest address ranges"
3681 );
3682
3683 let _ = std::fs::remove_file(&path1);
3684 let _ = std::fs::remove_file(&path2);
3685 }
3686
3687 #[test]
3690 fn test_map_file_cow_shared_mem_overlap() {
3691 let (path, _) = create_test_file(
3692 "hyperlight_test_map_file_cow_overlap_shm.bin",
3693 &[0xCC; 4096],
3694 );
3695
3696 let mut u_sbox =
3697 UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
3698 .unwrap();
3699
3700 let base_addr = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;
3702 let result = u_sbox.map_file_cow(&path, base_addr);
3704 assert!(
3705 result.is_err(),
3706 "map_file_cow should reject guest_base inside shared memory"
3707 );
3708
3709 let _ = std::fs::remove_file(&path);
3710 }
3711
3712 #[test]
3713 fn map_region_rejects_overlapping_regions() {
3714 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3715 .build()
3716 .unwrap();
3717
3718 let mem1 = allocate_guest_memory();
3719 let mem2 = allocate_guest_memory();
3720 let guest_base: usize = 0x200000000;
3721 let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
3722
3723 unsafe { sbox.map_region(®ion1).unwrap() };
3725
3726 let region2 = region_for_memory(&mem2, guest_base, MemoryRegionFlags::READ);
3728 let err = unsafe { sbox.map_region(®ion2) }.unwrap_err();
3729 assert!(
3730 format!("{err:?}").contains("Overlapping"),
3731 "Expected Overlapping error, got: {err:?}"
3732 );
3733 }
3734
3735 #[test]
3736 fn map_region_rejects_partial_overlap() {
3737 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3738 .build()
3739 .unwrap();
3740
3741 let ps = page_size::get();
3743 let mem1 = page_aligned_memory(&vec![0xAA; ps * 2]); let mem2 = page_aligned_memory(&vec![0xBB; ps * 2]); let guest_base: usize = 0x200000000;
3746 let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
3747
3748 unsafe { sbox.map_region(®ion1).unwrap() };
3749
3750 let overlap_base = guest_base - ps;
3752 let region2 = region_for_memory(&mem2, overlap_base, MemoryRegionFlags::READ);
3753 let err = unsafe { sbox.map_region(®ion2) }.unwrap_err();
3754 assert!(
3755 format!("{err:?}").contains("verlap"),
3756 "Expected overlap error for partial overlap, got: {err:?}"
3757 );
3758 }
3759
3760 #[test]
3761 fn map_region_allows_adjacent_non_overlapping() {
3762 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3763 .build()
3764 .unwrap();
3765
3766 let mem1 = allocate_guest_memory();
3767 let mem2 = allocate_guest_memory();
3768 let guest_base: usize = 0x200000000;
3769 let region1 = region_for_memory(&mem1, guest_base, MemoryRegionFlags::READ);
3770 let region_size = mem1.mem_size();
3771
3772 unsafe { sbox.map_region(®ion1).unwrap() };
3773
3774 let adjacent_base = guest_base + region_size;
3776 let region2 = region_for_memory(&mem2, adjacent_base, MemoryRegionFlags::READ);
3777 unsafe { sbox.map_region(®ion2).unwrap() };
3778 }
3779
3780 #[test]
3781 fn map_region_rejects_overlap_with_snapshot() {
3782 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3783 .build()
3784 .unwrap();
3785
3786 let mem = allocate_guest_memory();
3788 let region = region_for_memory(
3789 &mem,
3790 crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS,
3791 MemoryRegionFlags::READ,
3792 );
3793 let err = unsafe { sbox.map_region(®ion) }.unwrap_err();
3794 assert!(
3795 format!("{err:?}").contains("Overlapping"),
3796 "Expected Overlapping error for snapshot overlap, got: {err:?}"
3797 );
3798 }
3799
3800 #[test]
3801 fn map_region_rejects_overlap_with_scratch() {
3802 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3803 .build()
3804 .unwrap();
3805
3806 let scratch_addr = hyperlight_common::layout::scratch_base_gpa(
3808 crate::sandbox::SandboxConfiguration::DEFAULT_SCRATCH_SIZE,
3809 ) as usize;
3810 let mem = allocate_guest_memory();
3811 let region = region_for_memory(&mem, scratch_addr, MemoryRegionFlags::READ);
3812 let err = unsafe { sbox.map_region(®ion) }.unwrap_err();
3813 assert!(
3814 format!("{err:?}").contains("verlap"),
3815 "Expected overlap error for scratch region, got: {err:?}"
3816 );
3817 }
3818
3819 #[cfg(target_arch = "x86_64")]
3820 mod msr_tests {
3821 use super::*;
3822 use crate::hypervisor::hyperlight_vm::{CreateHyperlightVmError, HyperlightVmError};
3823 use crate::hypervisor::regs::{
3824 MSR_APERF, MSR_BNDCFGS, MSR_CSTAR, MSR_DEBUGCTL, MSR_IA32_SSP,
3825 MSR_INTERRUPT_SSP_TABLE_ADDR, MSR_KERNEL_GS_BASE as KERNEL_GS_BASE, MSR_LSTAR,
3826 MSR_MPERF, MSR_MTRR_DEF_TYPE, MSR_MTRR_FIX64K_00000, MSR_PAT, MSR_PL0_SSP, MSR_PL1_SSP,
3827 MSR_PL2_SSP, MSR_PL3_SSP, MSR_S_CET, MSR_SFMASK, MSR_SPEC_CTRL, MSR_STAR,
3828 MSR_SYSENTER_CS as SYSENTER_CS, MSR_SYSENTER_EIP, MSR_SYSENTER_ESP, MSR_TSC,
3829 MSR_TSC_ADJUST, MSR_TSC_AUX, MSR_TSC_DEADLINE, MSR_TSX_CTRL, MSR_U_CET,
3830 MSR_UMWAIT_CONTROL, MSR_VIRT_SPEC_CTRL, MSR_XFD, MSR_XFD_ERR, MSR_XSS,
3831 };
3832 use crate::hypervisor::virtual_machine::{
3833 CreateVmError, RegisterError, ResetVcpuError, VmError,
3834 };
3835 use crate::sandbox::snapshot::Snapshot;
3836
3837 fn assert_msr_not_declarable(error: &HyperlightError, expected: u32) {
3838 assert!(
3839 matches!(
3840 error,
3841 HyperlightError::HyperlightVmError(HyperlightVmError::Create(
3842 CreateHyperlightVmError::Vm(VmError::CreateVm(
3843 CreateVmError::MsrNotDeclarable { msr, .. }
3844 ))
3845 )) if *msr == expected
3846 ),
3847 "expected MsrNotAllowable for {expected:#x}, got: {error:?}"
3848 );
3849 }
3850
3851 fn assert_snapshot_msr_index_invalid(error: &HyperlightError) {
3852 assert!(
3853 matches!(
3854 error,
3855 HyperlightError::HyperlightVmError(HyperlightVmError::Restore(
3856 ResetVcpuError::Register(RegisterError::InvalidSnapshotMsrIndex { .. })
3857 ))
3858 ),
3859 "expected InvalidSnapshotMsrIndex, got: {error:?}"
3860 );
3861 }
3862
3863 #[test]
3864 fn kernel_gs_base_does_not_leak_through_swapgs() {
3865 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3866 .build()
3867 .unwrap();
3868
3869 let original: u64 = sandbox.call("ReadKernelGsBaseViaSwapgs", ()).unwrap();
3870 let sentinel = if original == 0x0000_7AAA_5555_AAAA {
3871 0x0000_6BBB_4444_BBBB
3872 } else {
3873 0x0000_7AAA_5555_AAAA
3874 };
3875 let snapshot = sandbox.snapshot().unwrap();
3876
3877 sandbox
3878 .call::<()>("WriteKernelGsBaseViaSwapgs", sentinel)
3879 .unwrap();
3880 assert_eq!(
3881 sandbox
3882 .call::<u64>("ReadKernelGsBaseViaSwapgs", ())
3883 .unwrap(),
3884 sentinel
3885 );
3886
3887 sandbox.restore(snapshot).unwrap();
3888 assert_eq!(
3889 sandbox
3890 .call::<u64>("ReadKernelGsBaseViaSwapgs", ())
3891 .unwrap(),
3892 original,
3893 "KERNEL_GS_BASE leaked across restore"
3894 );
3895 }
3896
3897 #[test]
3898 fn snapshot_msr_values_survive_full_in_memory_lifecycle() {
3899 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3900 .guest_msrs(&[KERNEL_GS_BASE])
3901 .unwrap()
3902 .build()
3903 .unwrap();
3904 let first = 0x1111;
3905 let second = 0x2222;
3906 let third = 0x3333;
3907
3908 source
3909 .call::<()>("WriteMSR", (KERNEL_GS_BASE, first))
3910 .unwrap();
3911 assert_eq!(
3912 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3913 first
3914 );
3915 let first_snapshot = source.snapshot().unwrap();
3916
3917 source
3918 .call::<()>("WriteMSR", (KERNEL_GS_BASE, second))
3919 .unwrap();
3920 assert_eq!(
3921 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3922 second
3923 );
3924 source.restore(first_snapshot.clone()).unwrap();
3925 assert_eq!(
3926 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3927 first
3928 );
3929
3930 let mut clone = SandboxBuilder::from_snapshot(first_snapshot.clone())
3931 .guest_msrs(&[KERNEL_GS_BASE])
3932 .unwrap()
3933 .build()
3934 .unwrap();
3935 assert_eq!(clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(), first);
3936
3937 clone
3938 .call::<()>("WriteMSR", (KERNEL_GS_BASE, third))
3939 .unwrap();
3940 assert_eq!(clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(), third);
3941 let third_snapshot = clone.snapshot().unwrap();
3942 source.restore(third_snapshot.clone()).unwrap();
3943 assert_eq!(
3944 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3945 third
3946 );
3947
3948 let mut second_clone = SandboxBuilder::from_snapshot(third_snapshot)
3949 .guest_msrs(&[KERNEL_GS_BASE])
3950 .unwrap()
3951 .build()
3952 .unwrap();
3953 assert_eq!(
3954 second_clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3955 third
3956 );
3957 second_clone.restore(first_snapshot).unwrap();
3958 assert_eq!(
3959 second_clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3960 first
3961 );
3962 }
3963
3964 #[test]
3965 fn equivalent_msr_configs_are_order_independent_across_sandboxes() {
3966 let source_order = [KERNEL_GS_BASE, SYSENTER_CS];
3967 let target_order = [SYSENTER_CS, KERNEL_GS_BASE];
3968 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3969 .guest_msrs(&source_order)
3970 .unwrap()
3971 .build()
3972 .unwrap();
3973 source
3974 .call::<()>("WriteMSR", (KERNEL_GS_BASE, 0x4444u64))
3975 .unwrap();
3976 assert_eq!(
3977 source.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3978 0x4444
3979 );
3980 source
3981 .call::<()>("WriteMSR", (SYSENTER_CS, 0x5555u64))
3982 .unwrap();
3983 assert_eq!(source.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
3984 let snapshot = source.snapshot().unwrap();
3985
3986 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
3987 .guest_msrs(&target_order)
3988 .unwrap()
3989 .build()
3990 .unwrap();
3991 target
3992 .call::<()>("WriteMSR", (KERNEL_GS_BASE, 0xAAAAu64))
3993 .unwrap();
3994 assert_eq!(
3995 target.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
3996 0xAAAA
3997 );
3998 target
3999 .call::<()>("WriteMSR", (SYSENTER_CS, 0xBBBBu64))
4000 .unwrap();
4001 assert_eq!(target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0xBBBB);
4002 target.restore(snapshot.clone()).unwrap();
4003 assert_eq!(
4004 target.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4005 0x4444
4006 );
4007 assert_eq!(target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4008
4009 let mut clone = SandboxBuilder::from_snapshot(snapshot)
4010 .guest_msrs(&target_order)
4011 .unwrap()
4012 .build()
4013 .unwrap();
4014 assert_eq!(
4015 clone.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4016 0x4444
4017 );
4018 assert_eq!(clone.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), 0x5555);
4019 }
4020
4021 #[test]
4025 fn snapshot_restores_into_superset_guest_msrs() {
4026 const SYSENTER_ESP: u32 = 0x175;
4027 let sentinel: u64 = 0x1234;
4028 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4029 .guest_msrs(&[SYSENTER_CS])
4030 .unwrap()
4031 .build()
4032 .unwrap();
4033 source
4034 .call::<()>("WriteMSR", (SYSENTER_CS, sentinel))
4035 .unwrap();
4036 let snapshot = source.snapshot().unwrap();
4037
4038 let mut clone = SandboxBuilder::from_snapshot(snapshot.clone())
4039 .guest_msrs(&[SYSENTER_CS, SYSENTER_ESP])
4040 .unwrap()
4041 .build()
4042 .unwrap();
4043 assert_eq!(clone.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(), sentinel);
4044 let baseline: u64 = clone.call("ReadMSR", SYSENTER_ESP).unwrap();
4045
4046 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4047 .guest_msrs(&[SYSENTER_CS, SYSENTER_ESP])
4048 .unwrap()
4049 .build()
4050 .unwrap();
4051 target
4052 .call::<()>("WriteMSR", (SYSENTER_ESP, baseline ^ 0x55))
4053 .unwrap();
4054 target.restore(snapshot).unwrap();
4055 assert_eq!(
4056 target.call::<u64>("ReadMSR", SYSENTER_CS).unwrap(),
4057 sentinel
4058 );
4059 assert_eq!(
4061 target.call::<u64>("ReadMSR", SYSENTER_ESP).unwrap(),
4062 baseline
4063 );
4064 }
4065
4066 #[test]
4071 fn snapshot_rejects_non_superset_guest_msrs() {
4072 const SYSENTER_ESP: u32 = 0x175;
4073 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4074 .guest_msrs(&[SYSENTER_CS])
4075 .unwrap()
4076 .build()
4077 .unwrap();
4078 source
4079 .call::<()>("WriteMSR", (SYSENTER_CS, 0x1234u64))
4080 .unwrap();
4081 let snapshot = source.snapshot().unwrap();
4082
4083 for dest in [&[][..], &[SYSENTER_ESP][..]] {
4087 let err = SandboxBuilder::from_snapshot(snapshot.clone())
4088 .guest_msrs(dest)
4089 .unwrap()
4090 .build()
4091 .expect_err("from_snapshot must reject an unrestorable snapshot MSR");
4092 assert_snapshot_msr_index_invalid(&err);
4093
4094 let mut target = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4095 .guest_msrs(dest)
4096 .unwrap()
4097 .build()
4098 .unwrap();
4099 let err = target
4100 .restore(snapshot.clone())
4101 .expect_err("restore must reject an unrestorable snapshot MSR");
4102 assert_snapshot_msr_index_invalid(&err);
4103 assert!(target.status().is_poisoned());
4104 assert!(matches!(
4105 target.call::<String>("Echo", "hi".to_string()),
4106 Err(HyperlightError::PoisonedSandbox)
4107 ));
4108 }
4109 }
4110
4111 #[test]
4112 fn from_pre_init_snapshot_uses_local_msr_reset_set() {
4113 let mut config = SandboxConfiguration::default();
4114 config.guest_msrs(&[KERNEL_GS_BASE]).unwrap();
4115 let snapshot = Arc::new(
4116 Snapshot::from_env(GuestBinary::FilePath(simple_guest_as_pathbuf()), config)
4117 .unwrap(),
4118 );
4119 assert!(snapshot.msrs().is_none());
4120
4121 let mut sandbox = SandboxBuilder::from_snapshot(snapshot.clone())
4122 .guest_msrs(&[KERNEL_GS_BASE])
4123 .unwrap()
4124 .build()
4125 .unwrap();
4126 let baseline: u64 = sandbox.call("ReadMSR", KERNEL_GS_BASE).unwrap();
4127 sandbox
4128 .call::<()>("WriteMSR", (KERNEL_GS_BASE, baseline ^ 0x55))
4129 .unwrap();
4130 assert_eq!(
4131 sandbox.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap(),
4132 baseline ^ 0x55
4133 );
4134 }
4135
4136 #[test]
4137 #[cfg(kvm)]
4138 fn guest_cannot_enable_x2apic_through_apic_base() {
4139 use crate::hypervisor::regs::APIC_BASE_X2APIC_ENABLE;
4140 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4141
4142 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4143 return;
4144 }
4145
4146 const MSR_IA32_APIC_BASE: u32 = 0x1B;
4147 const MSR_X2APIC_BASE: u32 = 0x800;
4148 const APIC_BASE_DEFAULT: u64 = 0xFEE0_0900;
4149
4150 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4151 .build()
4152 .unwrap();
4153 let snapshot = sandbox.snapshot().unwrap();
4154
4155 let x2apic_base = APIC_BASE_DEFAULT | APIC_BASE_X2APIC_ENABLE;
4156 let result = sandbox.call::<()>("WriteMSR", (MSR_IA32_APIC_BASE, x2apic_base));
4157 assert!(
4158 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4159 "guest enabled x2APIC through APIC_BASE: {result:?}"
4160 );
4161 assert!(sandbox.status().is_poisoned());
4162 sandbox.restore(snapshot).unwrap();
4163 assert!(!sandbox.status().is_poisoned());
4164
4165 let result = sandbox.call::<()>("WriteMSR", (MSR_X2APIC_BASE, 1u64));
4166 assert!(
4167 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4168 "x2APIC MSR access succeeded after restore: {result:?}"
4169 );
4170 assert!(sandbox.status().is_poisoned());
4171 }
4172
4173 #[test]
4174 #[cfg(kvm)]
4175 fn denied_msr_access_poisons_sandbox() {
4176 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4177
4178 match get_available_hypervisor() {
4179 Some(HypervisorType::Kvm) => {}
4180 _ => {
4181 return;
4182 }
4183 }
4184
4185 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4186 .build()
4187 .unwrap();
4188
4189 let snapshot = sbox.snapshot().unwrap();
4190 let msr_index: u32 = 0xC000_0102; let result = sbox.call::<u64>("ReadMSR", msr_index);
4193 assert!(
4194 matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
4195 "RDMSR 0x{:X}: expected direct #GP, got: {:?}",
4196 msr_index,
4197 result
4198 );
4199 assert!(sbox.status().is_poisoned());
4200
4201 sbox.restore(snapshot.clone()).unwrap();
4202
4203 let result = sbox.call::<()>("WriteMSR", (msr_index, 0x5u64));
4204 assert!(
4205 matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
4206 "WRMSR 0x{:X}: expected direct #GP, got: {:?}",
4207 msr_index,
4208 result
4209 );
4210 assert!(sbox.status().is_poisoned());
4211 }
4212
4213 #[test]
4214 #[cfg(kvm)]
4215 fn batched_msr_probe_recovers_from_denied_reads() {
4216 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4217
4218 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4219 return;
4220 }
4221
4222 const KVM_CUSTOM_MSR: u32 = 0x4B56_4D00;
4223 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4224 .guest_msrs(&[KERNEL_GS_BASE])
4225 .unwrap()
4226 .build()
4227 .unwrap();
4228
4229 assert_eq!(
4230 sbox.call::<Vec<u8>>("ProbeReadableMSRs", (0u32, 4096u32))
4231 .unwrap()
4232 .len(),
4233 512
4234 );
4235 assert_eq!(
4236 sbox.call::<Vec<u8>>("ProbeReadableMSRs", (KERNEL_GS_BASE, 1u32))
4237 .unwrap(),
4238 vec![1]
4239 );
4240 assert_eq!(
4241 sbox.call::<Vec<u8>>("ProbeReadableMSRs", (KVM_CUSTOM_MSR, 1u32))
4242 .unwrap(),
4243 vec![0]
4244 );
4245 assert!(!sbox.status().is_poisoned());
4246 sbox.call::<u64>("ReadMSR", KERNEL_GS_BASE).unwrap();
4247 }
4248
4249 #[test]
4250 #[cfg(target_arch = "x86_64")]
4251 fn nested_virtualization_is_hidden_from_guest() {
4252 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4253 .build()
4254 .unwrap();
4255
4256 let features: u32 = sandbox.call("NestedVirtualizationCpuid", ()).unwrap();
4257 assert_eq!(features & 0b11, 0, "guest CPUID exposes VMX or SVM");
4258 }
4259
4260 #[test]
4261 #[cfg(kvm)]
4262 fn nested_vmx_setup_msrs_are_denied() {
4263 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4264
4265 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4266 return;
4267 }
4268
4269 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4270 .build()
4271 .unwrap();
4272
4273 let snapshot = sandbox.snapshot().unwrap();
4274 let vmx_basic: u32 = 0x480;
4275 let result = sandbox.call::<u64>("ReadMSR", vmx_basic);
4276 assert!(
4277 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4278 "RDMSR 0x{vmx_basic:X}: expected direct #GP, got: {result:?}"
4279 );
4280
4281 sandbox.restore(snapshot).unwrap();
4282 let feature_control: u32 = 0x3A;
4283 let result = sandbox.call::<()>("WriteMSR", (feature_control, 0x5u64));
4284 assert!(
4285 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4286 "WRMSR 0x{feature_control:X}: expected direct #GP, got: {result:?}"
4287 );
4288 }
4289
4290 #[test]
4295 #[cfg(target_arch = "x86_64")]
4296 fn guest_cannot_enter_vmx_operation() {
4297 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4298 .build()
4299 .unwrap();
4300
4301 let result = sandbox.call::<()>("EnableVmxOperation", ());
4302 assert!(
4303 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4304 "guest entered VMX operation via CR4.VMXE: {result:?}"
4305 );
4306 assert!(sandbox.status().is_poisoned());
4307 }
4308
4309 #[test]
4314 #[cfg(target_arch = "x86_64")]
4315 fn guest_vmlaunch_faults() {
4316 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4317 .build()
4318 .unwrap();
4319
4320 let result = sandbox.call::<()>("ExecuteVmlaunch", ());
4321 assert!(
4322 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4323 "guest executed VMLAUNCH without faulting: {result:?}"
4324 );
4325 assert!(sandbox.status().is_poisoned());
4326 }
4327
4328 #[test]
4331 #[cfg(kvm)]
4332 fn x2apic_is_hidden_from_guest_cpuid() {
4333 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4334
4335 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4336 return;
4337 }
4338
4339 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4340 .build()
4341 .unwrap();
4342
4343 assert!(
4344 !sandbox.call::<bool>("X2apicSupported", ()).unwrap(),
4345 "guest CPUID advertises x2APIC"
4346 );
4347 }
4348
4349 #[test]
4351 #[cfg(target_arch = "x86_64")]
4352 fn test_allow_non_resettable_msr_fails_creation() {
4353 let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4355 .guest_msrs(&[0x49])
4356 .unwrap()
4357 .build()
4358 .unwrap_err();
4359
4360 assert_msr_not_declarable(&err, 0x49);
4361 }
4362
4363 #[test]
4365 #[cfg(kvm)]
4366 fn unclassified_declared_msr_rejected_at_creation() {
4367 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4368
4369 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4370 return;
4371 }
4372
4373 let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4375 .guest_msrs(&[0x1A0])
4376 .unwrap()
4377 .build()
4378 .expect_err("an unclassified declared MSR must be rejected at creation");
4379
4380 assert_msr_not_declarable(&err, 0x1A0);
4381 }
4382
4383 #[test]
4384 #[cfg(target_arch = "x86_64")]
4385 fn test_multiple_guest_msrs_reset_across_restore() {
4386 let msrs: [u32; 4] = [0x174, 0x175, 0x176, 0xC000_0102];
4388
4389 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4390 .guest_msrs(&msrs)
4391 .unwrap()
4392 .build()
4393 .unwrap();
4394
4395 let baseline_snapshot = sbox.snapshot().unwrap();
4396
4397 let value: u64 = 0x1000;
4398 for &msr in &msrs {
4399 sbox.call::<()>("WriteMSR", (msr, value)).unwrap();
4400 let read_value: u64 = sbox.call("ReadMSR", msr).unwrap();
4401 assert_eq!(read_value, value, "MSR 0x{msr:X} should be writable");
4402 }
4403
4404 sbox.restore(baseline_snapshot).unwrap();
4405 for &msr in &msrs {
4406 let read_value: u64 = sbox.call("ReadMSR", msr).unwrap();
4407 assert_ne!(
4408 read_value, value,
4409 "MSR 0x{msr:X} should be reset to baseline across restore"
4410 );
4411 }
4412 }
4413
4414 #[test]
4416 #[cfg(target_arch = "x86_64")]
4417 fn test_declared_msr_does_not_leak_across_restore() {
4418 let msr_index: u32 = 0xC000_0102; let sentinel: u64 = 0xCAFE_F00D;
4420
4421 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4422 .guest_msrs(&[msr_index])
4423 .unwrap()
4424 .build()
4425 .unwrap();
4426
4427 let baseline = sbox.snapshot().unwrap();
4428 let original: u64 = sbox.call("ReadMSR", msr_index).unwrap();
4429 assert_ne!(
4430 original, sentinel,
4431 "test sentinel must differ from the baseline value"
4432 );
4433
4434 sbox.call::<()>("WriteMSR", (msr_index, sentinel)).unwrap();
4435 assert_eq!(
4436 sbox.call::<u64>("ReadMSR", msr_index).unwrap(),
4437 sentinel,
4438 "sentinel should be observable before restore"
4439 );
4440 sbox.restore(baseline).unwrap();
4441
4442 let after: u64 = sbox.call("ReadMSR", msr_index).unwrap();
4443 assert_ne!(after, sentinel, "sentinel leaked across restore");
4444 assert_eq!(after, original, "MSR not reset to its baseline value");
4445 }
4446
4447 #[test]
4449 #[cfg(all(kvm, target_arch = "x86_64"))]
4450 fn test_debugctl_and_x2apic_msr_denied_by_default() {
4451 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4452
4453 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4454 return;
4455 }
4456
4457 for msr_index in [0x1D9_u32, 0x800] {
4458 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4459 .build()
4460 .unwrap();
4461
4462 let result = sbox.call::<()>("WriteMSR", (msr_index, 0x1u64));
4463 assert!(
4464 matches!(&result, Err(HyperlightError::GuestAborted(_, _))),
4465 "WRMSR 0x{msr_index:X}: expected direct #GP, got: {result:?}"
4466 );
4467 assert!(
4468 sbox.status().is_poisoned(),
4469 "sandbox should be poisoned after a denied WRMSR to 0x{msr_index:X}"
4470 );
4471 }
4472 }
4473
4474 #[test]
4475 #[cfg(all(kvm, target_arch = "x86_64"))]
4476 fn all_kvm_custom_msrs_are_denied() {
4477 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4478
4479 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4480 return;
4481 }
4482
4483 const KVM_CUSTOM_MSR_START: u32 = 0x4B56_4D00;
4484 const KVM_CUSTOM_MSR_END: u32 = 0x4B56_4DFF;
4485
4486 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4487 .build()
4488 .unwrap();
4489 let snapshot = sandbox.snapshot().unwrap();
4490
4491 for index in KVM_CUSTOM_MSR_START..=KVM_CUSTOM_MSR_END {
4492 let result = sandbox.call::<u64>("ReadMSR", index);
4493 assert!(
4494 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4495 "RDMSR {index:#x} was not denied: {result:?}"
4496 );
4497 sandbox.restore(snapshot.clone()).unwrap();
4498
4499 let result = sandbox.call::<()>("WriteMSR", (index, 1u64));
4500 assert!(
4501 matches!(result, Err(HyperlightError::GuestAborted(_, _))),
4502 "WRMSR {index:#x} was not denied: {result:?}"
4503 );
4504 sandbox.restore(snapshot.clone()).unwrap();
4505 }
4506 }
4507
4508 #[test]
4512 #[cfg(target_arch = "x86_64")]
4513 fn unresettable_msr_classes_do_not_leak() {
4514 let cases: &[(u32, &str)] = &[
4515 (0xC1, "PMU IA32_PMC0"),
4516 (0x186, "PMU IA32_PERFEVTSEL0"),
4517 (0x38F, "PMU IA32_PERF_GLOBAL_CTRL"),
4518 (0x1C8, "LBR_SELECT"),
4519 (0x14CE, "arch-LBR IA32_LBR_CTL"),
4520 (0x1D4, "FRED IA32_FRED_CONFIG"),
4521 (0xC001_0114, "AMD VM_CR"),
4522 (0xC001_0117, "AMD VM_HSAVE_PA"),
4523 ];
4524
4525 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4526 .build()
4527 .unwrap();
4528
4529 for &(msr, _name) in cases {
4530 assert_msr_write_does_not_survive_restore(&mut sbox, msr, 0x1);
4531 }
4532 }
4533
4534 #[test]
4537 #[cfg(target_arch = "x86_64")]
4538 fn misc_enable_guest_write_does_not_survive_restore() {
4539 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4540 .build()
4541 .unwrap();
4542 assert_msr_write_does_not_survive_restore(&mut sbox, 0x1A0, 1u64 << 40);
4543 }
4544
4545 #[test]
4547 #[cfg(target_arch = "x86_64")]
4548 fn runtime_msr_table_entries_are_justified() {
4549 use crate::hypervisor::regs::resettable_msr_indices;
4550
4551 #[cfg(kvm)]
4552 let is_kvm = matches!(
4553 crate::hypervisor::virtual_machine::get_available_hypervisor(),
4554 Some(crate::hypervisor::virtual_machine::HypervisorType::Kvm)
4555 );
4556 #[cfg(not(kvm))]
4557 let is_kvm = false;
4558
4559 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4560 .build()
4561 .unwrap();
4562
4563 let reset_indices: Vec<u32> = sbox.vm.reset_set_indices();
4564
4565 for index in resettable_msr_indices() {
4566 if !reset_indices.contains(&index) {
4567 assert_omitted_msr_does_not_retain(&mut sbox, index);
4568 } else if is_kvm && index == KERNEL_GS_BASE {
4569 } else if (index == MSR_TSC && !is_kvm) || matches!(index, MSR_MPERF | MSR_APERF) {
4572 assert_guest_counter_is_writable_and_restored(&mut sbox, index);
4573 } else if let Some(test_value) = guest_write_test_value(index) {
4574 assert_guest_msr_is_writable_and_restored(&mut sbox, index, test_value);
4575 } else {
4576 assert!(
4577 reset_exception_reason(index).is_some(),
4578 "MSR 0x{index:X} is in the reset set without positive guest-write coverage or an explicit reason"
4579 );
4580 }
4581 }
4582 }
4583
4584 fn assert_omitted_msr_does_not_retain(sbox: &mut Sandbox, index: u32) {
4585 let baseline = sbox.snapshot().unwrap();
4586 let original: u64 = match sbox.call("ReadMSR", index) {
4587 Ok(value) => value,
4588 Err(_) => {
4589 assert!(
4590 sbox.status().is_poisoned(),
4591 "0x{index:X}: fault did not poison sandbox"
4592 );
4593 sbox.restore(baseline).unwrap();
4594 return;
4595 }
4596 };
4597 let preferred = guest_write_test_value(index).unwrap_or(original ^ 1);
4598 let candidates = [preferred, original ^ 1, original ^ 2, 0, 1, 0x1000];
4599
4600 for candidate in candidates {
4601 if candidate == original {
4602 continue;
4603 }
4604 if sbox.call::<()>("WriteMSR", (index, candidate)).is_err() {
4605 assert!(
4606 sbox.status().is_poisoned(),
4607 "0x{index:X}: fault did not poison sandbox"
4608 );
4609 sbox.restore(baseline.clone()).unwrap();
4610 continue;
4611 }
4612 let written: u64 = sbox.call("ReadMSR", index).unwrap_or_else(|error| {
4613 panic!("0x{index:X}: read after successful write failed: {error:?}")
4614 });
4615 if written != original {
4616 sbox.restore(baseline).unwrap();
4617 let after: u64 = sbox.call("ReadMSR", index).unwrap();
4618 assert_eq!(
4619 after, original,
4620 "0x{index:X}: guest retained a write but the MSR is absent from the reset set"
4621 );
4622 return;
4623 }
4624 sbox.restore(baseline.clone()).unwrap();
4625 }
4626 }
4627
4628 fn guest_write_test_value(index: u32) -> Option<u64> {
4629 match index {
4630 SYSENTER_CS => Some(0x10),
4631 MSR_SYSENTER_ESP | MSR_SYSENTER_EIP => Some(0x1000),
4632 MSR_PAT => Some(0x0007_0406_0007_0406),
4633 MSR_STAR => Some(0x001B_0008_0000_0000),
4634 MSR_LSTAR | MSR_CSTAR => Some(0x1000),
4635 MSR_SFMASK => Some(0x200),
4636 KERNEL_GS_BASE => Some(0x1000),
4637 MSR_TSC_ADJUST => Some(0x1000),
4638 MSR_TSC_AUX => Some(0x5),
4639 MSR_MTRR_DEF_TYPE => Some(0xC00),
4640 0x200..=0x21F if index & 1 == 0 => Some(0x6), 0x200..=0x21F => Some(0x800), MSR_MTRR_FIX64K_00000 | 0x258 | 0x259 | 0x268..=0x26F => {
4643 Some(0x0606_0606_0606_0606)
4644 }
4645 _ => None,
4646 }
4647 }
4648
4649 fn reset_exception_reason(index: u32) -> Option<&'static str> {
4650 match index {
4651 MSR_TSC => Some("KVM denies direct guest TSC MSR access"),
4652 MSR_IA32_SSP => Some(
4653 "active SSP has no architectural RDMSR/WRMSR; covered by active_ssp_does_not_leak_across_restore",
4654 ),
4655 MSR_DEBUGCTL => Some("DEBUGCTL support depends on exposed debug features"),
4656 MSR_SPEC_CTRL => Some("SPEC_CTRL writable bits depend on mitigation features"),
4657 MSR_U_CET
4658 | MSR_S_CET
4659 | MSR_PL0_SSP
4660 | MSR_PL1_SSP
4661 | MSR_PL2_SSP
4662 | MSR_PL3_SSP
4663 | MSR_INTERRUPT_SSP_TABLE_ADDR => {
4664 Some("CET writable state depends on exposed CET features")
4665 }
4666 MSR_TSX_CTRL => Some("TSX_CTRL writable bits depend on exposed TSX features"),
4667 MSR_XFD | MSR_XFD_ERR => Some("XFD writable bits depend on exposed XSAVE features"),
4668 MSR_UMWAIT_CONTROL => {
4669 Some("UMWAIT_CONTROL writable bits depend on exposed WAITPKG features")
4670 }
4671 MSR_TSC_DEADLINE => {
4672 Some("TSC_DEADLINE writable bits depend on exposed APIC-timer features")
4673 }
4674 MSR_BNDCFGS => Some("BNDCFGS writable bits depend on exposed MPX features"),
4675 MSR_XSS => Some("XSS writable bits depend on exposed XSAVE features"),
4676 MSR_VIRT_SPEC_CTRL => {
4677 Some("VIRT_SPEC_CTRL writable bits depend on exposed AMD SSBD virtualization")
4678 }
4679 _ => None,
4680 }
4681 }
4682
4683 fn assert_guest_msr_is_writable_and_restored(
4684 sbox: &mut Sandbox,
4685 index: u32,
4686 sentinel: u64,
4687 ) {
4688 let baseline = sbox.snapshot().unwrap();
4689 let original: u64 = sbox
4690 .call("ReadMSR", index)
4691 .unwrap_or_else(|error| panic!("0x{index:X}: guest RDMSR failed: {error:?}"));
4692 let value = if original == sentinel { 0 } else { sentinel };
4693
4694 sbox.call::<()>("WriteMSR", (index, value))
4695 .unwrap_or_else(|error| panic!("0x{index:X}: guest WRMSR failed: {error:?}"));
4696 let written: u64 = sbox
4697 .call("ReadMSR", index)
4698 .unwrap_or_else(|error| panic!("0x{index:X}: guest read-back failed: {error:?}"));
4699 assert_eq!(written, value, "0x{index:X}: guest write did not stick");
4700
4701 sbox.restore(baseline).unwrap();
4702 let restored: u64 = sbox.call("ReadMSR", index).unwrap();
4703 assert_eq!(
4704 restored, original,
4705 "0x{index:X}: restore did not recover the baseline"
4706 );
4707 }
4708
4709 fn assert_guest_counter_is_writable_and_restored(sbox: &mut Sandbox, index: u32) {
4710 let baseline = sbox.snapshot().unwrap();
4711 let original: u64 = sbox.call("ReadMSR", index).unwrap();
4712 let jump = original.wrapping_add(1 << 60);
4713
4714 sbox.call::<()>("WriteMSR", (index, jump)).unwrap();
4715 let written: u64 = sbox.call("ReadMSR", index).unwrap();
4716 assert!(
4717 written >= jump / 2,
4718 "0x{index:X}: guest write did not stick"
4719 );
4720
4721 sbox.restore(baseline).unwrap();
4722 let restored: u64 = sbox.call("ReadMSR", index).unwrap();
4723 assert!(
4724 restored < jump / 2,
4725 "0x{index:X}: restore did not pull the counter below the guest-written jump"
4726 );
4727 }
4728
4729 #[cfg(target_arch = "x86_64")]
4731 fn assert_msr_write_does_not_survive_restore(sbox: &mut Sandbox, msr: u32, sentinel: u64) {
4732 let baseline = sbox.snapshot().unwrap();
4733 let original: u64 = match sbox.call("ReadMSR", msr) {
4734 Ok(v) => v,
4735 Err(_) => {
4736 assert!(
4737 sbox.status().is_poisoned(),
4738 "0x{msr:X}: a faulting RDMSR should poison the sandbox"
4739 );
4740 sbox.restore(baseline).unwrap();
4741 return;
4742 }
4743 };
4744 assert_ne!(
4745 original, sentinel,
4746 "0x{msr:X}: sentinel must differ from baseline"
4747 );
4748
4749 if sbox.call::<()>("WriteMSR", (msr, sentinel)).is_err() {
4750 assert!(
4751 sbox.status().is_poisoned(),
4752 "0x{msr:X}: a faulting WRMSR should poison the sandbox"
4753 );
4754 sbox.restore(baseline).unwrap();
4755 return;
4756 }
4757
4758 sbox.restore(baseline).unwrap();
4759 let after: u64 = sbox.call("ReadMSR", msr).unwrap();
4760 assert_eq!(
4761 after, original,
4762 "0x{msr:X}: MSR leaked across restore (expected 0x{original:X}, got 0x{after:X})"
4763 );
4764 }
4765
4766 #[test]
4768 #[ignore = "slow host-dependent hardware MSR audit"]
4769 #[cfg(target_arch = "x86_64")]
4770 fn test_no_msr_leaks_across_restore_full_window_sweep() {
4771 const FREE_RUNNING: &[u32] = &[
4773 0x10, 0xE7, 0xE8, ];
4777
4778 #[cfg(kvm)]
4779 if matches!(
4780 crate::hypervisor::virtual_machine::get_available_hypervisor(),
4781 Some(crate::hypervisor::virtual_machine::HypervisorType::Kvm)
4782 ) {
4783 return;
4784 }
4785
4786 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4787 .build()
4788 .unwrap();
4789
4790 let baseline = sbox.snapshot().unwrap();
4791
4792 let mut readable = 0usize;
4794 let mut exercised: Vec<u32> = Vec::new();
4795 let mut read_only: Vec<u32> = Vec::new();
4796 let mut masked_only: Vec<u32> = Vec::new();
4797 let mut free_running_leaked: Vec<u32> = Vec::new();
4799
4800 const PROBE_CHUNK_SIZE: u32 = 4096;
4801 let low = 0x0000_0000u32..=0x0000_1FFF;
4803 let hyperv_synthetic = 0x4000_0000u32..=0x4000_1FFF;
4805 let extended = 0xC000_0000u32..=0xC001_FFFF;
4807
4808 let mut readable_msrs = Vec::new();
4809 for window in [low, hyperv_synthetic, extended] {
4810 let window_end = *window.end();
4811 for chunk_start in window.step_by(PROBE_CHUNK_SIZE as usize) {
4812 let chunk_len = PROBE_CHUNK_SIZE.min(window_end - chunk_start + 1);
4813 let bitmap: Vec<u8> = sbox
4814 .call("ProbeReadableMSRs", (chunk_start, chunk_len))
4815 .unwrap();
4816 assert_eq!(bitmap.len(), chunk_len.div_ceil(8) as usize);
4817 readable_msrs.extend((0..chunk_len).filter_map(|offset| {
4818 let byte = bitmap[offset as usize / 8];
4819 (byte & (1 << (offset % 8)) != 0).then_some(chunk_start + offset)
4820 }));
4821 }
4822 }
4823
4824 for msr in readable_msrs {
4825 let original: u64 = sbox.call("ReadMSR", msr).unwrap();
4826 readable += 1;
4827
4828 if FREE_RUNNING.contains(&msr) {
4830 let jump = original.wrapping_add(1 << 60);
4831 if sbox.call::<()>("WriteMSR", (msr, jump)).is_err() {
4832 sbox.restore(baseline.clone()).unwrap();
4833 read_only.push(msr);
4834 continue;
4835 }
4836 let planted = match sbox.call::<u64>("ReadMSR", msr) {
4837 Ok(v) => v,
4838 Err(_) => {
4839 sbox.restore(baseline.clone()).unwrap();
4840 masked_only.push(msr);
4841 continue;
4842 }
4843 };
4844 if planted < jump / 2 {
4845 sbox.restore(baseline.clone()).unwrap();
4846 masked_only.push(msr);
4847 continue;
4848 }
4849 sbox.restore(baseline.clone()).unwrap();
4850 let after: u64 = sbox.call("ReadMSR", msr).unwrap();
4851 if after < jump / 2 {
4852 exercised.push(msr);
4853 } else {
4854 free_running_leaked.push(msr);
4855 }
4856 continue;
4857 }
4858
4859 let candidates = [
4861 original ^ 0x55,
4862 original ^ 0x1,
4863 original ^ (1 << 12),
4864 original ^ (1 << 20),
4865 original ^ (1 << 32),
4866 original.wrapping_add(1),
4867 0,
4868 ];
4869 let mut planted = false;
4870 let mut saw_write = false;
4871 for cand in candidates {
4872 if cand == original {
4873 continue;
4874 }
4875 if sbox.call::<()>("WriteMSR", (msr, cand)).is_err() {
4876 sbox.restore(baseline.clone()).unwrap();
4877 continue;
4878 }
4879 saw_write = true;
4880 match sbox.call::<u64>("ReadMSR", msr) {
4881 Ok(v) if v != original => {
4882 planted = true;
4883 break;
4884 }
4885 _ => {
4886 sbox.restore(baseline.clone()).unwrap();
4887 }
4888 }
4889 }
4890
4891 if planted {
4892 sbox.restore(baseline.clone()).unwrap();
4893 match sbox.call::<u64>("ReadMSR", msr) {
4894 Ok(after) => assert_eq!(
4895 after, original,
4896 "0x{msr:X}: a guest MSR write leaked across restore \
4897 (expected 0x{original:X}, got 0x{after:X})"
4898 ),
4899 Err(e) => panic!("0x{msr:X}: read-back after restore failed: {e:?}"),
4900 }
4901 exercised.push(msr);
4902 } else if saw_write {
4903 masked_only.push(msr);
4904 } else {
4905 read_only.push(msr);
4906 }
4907 }
4908
4909 let fmt = |v: &[u32]| {
4910 v.iter()
4911 .map(|m| format!("0x{m:X}"))
4912 .collect::<Vec<_>>()
4913 .join(", ")
4914 };
4915 eprintln!(
4916 "full-window MSR sweep: readable={readable} exercised={} masked_only={} read_only={}",
4917 exercised.len(),
4918 masked_only.len(),
4919 read_only.len()
4920 );
4921 eprintln!(" exercised: [{}]", fmt(&exercised));
4922 eprintln!(" masked_only: [{}]", fmt(&masked_only));
4923 eprintln!(" read_only: [{}]", fmt(&read_only));
4924 eprintln!(" free_running_leaked: [{}]", fmt(&free_running_leaked));
4925 assert!(
4926 free_running_leaked.is_empty(),
4927 "free-running MSRs not reset across restore on this backend: [{}]",
4928 fmt(&free_running_leaked)
4929 );
4930 assert!(
4931 !exercised.is_empty(),
4932 "sweep was vacuous: no guest MSR write ever retained a value that restore \
4933 then rolled back, so the rollback path was never exercised"
4934 );
4935 }
4936
4937 #[test]
4941 #[cfg(all(any(mshv3, target_os = "windows"), target_arch = "x86_64"))]
4942 fn active_ssp_does_not_leak_across_restore() {
4943 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4944 .build()
4945 .unwrap();
4946
4947 if !sbox.call::<bool>("CetShadowStackSupported", ()).unwrap() {
4948 return;
4949 }
4950
4951 let baseline = sbox.snapshot().unwrap();
4952 let original: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
4953
4954 let mutated: u64 = sbox.call("IncrementActiveSsp", ()).unwrap();
4955 assert_ne!(mutated, original, "guest did not change active SSP");
4956 let seen: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
4957 assert_eq!(seen, mutated, "guest did not observe its own SSP mutation");
4958
4959 sbox.restore(baseline).unwrap();
4960
4961 let after: u64 = sbox.call("ReadActiveSsp", ()).unwrap();
4962 assert_eq!(
4963 after, original,
4964 "active SSP leaked across restore (original=0x{original:X}, mutated=0x{mutated:X}, after=0x{after:X})"
4965 );
4966 }
4967
4968 #[test]
4973 #[cfg(all(kvm, target_arch = "x86_64"))]
4974 fn kvm_does_not_expose_cet_to_guest() {
4975 use crate::hypervisor::virtual_machine::{HypervisorType, get_available_hypervisor};
4976
4977 if !matches!(get_available_hypervisor(), Some(HypervisorType::Kvm)) {
4978 return;
4979 }
4980
4981 let mut sbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4982 .build()
4983 .unwrap();
4984 assert!(
4985 !sbox.call::<bool>("CetShadowStackSupported", ()).unwrap(),
4986 "KVM guest CPUID exposes CET shadow stacks"
4987 );
4988
4989 let err = SandboxBuilder::from_file(simple_guest_as_pathbuf())
4992 .guest_msrs(&[MSR_S_CET])
4993 .unwrap()
4994 .build()
4995 .expect_err("allowing IA32_S_CET must be rejected when CET is hidden");
4996 assert_msr_not_declarable(&err, MSR_S_CET);
4997 }
4998 }
4999
5000 mod from_snapshot {
5002 use std::sync::Arc;
5003
5004 use hyperlight_common::layout;
5005 use hyperlight_testing::simple_guest_as_pathbuf;
5006
5007 use crate::func::Registerable;
5008 use crate::sandbox::SandboxConfiguration;
5009 use crate::sandbox::snapshot::Snapshot;
5010 use crate::{GuestBinary, HostFunctions, HyperlightError, Sandbox, SandboxBuilder};
5011
5012 fn make_sandbox() -> Sandbox {
5013 let path = simple_guest_as_pathbuf();
5014 SandboxBuilder::from_file(path).build().unwrap()
5015 }
5016
5017 fn make_sandbox_with_add() -> Sandbox {
5019 let path = simple_guest_as_pathbuf();
5020 SandboxBuilder::from_file(path)
5021 .host_function("Add", |a: i32, b: i32| a + b)
5022 .build()
5023 .unwrap()
5024 }
5025
5026 fn host_funcs_with_matching_add() -> HostFunctions {
5027 let mut hf = HostFunctions::default();
5028 hf.register_host_function("Add", |a: i32, b: i32| Ok(a + b))
5029 .unwrap();
5030 hf
5031 }
5032
5033 #[test]
5034 fn round_trip_running_sandbox() {
5035 let mut sbox = make_sandbox();
5036 sbox.call::<i32>("AddToStatic", 11i32).unwrap();
5037 let snapshot = sbox.snapshot().unwrap();
5038 assert!(snapshot.virtq().is_some());
5039 let mut sbox2 = SandboxBuilder::from_snapshot(snapshot).build().unwrap();
5040 super::assert_virtq_attached(&sbox2);
5041 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 11);
5042 let echoed: String = sbox2.call("Echo", "hi".to_string()).unwrap();
5043 assert_eq!(echoed, "hi");
5044 }
5045
5046 #[test]
5047 fn rejects_noncanonical_transport_snapshot() {
5048 let mut sbox = make_sandbox();
5049 sbox.call::<i32>("AddToStatic", 1i32).unwrap();
5050
5051 sbox.checkpoint_transport_for_snapshot().unwrap();
5053
5054 let layout = &sbox.mem_mgr.layout;
5055 let scratch_base = layout::scratch_base_gpa(layout.get_scratch_size());
5056
5057 let ring_offset =
5058 (layout.get_transport_arena().g2h_ring_addr() - scratch_base) as usize;
5059
5060 sbox.mem_mgr
5061 .scratch_mem
5062 .write::<u64>(ring_offset, 1)
5063 .unwrap();
5064
5065 let Err(err) = sbox.snapshot() else {
5066 panic!("noncanonical transport must fail snapshot creation");
5067 };
5068
5069 assert!(err.to_string().contains("invalid canonical G2H image"));
5070 }
5071
5072 #[test]
5073 fn round_trip_pre_init_snapshot() {
5074 let path = simple_guest_as_pathbuf();
5075 let snap =
5076 Snapshot::from_env(GuestBinary::FilePath(path), SandboxConfiguration::default())
5077 .unwrap();
5078 assert!(snap.virtq().is_none());
5079 let mut sbox = SandboxBuilder::from_snapshot(Arc::new(snap))
5080 .build()
5081 .unwrap();
5082 assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 0);
5083 }
5084
5085 #[test]
5096 #[ignore]
5097 fn max_guest_log_level_is_honored_from_snapshot() {
5098 use hyperlight_common::log_level::GuestLogFilter;
5099 use hyperlight_testing::logger::{LOGGER, Logger};
5100 use tracing_core::LevelFilter;
5101
5102 Logger::initialize_test_logger();
5103 LOGGER.set_max_level(log::LevelFilter::Trace);
5104
5105 let count_guest_logs = |max_level: LevelFilter| -> usize {
5109 let snap = Snapshot::from_env(
5110 GuestBinary::FilePath(simple_guest_as_pathbuf()),
5111 SandboxConfiguration::default(),
5112 )
5113 .unwrap();
5114 let mut config = SandboxConfiguration::default();
5115 config.set_max_guest_log_level(max_level);
5116 let mut sbox =
5117 Sandbox::from_snapshot(Arc::new(snap), HostFunctions::default(), Some(config))
5118 .unwrap();
5119
5120 LOGGER.clear_log_calls();
5122
5123 for level in [
5124 LevelFilter::TRACE,
5125 LevelFilter::DEBUG,
5126 LevelFilter::INFO,
5127 LevelFilter::WARN,
5128 LevelFilter::ERROR,
5129 ] {
5130 let encoded: u64 = GuestLogFilter::from(level).into();
5131 sbox.call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
5132 .unwrap();
5133 }
5134
5135 let count = (0..LOGGER.num_log_calls())
5136 .filter_map(|i| LOGGER.get_log_call(i))
5137 .filter(|c| c.target == "hyperlight_guest")
5138 .count();
5139 LOGGER.clear_log_calls();
5140 count
5141 };
5142
5143 let trace_count = count_guest_logs(LevelFilter::TRACE);
5144 let error_count = count_guest_logs(LevelFilter::ERROR);
5145
5146 assert!(
5147 error_count >= 1,
5148 "an ERROR-level guest log must reach the host, got {error_count}"
5149 );
5150 assert!(
5151 trace_count > error_count,
5152 "TRACE must let more guest logs through than ERROR (trace={trace_count}, \
5153 error={error_count}); equal counts mean max_guest_log_level was ignored"
5154 );
5155 }
5156
5157 #[test]
5162 #[ignore]
5163 fn max_guest_log_level_overrides_initialized_snapshot() {
5164 use hyperlight_common::log_level::GuestLogFilter;
5165 use hyperlight_testing::logger::{LOGGER, Logger};
5166 use tracing_core::LevelFilter;
5167
5168 Logger::initialize_test_logger();
5169 LOGGER.set_max_level(log::LevelFilter::Trace);
5170
5171 let initialized_snapshot = |captured_level: LevelFilter| {
5172 SandboxBuilder::from_file(simple_guest_as_pathbuf())
5173 .guest_log_level(captured_level)
5174 .build()
5175 .unwrap()
5176 .snapshot()
5177 .unwrap()
5178 };
5179
5180 let count_guest_logs =
5181 |snapshot: Arc<Snapshot>, override_level: Option<LevelFilter>| -> usize {
5182 let config = override_level.map(|level| {
5183 let mut config = SandboxConfiguration::default();
5184 config.set_max_guest_log_level(level);
5185 config
5186 });
5187 let mut sandbox =
5188 Sandbox::from_snapshot(snapshot, HostFunctions::default(), config).unwrap();
5189
5190 LOGGER.clear_log_calls();
5191 for level in [
5192 LevelFilter::TRACE,
5193 LevelFilter::DEBUG,
5194 LevelFilter::INFO,
5195 LevelFilter::WARN,
5196 LevelFilter::ERROR,
5197 ] {
5198 let encoded: u64 = GuestLogFilter::from(level).into();
5199 sandbox
5200 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
5201 .unwrap();
5202 }
5203
5204 let count = (0..LOGGER.num_log_calls())
5205 .filter_map(|i| LOGGER.get_log_call(i))
5206 .filter(|call| call.target == "hyperlight_guest")
5207 .count();
5208 LOGGER.clear_log_calls();
5209 count
5210 };
5211
5212 let trace_snapshot = initialized_snapshot(LevelFilter::TRACE);
5213 let error_snapshot = initialized_snapshot(LevelFilter::ERROR);
5214
5215 let captured_trace = count_guest_logs(trace_snapshot.clone(), None);
5216 let overridden_trace = count_guest_logs(trace_snapshot, Some(LevelFilter::ERROR));
5217 let captured_error = count_guest_logs(error_snapshot.clone(), None);
5218 let overridden_error = count_guest_logs(error_snapshot, Some(LevelFilter::TRACE));
5219
5220 assert!(
5221 captured_trace > overridden_trace,
5222 "ERROR override should reduce TRACE snapshot logs (trace={}, error={})",
5223 captured_trace,
5224 overridden_trace
5225 );
5226 assert!(
5227 overridden_error > captured_error,
5228 "TRACE override should increase ERROR snapshot logs (trace={}, error={})",
5229 overridden_error,
5230 captured_error
5231 );
5232 }
5233
5234 #[test]
5239 #[ignore]
5240 fn max_guest_log_level_setter_survives_restore() {
5241 use hyperlight_common::log_level::GuestLogFilter;
5242 use hyperlight_testing::logger::{LOGGER, Logger};
5243 use tracing_core::LevelFilter;
5244
5245 Logger::initialize_test_logger();
5246 LOGGER.set_max_level(log::LevelFilter::Trace);
5247
5248 let mut source = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5249 .guest_log_level(LevelFilter::TRACE)
5250 .build()
5251 .unwrap();
5252 let snapshot = source.snapshot().unwrap();
5253 let mut sandbox = SandboxBuilder::from_snapshot(snapshot.clone())
5254 .build()
5255 .unwrap();
5256 sandbox.log_level(LevelFilter::ERROR).unwrap();
5257
5258 let count_guest_logs = |sandbox: &mut Sandbox| {
5259 LOGGER.clear_log_calls();
5260 for level in [
5261 LevelFilter::TRACE,
5262 LevelFilter::DEBUG,
5263 LevelFilter::INFO,
5264 LevelFilter::WARN,
5265 LevelFilter::ERROR,
5266 ] {
5267 let encoded: u64 = GuestLogFilter::from(level).into();
5268 sandbox
5269 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
5270 .unwrap();
5271 }
5272 let count = (0..LOGGER.num_log_calls())
5273 .filter_map(|i| LOGGER.get_log_call(i))
5274 .filter(|call| call.target == "hyperlight_guest")
5275 .count();
5276 LOGGER.clear_log_calls();
5277 count
5278 };
5279
5280 let before_restore = count_guest_logs(&mut sandbox);
5281 sandbox.restore(snapshot).unwrap();
5282 let after_restore = count_guest_logs(&mut sandbox);
5283
5284 assert_eq!(before_restore, 1);
5285 assert_eq!(before_restore, after_restore);
5286 }
5287
5288 #[test]
5293 #[ignore]
5294 fn max_guest_log_level_can_be_disabled_and_reenabled() {
5295 use hyperlight_common::log_level::GuestLogFilter;
5296 use hyperlight_testing::logger::{LOGGER, Logger};
5297 use tracing_core::LevelFilter;
5298
5299 Logger::initialize_test_logger();
5300 LOGGER.set_max_level(log::LevelFilter::Trace);
5301
5302 let mut sandbox = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5303 .guest_log_level(LevelFilter::TRACE)
5304 .build()
5305 .unwrap();
5306 let encoded: u64 = GuestLogFilter::Trace.into();
5307 let count_guest_logs = |sandbox: &mut Sandbox| {
5308 LOGGER.clear_log_calls();
5309 sandbox
5310 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
5311 .unwrap();
5312 (0..LOGGER.num_log_calls())
5313 .filter_map(|i| LOGGER.get_log_call(i))
5314 .filter(|call| call.target == "hyperlight_guest")
5315 .count()
5316 };
5317
5318 assert!(count_guest_logs(&mut sandbox) > 0);
5319 sandbox.log_level(LevelFilter::OFF).unwrap();
5320 assert_eq!(count_guest_logs(&mut sandbox), 0);
5321 sandbox.log_level(LevelFilter::TRACE).unwrap();
5322 assert!(count_guest_logs(&mut sandbox) > 0);
5323 }
5324
5325 #[test]
5331 #[ignore]
5332 fn max_guest_log_level_can_be_enabled_after_off_init() {
5333 use hyperlight_common::log_level::GuestLogFilter;
5334 use hyperlight_testing::logger::{LOGGER, Logger};
5335 use tracing_core::LevelFilter;
5336
5337 Logger::initialize_test_logger();
5338 LOGGER.set_max_level(log::LevelFilter::Trace);
5339
5340 let encoded: u64 = GuestLogFilter::Trace.into();
5341 let count_guest_logs = |sandbox: &mut Sandbox| {
5342 LOGGER.clear_log_calls();
5343 sandbox
5344 .call::<()>("LogMessage", ("hello".to_string(), encoded as i32))
5345 .unwrap();
5346 (0..LOGGER.num_log_calls())
5347 .filter_map(|i| LOGGER.get_log_call(i))
5348 .filter(|call| call.target == "hyperlight_guest")
5349 .count()
5350 };
5351
5352 let mut from_trace = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5353 .guest_log_level(LevelFilter::TRACE)
5354 .build()
5355 .unwrap();
5356 let _ = count_guest_logs(&mut from_trace);
5357 let expected = count_guest_logs(&mut from_trace);
5358
5359 let mut from_off = SandboxBuilder::from_file(simple_guest_as_pathbuf())
5360 .guest_log_level(LevelFilter::OFF)
5361 .build()
5362 .unwrap();
5363 assert_eq!(count_guest_logs(&mut from_off), 0);
5365
5366 from_off.log_level(LevelFilter::TRACE).unwrap();
5367 assert_eq!(count_guest_logs(&mut from_off), expected);
5368 }
5369
5370 #[test]
5374 fn arc_clone_isolation_and_restore_compat() {
5375 let mut sbox = make_sandbox();
5376 sbox.call::<i32>("AddToStatic", 3i32).unwrap();
5377 let snapshot = sbox.snapshot().unwrap();
5378
5379 let mut a = SandboxBuilder::from_snapshot(snapshot.clone())
5380 .build()
5381 .unwrap();
5382 let mut b = SandboxBuilder::from_snapshot(snapshot.clone())
5383 .build()
5384 .unwrap();
5385 super::assert_virtq_attached(&a);
5386 super::assert_virtq_attached(&b);
5387 assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 3);
5388 assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
5389
5390 a.call::<i32>("AddToStatic", 7i32).unwrap();
5391 assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 10);
5392 assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
5393
5394 a.restore(snapshot.clone()).unwrap();
5395 b.restore(snapshot).unwrap();
5396 super::assert_virtq_attached(&a);
5397 super::assert_virtq_attached(&b);
5398 assert_eq!(a.call::<i32>("GetStatic", ()).unwrap(), 3);
5399 assert_eq!(b.call::<i32>("GetStatic", ()).unwrap(), 3);
5400 }
5401
5402 #[test]
5403 fn accepts_matching_host_functions() {
5404 let mut sbox = make_sandbox_with_add();
5405 sbox.call::<i32>("AddToStatic", 5i32).unwrap();
5406 let snap = sbox.snapshot().unwrap();
5407 let mut sbox2 = SandboxBuilder::from_snapshot(snap)
5408 .host_functions(host_funcs_with_matching_add())
5409 .build()
5410 .unwrap();
5411 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 5);
5412 }
5413
5414 #[test]
5415 fn rejects_missing_host_function() {
5416 let mut sbox = make_sandbox_with_add();
5417 let snap = sbox.snapshot().unwrap();
5418 let err = SandboxBuilder::from_snapshot(snap)
5419 .build()
5420 .expect_err("missing `Add` must be rejected");
5421 assert!(
5422 matches!(
5423 &err,
5424 HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
5425 if missing.iter().any(|n| n == "Add") && signature_mismatches.is_empty()
5426 ),
5427 "got: {:?}",
5428 err
5429 );
5430 }
5431
5432 #[test]
5438 fn restore_rejects_missing_host_function() {
5439 let mut sbox_with_add = make_sandbox_with_add();
5440 let snap = sbox_with_add.snapshot().unwrap();
5441 let mut sbox_without_add = make_sandbox();
5442 let err = sbox_without_add
5443 .restore(snap)
5444 .expect_err("missing `Add` must be rejected on restore");
5445 assert!(
5446 matches!(
5447 &err,
5448 HyperlightError::SnapshotHostFunctionMismatch { missing, .. }
5449 if missing.iter().any(|n| n == "Add")
5450 ),
5451 "got: {:?}",
5452 err
5453 );
5454 }
5455
5456 #[test]
5459 fn restore_rejects_signature_mismatch() {
5460 let mut sbox_with_add = make_sandbox_with_add();
5461 let snap = sbox_with_add.snapshot().unwrap();
5462 let path = simple_guest_as_pathbuf();
5463 let mut sbox_wrong_add = SandboxBuilder::from_file(path)
5464 .host_function("Add", |a: String, b: String| format!("{a}{b}"))
5465 .build()
5466 .unwrap();
5467 let err = sbox_wrong_add
5468 .restore(snap)
5469 .expect_err("signature mismatch on `Add` must be rejected on restore");
5470 assert!(
5471 matches!(
5472 &err,
5473 HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
5474 if missing.is_empty() && signature_mismatches.iter().any(|s| s.contains("Add"))
5475 ),
5476 "got: {:?}",
5477 err
5478 );
5479 }
5480
5481 #[test]
5484 fn restore_across_sandboxes_with_superset_host_funcs() {
5485 let mut source = make_sandbox_with_add();
5486 source.call::<i32>("AddToStatic", 17i32).unwrap();
5487 let snap = source.snapshot().unwrap();
5488
5489 let path = simple_guest_as_pathbuf();
5490 let mut target = SandboxBuilder::from_file(path)
5491 .host_function("Add", |a: i32, b: i32| a + b)
5492 .host_function("Mul", |a: i32, b: i32| a * b)
5493 .build()
5494 .unwrap();
5495
5496 target.restore(snap).unwrap();
5497 assert_eq!(target.call::<i32>("GetStatic", ()).unwrap(), 17);
5498 }
5499
5500 #[test]
5501 fn rejects_signature_mismatch() {
5502 let mut sbox = make_sandbox_with_add();
5503 let snap = sbox.snapshot().unwrap();
5504 let mut hf = HostFunctions::default();
5505 hf.register_host_function("Add", |a: String, b: String| Ok(format!("{a}{b}")))
5506 .unwrap();
5507 let err = SandboxBuilder::from_snapshot(snap)
5508 .host_functions(hf)
5509 .build()
5510 .expect_err("signature mismatch on `Add` must be rejected");
5511 assert!(
5512 matches!(
5513 &err,
5514 HyperlightError::SnapshotHostFunctionMismatch { missing, signature_mismatches }
5515 if missing.is_empty() && signature_mismatches.iter().any(|s| s.contains("Add"))
5516 ),
5517 "got: {:?}",
5518 err
5519 );
5520 }
5521
5522 #[test]
5525 fn accepts_extra_host_functions() {
5526 let mut sbox = make_sandbox_with_add();
5527 sbox.call::<i32>("AddToStatic", 9i32).unwrap();
5528 let snap = sbox.snapshot().unwrap();
5529 let mut hf = host_funcs_with_matching_add();
5530 hf.register_host_function("Mul", |a: i32, b: i32| Ok(a * b))
5531 .unwrap();
5532 let mut sbox2 = SandboxBuilder::from_snapshot(snap)
5533 .host_functions(hf)
5534 .build()
5535 .unwrap();
5536 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 9);
5537 }
5538
5539 #[test]
5542 fn re_snapshot_after_from_snapshot() {
5543 let mut sbox = make_sandbox();
5544 sbox.call::<i32>("AddToStatic", 4i32).unwrap();
5545 let snap1 = sbox.snapshot().unwrap();
5546
5547 let mut sbox2 = SandboxBuilder::from_snapshot(snap1).build().unwrap();
5548 sbox2.call::<i32>("AddToStatic", 6i32).unwrap();
5549 let snap2 = sbox2.snapshot().unwrap();
5550
5551 sbox2.call::<i32>("AddToStatic", 100i32).unwrap();
5552 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 110);
5553
5554 sbox2.restore(snap2.clone()).unwrap();
5555 assert_eq!(sbox2.call::<i32>("GetStatic", ()).unwrap(), 10);
5556
5557 let mut sbox3 = SandboxBuilder::from_snapshot(snap2).build().unwrap();
5558 assert_eq!(sbox3.call::<i32>("GetStatic", ()).unwrap(), 10);
5559 }
5560
5561 #[test]
5564 fn supplied_host_function_is_callable() {
5565 let path = simple_guest_as_pathbuf();
5566 let mut sbox = SandboxBuilder::from_file(path)
5567 .host_function("Echo42", || 1i64)
5568 .build()
5569 .unwrap();
5570 let snap = sbox.snapshot().unwrap();
5571
5572 let mut hf = HostFunctions::default();
5573 hf.register_host_function("Echo42", || Ok(42i64)).unwrap();
5574 let mut sbox2 = SandboxBuilder::from_snapshot(snap)
5575 .host_functions(hf)
5576 .build()
5577 .unwrap();
5578
5579 let got: i64 = sbox2
5580 .call(
5581 "CallGivenParamlessHostFuncThatReturnsI64",
5582 "Echo42".to_string(),
5583 )
5584 .unwrap();
5585 assert_eq!(got, 42);
5586 }
5587
5588 #[test]
5591 fn pre_init_snapshot_accepts_arbitrary_host_functions() {
5592 let path = simple_guest_as_pathbuf();
5593 let snap =
5594 Snapshot::from_env(GuestBinary::FilePath(path), SandboxConfiguration::default())
5595 .unwrap();
5596 let mut hf = HostFunctions::default();
5597 hf.register_host_function("Unrelated", |a: i32| Ok(a + 1))
5598 .unwrap();
5599 let mut sbox = SandboxBuilder::from_snapshot(Arc::new(snap))
5600 .host_functions(hf)
5601 .build()
5602 .unwrap();
5603 assert_eq!(sbox.call::<i32>("GetStatic", ()).unwrap(), 0);
5604 }
5605
5606 #[test]
5610 fn snapshot_generation_propagates() {
5611 let mut sbox = make_sandbox();
5612 sbox.call::<i32>("AddToStatic", 1i32).unwrap();
5613 let snap1 = sbox.snapshot().unwrap();
5614 let gen1 = snap1.snapshot_generation();
5615 sbox.call::<i32>("AddToStatic", 1i32).unwrap();
5616 let snap2 = sbox.snapshot().unwrap();
5617 let gen2 = snap2.snapshot_generation();
5618 assert_eq!(gen2, gen1 + 1);
5619
5620 let mut sbox2 = SandboxBuilder::from_snapshot(snap2).build().unwrap();
5621 sbox2.call::<i32>("AddToStatic", 1i32).unwrap();
5622 let snap3 = sbox2.snapshot().unwrap();
5623 assert_eq!(snap3.snapshot_generation(), gen2 + 1);
5624 }
5625
5626 #[test]
5631 fn late_register_invalidates_snapshot_cache() {
5632 let mut sbox = make_sandbox();
5633 let _ = sbox.snapshot().unwrap();
5635
5636 sbox.register_host_function("Echo42", || Ok(42i64)).unwrap();
5637
5638 let snap = sbox.snapshot().unwrap();
5642 let err = SandboxBuilder::from_snapshot(snap)
5643 .build()
5644 .expect_err("late-registered `Echo42` must be required by the new snapshot");
5645 let msg = format!("{}", err);
5646 assert!(msg.contains("Echo42"), "got: {}", msg);
5647 }
5648 }
5649}