1mod file;
5mod file_tests;
6pub(crate) mod memory;
7mod tripwires;
8
9use std::cell::{Cell, RefCell};
10use std::collections::BTreeMap;
11use std::ops::Range;
12use std::sync::Arc;
13
14pub(crate) use file::host_cpu_vendor_golden_tag;
15pub use file::reference::{OciDigest, OciReference, OciTag};
16use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
17use hyperlight_common::layout::{
18 SCRATCH_TOP_GVA, io_page, scratch_base_gpa, scratch_base_gva, scratch_reserved_top_gpa,
19 scratch_reserved_top_gva, scratch_transport_end_gva,
20};
21use hyperlight_common::vmem;
22use hyperlight_common::vmem::{
23 BasicMapping, CowMapping, Mapping, MappingKind, PAGE_SIZE, SpaceAwareMapping, SpaceId, TableOps,
24};
25use tracing::{Span, instrument};
26
27pub(crate) use self::memory::{SnapshotBlob, SnapshotMemory, SnapshotMemoryBacking};
28use crate::Result;
29use crate::hypervisor::regs::CommonSpecialRegisters;
30#[cfg(target_arch = "x86_64")]
31use crate::hypervisor::regs::MsrEntry;
32use crate::mem::exe::{ExeInfo, LoadInfo};
33use crate::mem::layout::SandboxMemoryLayout;
34use crate::mem::memory_region::MemoryRegionFlags;
35use crate::mem::mgr::{BackingSource, GuestBacking, GuestPageTableBuffer, GuestPhysicalMemoryView};
36use crate::mem::shared_mem::ExclusiveSharedMemory;
37use crate::mem::virtq::VirtqSnapshot;
38use crate::sandbox::SandboxConfiguration;
39use crate::sandbox::uninitialized::{GuestBinary, GuestEnvironment};
40
41const PTE_SIZE: usize = size_of::<vmem::PageTableEntry>();
42
43#[derive(Copy, Clone, PartialEq, Eq)]
53pub enum NextAction {
54 Initialise(u64),
57 Call(u64),
60 #[cfg(test)]
63 None,
64}
65
66#[derive(Clone, Debug, Default)]
71pub struct SnapshotOptions {
72 pub(crate) scratch_size: Option<usize>,
73}
74
75impl SnapshotOptions {
76 #[must_use]
96 pub fn scratch_size(mut self, scratch_size: usize) -> Self {
97 self.scratch_size = Some(scratch_size);
98 self
99 }
100}
101
102pub struct Snapshot {
104 state: Arc<SnapshotState>,
105 metadata: BTreeMap<String, serde_json::Value>,
107}
108
109struct SnapshotState {
111 layout: crate::mem::layout::SandboxMemoryLayout,
115 memory: Arc<SnapshotMemory>,
117 load_info: LoadInfo,
125 stack_top_gva: u64,
127
128 sregs: Option<CommonSpecialRegisters>,
134
135 #[cfg(target_arch = "x86_64")]
137 msrs: Option<Vec<MsrEntry>>,
138
139 next_action: NextAction,
141
142 original_entrypoint: u64,
150
151 snapshot_generation: u64,
157
158 host_functions: HostFunctionDetails,
164
165 virtq: Option<VirtqSnapshot>,
170}
171
172impl core::convert::AsRef<Snapshot> for Snapshot {
173 fn as_ref(&self) -> &Self {
174 self
175 }
176}
177impl hyperlight_common::vmem::TableReadOps for Snapshot {
178 type TableAddr = u64;
179 fn entry_addr(addr: u64, offset: u64) -> u64 {
180 addr + offset
181 }
182 unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
183 let mut pte_bytes = [0u8; PTE_SIZE];
184 if self
185 .state
186 .memory
187 .read_page_tables(self.state.layout.get_pt_base_gpa(), addr, &mut pte_bytes)
188 .is_err()
189 {
190 return 0;
195 }
196 vmem::PageTableEntry::from_le_bytes(pte_bytes)
197 }
198 #[allow(clippy::unnecessary_cast)]
199 fn to_phys(addr: u64) -> vmem::PhysAddr {
200 addr as vmem::PhysAddr
201 }
202 #[allow(clippy::unnecessary_cast)]
203 fn from_phys(addr: vmem::PhysAddr) -> u64 {
204 addr as u64
205 }
206 fn root_table(&self) -> u64 {
207 self.root_pt_gpa()
208 }
209}
210
211pub(crate) struct PageTableReader<'a> {
212 memory: &'a GuestPhysicalMemoryView<'a>,
213 root: u64,
214 failure: Cell<Option<&'static str>>,
215 cache: RefCell<(u64, [u8; PAGE_SIZE])>,
218}
219impl<'a> PageTableReader<'a> {
220 pub(crate) fn new(memory: &'a GuestPhysicalMemoryView<'a>, root: u64) -> Self {
221 Self {
222 memory,
223 root,
224 failure: Cell::new(None),
225 cache: RefCell::new((u64::MAX, [0; PAGE_SIZE])),
227 }
228 }
229
230 pub(crate) fn finish(&self) -> Result<()> {
232 match self.failure.get() {
233 Some(failure) => Err(crate::new_error!("{}", failure)),
234 None => Ok(()),
235 }
236 }
237
238 fn read_cached(&self, addr: u64) -> Option<vmem::PageTableEntry> {
239 let page = addr & !(PAGE_SIZE as u64 - 1);
240 let offset = usize::try_from(addr - page).ok()?;
241 let mut cache = self.cache.borrow_mut();
242 if cache.0 != page {
243 cache.0 = u64::MAX;
244 self.memory.read(page, &mut cache.1).ok()?;
245 cache.0 = page;
246 }
247 let entry = cache.1.get(offset..offset + PTE_SIZE)?;
248 Some(vmem::PageTableEntry::from_le_bytes(entry.try_into().ok()?))
249 }
250}
251impl<'a> hyperlight_common::vmem::TableReadOps for PageTableReader<'a> {
252 type TableAddr = u64;
253 fn entry_addr(addr: u64, offset: u64) -> u64 {
254 addr + offset
255 }
256 unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
257 if let Some(entry) = self.read_cached(addr) {
258 return entry;
259 }
260 let mut pte_bytes = [0u8; PTE_SIZE];
261 if self.memory.read(addr, &mut pte_bytes).is_err() {
262 self.failure
268 .set(Some("snapshot page-table walk accessed unbacked memory"));
269 return 0;
270 }
271 vmem::PageTableEntry::from_le_bytes(pte_bytes)
272 }
273 #[allow(clippy::unnecessary_cast)]
274 fn to_phys(addr: u64) -> vmem::PhysAddr {
275 addr as vmem::PhysAddr
276 }
277 #[allow(clippy::unnecessary_cast)]
278 fn from_phys(addr: vmem::PhysAddr) -> u64 {
279 addr as u64
280 }
281 fn root_table(&self) -> u64 {
282 self.root
283 }
284}
285impl<'a> core::convert::AsRef<PageTableReader<'a>> for PageTableReader<'a> {
286 fn as_ref(&self) -> &Self {
287 self
288 }
289}
290
291fn skip_virt(virt_base: u64, scratch_gva: u64) -> bool {
296 if virt_base >= scratch_gva {
297 return true;
298 }
299 if virt_base >= hyperlight_common::layout::SNAPSHOT_PT_GVA_MIN as u64
300 && virt_base <= hyperlight_common::layout::SNAPSHOT_PT_GVA_MAX as u64
301 {
302 return true;
303 }
304 false
305}
306
307fn for_each_mapping_page(
308 mapping: &Mapping,
309 mut visitor: impl FnMut(u64, u64, MappingKind) -> Result<()>,
310) -> Result<()> {
311 if !validate_mapping(mapping)? {
312 return Ok(());
313 }
314 let mut offset = 0u64;
315 while offset < mapping.len {
316 let phys = mapping
317 .phys_base
318 .checked_add(offset)
319 .ok_or_else(|| crate::new_error!("guest physical mapping overflows"))?;
320 let virt = mapping
321 .virt_base
322 .checked_add(offset)
323 .ok_or_else(|| crate::new_error!("guest virtual mapping overflows"))?;
324 visitor(phys, virt, mapping.kind)?;
325 offset = offset
326 .checked_add(PAGE_SIZE as u64)
327 .ok_or_else(|| crate::new_error!("guest mapping offset overflows"))?;
328 }
329 Ok(())
330}
331
332fn validate_mapping(mapping: &Mapping) -> Result<bool> {
333 if mapping.kind == MappingKind::Unmapped {
334 return Ok(false);
335 }
336 if mapping.len == 0
337 || !mapping.phys_base.is_multiple_of(PAGE_SIZE as u64)
338 || !mapping.virt_base.is_multiple_of(PAGE_SIZE as u64)
339 || !mapping.len.is_multiple_of(PAGE_SIZE as u64)
340 {
341 return Err(crate::new_error!("guest mapping is not page aligned"));
342 }
343 Ok(true)
344}
345
346fn mapping_has_skipped_pages(mapping: &Mapping, scratch_gva: u64) -> Result<bool> {
347 let last_page = mapping
348 .virt_base
349 .checked_add(mapping.len - PAGE_SIZE as u64)
350 .ok_or_else(|| crate::new_error!("guest virtual mapping overflows"))?;
351 let snapshot_pt_start = hyperlight_common::layout::SNAPSHOT_PT_GVA_MIN as u64;
352 let snapshot_pt_end = hyperlight_common::layout::SNAPSHOT_PT_GVA_MAX as u64;
353 Ok(last_page >= scratch_gva
354 || (mapping.virt_base <= snapshot_pt_end && snapshot_pt_start <= last_page))
355}
356
357#[derive(Clone, Copy)]
358struct NewPage {
359 source_gpa: u64,
360 backing: GuestBacking,
361}
362
363fn record_backed_pages(
365 backing: GuestBacking,
366 source_gpa: u64,
367 len: usize,
368 reused_layers: Option<&mut [bool]>,
369 new_pages: &mut Vec<NewPage>,
370) -> Result<()> {
371 if let BackingSource::Snapshot(layer_index) = backing.source
372 && let Some(reused_layers) = reused_layers
373 {
374 *reused_layers
375 .get_mut(layer_index)
376 .ok_or_else(|| crate::new_error!("snapshot layer index is out of bounds"))? = true;
377 return Ok(());
378 }
379
380 for offset in (0..len).step_by(PAGE_SIZE) {
381 new_pages.push(NewPage {
382 source_gpa: source_gpa
383 .checked_add(u64::try_from(offset)?)
384 .ok_or_else(|| crate::new_error!("snapshot source GPA overflows"))?,
385 backing: GuestBacking {
386 offset: backing
387 .offset
388 .checked_add(offset)
389 .ok_or_else(|| crate::new_error!("snapshot source backing offset overflows"))?,
390 ..backing
391 },
392 });
393 }
394 Ok(())
395}
396
397struct NewPageRun {
398 source: Range<u64>,
399 destination_start: u64,
400}
401
402struct NewPageCopy {
403 backing: GuestBacking,
404 destination: Range<usize>,
405}
406
407fn new_page_copies(pages: &[NewPage]) -> Result<Vec<NewPageCopy>> {
408 let mut copies = Vec::<NewPageCopy>::new();
409 for (index, page) in pages.iter().enumerate() {
410 let start = index
411 .checked_mul(PAGE_SIZE)
412 .ok_or_else(|| crate::new_error!("snapshot page offset overflows"))?;
413 let end = start
414 .checked_add(PAGE_SIZE)
415 .ok_or_else(|| crate::new_error!("snapshot page range overflows"))?;
416 if let Some(copy) = copies.last_mut()
417 && copy.backing.source == page.backing.source
418 && copy.backing.offset.checked_add(copy.destination.len()) == Some(page.backing.offset)
419 {
420 copy.destination.end = end;
421 } else {
422 copies.push(NewPageCopy {
423 backing: page.backing,
424 destination: start..end,
425 });
426 }
427 }
428 Ok(copies)
429}
430
431fn new_page_runs(pages: &[NewPage], destination_start: u64) -> Result<Vec<NewPageRun>> {
432 let mut runs = Vec::<NewPageRun>::new();
433 for (index, page) in pages.iter().enumerate() {
434 let source_gpa = page.source_gpa;
435 let destination = destination_start
436 .checked_add(u64::try_from(index.checked_mul(PAGE_SIZE).ok_or_else(
437 || crate::new_error!("snapshot page offset overflows"),
438 )?)?)
439 .ok_or_else(|| crate::new_error!("snapshot page GPA overflows"))?;
440 if let Some(run) = runs.last_mut()
441 && run.source.end == source_gpa
442 {
443 run.source.end = run
444 .source
445 .end
446 .checked_add(PAGE_SIZE as u64)
447 .ok_or_else(|| crate::new_error!("snapshot source page run overflows"))?;
448 } else {
449 let source_end = source_gpa
450 .checked_add(PAGE_SIZE as u64)
451 .ok_or_else(|| crate::new_error!("snapshot source page overflows"))?;
452 runs.push(NewPageRun {
453 source: source_gpa..source_end,
454 destination_start: destination,
455 });
456 }
457 }
458 Ok(runs)
459}
460
461fn page_destination(runs: &[NewPageRun], source_gpa: u64) -> Option<u64> {
462 let index = runs.partition_point(|run| run.source.end <= source_gpa);
463 let run = runs.get(index)?;
464 let offset = source_gpa.checked_sub(run.source.start)?;
465 (source_gpa < run.source.end).then(|| run.destination_start.checked_add(offset))?
466}
467
468fn packed_data_len(page_count: usize, host_page_size: usize) -> Result<usize> {
469 let page_bytes = page_count
470 .checked_mul(PAGE_SIZE)
471 .ok_or_else(|| crate::new_error!("snapshot data size overflows"))?;
472 page_bytes
473 .checked_next_multiple_of(host_page_size)
474 .ok_or_else(|| crate::new_error!("snapshot data padding overflows"))
475}
476
477fn first_fit_blob_gpa(
478 data_len: usize,
479 layers: &[Arc<SnapshotBlob>],
480 scratch_base: u64,
481) -> Option<u64> {
482 if data_len == 0 {
483 return None;
484 }
485 let data_len = u64::try_from(data_len).ok()?;
486 let mut candidate = SandboxMemoryLayout::BASE_ADDRESS as u64;
487 for range in layers.iter().map(|layer| layer.gpa_range()) {
488 let end = candidate.checked_add(data_len)?;
489 if end <= range.start {
490 return Some(candidate);
491 }
492 candidate = candidate.max(range.end);
493 }
494 (candidate.checked_add(data_len)? <= scratch_base).then_some(candidate)
495}
496
497fn snapshot_mapping_kind(kind: MappingKind) -> Option<MappingKind> {
498 match kind {
499 MappingKind::Cow(mapping) => Some(MappingKind::Cow(mapping)),
500 MappingKind::Basic(mapping) if mapping.writable => Some(MappingKind::Cow(CowMapping {
501 readable: mapping.readable,
502 executable: mapping.executable,
503 })),
504 MappingKind::Basic(mapping) => Some(MappingKind::Basic(BasicMapping {
505 readable: mapping.readable,
506 writable: false,
507 executable: mapping.executable,
508 })),
509 MappingKind::ZeroInit(mapping) => Some(MappingKind::ZeroInit(mapping)),
510 MappingKind::Unmapped => None,
511 }
512}
513
514fn map_specials(pt_buf: &GuestPageTableBuffer, scratch_size: usize) {
515 if let Some((phys_base, virt_base)) = io_page() {
516 let mapping = Mapping {
518 phys_base,
519 virt_base,
520 len: PAGE_SIZE as u64,
521 kind: MappingKind::Basic(BasicMapping {
522 readable: true,
523 writable: true,
524 executable: false,
525 }),
526 };
527 unsafe { vmem::map(pt_buf, mapping) };
528 }
529 let base_gpa = scratch_base_gpa(scratch_size);
533 let base_gva = scratch_base_gva(scratch_size);
534 let gap_gva = scratch_transport_end_gva();
535 let top_gva = scratch_reserved_top_gva();
536 let ranges = if base_gva < gap_gva {
537 [
538 (base_gpa, base_gva, gap_gva - base_gva),
539 (
540 scratch_reserved_top_gpa(),
541 top_gva,
542 SCRATCH_TOP_GVA as u64 + 1 - top_gva,
543 ),
544 ]
545 } else {
546 [(base_gpa, base_gva, scratch_size as u64), (0, 0, 0)]
548 };
549 for (phys_base, virt_base, len) in ranges.into_iter().filter(|r| r.2 != 0) {
550 let mapping = Mapping {
551 phys_base,
552 virt_base,
553 len,
554 kind: MappingKind::Basic(BasicMapping {
555 readable: true,
556 writable: true,
557 executable: false,
560 }),
561 };
562 unsafe { vmem::map(pt_buf, mapping) };
563 }
564}
565
566impl Snapshot {
567 pub(crate) fn from_env<'b>(
570 env: impl Into<GuestEnvironment<'b>>,
571 cfg: SandboxConfiguration,
572 ) -> Result<Self> {
573 let env = env.into();
574 let mut bin = env.guest_binary;
575 bin.canonicalize()?;
576 let blob = env.init_data;
577
578 let exe_info = match bin {
579 GuestBinary::FilePath(bin_path) => ExeInfo::from_file(&bin_path)?,
580 GuestBinary::Buffer(buffer) => ExeInfo::from_buf(buffer)?,
581 };
582
583 let host_version = env!("CARGO_PKG_VERSION");
585 if let Some(v) = exe_info.guest_bin_version()
586 && v != host_version
587 {
588 return Err(crate::HyperlightError::GuestBinVersionMismatch {
589 guest_bin_version: v.to_string(),
590 host_version: host_version.to_string(),
591 });
592 }
593
594 let guest_blob_size = blob.as_ref().map(|b| b.data.len()).unwrap_or(0);
595 let guest_blob_mem_flags = blob.as_ref().map(|b| b.permissions);
596
597 let mut layout = crate::mem::layout::SandboxMemoryLayout::new(
598 cfg,
599 exe_info.loaded_size(),
600 guest_blob_size,
601 guest_blob_mem_flags,
602 )?;
603
604 let load_addr = layout.get_guest_code_gpa() as u64;
605 let base_va = exe_info.base_va();
606 let entrypoint_va: u64 = exe_info.entrypoint().into();
607 let is_pie = exe_info.is_pie();
608
609 let code_gva = if is_pie { load_addr } else { base_va };
610 layout.set_code_gva(code_gva)?;
611 let regions = layout.get_memory_regions()?;
612
613 let pt_buf = GuestPageTableBuffer::new(layout.get_pt_base_gpa() as usize);
615
616 for rgn in regions.iter() {
618 let readable = rgn.flags.contains(MemoryRegionFlags::READ);
619 let executable = rgn.flags.contains(MemoryRegionFlags::EXECUTE);
620 let writable = rgn.flags.contains(MemoryRegionFlags::WRITE);
621 let kind = if writable {
622 MappingKind::Cow(CowMapping {
623 readable,
624 executable,
625 })
626 } else {
627 MappingKind::Basic(BasicMapping {
628 readable,
629 writable: false,
630 executable,
631 })
632 };
633
634 let mapping = Mapping {
635 phys_base: rgn.host_region.start as u64,
636 virt_base: rgn.guest_region.start as u64,
637 len: rgn.guest_region.len() as u64,
638 kind,
639 };
640 unsafe { vmem::map(&pt_buf, mapping) };
641 }
642
643 map_specials(&pt_buf, layout.get_scratch_size());
645
646 let pt_bytes = pt_buf.into_bytes();
647 layout.ensure_page_tables_fit(pt_bytes.len())?;
648
649 let exn_stack_top_gva = hyperlight_common::layout::SCRATCH_TOP_GVA as u64
650 - hyperlight_common::layout::SCRATCH_TOP_EXN_STACK_OFFSET
651 + 1;
652
653 let entrypoint_offset = entrypoint_va.checked_sub(base_va).ok_or_else(|| {
654 crate::new_error!(
655 "ELF entrypoint VA ({:#x}) is below base VA ({:#x})",
656 entrypoint_va,
657 base_va
658 )
659 })?;
660
661 let entrypoint_gva = (layout.get_guest_code_gva() as u64)
662 .checked_add(entrypoint_offset)
663 .ok_or_else(|| crate::new_error!("ELF entrypoint GVA overflows"))?;
664
665 let host_page_size = self::memory::host_page_size();
667 let data_len = layout.get_memory_size()?.next_multiple_of(host_page_size);
668 let mut memory = ExclusiveSharedMemory::new(
669 (data_len + pt_bytes.len()).next_multiple_of(host_page_size),
670 )?;
671 let data = &mut memory.as_mut_slice()[..data_len];
672
673 let load_info = exe_info.load(
674 layout.get_guest_code_gva() as u64,
675 &mut data[layout.guest_code_offset()..],
676 )?;
677
678 layout.write_peb(data)?;
679
680 blob.map(|x| layout.write_init_data(data, x.data))
681 .transpose()?;
682 memory.copy_from_slice(&pt_bytes, data_len)?;
683 let memory = Arc::new(SnapshotMemory::from_flat(
684 memory.freeze(data_len)?,
685 SandboxMemoryLayout::BASE_ADDRESS as u64,
686 pt_bytes.len(),
687 scratch_base_gpa(layout.get_scratch_size()),
688 )?);
689
690 Ok(Self {
691 state: Arc::new(SnapshotState {
692 memory,
693 layout,
694 load_info,
695 stack_top_gva: exn_stack_top_gva,
696 sregs: None,
697 #[cfg(target_arch = "x86_64")]
698 msrs: None,
699 next_action: NextAction::Initialise(entrypoint_gva),
700 original_entrypoint: entrypoint_gva,
701 snapshot_generation: 0,
702 host_functions: HostFunctionDetails {
703 host_functions: None,
704 },
705 virtq: None,
706 }),
707 metadata: BTreeMap::new(),
708 })
709 }
710
711 #[allow(clippy::too_many_arguments)]
717 #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
726 pub(crate) fn new(
727 memory_view: &GuestPhysicalMemoryView<'_>,
728 layout: SandboxMemoryLayout,
729 load_info: LoadInfo,
730 root_pt_gpas: &[u64],
731 stack_top_gva: u64,
732 sregs: CommonSpecialRegisters,
733 #[cfg(target_arch = "x86_64")] msrs: Vec<MsrEntry>,
734 next_action: NextAction,
735 original_entrypoint: u64,
736 snapshot_generation: u64,
737 host_functions: HostFunctionDetails,
738 virtq: Option<VirtqSnapshot>,
739 scratch_size: usize,
740 ) -> Result<Self> {
741 if root_pt_gpas.is_empty() {
742 return Err(crate::new_error!("snapshot has no page-table roots"));
743 }
744 let target = layout.with_scratch_size(scratch_size)?;
745 let scratch_gva = scratch_base_gva(layout.get_scratch_size());
746 let grown_band = scratch_base_gva(scratch_size)..scratch_gva;
749 if let Some(root) = root_pt_gpas
751 .iter()
752 .find(|root| !root.is_multiple_of(PAGE_SIZE as u64))
753 {
754 return Err(crate::new_error!(
755 "snapshot page-table root {root:#x} is not aligned"
756 ));
757 }
758 let op = PageTableReader::new(memory_view, root_pt_gpas[0]);
769 let walk = unsafe {
772 vmem::walk_va_spaces(
773 &op,
774 root_pt_gpas,
775 0,
776 hyperlight_common::layout::SCRATCH_TOP_GVA as u64,
777 )
778 };
779 op.finish()?;
780 let source_layers = memory_view.snapshot().reusable_layers();
781 let mut reused_layers = source_layers.map(|layers| vec![false; layers.len()]);
782 let mut new_pages = Vec::new();
783 for (_, mappings) in &walk {
784 for mapping in mappings {
785 let SpaceAwareMapping::ThisSpace(mapping) = mapping else {
786 continue;
787 };
788 if !grown_band.is_empty()
789 && mapping.virt_base < grown_band.end
790 && grown_band.start < mapping.virt_base.saturating_add(mapping.len)
791 {
792 for_each_mapping_page(mapping, |_, virt_gva, _| {
793 if grown_band.contains(&virt_gva) && !skip_virt(virt_gva, scratch_gva) {
794 return Err(crate::new_error!(
795 "a scratch size of {scratch_size} would map scratch over the guest mapping at {virt_gva:#x}"
796 ));
797 }
798 Ok(())
799 })?;
800 }
801 if validate_mapping(mapping)? && !mapping_has_skipped_pages(mapping, scratch_gva)? {
802 if matches!(mapping.kind, MappingKind::ZeroInit(_)) {
803 continue;
804 }
805 let mapping_len = usize::try_from(mapping.len)?;
806 if let Some(backing) = memory_view.resolve(mapping.phys_base, mapping_len) {
807 record_backed_pages(
808 backing,
809 mapping.phys_base,
810 mapping_len,
811 reused_layers.as_deref_mut(),
812 &mut new_pages,
813 )?;
814 continue;
815 }
816 }
817 for_each_mapping_page(mapping, |source_gpa, virt_gva, kind| {
818 if skip_virt(virt_gva, scratch_gva) || matches!(kind, MappingKind::ZeroInit(_))
819 {
820 return Ok(());
821 }
822 let backing = memory_view.resolve(source_gpa, PAGE_SIZE).ok_or_else(|| {
823 crate::new_error!("snapshot leaf names unbacked GPA {source_gpa:#x}")
824 })?;
825 record_backed_pages(
826 backing,
827 source_gpa,
828 PAGE_SIZE,
829 reused_layers.as_deref_mut(),
830 &mut new_pages,
831 )
832 })?;
833 }
834 }
835
836 new_pages.sort_unstable_by_key(|page| page.source_gpa);
837 new_pages.dedup_by_key(|page| page.source_gpa);
838
839 let mut layers: Vec<Arc<SnapshotBlob>> = match (source_layers, reused_layers) {
840 (Some(source_layers), Some(reused_layers)) => source_layers
841 .iter()
842 .zip(reused_layers)
843 .filter(|(_, reused)| *reused)
844 .map(|(layer, _)| layer.clone())
845 .collect(),
846 _ => Vec::new(),
847 };
848 let target_scratch_gpa = scratch_base_gpa(scratch_size);
849 if let Some(layer) = layers
850 .iter()
851 .find(|layer| layer.gpa_range().end > target_scratch_gpa)
852 {
853 return Err(crate::new_error!(
854 "a scratch size of {scratch_size} would map scratch over the snapshot layer at {:#x}",
855 layer.gpa_start()
856 ));
857 }
858 let host_page_size = self::memory::host_page_size();
859 let data_len = packed_data_len(new_pages.len(), host_page_size)?;
860 let new_blob_gpa = if data_len == 0 {
861 None
862 } else {
863 Some(
864 first_fit_blob_gpa(data_len, &layers, target_scratch_gpa).ok_or_else(|| {
865 crate::new_error!("snapshot has no address space for a new layer")
866 })?,
867 )
868 };
869 let new_page_runs = match new_blob_gpa {
870 Some(destination_start) => new_page_runs(&new_pages, destination_start)?,
871 None => Vec::new(),
872 };
873
874 let pt_buf = GuestPageTableBuffer::new(target.get_pt_base_gpa() as usize);
880 let mut root_addrs = Vec::with_capacity(root_pt_gpas.len());
884 root_addrs.push(pt_buf.initial_root());
885 for _ in 1..root_pt_gpas.len() {
886 root_addrs.push(unsafe { pt_buf.alloc_table() });
888 }
889
890 let mut built_roots: BTreeMap<SpaceId, u64> = BTreeMap::new();
891 for (root_index, (space_id, mappings)) in walk.into_iter().enumerate() {
892 pt_buf.set_root(root_addrs[root_index]);
893 built_roots.insert(space_id, root_addrs[root_index]);
894 let mut pending_mapping: Option<Mapping> = None;
895 let flush_mapping = |pending: &mut Option<Mapping>| {
896 if let Some(mapping) = pending.take() {
897 unsafe { vmem::map(&pt_buf, mapping) };
900 }
901 };
902 for mapping in mappings {
903 match mapping {
904 SpaceAwareMapping::ThisSpace(mapping) => {
905 for_each_mapping_page(&mapping, |source_gpa, virt_gva, kind| {
906 if skip_virt(virt_gva, scratch_gva) {
911 flush_mapping(&mut pending_mapping);
912 return Ok(());
913 }
914 let kind = snapshot_mapping_kind(kind).ok_or_else(|| {
918 crate::new_error!("snapshot walker returned an unmapped leaf")
919 })?;
920 let destination_gpa =
921 page_destination(&new_page_runs, source_gpa).unwrap_or(source_gpa);
922 if let Some(pending) = pending_mapping.as_mut()
923 && pending.kind == kind
924 && pending.phys_base.checked_add(pending.len)
925 == Some(destination_gpa)
926 && pending.virt_base.checked_add(pending.len) == Some(virt_gva)
927 {
928 pending.len =
929 pending.len.checked_add(PAGE_SIZE as u64).ok_or_else(|| {
930 crate::new_error!("snapshot mapping length overflows")
931 })?;
932 } else {
933 flush_mapping(&mut pending_mapping);
934 pending_mapping = Some(Mapping {
935 phys_base: destination_gpa,
936 virt_base: virt_gva,
937 len: PAGE_SIZE as u64,
938 kind,
939 });
940 }
941 Ok(())
942 })?;
943 }
944 SpaceAwareMapping::AnotherSpace(reference) => {
945 flush_mapping(&mut pending_mapping);
946 unsafe { vmem::space_aware_map(&pt_buf, reference, &built_roots) };
956 }
957 }
958 }
959 flush_mapping(&mut pending_mapping);
960 }
961
962 for &root_addr in &root_addrs {
964 pt_buf.set_root(root_addr);
965 map_specials(&pt_buf, scratch_size);
966 }
967 pt_buf.set_root(pt_buf.initial_root());
968 let page_tables = pt_buf.into_bytes();
972 target.ensure_page_tables_fit(page_tables.len())?;
973 let blob_len = data_len
974 .checked_add(page_tables.len())
975 .and_then(|len| len.checked_next_multiple_of(host_page_size))
976 .ok_or_else(|| crate::new_error!("snapshot blob size overflows"))?;
977 let mut allocation = ExclusiveSharedMemory::new(blob_len)?;
978 for copy in new_page_copies(&new_pages)? {
979 let destination = allocation
980 .as_mut_slice()
981 .get_mut(copy.destination)
982 .ok_or_else(|| crate::new_error!("snapshot destination page is out of bounds"))?;
983 memory_view.read_backing(copy.backing, destination)?;
984 }
985 allocation.copy_from_slice(&page_tables, data_len)?;
986 let blob = Arc::new(SnapshotBlob::new(
987 allocation.freeze(data_len)?,
988 new_blob_gpa.unwrap_or_default(),
989 page_tables.len(),
990 target_scratch_gpa,
991 )?);
992 if data_len > 0 {
993 layers.push(blob.clone());
994 }
995 let memory = Arc::new(SnapshotMemory::new(layers.into_boxed_slice(), blob)?);
997
998 Ok(Self {
999 state: Arc::new(SnapshotState {
1000 layout: target,
1001 memory,
1002 load_info,
1003 stack_top_gva,
1004 sregs: Some(sregs),
1005 #[cfg(target_arch = "x86_64")]
1006 msrs: Some(msrs),
1007 next_action,
1008 original_entrypoint,
1009 snapshot_generation,
1010 host_functions,
1011 virtq,
1012 }),
1013 metadata: BTreeMap::new(),
1014 })
1015 }
1016
1017 pub fn metadata<T>(&self, namespace: &str) -> Result<Option<T>>
1048 where
1049 T: serde::de::DeserializeOwned,
1050 {
1051 self.metadata
1052 .get(namespace)
1053 .map(serde::Deserialize::deserialize)
1054 .transpose()
1055 .map_err(Into::into)
1056 }
1057
1058 pub fn with_metadata<T>(&self, namespace: impl Into<String>, metadata: &T) -> Result<Arc<Self>>
1091 where
1092 T: serde::Serialize,
1093 {
1094 let namespace = namespace.into();
1095 let metadata = serde_json::to_value(metadata)?;
1096 let mut metadata_by_namespace = self.metadata.clone();
1097 metadata_by_namespace.insert(namespace, metadata);
1098 Ok(Arc::new(Self {
1099 state: Arc::clone(&self.state),
1100 metadata: metadata_by_namespace,
1101 }))
1102 }
1103
1104 pub(crate) fn snapshot_generation(&self) -> u64 {
1106 self.state.snapshot_generation
1107 }
1108
1109 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
1111 pub(crate) fn snapshot_memory(&self) -> &Arc<SnapshotMemory> {
1112 &self.state.memory
1113 }
1114
1115 pub(crate) fn load_info(&self) -> LoadInfo {
1117 self.state.load_info.clone()
1118 }
1119
1120 pub(crate) fn layout(&self) -> &crate::mem::layout::SandboxMemoryLayout {
1121 &self.state.layout
1122 }
1123
1124 pub(crate) fn root_pt_gpa(&self) -> u64 {
1125 self.state.layout.get_pt_base_gpa()
1126 }
1127
1128 pub(crate) fn stack_top_gva(&self) -> u64 {
1129 self.state.stack_top_gva
1130 }
1131
1132 pub(crate) fn sregs(&self) -> Option<&CommonSpecialRegisters> {
1138 self.state.sregs.as_ref()
1139 }
1140
1141 #[cfg(target_arch = "x86_64")]
1143 pub(crate) fn msrs(&self) -> Option<&Vec<MsrEntry>> {
1144 self.state.msrs.as_ref()
1145 }
1146
1147 pub(crate) fn next_action(&self) -> NextAction {
1148 self.state.next_action
1149 }
1150
1151 pub(crate) fn virtq(&self) -> Option<&VirtqSnapshot> {
1152 self.state.virtq.as_ref()
1153 }
1154
1155 pub(crate) fn original_entrypoint(&self) -> u64 {
1159 self.state.original_entrypoint
1160 }
1161
1162 pub(crate) fn validate_host_functions(
1171 &self,
1172 provided: &crate::sandbox::host_funcs::FunctionRegistry,
1173 ) -> Result<()> {
1174 let required = match &self.state.host_functions.host_functions {
1175 Some(v) => v,
1176 None => return Ok(()),
1177 };
1178 if required.is_empty() {
1179 return Ok(());
1180 }
1181
1182 let mut missing: Vec<String> = Vec::new();
1183 let mut signature_mismatches: Vec<String> = Vec::new();
1184
1185 for req in required {
1186 match provided.function_signature(&req.function_name) {
1187 None => missing.push(req.function_name.clone()),
1189 Some((found_parameter_types, found_return_type))
1191 if {
1192 let params_match = match req.parameter_types.as_deref() {
1193 Some(params) => params == found_parameter_types,
1194 None => found_parameter_types.is_empty(),
1195 };
1196 !params_match || req.return_type != found_return_type
1197 } =>
1198 {
1199 signature_mismatches.push(format!(
1200 "{}: snapshot has {:?} -> {:?}, registered {:?} -> {:?}",
1201 req.function_name,
1202 req.parameter_types,
1203 req.return_type,
1204 Some(found_parameter_types.to_vec()),
1205 found_return_type,
1206 ));
1207 }
1208 Some(_) => {}
1210 }
1211 }
1212
1213 if missing.is_empty() && signature_mismatches.is_empty() {
1214 return Ok(());
1215 }
1216
1217 Err(crate::HyperlightError::SnapshotHostFunctionMismatch {
1218 missing,
1219 signature_mismatches,
1220 })
1221 }
1222}
1223
1224#[cfg(test)]
1225mod tests {
1226 use std::sync::Arc;
1227
1228 use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
1229 use hyperlight_common::vmem::{
1230 self, BasicMapping, Mapping, MappingKind, PAGE_SIZE, PAGE_TABLE_SIZE,
1231 };
1232
1233 use super::SnapshotMemoryBacking;
1234 use crate::hypervisor::regs::CommonSpecialRegisters;
1235 use crate::mem::exe::LoadInfo;
1236 use crate::mem::layout::SandboxMemoryLayout;
1237 use crate::mem::mgr::{
1238 BackingSource, GuestBacking, GuestPageTableBuffer, GuestPhysicalMemoryView,
1239 SandboxMemoryManager,
1240 };
1241 use crate::mem::shared_mem::{ExclusiveSharedMemory, HostSharedMemory};
1242
1243 fn default_sregs() -> CommonSpecialRegisters {
1244 CommonSpecialRegisters::default()
1245 }
1246
1247 fn new_page(source_gpa: u64, offset: usize) -> super::NewPage {
1248 super::NewPage {
1249 source_gpa,
1250 backing: GuestBacking {
1251 source: BackingSource::Snapshot(0),
1252 offset,
1253 },
1254 }
1255 }
1256
1257 #[test]
1258 fn page_runs_map_each_source_to_its_destination() {
1259 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1260 let page = PAGE_SIZE as u64;
1261 let destination = base + 0x10_0000;
1262 let pages = [
1264 new_page(base, 0),
1265 new_page(base + page, PAGE_SIZE),
1266 new_page(base + 8 * page, 8 * PAGE_SIZE),
1267 ];
1268
1269 let runs = super::new_page_runs(&pages, destination).unwrap();
1270 assert_eq!(runs.len(), 2);
1271
1272 assert_eq!(super::page_destination(&runs, base), Some(destination));
1274 assert_eq!(
1275 super::page_destination(&runs, base + page),
1276 Some(destination + page)
1277 );
1278 assert_eq!(
1279 super::page_destination(&runs, base + 8 * page),
1280 Some(destination + 2 * page)
1281 );
1282 assert_eq!(super::page_destination(&runs, base + 2 * page), None);
1284 assert_eq!(super::page_destination(&runs, base + 9 * page), None);
1285 }
1286
1287 #[test]
1288 fn page_copies_merge_only_contiguous_backings() {
1289 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1290 let page = PAGE_SIZE as u64;
1291 let pages = [
1294 new_page(base, 0),
1295 new_page(base + page, PAGE_SIZE),
1296 new_page(base + 2 * page, 9 * PAGE_SIZE),
1297 ];
1298
1299 let copies = super::new_page_copies(&pages).unwrap();
1300 assert_eq!(copies.len(), 2);
1301 assert_eq!(copies[0].destination, 0..2 * PAGE_SIZE);
1302 assert_eq!(copies[1].destination, 2 * PAGE_SIZE..3 * PAGE_SIZE);
1303 }
1304
1305 #[test]
1306 fn blob_placement_respects_the_scratch_boundary() {
1307 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1308 let scratch_base = base + 2 * PAGE_SIZE as u64;
1309
1310 assert_eq!(super::first_fit_blob_gpa(0, &[], scratch_base), None);
1312 assert_eq!(
1314 super::first_fit_blob_gpa(PAGE_SIZE, &[], scratch_base),
1315 Some(base)
1316 );
1317 assert_eq!(
1319 super::first_fit_blob_gpa(2 * PAGE_SIZE, &[], scratch_base),
1320 Some(base)
1321 );
1322 assert_eq!(
1324 super::first_fit_blob_gpa(3 * PAGE_SIZE, &[], scratch_base),
1325 None
1326 );
1327 }
1328
1329 #[test]
1330 fn snapshot_page_policy_reuses_shared_and_copies_private_backings() {
1331 let source_gpa = SandboxMemoryLayout::BASE_ADDRESS as u64;
1332 let backing = GuestBacking {
1333 source: BackingSource::Snapshot(0),
1334 offset: 0,
1335 };
1336 let mut reused = vec![false];
1337 let mut copied = Vec::new();
1338
1339 super::record_backed_pages(
1340 backing,
1341 source_gpa,
1342 2 * PAGE_SIZE,
1343 Some(reused.as_mut_slice()),
1344 &mut copied,
1345 )
1346 .unwrap();
1347 assert_eq!(reused, [true]);
1348 assert!(copied.is_empty());
1349
1350 reused[0] = false;
1351 super::record_backed_pages(backing, source_gpa, 2 * PAGE_SIZE, None, &mut copied).unwrap();
1352 assert_eq!(reused, [false]);
1353 assert_eq!(copied.len(), 2);
1354 assert_eq!(copied[0].source_gpa, source_gpa);
1355 assert_eq!(copied[0].backing, backing);
1356 assert_eq!(copied[1].source_gpa, source_gpa + PAGE_SIZE as u64);
1357 assert_eq!(
1358 copied[1].backing,
1359 GuestBacking {
1360 source: BackingSource::Snapshot(0),
1361 offset: PAGE_SIZE,
1362 }
1363 );
1364 }
1365
1366 fn make_simple_pt_memory(contents: &[u8], pt_base: u64) -> super::SnapshotMemory {
1367 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1368 make_pt_memory(contents, pt_base, base, &[base])
1369 }
1370
1371 fn make_pt_memory(
1374 contents: &[u8],
1375 pt_base: u64,
1376 data_gpa: u64,
1377 gvas: &[u64],
1378 ) -> super::SnapshotMemory {
1379 let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1380 for &virt_base in gvas {
1381 let mapping = Mapping {
1382 phys_base: data_gpa,
1383 virt_base,
1384 len: page_size::get() as u64,
1385 kind: MappingKind::Basic(BasicMapping {
1386 readable: true,
1387 writable: true,
1388 executable: true,
1389 }),
1390 };
1391 unsafe { vmem::map(&pt_buf, mapping) };
1392 }
1393 super::map_specials(&pt_buf, PAGE_SIZE);
1394 let pt_bytes = pt_buf.into_bytes();
1395
1396 super::memory::tests::flat_memory(
1397 contents,
1398 &pt_bytes,
1399 data_gpa,
1400 hyperlight_common::layout::scratch_base_gpa(PAGE_SIZE),
1401 )
1402 }
1403
1404 fn make_simple_pt_host_mem(
1405 contents: &[u8],
1406 pt_base: u64,
1407 ) -> SnapshotMemoryBacking<HostSharedMemory> {
1408 SnapshotMemoryBacking::from_snapshot(Arc::new(make_simple_pt_memory(contents, pt_base)))
1409 .unwrap()
1410 .build()
1411 .0
1412 }
1413
1414 fn make_simple_pt_mgr() -> (SandboxMemoryManager<HostSharedMemory>, u64) {
1415 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1416 make_pt_mgr(base, &[base])
1417 }
1418
1419 fn make_pt_mgr(data_gpa: u64, gvas: &[u64]) -> (SandboxMemoryManager<HostSharedMemory>, u64) {
1422 let cfg = crate::sandbox::SandboxConfiguration::default();
1423 let scratch_mem = ExclusiveSharedMemory::new(cfg.get_scratch_size()).unwrap();
1424 let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
1425 let pt_base = layout.get_pt_base_gpa();
1426 let memory = make_pt_memory(&vec![0u8; page_size::get()], pt_base, data_gpa, gvas);
1427 layout
1428 .ensure_page_tables_fit(memory.page_table_len())
1429 .unwrap();
1430 let mgr = SandboxMemoryManager::new(
1431 layout,
1432 SnapshotMemoryBacking::from_snapshot(Arc::new(memory)).unwrap(),
1433 scratch_mem,
1434 super::NextAction::None,
1435 );
1436 let (mgr, _) = mgr.build().unwrap();
1437 (mgr, pt_base)
1438 }
1439
1440 #[test]
1441 fn capture_and_restore_preserve_multiple_page_table_roots() {
1442 let cfg = crate::sandbox::SandboxConfiguration::default();
1443 let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
1444 let pt_base = layout.get_pt_base_gpa();
1445 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1446 let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1447 let first_root = pt_buf.initial_root();
1448 let second_root = unsafe { <GuestPageTableBuffer as vmem::TableOps>::alloc_table(&pt_buf) };
1450 let kind = MappingKind::Basic(BasicMapping {
1451 readable: true,
1452 writable: false,
1453 executable: false,
1454 });
1455 unsafe {
1457 vmem::map(
1458 &pt_buf,
1459 Mapping {
1460 phys_base: base,
1461 virt_base: base,
1462 len: PAGE_SIZE as u64,
1463 kind,
1464 },
1465 );
1466 pt_buf.set_root(second_root);
1467 vmem::map(
1468 &pt_buf,
1469 Mapping {
1470 phys_base: base + PAGE_SIZE as u64,
1471 virt_base: base + PAGE_SIZE as u64,
1472 len: PAGE_SIZE as u64,
1473 kind,
1474 },
1475 );
1476 }
1477 pt_buf.set_root(first_root);
1478 let page_tables = pt_buf.into_bytes();
1479 layout.ensure_page_tables_fit(page_tables.len()).unwrap();
1480
1481 let data_len = 2 * page_size::get();
1482 let mut bytes = vec![0u8; data_len];
1483 bytes[..PAGE_SIZE].fill(0x11);
1484 bytes[PAGE_SIZE..2 * PAGE_SIZE].fill(0x22);
1485 let memory = super::memory::tests::flat_memory(
1486 &bytes,
1487 &page_tables,
1488 base,
1489 hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
1490 );
1491 let manager = SandboxMemoryManager::new(
1492 layout,
1493 SnapshotMemoryBacking::from_snapshot(Arc::new(memory)).unwrap(),
1494 ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap(),
1495 super::NextAction::None,
1496 );
1497 let (mut manager, _) = manager.build().unwrap();
1498
1499 let snapshot = manager
1500 .with_guest_memory(&[], |memory| {
1501 super::Snapshot::new(
1502 memory,
1503 manager.layout,
1504 LoadInfo::dummy(),
1505 &[first_root, second_root],
1506 0,
1507 default_sregs(),
1508 #[cfg(target_arch = "x86_64")]
1509 Vec::new(),
1510 super::NextAction::None,
1511 0,
1512 1,
1513 HostFunctionDetails::default(),
1514 None,
1515 manager.layout.get_scratch_size(),
1516 )
1517 })
1518 .unwrap();
1519 let rebuilt_first_root = snapshot.root_pt_gpa();
1520 let rebuilt_second_root = rebuilt_first_root + PAGE_TABLE_SIZE as u64;
1521 let roots = [rebuilt_first_root, rebuilt_second_root];
1522 let walked = unsafe { vmem::walk_va_spaces(&snapshot, &roots, base, 2 * PAGE_SIZE as u64) };
1524 assert_eq!(walked.len(), 2);
1525 assert!(walked[0].1.iter().any(|mapping| matches!(
1526 mapping,
1527 vmem::SpaceAwareMapping::ThisSpace(mapping) if mapping.virt_base == base
1528 )));
1529 assert!(walked[1].1.iter().any(|mapping| matches!(
1530 mapping,
1531 vmem::SpaceAwareMapping::ThisSpace(mapping)
1532 if mapping.virt_base == base + PAGE_SIZE as u64
1533 )));
1534
1535 manager.restore_snapshot(&snapshot).unwrap();
1536 manager
1537 .with_guest_memory(&[], |memory| {
1538 for (root, gva, expected) in [
1539 (rebuilt_first_root, base, 0x11),
1540 (rebuilt_second_root, base + PAGE_SIZE as u64, 0x22),
1541 ] {
1542 let reader = super::PageTableReader::new(memory, root);
1543 let mapping = unsafe { vmem::virt_to_phys(&reader, gva, 1) }
1545 .next()
1546 .unwrap();
1547 let gpa = mapping.phys_base + gva - mapping.virt_base;
1548 let mut byte = [0u8; 1];
1549 memory.read(gpa, &mut byte).unwrap();
1550 assert_eq!(byte, [expected]);
1551 }
1552 Ok(())
1553 })
1554 .unwrap();
1555 }
1556
1557 #[cfg(target_arch = "x86_64")]
1558 #[test]
1559 fn capture_rejects_unbacked_intermediate_page_table() {
1560 let (manager, pt_base) = make_simple_pt_mgr();
1561 let scratch_base =
1562 hyperlight_common::layout::scratch_base_gpa(manager.layout.get_scratch_size());
1563 let root_offset = usize::try_from(pt_base - scratch_base).unwrap();
1564 let invalid_entry = (0xdead_0000 | vmem::PAGE_PRESENT).to_le_bytes();
1565 manager
1566 .scratch_mem
1567 .copy_from_slice(&invalid_entry, root_offset)
1568 .unwrap();
1569
1570 let result = manager.with_guest_memory(&[], |memory| {
1571 super::Snapshot::new(
1572 memory,
1573 manager.layout,
1574 LoadInfo::dummy(),
1575 &[pt_base],
1576 0,
1577 default_sregs(),
1578 Vec::new(),
1579 super::NextAction::None,
1580 0,
1581 1,
1582 HostFunctionDetails::default(),
1583 None,
1584 manager.layout.get_scratch_size(),
1585 )
1586 });
1587 let error = match result {
1588 Ok(_) => panic!("capture unexpectedly accepted an unbacked page table"),
1589 Err(error) => error,
1590 };
1591 assert!(error.to_string().contains("accessed unbacked memory"));
1592 }
1593
1594 #[test]
1595 fn multiple_snapshots_independent() {
1596 let (mut mgr, pt_base) = make_simple_pt_mgr();
1597
1598 let pattern_a = vec![0xAA; page_size::get()];
1600 let pattern_a_memory = make_simple_pt_host_mem(&pattern_a, pt_base);
1601 let snapshot_a = GuestPhysicalMemoryView::with_memory(
1602 &pattern_a_memory,
1603 &mgr.scratch_mem,
1604 &[],
1605 mgr.layout,
1606 |memory| {
1607 super::Snapshot::new(
1608 memory,
1609 mgr.layout,
1610 LoadInfo::dummy(),
1611 &[pt_base],
1612 0,
1613 default_sregs(),
1614 #[cfg(target_arch = "x86_64")]
1615 Vec::new(),
1616 super::NextAction::None,
1617 0,
1618 1,
1619 HostFunctionDetails::default(),
1620 None,
1621 mgr.layout.get_scratch_size(),
1622 )
1623 },
1624 )
1625 .unwrap();
1626 assert_eq!(snapshot_a.snapshot_memory().layers().len(), 1);
1627
1628 let pattern_b = vec![0xBB; page_size::get()];
1630 let pattern_b_memory = make_simple_pt_host_mem(&pattern_b, pt_base);
1631 let snapshot_b = GuestPhysicalMemoryView::with_memory(
1632 &pattern_b_memory,
1633 &mgr.scratch_mem,
1634 &[],
1635 mgr.layout,
1636 |memory| {
1637 super::Snapshot::new(
1638 memory,
1639 mgr.layout,
1640 LoadInfo::dummy(),
1641 &[pt_base],
1642 0,
1643 default_sregs(),
1644 #[cfg(target_arch = "x86_64")]
1645 Vec::new(),
1646 super::NextAction::None,
1647 0,
1648 2,
1649 HostFunctionDetails::default(),
1650 None,
1651 mgr.layout.get_scratch_size(),
1652 )
1653 },
1654 )
1655 .unwrap();
1656
1657 mgr.restore_snapshot(&snapshot_a).unwrap();
1659 let mut restored = vec![0u8; pattern_a.len()];
1660 mgr.shared_mem
1661 .read_snapshot_gpa(SandboxMemoryLayout::BASE_ADDRESS as u64, &mut restored)
1662 .unwrap();
1663 assert_eq!(restored, pattern_a);
1664
1665 mgr.restore_snapshot(&snapshot_b).unwrap();
1667 restored.fill(0);
1668 mgr.shared_mem
1669 .read_snapshot_gpa(SandboxMemoryLayout::BASE_ADDRESS as u64, &mut restored)
1670 .unwrap();
1671 assert_eq!(restored, pattern_b);
1672 }
1673
1674 #[test]
1675 fn page_table_reader_reports_unbacked_memory() {
1676 let (manager, pt_base) = make_simple_pt_mgr();
1677 manager
1678 .with_guest_memory(&[], |memory| {
1679 let reader = super::PageTableReader::new(memory, pt_base);
1680 assert!(reader.finish().is_ok());
1681
1682 let entry = unsafe {
1686 <super::PageTableReader as vmem::TableReadOps>::read_entry(
1687 &reader,
1688 !(PAGE_SIZE as u64 - 1),
1689 )
1690 };
1691 assert_eq!(entry, 0);
1692 let error = reader.finish().unwrap_err().to_string();
1693 assert!(error.contains("accessed unbacked memory"), "{error}");
1694 Ok(())
1695 })
1696 .unwrap();
1697 }
1698 fn snapshot_with_scratch(
1699 data_gpa: u64,
1700 gvas: &[u64],
1701 scratch_size: usize,
1702 ) -> crate::Result<super::Snapshot> {
1703 let (mgr, pt_base) = make_pt_mgr(data_gpa, gvas);
1704 mgr.with_guest_memory(&[], |memory| {
1705 super::Snapshot::new(
1706 memory,
1707 mgr.layout,
1708 LoadInfo::dummy(),
1709 &[pt_base],
1710 0,
1711 default_sregs(),
1712 #[cfg(target_arch = "x86_64")]
1713 Vec::new(),
1714 super::NextAction::None,
1715 0,
1716 1,
1717 HostFunctionDetails::default(),
1718 None,
1719 scratch_size,
1720 )
1721 })
1722 }
1723
1724 #[test]
1727 fn larger_scratch_must_not_cover_guest_mappings() {
1728 let scratch_size = crate::sandbox::SandboxConfiguration::default().get_scratch_size();
1729 let larger = scratch_size * 2;
1730 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1731
1732 let Ok(snapshot) = snapshot_with_scratch(base, &[base], larger) else {
1733 panic!("a larger scratch window over no guest mapping is rejected");
1734 };
1735 assert_eq!(snapshot.layout().get_scratch_size(), larger);
1736
1737 let in_band = super::scratch_base_gva(scratch_size) - PAGE_SIZE as u64;
1738 let Err(err) = snapshot_with_scratch(base, &[base, in_band], larger) else {
1739 panic!("a larger scratch window covers a guest mapping");
1740 };
1741 assert!(err.to_string().contains(&format!("{in_band:#x}")), "{err}");
1742
1743 assert!(snapshot_with_scratch(base, &[base, in_band], scratch_size).is_ok());
1745 }
1746
1747 #[test]
1749 #[cfg(not(unshared_snapshot_mem))]
1750 fn larger_scratch_must_not_cover_kept_layers() {
1751 let scratch_size = crate::sandbox::SandboxConfiguration::default().get_scratch_size();
1752 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1753 let high = super::scratch_base_gpa(scratch_size) - page_size::get() as u64;
1754
1755 let Err(err) = snapshot_with_scratch(high, &[base], scratch_size * 2) else {
1756 panic!("a larger scratch window covers a kept layer");
1757 };
1758 assert!(err.to_string().contains(&format!("{high:#x}")), "{err}");
1759
1760 let snapshot = snapshot_with_scratch(high, &[base], scratch_size).unwrap();
1761 assert_eq!(snapshot.snapshot_memory().layers()[0].gpa_start(), high);
1762 }
1763
1764 #[test]
1765 fn page_table_reader_switches_cached_table_pages() {
1766 let (manager, pt_base) = make_simple_pt_mgr();
1767 let first = 8;
1768 let second = PAGE_SIZE + 16;
1769 manager.scratch_mem.write::<u64>(first, 0x1111).unwrap();
1770 manager.scratch_mem.write::<u64>(second, 0x2222).unwrap();
1771 let scratch_base =
1772 hyperlight_common::layout::scratch_base_gpa(manager.layout.get_scratch_size());
1773 manager
1774 .with_guest_memory(&[], |memory| {
1775 let reader = super::PageTableReader::new(memory, pt_base);
1776 let read = |offset: usize| unsafe {
1778 <super::PageTableReader as vmem::TableReadOps>::read_entry(
1779 &reader,
1780 scratch_base + offset as u64,
1781 )
1782 };
1783
1784 assert_eq!(read(first), 0x1111);
1785 assert_eq!(read(second), 0x2222);
1786 assert_eq!(read(first), 0x1111);
1787 assert!(reader.finish().is_ok());
1788 Ok(())
1789 })
1790 .unwrap();
1791 }
1792
1793 #[test]
1794 fn capture_rejects_invalid_page_table_roots() {
1795 let (manager, root) = make_simple_pt_mgr();
1796 for roots in [
1797 Vec::new(),
1798 vec![root + 1],
1799 vec![u64::MAX - (PAGE_SIZE as u64 - 1)],
1800 ] {
1801 let result = manager.with_guest_memory(&[], |memory| {
1802 super::Snapshot::new(
1803 memory,
1804 manager.layout,
1805 LoadInfo::dummy(),
1806 &roots,
1807 0,
1808 default_sregs(),
1809 #[cfg(target_arch = "x86_64")]
1810 Vec::new(),
1811 super::NextAction::None,
1812 0,
1813 1,
1814 HostFunctionDetails::default(),
1815 None,
1816 manager.layout.get_scratch_size(),
1817 )
1818 });
1819 assert!(result.is_err(), "invalid roots accepted: {roots:?}");
1820 }
1821 }
1822
1823 #[test]
1824 fn capture_reuses_shared_pages_and_materializes_private_pages() {
1825 let host_page_size = page_size::get();
1826 let cfg = crate::sandbox::SandboxConfiguration::default();
1827 let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
1828 let pt_base = layout.get_pt_base_gpa();
1829 let scratch_offset = layout.get_scratch_size() / 2;
1830 let scratch_gpa = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size())
1831 + scratch_offset as u64;
1832 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1833
1834 let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1835 unsafe {
1838 vmem::map(
1839 &pt_buf,
1840 Mapping {
1841 phys_base: base,
1842 virt_base: base,
1843 len: host_page_size as u64,
1844 kind: MappingKind::Basic(BasicMapping {
1845 readable: true,
1846 writable: false,
1847 executable: true,
1848 }),
1849 },
1850 );
1851 vmem::map(
1852 &pt_buf,
1853 Mapping {
1854 phys_base: scratch_gpa,
1855 virt_base: base + (2 * host_page_size) as u64,
1856 len: host_page_size as u64,
1857 kind: MappingKind::Basic(BasicMapping {
1858 readable: true,
1859 writable: true,
1860 executable: false,
1861 }),
1862 },
1863 );
1864 vmem::map(
1865 &pt_buf,
1866 Mapping {
1867 phys_base: scratch_gpa,
1868 virt_base: base + host_page_size as u64,
1869 len: host_page_size as u64,
1870 kind: MappingKind::Basic(BasicMapping {
1871 readable: true,
1872 writable: true,
1873 executable: false,
1874 }),
1875 },
1876 );
1877 }
1878 super::map_specials(&pt_buf, layout.get_scratch_size());
1879 let page_tables = pt_buf.into_bytes();
1880 layout.ensure_page_tables_fit(page_tables.len()).unwrap();
1881
1882 let mut source_bytes = vec![0u8; 2 * host_page_size];
1883 source_bytes[..host_page_size].fill(0x11);
1884 source_bytes[host_page_size..2 * host_page_size].fill(0x22);
1885 let source = super::memory::tests::flat_memory(
1886 &source_bytes,
1887 &page_tables,
1888 base,
1889 hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
1890 );
1891 let source_blob = source.layers()[0].clone();
1892 let managed = SnapshotMemoryBacking::from_snapshot(Arc::new(source)).unwrap();
1893 let scratch = ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap();
1894 let manager = SandboxMemoryManager::new(layout, managed, scratch, super::NextAction::None);
1895 let (manager, _) = manager.build().unwrap();
1896 let reuses_source_layers = manager.shared_mem.reusable_layers().is_some();
1897 #[cfg(gdb)]
1898 {
1899 let (layer_index, offset) = manager.shared_mem.resolve(base, host_page_size).unwrap();
1900 manager
1901 .shared_mem
1902 .write_layer(layer_index, offset, &vec![0x44; host_page_size])
1903 .unwrap();
1904 }
1905 let mut source_page = vec![0u8; host_page_size];
1906 manager
1907 .shared_mem
1908 .read_snapshot_gpa(base, &mut source_page)
1909 .unwrap();
1910 manager
1911 .scratch_mem
1912 .copy_from_slice(&vec![0x33; host_page_size], scratch_offset)
1913 .unwrap();
1914
1915 let captured = manager
1916 .with_guest_memory(&[], |memory| {
1917 super::Snapshot::new(
1918 memory,
1919 manager.layout,
1920 LoadInfo::dummy(),
1921 &[pt_base],
1922 0,
1923 default_sregs(),
1924 #[cfg(target_arch = "x86_64")]
1925 Vec::new(),
1926 super::NextAction::None,
1927 0,
1928 1,
1929 HostFunctionDetails::default(),
1930 None,
1931 manager.layout.get_scratch_size(),
1932 )
1933 })
1934 .unwrap();
1935
1936 let layers = captured.snapshot_memory().layers();
1937 let delta_gpa = if reuses_source_layers {
1938 assert_eq!(layers.len(), 2);
1939 assert!(std::sync::Arc::ptr_eq(&layers[0], &source_blob));
1940 assert_eq!(layers[1].data_len(), host_page_size);
1941 assert_eq!(layers[1].gpa_start(), base + (2 * host_page_size) as u64);
1942 base + (2 * host_page_size) as u64
1943 } else {
1944 assert_eq!(layers.len(), 1);
1945 assert!(!std::sync::Arc::ptr_eq(&layers[0], &source_blob));
1946 assert_eq!(layers[0].data_len(), 2 * host_page_size);
1947 assert_eq!(layers[0].gpa_start(), base);
1948 base + host_page_size as u64
1949 };
1950
1951 let mappings = unsafe { vmem::virt_to_phys(&captured, base, 3 * host_page_size as u64) }
1953 .step_by(host_page_size / PAGE_SIZE)
1954 .collect::<Vec<_>>();
1955 assert_eq!(mappings.len(), 3);
1956 assert_eq!(mappings[0].phys_base, base);
1957 assert_eq!(mappings[1].phys_base, delta_gpa);
1958 assert_eq!(mappings[2].phys_base, mappings[1].phys_base);
1959 assert_eq!(
1960 mappings[0].kind,
1961 MappingKind::Basic(BasicMapping {
1962 readable: true,
1963 writable: false,
1964 executable: true,
1965 })
1966 );
1967 assert_eq!(
1968 mappings[1].kind,
1969 MappingKind::Cow(hyperlight_common::vmem::CowMapping {
1970 readable: true,
1971 executable: false,
1972 })
1973 );
1974 let (delta_layer, delta_offset) = captured
1975 .snapshot_memory()
1976 .resolve(mappings[1].phys_base, host_page_size)
1977 .unwrap();
1978 assert_eq!(
1979 layers[delta_layer].memory().as_slice()[delta_offset..delta_offset + host_page_size],
1980 vec![0x33; host_page_size]
1981 );
1982 let (kept_layer, kept_offset) = captured
1983 .snapshot_memory()
1984 .resolve(base, host_page_size)
1985 .unwrap();
1986 assert_eq!(
1987 layers[kept_layer].memory().as_slice()[kept_offset..kept_offset + host_page_size],
1988 source_page
1989 );
1990 let (replaced_layer, replaced_offset) = captured
1993 .snapshot_memory()
1994 .resolve(base + host_page_size as u64, host_page_size)
1995 .unwrap();
1996 let replaced = vec![if reuses_source_layers { 0x22 } else { 0x33 }; host_page_size];
1997 assert_eq!(
1998 layers[replaced_layer].memory().as_slice()
1999 [replaced_offset..replaced_offset + host_page_size],
2000 replaced
2001 );
2002 }
2003
2004 #[test]
2005 fn capture_rejects_leaf_into_page_table_tail() {
2006 let host_page_size = page_size::get();
2007 let cfg = crate::sandbox::SandboxConfiguration::default();
2008 let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
2009 let pt_base = layout.get_pt_base_gpa();
2010 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
2011 let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
2012 unsafe {
2015 vmem::map(
2016 &pt_buf,
2017 Mapping {
2018 phys_base: base + host_page_size as u64,
2019 virt_base: base,
2020 len: PAGE_SIZE as u64,
2021 kind: MappingKind::Basic(BasicMapping {
2022 readable: true,
2023 writable: false,
2024 executable: false,
2025 }),
2026 },
2027 );
2028 }
2029 super::map_specials(&pt_buf, layout.get_scratch_size());
2030 let page_tables = pt_buf.into_bytes();
2031 layout.ensure_page_tables_fit(page_tables.len()).unwrap();
2032
2033 let bytes = vec![0u8; host_page_size];
2034 let source = super::memory::tests::flat_memory(
2035 &bytes,
2036 &page_tables,
2037 base,
2038 hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
2039 );
2040 let manager = SandboxMemoryManager::new(
2041 layout,
2042 SnapshotMemoryBacking::from_snapshot(Arc::new(source)).unwrap(),
2043 ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap(),
2044 super::NextAction::None,
2045 );
2046 let (manager, _) = manager.build().unwrap();
2047
2048 let result = manager.with_guest_memory(&[], |memory| {
2049 super::Snapshot::new(
2050 memory,
2051 manager.layout,
2052 LoadInfo::dummy(),
2053 &[pt_base],
2054 0,
2055 default_sregs(),
2056 #[cfg(target_arch = "x86_64")]
2057 Vec::new(),
2058 super::NextAction::None,
2059 0,
2060 1,
2061 HostFunctionDetails::default(),
2062 None,
2063 manager.layout.get_scratch_size(),
2064 )
2065 });
2066 let error = match result {
2067 Ok(_) => panic!("capture unexpectedly accepted a page-table-tail leaf"),
2068 Err(error) => error,
2069 };
2070
2071 assert!(
2072 error
2073 .to_string()
2074 .contains("snapshot leaf names unbacked GPA")
2075 );
2076 }
2077
2078 #[test]
2079 #[cfg(not(unshared_snapshot_mem))]
2080 fn capture_rejects_delta_exceeding_layer_limit() {
2081 let host_page_size = page_size::get();
2082 let cfg = crate::sandbox::SandboxConfiguration::default();
2083 let layout = SandboxMemoryLayout::new(cfg, 4096, 0x3000, None).unwrap();
2084 let pt_base = layout.get_pt_base_gpa();
2085 let scratch_offset = layout.get_scratch_size() / 2;
2086 let scratch_gpa = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size())
2087 + scratch_offset as u64;
2088 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
2089 let max_layers = super::memory::MAX_SNAPSHOT_LAYERS;
2090
2091 let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
2092 for index in 0..=max_layers {
2095 let phys_base = if index < max_layers {
2096 base + (index * host_page_size) as u64
2097 } else {
2098 scratch_gpa
2099 };
2100 unsafe {
2103 vmem::map(
2104 &pt_buf,
2105 Mapping {
2106 phys_base,
2107 virt_base: base + (index * host_page_size) as u64,
2108 len: host_page_size as u64,
2109 kind: MappingKind::Basic(BasicMapping {
2110 readable: true,
2111 writable: index == max_layers,
2112 executable: false,
2113 }),
2114 },
2115 );
2116 }
2117 }
2118 super::map_specials(&pt_buf, layout.get_scratch_size());
2119 let page_tables = pt_buf.into_bytes();
2120 layout.ensure_page_tables_fit(page_tables.len()).unwrap();
2121
2122 let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
2123 let source_layers = (0..max_layers)
2124 .map(|index| {
2125 let storage = crate::mem::shared_mem::ReadonlySharedMemory::from_bytes(
2126 &vec![index as u8; host_page_size],
2127 host_page_size,
2128 )
2129 .unwrap();
2130 Arc::new(
2131 super::SnapshotBlob::new(
2132 storage,
2133 base + (index * host_page_size) as u64,
2134 0,
2135 scratch_base,
2136 )
2137 .unwrap(),
2138 )
2139 })
2140 .collect::<Box<[_]>>();
2141 let source = super::SnapshotMemory::new(
2142 source_layers.clone(),
2143 super::memory::tests::page_tables_from_bytes(&page_tables),
2144 )
2145 .unwrap();
2146 let managed = SnapshotMemoryBacking::from_snapshot(Arc::new(source)).unwrap();
2147 let scratch = ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap();
2148 let manager = SandboxMemoryManager::new(layout, managed, scratch, super::NextAction::None);
2149 let (mut manager, _) = manager.build().unwrap();
2150 manager
2151 .scratch_mem
2152 .copy_from_slice(&vec![0x55; host_page_size], scratch_offset)
2153 .unwrap();
2154
2155 let result = manager.snapshot(
2156 Vec::new(),
2157 &[pt_base],
2158 0,
2159 default_sregs(),
2160 #[cfg(target_arch = "x86_64")]
2161 Vec::new(),
2162 super::NextAction::None,
2163 HostFunctionDetails::default(),
2164 manager.layout.get_scratch_size(),
2165 );
2166 let error = match result {
2167 Ok(_) => panic!("capture unexpectedly exceeded the layer limit"),
2168 Err(error) => error,
2169 };
2170
2171 assert!(error.to_string().contains("layer count 31 exceeds 30"));
2172 assert_eq!(manager.snapshot_count, 0);
2173 assert!(
2174 manager
2175 .shared_mem
2176 .layers()
2177 .iter()
2178 .zip(&source_layers)
2179 .all(|(layer, source)| Arc::ptr_eq(layer, source))
2180 );
2181 assert_eq!(
2182 manager.scratch_mem.read::<u8>(scratch_offset).unwrap(),
2183 0x55
2184 );
2185 }
2186}