1use flatbuffers::FlatBufferBuilder;
5use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCall;
6use hyperlight_common::flatbuffer_wrappers::function_types::FunctionCallResult;
7use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
8use hyperlight_common::flatbuffer_wrappers::util::estimate_flatbuffer_capacity;
9use hyperlight_common::log_level::GuestLogFilter;
10use hyperlight_common::transport::{Buf, EncodedMessage, ExternalValues, MailboxValue, MsgKind};
11use hyperlight_common::virtq::ReplyChain;
12use hyperlight_common::vmem::{self, PAGE_TABLE_SIZE};
13#[cfg(crashdump)]
14use hyperlight_common::vmem::{BasicMapping, MappingKind};
15use tracing::{Span, instrument};
16
17use super::layout::SandboxMemoryLayout;
18use super::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, HostSharedMemory, SharedMemory};
19use super::virtq::{self, G2hConsumer, H2gConsumer, VirtqSnapshot};
20use crate::hypervisor::regs::CommonSpecialRegisters;
21use crate::mem::memory_region::MemoryRegion;
22#[cfg(crashdump)]
23use crate::mem::memory_region::{CrashDumpRegion, MemoryRegionFlags, MemoryRegionType};
24use crate::sandbox::snapshot::{NextAction, Snapshot, SnapshotMemoryBacking};
25use crate::{HyperlightError, Result, new_error};
26
27#[cfg(crashdump)]
28fn mapping_kind_to_flags(kind: &MappingKind) -> (MemoryRegionFlags, MemoryRegionType) {
29 match kind {
30 MappingKind::Basic(BasicMapping {
31 readable,
32 writable,
33 executable,
34 }) => {
35 let mut flags = MemoryRegionFlags::empty();
36 if *readable {
37 flags |= MemoryRegionFlags::READ;
38 }
39 if *writable {
40 flags |= MemoryRegionFlags::WRITE;
41 }
42 if *executable {
43 flags |= MemoryRegionFlags::EXECUTE;
44 }
45 (flags, MemoryRegionType::Snapshot)
46 }
47 MappingKind::Cow(cow) => {
48 let mut flags = MemoryRegionFlags::empty();
49 if cow.readable {
50 flags |= MemoryRegionFlags::READ;
51 }
52 if cow.executable {
53 flags |= MemoryRegionFlags::EXECUTE;
54 }
55 (flags, MemoryRegionType::Scratch)
56 }
57 MappingKind::Unmapped => (MemoryRegionFlags::empty(), MemoryRegionType::Snapshot),
58 MappingKind::ZeroInit(bm) => {
59 let mut flags = MemoryRegionFlags::empty();
60 if bm.readable {
61 flags |= MemoryRegionFlags::READ;
62 }
63 if bm.writable {
64 flags |= MemoryRegionFlags::WRITE;
65 }
66 if bm.executable {
67 flags |= MemoryRegionFlags::EXECUTE;
68 }
69 (flags, MemoryRegionType::Snapshot)
70 }
71 }
72}
73
74#[cfg(crashdump)]
79fn try_coalesce_region(
80 regions: &mut [CrashDumpRegion],
81 virt_base: usize,
82 virt_end: usize,
83 host_base: usize,
84 flags: MemoryRegionFlags,
85) -> bool {
86 if let Some(last) = regions.last_mut()
87 && last.guest_region.end == virt_base
88 && last.host_region.end == host_base
89 && last.flags == flags
90 {
91 last.guest_region.end = virt_end;
92 last.host_region.end = host_base + (virt_end - virt_base);
93 return true;
94 }
95 false
96}
97
98#[derive(Clone, Copy, Debug, PartialEq, Eq)]
99pub(crate) enum BackingSource {
100 Snapshot(usize),
102 Scratch,
103 Dynamic(usize),
105}
106
107#[derive(Clone, Copy, Debug, PartialEq, Eq)]
109pub(crate) struct GuestBacking {
110 pub(crate) source: BackingSource,
111 pub(crate) offset: usize,
112}
113
114pub(crate) struct GuestPhysicalMemoryView<'a> {
116 snapshot: &'a SnapshotMemoryBacking<HostSharedMemory>,
117 scratch: &'a [u8],
118 dynamic: &'a [MemoryRegion],
119 layout: SandboxMemoryLayout,
120}
121
122impl<'a> GuestPhysicalMemoryView<'a> {
123 pub(crate) fn with_memory<T>(
126 snapshot: &SnapshotMemoryBacking<HostSharedMemory>,
127 scratch: &HostSharedMemory,
128 dynamic: &[MemoryRegion],
129 layout: SandboxMemoryLayout,
130 f: impl FnOnce(&GuestPhysicalMemoryView<'_>) -> Result<T>,
131 ) -> Result<T> {
132 scratch.with_exclusive_contents(|scratch| {
133 f(&GuestPhysicalMemoryView {
134 snapshot,
135 scratch,
136 dynamic,
137 layout,
138 })
139 })?
140 }
141
142 pub(crate) fn snapshot(&self) -> &'a SnapshotMemoryBacking<HostSharedMemory> {
143 self.snapshot
144 }
145
146 pub(crate) fn resolve(&self, gpa: u64, len: usize) -> Option<GuestBacking> {
147 let end = gpa.checked_add(u64::try_from(len).ok()?)?;
148 let scratch_start =
149 hyperlight_common::layout::scratch_base_gpa(self.layout.get_scratch_size());
150 let scratch_end = scratch_start.checked_add(self.layout.get_scratch_size() as u64)?;
151 if scratch_start <= gpa && end <= scratch_end {
152 return Some(GuestBacking {
153 source: BackingSource::Scratch,
154 offset: usize::try_from(gpa - scratch_start).ok()?,
155 });
156 }
157 if let Some((layer_index, offset)) = self.snapshot.resolve(gpa, len) {
158 return Some(GuestBacking {
159 source: BackingSource::Snapshot(layer_index),
160 offset,
161 });
162 }
163 self.dynamic
164 .iter()
165 .enumerate()
166 .find_map(|(region_index, region)| {
167 let start = u64::try_from(region.guest_region.start).ok()?;
168 let region_end = u64::try_from(region.guest_region.end).ok()?;
169 if start <= gpa && end <= region_end {
170 Some(GuestBacking {
171 source: BackingSource::Dynamic(region_index),
172 offset: usize::try_from(gpa - start).ok()?,
173 })
174 } else {
175 None
176 }
177 })
178 }
179
180 pub(crate) fn read(&self, gpa: u64, destination: &mut [u8]) -> Result<GuestBacking> {
181 let backing = self
182 .resolve(gpa, destination.len())
183 .ok_or_else(|| new_error!("GPA range is not backed: {gpa:#x}"))?;
184 self.read_backing(backing, destination)?;
185 Ok(backing)
186 }
187
188 pub(crate) fn read_backing(&self, backing: GuestBacking, destination: &mut [u8]) -> Result<()> {
189 let offset = backing.offset;
190 match backing.source {
191 BackingSource::Snapshot(layer_index) => {
192 self.snapshot
193 .copy_layer_to_slice(layer_index, destination, offset)?
194 }
195 BackingSource::Scratch => {
196 let source = offset
197 .checked_add(destination.len())
198 .and_then(|end| self.scratch.get(offset..end))
199 .ok_or_else(|| new_error!("scratch read range is out of bounds"))?;
200 destination.copy_from_slice(source);
201 }
202 BackingSource::Dynamic(region_index) => {
203 let region = &self.dynamic[region_index];
204 #[allow(clippy::useless_conversion)]
205 let host_start: usize = region.host_region.start.into();
206 #[allow(clippy::useless_conversion)]
207 let host_end: usize = region.host_region.end.into();
208 let source_end = offset
209 .checked_add(destination.len())
210 .ok_or_else(|| new_error!("dynamic memory read range overflows"))?;
211 let host_len = host_end
212 .checked_sub(host_start)
213 .ok_or_else(|| new_error!("dynamic memory host range is invalid"))?;
214 if source_end > host_len {
215 return Err(new_error!("dynamic memory read range is out of bounds"));
216 }
217 let source_start = host_start
218 .checked_add(offset)
219 .ok_or_else(|| new_error!("dynamic memory host address overflows"))?;
220 unsafe {
224 std::ptr::copy(
225 source_start as *const u8,
226 destination.as_mut_ptr(),
227 destination.len(),
228 )
229 };
230 }
231 }
232 Ok(())
233 }
234
235 #[cfg(crashdump)]
236 fn host_range(&self, gpa: u64, len: usize) -> Result<std::ops::Range<usize>> {
237 let backing = self
238 .resolve(gpa, len)
239 .ok_or_else(|| new_error!("GPA range is not backed: {gpa:#x}"))?;
240 let offset = backing.offset;
241 let (base, backing_len) = match backing.source {
242 BackingSource::Snapshot(layer_index) => self.snapshot.host_range(layer_index)?,
243 BackingSource::Scratch => (self.scratch.as_ptr() as usize, self.scratch.len()),
244 BackingSource::Dynamic(region_index) => {
245 let region = &self.dynamic[region_index];
246 #[allow(clippy::useless_conversion)]
247 let start: usize = region.host_region.start.into();
248 #[allow(clippy::useless_conversion)]
249 let end: usize = region.host_region.end.into();
250 (start, end - start)
251 }
252 };
253 let end_offset = offset
254 .checked_add(len)
255 .filter(|end| *end <= backing_len)
256 .ok_or_else(|| new_error!("resolved GPA range is out of bounds"))?;
257 let start = base
258 .checked_add(offset)
259 .ok_or_else(|| new_error!("resolved host address overflows"))?;
260 let end = base
261 .checked_add(end_offset)
262 .ok_or_else(|| new_error!("resolved host address overflows"))?;
263 Ok(start..end)
264 }
265}
266#[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
267pub(crate) struct GuestVirtualMemoryReader<'a> {
268 memory: &'a GuestPhysicalMemoryView<'a>,
269 root_pt: u64,
270 cached_page: Option<(u64, u64)>,
271}
272
273#[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
274impl<'a> GuestVirtualMemoryReader<'a> {
275 fn new(memory: &'a GuestPhysicalMemoryView<'a>, root_pt: u64) -> Self {
276 Self {
277 memory,
278 root_pt,
279 cached_page: None,
280 }
281 }
282
283 fn translate_page(&mut self, page_gva: u64) -> Result<u64> {
284 if let Some((cached_gva, cached_gpa)) = self.cached_page
285 && cached_gva == page_gva
286 {
287 return Ok(cached_gpa);
288 }
289
290 use crate::sandbox::snapshot::PageTableReader;
291
292 let pt_buf = PageTableReader::new(self.memory, self.root_pt);
293 let mapping = unsafe {
296 hyperlight_common::vmem::virt_to_phys(
297 &pt_buf,
298 page_gva,
299 hyperlight_common::vmem::PAGE_SIZE as u64,
300 )
301 }
302 .next();
303 pt_buf.finish()?;
306 let mapping = mapping.ok_or_else(|| new_error!("GVA page is not mapped: {page_gva:#x}"))?;
307 let mapping_offset = page_gva
308 .checked_sub(mapping.virt_base)
309 .ok_or_else(|| new_error!("page-table mapping starts after requested GVA"))?;
310 if mapping
311 .len
312 .checked_sub(mapping_offset)
313 .is_none_or(|len| len < hyperlight_common::vmem::PAGE_SIZE as u64)
314 {
315 return Err(new_error!(
316 "page-table mapping does not cover requested GVA page"
317 ));
318 }
319 let page_gpa = mapping
320 .phys_base
321 .checked_add(mapping_offset)
322 .ok_or_else(|| new_error!("guest physical address overflows"))?;
323 self.cached_page = Some((page_gva, page_gpa));
324 Ok(page_gpa)
325 }
326
327 pub(crate) fn read_exact(&mut self, gva: u64, destination: &mut [u8]) -> Result<()> {
328 gva.checked_add(u64::try_from(destination.len())?)
329 .ok_or_else(|| new_error!("guest virtual address overflows"))?;
330 let mut copied = 0usize;
331 while copied < destination.len() {
332 let current_gva = gva
333 .checked_add(u64::try_from(copied)?)
334 .ok_or_else(|| new_error!("guest virtual address overflows"))?;
335 let page_gva = current_gva / hyperlight_common::vmem::PAGE_SIZE as u64
336 * hyperlight_common::vmem::PAGE_SIZE as u64;
337 let page_offset = usize::try_from(current_gva - page_gva)?;
338 let chunk_len =
339 (destination.len() - copied).min(hyperlight_common::vmem::PAGE_SIZE - page_offset);
340 let gpa = self
341 .translate_page(page_gva)?
342 .checked_add(u64::try_from(page_offset)?)
343 .ok_or_else(|| new_error!("guest physical address overflows"))?;
344 self.memory
345 .read(gpa, &mut destination[copied..copied + chunk_len])?;
346 copied += chunk_len;
347 }
348 Ok(())
349 }
350}
351
352#[derive(Debug, Clone, Copy, PartialEq, Eq)]
354pub(crate) enum ExecutionMode {
355 Unrestricted,
357 Restricted,
359}
360
361const GUEST_REQUEST_OFFSETS: [u64; 2] = [
364 hyperlight_common::layout::SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
365 hyperlight_common::layout::SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
366];
367
368pub(crate) struct SandboxMemoryManager<S: SharedMemory> {
371 pub(crate) shared_mem: SnapshotMemoryBacking<S>,
373 pub(crate) scratch_mem: S,
375 pub(crate) layout: SandboxMemoryLayout,
377 pub(crate) next_action: NextAction,
380 pub(crate) original_entrypoint: u64,
384 pub(crate) abort_buffer: Vec<u8>,
386 pub(crate) execution_mode: ExecutionMode,
388 pub(crate) snapshot_count: u64,
394 pub(crate) g2h_consumer: Option<G2hConsumer>,
396 pub(crate) h2g_consumer: Option<H2gConsumer>,
398 next_guest_cid: u32,
400}
401
402impl<S: Clone + SharedMemory> Clone for SandboxMemoryManager<S> {
403 fn clone(&self) -> Self {
404 Self {
405 shared_mem: self.shared_mem.clone(),
406 scratch_mem: self.scratch_mem.clone(),
407 layout: self.layout,
408 next_action: self.next_action,
409 original_entrypoint: self.original_entrypoint,
410 abort_buffer: self.abort_buffer.clone(),
411 execution_mode: self.execution_mode,
412 snapshot_count: self.snapshot_count,
413 g2h_consumer: None,
414 h2g_consumer: None,
415 next_guest_cid: self.next_guest_cid,
416 }
417 }
418}
419
420pub(crate) struct GuestPageTableBuffer {
424 buffer: std::cell::RefCell<Vec<u8>>,
425 phys_base: usize,
426 root: std::cell::Cell<u64>,
431}
432
433impl vmem::TableReadOps for GuestPageTableBuffer {
434 type TableAddr = u64;
435
436 fn entry_addr(addr: u64, offset: u64) -> u64 {
437 addr + offset
438 }
439
440 unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
441 let buffer = self.buffer.borrow();
442 let byte_offset = addr as usize - self.phys_base;
443 let pte_size = core::mem::size_of::<vmem::PageTableEntry>();
444 let Some(bytes) = buffer.get(byte_offset..byte_offset + pte_size) else {
445 return 0;
446 };
447 let mut buf = [0u8; 8];
448 buf[..pte_size].copy_from_slice(bytes);
449 vmem::PageTableEntry::from_le_bytes(buf[..pte_size].try_into().unwrap_or_default())
450 }
451
452 fn to_phys(addr: u64) -> vmem::PhysAddr {
453 addr as vmem::PhysAddr
454 }
455
456 fn from_phys(addr: vmem::PhysAddr) -> u64 {
457 #[allow(clippy::unnecessary_cast)]
458 {
459 addr as u64
460 }
461 }
462
463 fn root_table(&self) -> u64 {
464 self.root.get()
465 }
466}
467
468impl vmem::TableOps for GuestPageTableBuffer {
469 type TableMovability = vmem::MayNotMoveTable;
470
471 unsafe fn alloc_table(&self) -> u64 {
472 let mut b = self.buffer.borrow_mut();
473 let offset = b.len();
474 b.resize(offset + PAGE_TABLE_SIZE, 0);
475 (self.phys_base + offset) as u64
476 }
477
478 unsafe fn write_entry(&self, addr: u64, entry: vmem::PageTableEntry) -> Option<vmem::Void> {
479 let mut b = self.buffer.borrow_mut();
480 let byte_offset = addr as usize - self.phys_base;
481 let pte_size = core::mem::size_of::<vmem::PageTableEntry>();
482 if let Some(slice) = b.get_mut(byte_offset..byte_offset + pte_size) {
483 slice.copy_from_slice(&entry.to_le_bytes()[..pte_size]);
484 }
485 None
486 }
487
488 unsafe fn update_root(&self, impossible: vmem::Void) {
489 match impossible {}
490 }
491}
492
493impl core::convert::AsRef<GuestPageTableBuffer> for GuestPageTableBuffer {
494 fn as_ref(&self) -> &Self {
495 self
496 }
497}
498
499impl GuestPageTableBuffer {
500 pub(crate) fn new(phys_base: usize) -> Self {
504 GuestPageTableBuffer {
505 buffer: std::cell::RefCell::new(vec![0u8; PAGE_TABLE_SIZE]),
506 phys_base,
507 root: std::cell::Cell::new(phys_base as u64),
508 }
509 }
510
511 pub(crate) fn set_root(&self, addr: u64) {
514 self.root.set(addr);
515 }
516
517 pub(crate) fn initial_root(&self) -> u64 {
519 self.phys_base as u64
520 }
521
522 #[cfg(test)]
523 #[allow(dead_code)]
524 pub(crate) fn size(&self) -> usize {
525 self.buffer.borrow().len()
526 }
527
528 pub(crate) fn into_bytes(self) -> Box<[u8]> {
529 self.buffer.into_inner().into_boxed_slice()
530 }
531}
532
533impl<S> SandboxMemoryManager<S>
534where
535 S: SharedMemory,
536{
537 pub(crate) fn first_free_scratch_gpa(&self) -> u64 {
539 self.layout.get_pt_base_gpa() + self.shared_mem.page_table_len() as u64
540 }
541
542 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
544 pub(crate) fn new(
545 layout: SandboxMemoryLayout,
546 shared_mem: SnapshotMemoryBacking<S>,
547 scratch_mem: S,
548 next_action: NextAction,
549 ) -> Self {
550 Self {
551 layout,
552 shared_mem,
553 scratch_mem,
554 next_action,
555 original_entrypoint: 0,
556 abort_buffer: Vec::new(),
557 execution_mode: ExecutionMode::Unrestricted,
558 snapshot_count: 0,
559 g2h_consumer: None,
560 h2g_consumer: None,
561 next_guest_cid: 1,
562 }
563 }
564
565 pub(crate) fn get_abort_buffer_mut(&mut self) -> &mut Vec<u8> {
567 &mut self.abort_buffer
568 }
569}
570
571impl SandboxMemoryManager<ExclusiveSharedMemory> {
572 pub(crate) fn from_snapshot(s: &Snapshot) -> Result<Self> {
573 let layout = *s.layout();
574 let shared_mem = SnapshotMemoryBacking::from_snapshot(s.snapshot_memory().clone())?;
575 let scratch_mem = ExclusiveSharedMemory::new(s.layout().get_scratch_size())?;
576 let next_action = s.next_action();
577 let mut mgr = Self::new(layout, shared_mem, scratch_mem, next_action);
578 mgr.original_entrypoint = s.original_entrypoint();
579 mgr.snapshot_count = s.snapshot_generation();
584 Ok(mgr)
585 }
586
587 pub fn build(
598 self,
599 ) -> Result<(
600 SandboxMemoryManager<HostSharedMemory>,
601 SandboxMemoryManager<GuestSharedMemory>,
602 )> {
603 let (hshm, gshm) = self.shared_mem.build();
604 let (hscratch, gscratch) = self.scratch_mem.build();
605 let mut host_mgr = SandboxMemoryManager {
606 shared_mem: hshm,
607 scratch_mem: hscratch,
608 layout: self.layout,
609 next_action: self.next_action,
610 original_entrypoint: self.original_entrypoint,
611 abort_buffer: self.abort_buffer,
612 execution_mode: self.execution_mode,
613 snapshot_count: self.snapshot_count,
614 g2h_consumer: None,
615 h2g_consumer: None,
616 next_guest_cid: self.next_guest_cid,
617 };
618 let guest_mgr = SandboxMemoryManager {
619 shared_mem: gshm,
620 scratch_mem: gscratch,
621 layout: self.layout,
622 next_action: self.next_action,
623 original_entrypoint: self.original_entrypoint,
624 abort_buffer: Vec::new(), execution_mode: self.execution_mode,
626 snapshot_count: self.snapshot_count,
627 g2h_consumer: None,
628 h2g_consumer: None,
629 next_guest_cid: self.next_guest_cid,
630 };
631 host_mgr.update_scratch_bookkeeping()?;
632
633 if matches!(host_mgr.next_action, NextAction::Initialise(_)) {
634 let cp = MailboxValue::CheckpointPending.as_bytes();
635 let mbx = host_mgr.layout.mbx_scratch_offset();
636
637 host_mgr.scratch_mem.copy_from_slice(cp, mbx)?;
638 host_mgr.create_virtq_consumers()?;
639 }
640
641 Ok((host_mgr, guest_mgr))
642 }
643}
644
645impl SandboxMemoryManager<HostSharedMemory> {
646 pub(crate) fn with_guest_memory<T>(
648 &self,
649 dynamic: &[MemoryRegion],
650 f: impl FnOnce(&GuestPhysicalMemoryView<'_>) -> Result<T>,
651 ) -> Result<T> {
652 GuestPhysicalMemoryView::with_memory(
653 &self.shared_mem,
654 &self.scratch_mem,
655 dynamic,
656 self.layout,
657 f,
658 )
659 }
660
661 #[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
662 pub(crate) fn with_guest_virtual_memory_reader<T>(
663 &self,
664 root_pt: u64,
665 f: impl FnOnce(&mut GuestVirtualMemoryReader<'_>) -> Result<T>,
666 ) -> Result<T> {
667 self.with_guest_memory(&[], |memory| {
668 f(&mut GuestVirtualMemoryReader::new(memory, root_pt))
669 })
670 }
671
672 #[allow(clippy::too_many_arguments)]
674 pub(crate) fn snapshot(
675 &mut self,
676 mapped_regions: Vec<MemoryRegion>,
677 root_pt_gpas: &[u64],
678 rsp_gva: u64,
679 sregs: CommonSpecialRegisters,
680 #[cfg(target_arch = "x86_64")] msrs: Vec<crate::hypervisor::regs::MsrEntry>,
681 next_action: NextAction,
682 host_functions: HostFunctionDetails,
683 scratch_size: usize,
684 ) -> Result<Snapshot> {
685 let virtq = match (&self.g2h_consumer, &self.h2g_consumer) {
686 (Some(_), Some(_)) => Some(VirtqSnapshot::capture(&self.layout, &self.scratch_mem)?),
687 (None, None) => None,
688 _ => return Err(new_error!("virtqueue consumer ownership is incomplete")),
689 };
690
691 let layout = self.layout;
692 let original_entrypoint = self.original_entrypoint;
693 let snapshot_generation = self.snapshot_count + 1;
694 let snapshot = self.with_guest_memory(&mapped_regions, |memory| {
695 Snapshot::new(
696 memory,
697 layout,
698 crate::mem::exe::LoadInfo::dummy(),
699 root_pt_gpas,
700 rsp_gva,
701 sregs,
702 #[cfg(target_arch = "x86_64")]
703 msrs,
704 next_action,
705 original_entrypoint,
706 snapshot_generation,
707 host_functions,
708 virtq,
709 scratch_size,
710 )
711 })?;
712 self.snapshot_count = snapshot.snapshot_generation();
713 Ok(snapshot)
714 }
715
716 fn create_virtq_consumers(&mut self) -> Result<()> {
721 if self.g2h_consumer.is_some() || self.h2g_consumer.is_some() {
722 return Err(new_error!("virtqueue consumers already exist"));
723 }
724
725 let (g2h, h2g) = virtq::create_consumers(&self.layout, &self.scratch_mem)?;
726 self.g2h_consumer = Some(g2h);
727 self.h2g_consumer = Some(h2g);
728 Ok(())
729 }
730
731 pub(crate) fn restore_virtq(&mut self, snapshot: &VirtqSnapshot) -> Result<()> {
733 if self.g2h_consumer.is_some() || self.h2g_consumer.is_some() {
734 return Err(new_error!("virtqueue consumers are already attached"));
735 }
736
737 let (g2h, h2g) = snapshot.restore(&self.layout, &self.scratch_mem)?;
738 self.g2h_consumer = Some(g2h);
739 self.h2g_consumer = Some(h2g);
740 Ok(())
741 }
742
743 #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
745 pub(crate) fn write_guest_function_call(&mut self, call: &FunctionCall) -> Result<u32> {
746 let cid = self.next_guest_cid;
747 let params = call.parameters.as_deref().unwrap_or_default();
748 let cap = estimate_flatbuffer_capacity(&call.function_name, params);
749
750 let mut builder = FlatBufferBuilder::with_capacity(cap);
751 let mut externals = ExternalValues::new();
752
753 let control = call.encode(&mut builder, &mut externals)?;
754
755 let Some(msg) = EncodedMessage::new(MsgKind::Request, cid, control, externals) else {
756 return Err(new_error!("H2G request exceeds the wire payload limit"));
757 };
758
759 self.write_h2g_message(&msg)?;
760
761 self.next_guest_cid = cid.wrapping_add(1);
762 if self.next_guest_cid == 0 {
763 self.next_guest_cid = 1;
764 }
765
766 Ok(cid)
767 }
768
769 fn write_h2g_message(&mut self, message: &EncodedMessage<'_>) -> Result<()> {
770 let consumer = self.h2g_consumer.as_mut().ok_or_else(|| {
771 HyperlightError::TransportError("H2G consumer is not attached".into())
772 })?;
773
774 let buffer_size = self.layout.get_h2g_buffer_size();
775 let buffer_count = message.total_len().div_ceil(buffer_size);
776
777 let control_reserve = usize::from(message.external_len() != 0);
779
780 let maybe_buffers = consumer
782 .poll_batch(buffer_count, control_reserve, 0)
783 .map_err(|error| {
784 HyperlightError::TransportError(format!("H2G poll failed: {error}"))
785 })?;
786
787 let Some(buffers) = maybe_buffers else {
788 return Err(new_error!(
789 "H2G capacity cannot provide {buffer_count} buffers with {control_reserve} spare"
790 ));
791 };
792
793 let mut message = message.as_buf();
797
798 for (recv, reply) in buffers {
799 let ReplyChain::Writable(mut buffer) = reply else {
800 return Err(HyperlightError::TransportError(
801 "H2G receive buffer is not writable".into(),
802 ));
803 };
804
805 if buffer.desc_count() != 1 || buffer.capacity() != buffer_size {
806 return Err(HyperlightError::TransportError(
807 "H2G receive buffer has an invalid shape".into(),
808 ));
809 }
810
811 while message.has_remaining() && buffer.remaining() != 0 {
812 let written = buffer.write(message.chunk()).map_err(|err| {
813 HyperlightError::TransportError(format!("H2G write failed: {err}"))
814 })?;
815
816 message.advance(written);
817 }
818
819 consumer.complete(recv, buffer).map_err(|err| {
820 HyperlightError::TransportError(format!("H2G completion failed: {err}"))
821 })?;
822 }
823
824 debug_assert!(!message.has_remaining());
825 Ok(())
826 }
827
828 #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
830 pub(crate) fn read_h2g_result_from_g2h(&mut self, cid: u32) -> Result<FunctionCallResult> {
831 let max_recv_len = self.layout.get_g2h_queue_dims().pool_len();
832
833 let Some(consumer) = self.g2h_consumer.as_mut() else {
834 return Err(HyperlightError::TransportError(
835 "G2H consumer is not attached".into(),
836 ));
837 };
838
839 loop {
840 let maybe_next = consumer.poll(max_recv_len).map_err(|err| {
841 HyperlightError::TransportError(format!("G2H poll failed: {err}"))
842 })?;
843
844 let Some((mut recv, reply)) = maybe_next else {
845 return Err(HyperlightError::TransportError(
846 "G2H has no guest function result after halt".into(),
847 ));
848 };
849
850 let header = virtq::read_message_header(&mut recv).map_err(|err| {
851 HyperlightError::TransportError(format!("Failed to read G2H result header: {err}"))
852 })?;
853
854 if !matches!(&reply, ReplyChain::Ack(_)) {
855 return Err(HyperlightError::TransportError(
856 "G2H result entry has writable buffers".into(),
857 ));
858 }
859
860 match header.kind {
861 MsgKind::Log => {
862 if header.cid != 0 {
863 return Err(HyperlightError::TransportError(
864 "G2H log has a correlation ID".into(),
865 ));
866 }
867
868 let log = virtq::read_guest_log_data(&mut recv).map_err(|err| {
869 HyperlightError::TransportError(format!("Failed to read G2H log: {err}"))
870 })?;
871
872 consumer.complete(recv, reply).map_err(|err| {
873 HyperlightError::TransportError(format!(
874 "Failed to complete G2H log: {err}"
875 ))
876 })?;
877
878 crate::sandbox::outb::emit_guest_log(&log);
879 }
880 MsgKind::Response => {
881 if header.cid != cid {
882 return Err(HyperlightError::TransportError(
883 "G2H guest function result correlation ID mismatch".into(),
884 ));
885 }
886
887 let result = virtq::read_guest_function_call_result(&mut recv);
888 consumer.complete(recv, reply).map_err(|err| {
889 HyperlightError::TransportError(format!(
890 "Failed to complete G2H guest function result: {err}"
891 ))
892 })?;
893
894 return result.map_err(|err| {
895 HyperlightError::TransportError(format!(
896 "Failed to decode G2H guest function result: {err}"
897 ))
898 });
899 }
900 kind => {
901 return Err(HyperlightError::TransportError(format!(
902 "Expected G2H guest function result, got {kind:?}"
903 )));
904 }
905 }
906 }
907 }
908
909 pub(crate) fn begin_snapshot_checkpoint(&mut self) -> Result<()> {
913 let offset = self.layout.mbx_scratch_offset();
914 let cp = MailboxValue::CheckpointPending.as_bytes();
915 self.scratch_mem.copy_from_slice(cp, offset)?;
916
917 let message = EncodedMessage::new_snapshot_cp();
918 self.write_h2g_message(&message)
919 }
920
921 pub(crate) fn finish_snapshot_checkpoint(&mut self) -> Result<()> {
923 let Some(g2h) = self.g2h_consumer.as_mut() else {
924 return Err(new_error!("G2H consumer is not attached"));
925 };
926
927 let Some(h2g) = self.h2g_consumer.as_mut() else {
928 return Err(new_error!("H2G consumer is not attached"));
929 };
930
931 g2h.reset()?;
932 h2g.reset()?;
933
934 let status = self
935 .scratch_mem
936 .read::<u64>(self.layout.mbx_scratch_offset())
937 .map_err(|error| HyperlightError::TransportError(error.to_string()))?;
938
939 match MailboxValue::try_from(status) {
940 Ok(MailboxValue::CheckpointComplete) => Ok(()),
941 Ok(MailboxValue::CheckpointPending) => Err(HyperlightError::TransportError(
942 "Guest did not publish snapshot checkpoint status".into(),
943 )),
944 Err(_) => Err(HyperlightError::TransportError(format!(
945 "Guest published invalid snapshot checkpoint status {status:#x}"
946 ))),
947 }
948 }
949
950 fn replace_snapshot_memory(
951 &mut self,
952 snapshot: &Snapshot,
953 ) -> Result<SnapshotMemoryBacking<GuestSharedMemory>> {
954 let new_snapshot_mem =
955 SnapshotMemoryBacking::from_snapshot(snapshot.snapshot_memory().clone())?;
956 let (hsnapshot, gsnapshot) = new_snapshot_mem.build();
957 self.shared_mem = hsnapshot;
958 Ok(gsnapshot)
959 }
960
961 fn apply_snapshot_metadata(&mut self, snapshot: &Snapshot) {
962 self.layout = *snapshot.layout();
963 self.snapshot_count = snapshot.snapshot_generation();
968 self.original_entrypoint = snapshot.original_entrypoint();
971 }
972
973 pub(crate) fn install_captured_snapshot(
978 &mut self,
979 snapshot: &Snapshot,
980 ) -> Result<(
981 SnapshotMemoryBacking<GuestSharedMemory>,
982 Option<GuestSharedMemory>,
983 )> {
984 if snapshot.layout().get_scratch_size() != self.scratch_mem.mem_size() {
985 let requests = self.guest_requests()?;
986 let memory = self.restore_snapshot(snapshot)?;
987 self.set_guest_requests(requests)?;
988 return Ok(memory);
989 }
990 let used_scratch_end = self.used_scratch_end_gpa()?;
991 let gsnapshot = self.replace_snapshot_memory(snapshot)?;
992 self.apply_snapshot_metadata(snapshot);
993 self.update_snapshot_scratch_bookkeeping()?;
994 self.zero_freed_scratch(used_scratch_end)?;
995 Ok((gsnapshot, None))
996 }
997
998 fn used_scratch_end_gpa(&self) -> Result<u64> {
1002 let offset = self.scratch_mem.mem_size()
1003 - hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
1004 let end = self.scratch_mem.read::<u64>(offset)?;
1005 Ok(end.min(self.layout.get_transport_arena().base_addr()))
1006 }
1007
1008 pub(crate) fn scratch_allocated_bytes(&self) -> Result<u64> {
1011 Ok(self
1012 .used_scratch_end_gpa()?
1013 .saturating_sub(self.first_free_scratch_gpa()))
1014 }
1015
1016 fn zero_freed_scratch(&mut self, end: u64) -> Result<()> {
1019 let scratch_base = hyperlight_common::layout::scratch_base_gpa(self.scratch_mem.mem_size());
1020 let start = self.first_free_scratch_gpa();
1021 if end <= start {
1022 return Ok(());
1023 }
1024 let start = usize::try_from(start - scratch_base)?;
1025 let end = usize::try_from(end - scratch_base)?;
1026 self.scratch_mem
1027 .with_exclusivity(|scratch| scratch.as_mut_slice()[start..end].fill(0))?;
1028 Ok(())
1029 }
1030
1031 pub(crate) fn restore_snapshot(
1033 &mut self,
1034 snapshot: &Snapshot,
1035 ) -> Result<(
1036 SnapshotMemoryBacking<GuestSharedMemory>,
1037 Option<GuestSharedMemory>,
1038 )> {
1039 let virtq = snapshot.virtq();
1040
1041 if virtq.is_none() && matches!(snapshot.next_action(), NextAction::Call(_)) {
1042 return Err(new_error!(
1043 "running snapshot has no canonical transport state"
1044 ));
1045 }
1046
1047 self.g2h_consumer = None;
1048 self.h2g_consumer = None;
1049 self.execution_mode = ExecutionMode::Unrestricted;
1050
1051 self.execution_mode = ExecutionMode::Unrestricted;
1053
1054 let gsnapshot = self.replace_snapshot_memory(snapshot)?;
1055 let new_scratch_size = snapshot.layout().get_scratch_size();
1056 let gscratch = if new_scratch_size == self.scratch_mem.mem_size() {
1057 self.scratch_mem.zero_or_replace()?
1060 } else {
1061 let new_scratch_mem = ExclusiveSharedMemory::new(new_scratch_size)?;
1062 let (hscratch, gscratch) = new_scratch_mem.build();
1063 self.scratch_mem = hscratch;
1069 Some(gscratch)
1070 };
1071 self.apply_snapshot_metadata(snapshot);
1072 self.update_scratch_bookkeeping()?;
1073 if let Some(virtq) = virtq {
1074 self.restore_virtq(virtq)?;
1075 } else if matches!(snapshot.next_action(), NextAction::Initialise(_)) {
1076 self.scratch_mem.copy_from_slice(
1077 MailboxValue::CheckpointPending.as_bytes(),
1078 self.layout.mbx_scratch_offset(),
1079 )?;
1080 self.create_virtq_consumers()?;
1081 }
1082 Ok((gsnapshot, gscratch))
1083 }
1084
1085 #[inline]
1086 fn update_scratch_bookkeeping_item(&mut self, offset: u64, value: u64) -> Result<()> {
1087 let scratch_size = self.scratch_mem.mem_size();
1088 let base_offset = scratch_size - offset as usize;
1089 self.scratch_mem
1090 .write::<u64>(base_offset, value)
1091 .map_err(From::from)
1092 }
1093
1094 fn guest_requests(&self) -> Result<[u64; 2]> {
1095 let scratch_size = self.scratch_mem.mem_size();
1096 let mut values = [0; 2];
1097 for (value, offset) in values.iter_mut().zip(GUEST_REQUEST_OFFSETS) {
1098 *value = self
1099 .scratch_mem
1100 .read::<u64>(scratch_size - offset as usize)?;
1101 }
1102 Ok(values)
1103 }
1104
1105 fn set_guest_requests(&mut self, values: [u64; 2]) -> Result<()> {
1106 for (value, offset) in values.into_iter().zip(GUEST_REQUEST_OFFSETS) {
1107 self.update_scratch_bookkeeping_item(offset, value)?;
1108 }
1109 Ok(())
1110 }
1111
1112 pub(crate) fn request_libc_rng_reseed(&mut self, seed: u32) -> Result<()> {
1113 self.update_scratch_bookkeeping_item(
1116 hyperlight_common::layout::SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
1117 (1_u64 << 32) | u64::from(seed),
1118 )
1119 }
1120
1121 pub(crate) fn request_guest_log_level_update(
1122 &mut self,
1123 log_level: tracing_core::LevelFilter,
1124 ) -> Result<()> {
1125 self.update_scratch_bookkeeping_item(
1126 hyperlight_common::layout::SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
1127 (hyperlight_common::log_level::GUEST_LOG_FILTER_UPDATE_PENDING)
1128 | u64::from(GuestLogFilter::from(log_level)),
1129 )
1130 }
1131
1132 fn update_scratch_bookkeeping(&mut self) -> Result<()> {
1133 use hyperlight_common::layout::*;
1134 let scratch_size = self.scratch_mem.mem_size();
1135 self.update_scratch_bookkeeping_item(SCRATCH_TOP_SIZE_OFFSET, scratch_size as u64)?;
1136 self.update_snapshot_scratch_bookkeeping()?;
1137
1138 Ok(())
1139 }
1140
1141 fn update_snapshot_scratch_bookkeeping(&mut self) -> Result<()> {
1142 use hyperlight_common::layout::*;
1143 self.update_scratch_bookkeeping_item(
1144 SCRATCH_TOP_ALLOCATOR_OFFSET,
1145 self.first_free_scratch_gpa(),
1146 )?;
1147 self.update_scratch_bookkeeping_item(
1156 SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET,
1157 self.layout.get_pt_base_gpa(),
1158 )?;
1159 self.update_scratch_bookkeeping_item(
1160 SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET,
1161 self.snapshot_count,
1162 )?;
1163 self.update_scratch_bookkeeping_item(
1164 SCRATCH_TOP_HEAP_EXECUTABLE_OFFSET,
1165 cfg!(feature = "executable_heap") as u64,
1166 )?;
1167 self.update_scratch_bookkeeping_item(
1169 SCRATCH_TOP_G2H_QUEUE_SIZE_OFFSET,
1170 u64::try_from(self.layout.get_g2h_queue_size())?,
1171 )?;
1172 self.update_scratch_bookkeeping_item(
1173 SCRATCH_TOP_G2H_POOL_PAGES_OFFSET,
1174 u64::try_from(self.layout.get_g2h_pool_pages())?,
1175 )?;
1176 self.update_scratch_bookkeeping_item(
1177 SCRATCH_TOP_G2H_BUFFER_SIZE_OFFSET,
1178 u64::try_from(self.layout.get_g2h_buffer_size())?,
1179 )?;
1180 self.update_scratch_bookkeeping_item(
1181 SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET,
1182 u64::try_from(self.layout.get_h2g_queue_size())?,
1183 )?;
1184 self.update_scratch_bookkeeping_item(
1185 SCRATCH_TOP_H2G_POOL_PAGES_OFFSET,
1186 u64::try_from(self.layout.get_h2g_pool_pages())?,
1187 )?;
1188 self.update_scratch_bookkeeping_item(
1189 SCRATCH_TOP_H2G_BUFFER_SIZE_OFFSET,
1190 u64::try_from(self.layout.get_h2g_buffer_size())?,
1191 )?;
1192
1193 let transport_arena = self.layout.get_transport_arena();
1194 self.update_scratch_bookkeeping_item(
1195 SCRATCH_TOP_TRANSPORT_ARENA_GPA_OFFSET,
1196 transport_arena.base_addr(),
1197 )?;
1198
1199 let page_tables = self.shared_mem.page_table_bytes();
1206 let offset = self.layout.get_pt_base_scratch_offset();
1207 self.scratch_mem
1208 .with_exclusivity(|scratch| scratch.copy_from_slice(page_tables, offset))??;
1209
1210 Ok(())
1211 }
1212
1213 #[cfg(crashdump)]
1218 pub(crate) fn get_guest_memory_regions(
1219 &mut self,
1220 root_pt: u64,
1221 mmap_regions: &[MemoryRegion],
1222 ) -> Result<Vec<CrashDumpRegion>> {
1223 use crate::sandbox::snapshot::PageTableReader;
1224
1225 let len = hyperlight_common::layout::SCRATCH_TOP_GVA;
1226 self.with_guest_memory(mmap_regions, |memory| {
1227 let pt_buf = PageTableReader::new(memory, root_pt);
1228 let mut regions: Vec<CrashDumpRegion> = Vec::new();
1229 let mut saw_mapping = false;
1230 for mapping in unsafe { hyperlight_common::vmem::virt_to_phys(&pt_buf, 0, len as u64) }
1233 {
1234 saw_mapping = true;
1235 let (flags, region_type) = mapping_kind_to_flags(&mapping.kind);
1236 let mut mapped = 0usize;
1237 let mapping_len = usize::try_from(mapping.len)?;
1238 while mapped < mapping_len {
1239 let chunk_len = (mapping_len - mapped).min(hyperlight_common::vmem::PAGE_SIZE);
1240 let gpa = mapping
1241 .phys_base
1242 .checked_add(u64::try_from(mapped)?)
1243 .ok_or_else(|| new_error!("crash-dump GPA overflows"))?;
1244 let Some(host_region) = memory.host_range(gpa, chunk_len).ok() else {
1245 mapped += chunk_len;
1246 continue;
1247 };
1248 let virt_base = usize::try_from(mapping.virt_base)?
1249 .checked_add(mapped)
1250 .ok_or_else(|| new_error!("crash-dump GVA overflows"))?;
1251 let virt_end = virt_base
1252 .checked_add(chunk_len)
1253 .ok_or_else(|| new_error!("crash-dump GVA range overflows"))?;
1254
1255 if !try_coalesce_region(
1256 &mut regions,
1257 virt_base,
1258 virt_end,
1259 host_region.start,
1260 flags,
1261 ) {
1262 regions.push(CrashDumpRegion {
1263 guest_region: virt_base..virt_end,
1264 host_region,
1265 flags,
1266 region_type,
1267 });
1268 }
1269 mapped += chunk_len;
1270 }
1271 }
1272 if !saw_mapping {
1273 return Err(new_error!("No page table mappings found (len {len})",));
1274 }
1275
1276 Ok(regions)
1277 })
1278 }
1279
1280 #[cfg(feature = "trace_guest")]
1293 pub(crate) fn read_guest_memory_by_gva(
1294 &self,
1295 gva: u64,
1296 len: usize,
1297 root_pt: u64,
1298 ) -> Result<Vec<u8>> {
1299 let mut result = vec![0; len];
1300 self.with_guest_virtual_memory_reader(root_pt, |reader| {
1301 reader.read_exact(gva, &mut result)
1302 })?;
1303 Ok(result)
1304 }
1305}
1306
1307#[cfg(test)]
1308mod tests {
1309 use std::sync::Arc;
1310
1311 use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCallType;
1312 use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterValue, ReturnType};
1313 use hyperlight_common::transport::{
1314 MsgHeader, SIZE_PREFIX_LEN, size_prefix_payload_len, size_prefixed_len,
1315 };
1316 use hyperlight_common::virtq::DescFlags;
1317 use hyperlight_common::vmem::{self, BasicMapping, Mapping, MappingKind, PAGE_SIZE};
1318 #[cfg(target_arch = "x86_64")]
1319 use hyperlight_testing::sandbox_sizes::{
1320 LARGE_SCRATCH_SIZE, MEDIUM_SCRATCH_SIZE, SMALL_SCRATCH_SIZE,
1321 };
1322 #[cfg(target_arch = "x86_64")]
1323 use hyperlight_testing::simple_guest_as_pathbuf;
1324
1325 use super::*;
1326 #[cfg(target_arch = "x86_64")]
1327 use crate::GuestBinary;
1328 use crate::mem::layout::SandboxMemoryLayout;
1329 use crate::mem::memory_region::MemoryRegionType;
1330 use crate::mem::shared_mem::{ExclusiveSharedMemory, ReadonlySharedMemory};
1331 use crate::mem::virtq::tests::{H2G_BUFFER_SIZE, SCRATCH_SIZE, TestCase, memory_layout};
1332 use crate::sandbox::SandboxConfiguration;
1333 #[cfg(target_arch = "x86_64")]
1334 use crate::sandbox::snapshot::Snapshot;
1335 use crate::sandbox::snapshot::memory::tests::flat_memory;
1336 use crate::sandbox::snapshot::{SnapshotBlob, SnapshotMemory};
1337
1338 fn manager(case: &TestCase) -> SandboxMemoryManager<HostSharedMemory> {
1339 let host_page_size = page_size::get();
1340 let layout = memory_layout();
1341 let snapshot = Arc::new(flat_memory(
1342 &vec![0; host_page_size],
1343 &[0; PAGE_SIZE],
1344 SandboxMemoryLayout::BASE_ADDRESS as u64,
1345 hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
1346 ));
1347
1348 let mut mgr = SandboxMemoryManager::new(
1349 layout,
1350 SnapshotMemoryBacking::from_snapshot(snapshot)
1351 .unwrap()
1352 .build()
1353 .0,
1354 case.scratch.clone(),
1355 NextAction::None,
1356 );
1357
1358 mgr.h2g_consumer = Some(case.h2g_consumer());
1359 mgr
1360 }
1361
1362 fn h2g_call(bytes: usize) -> FunctionCall {
1363 let params = (bytes != 0).then(|| vec![ParameterValue::VecBytes(vec![0xa5; bytes])]);
1364 FunctionCall::new(
1365 "call".to_string(),
1366 params,
1367 FunctionCallType::Guest,
1368 ReturnType::Void,
1369 )
1370 }
1371
1372 #[test]
1373 fn rejects_invalid_h2g_descriptors() {
1374 for (len, expected) in [
1375 (H2G_BUFFER_SIZE as u32, "Payload data too large"),
1376 (0, "not writable"),
1377 ] {
1378 let case = TestCase::new();
1379 let mut mgr = manager(&case);
1380 let mut desc = case.h2g_desc(0);
1381
1382 desc.flags &= !DescFlags::WRITE.bits();
1383 desc.len = len;
1384 case.set_h2g_desc(0, desc);
1385
1386 let error = mgr.write_guest_function_call(&h2g_call(0)).unwrap_err();
1387
1388 assert!(error.to_string().contains(expected), "{error:#}");
1389 assert!(error.is_poison_error());
1390 assert!(matches!(error, HyperlightError::TransportError(_)));
1391 }
1392 }
1393
1394 #[test]
1395 fn partial_h2g_write_is_fatal() {
1396 let case = TestCase::new();
1397 let mut mgr = manager(&case);
1398 let mut desc = case.h2g_desc(1);
1399
1400 desc.addr = hyperlight_common::layout::scratch_base_gva(SCRATCH_SIZE) + SCRATCH_SIZE as u64;
1401 case.set_h2g_desc(1, desc);
1402
1403 let error = mgr
1404 .write_guest_function_call(&h2g_call(H2G_BUFFER_SIZE + 1024))
1405 .unwrap_err();
1406
1407 assert!(error.to_string().contains("Memory write"), "{error:#}");
1408 assert!(error.is_poison_error());
1409 assert!(matches!(error, HyperlightError::TransportError(_)));
1410 assert_eq!(mgr.h2g_consumer.as_ref().unwrap().used_cursor().head(), 1);
1411 }
1412
1413 #[test]
1414 fn insufficient_h2g_capacity_rolls_back() {
1415 let case = TestCase::new();
1416 let mut mgr = manager(&case);
1417 let cursor = mgr.h2g_consumer.as_ref().unwrap().avail_cursor();
1418
1419 let error = mgr
1420 .write_guest_function_call(&h2g_call(H2G_BUFFER_SIZE * 4))
1421 .unwrap_err();
1422
1423 assert!(error.to_string().contains("H2G capacity"), "{error:#}");
1424 assert!(!error.is_poison_error());
1425 assert_eq!(mgr.h2g_consumer.as_ref().unwrap().avail_cursor(), cursor);
1426 assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
1427 }
1428
1429 #[test]
1430 fn missing_g2h_result_is_fatal() {
1431 let case = TestCase::new();
1432 let mut mgr = manager(&case);
1433 mgr.g2h_consumer = Some(case.g2h_consumer());
1434
1435 let Err(error) = mgr.read_h2g_result_from_g2h(1) else {
1436 panic!("expected missing G2H result");
1437 };
1438
1439 assert!(
1440 error
1441 .to_string()
1442 .contains("G2H has no guest function result")
1443 );
1444 assert!(error.is_poison_error());
1445 assert!(matches!(error, HyperlightError::TransportError(_)));
1446 }
1447
1448 #[test]
1449 fn writes_dense_h2g_request_and_reserves_control_buffer() {
1450 let case = TestCase::new();
1451 let mut mgr = manager(&case);
1452 let external_len = H2G_BUFFER_SIZE * 2;
1453 let buffers: Vec<_> = (0..4).map(|index| case.h2g_desc(index).addr).collect();
1454
1455 let cid = mgr
1456 .write_guest_function_call(&h2g_call(external_len))
1457 .unwrap();
1458
1459 let used = mgr.h2g_consumer.as_ref().unwrap().avail_cursor().head();
1460 let wire: Vec<u8> = (0..used)
1461 .flat_map(|index| case.h2g_buffer(index, buffers[index as usize]))
1462 .collect();
1463
1464 let header = MsgHeader::from_bytes(&wire[..MsgHeader::SIZE]).unwrap();
1465 assert_eq!(header.kind, MsgKind::Request);
1466 assert_eq!(header.cid, cid);
1467 assert_eq!(header.payload_len as usize, wire.len() - MsgHeader::SIZE);
1468
1469 let control =
1470 size_prefix_payload_len(&wire[MsgHeader::SIZE..MsgHeader::SIZE + SIZE_PREFIX_LEN])
1471 .unwrap();
1472
1473 let control_len = size_prefixed_len(control).unwrap();
1474 let external = &wire[MsgHeader::SIZE + control_len..];
1475 assert_eq!(external, vec![0xa5; external_len]);
1476
1477 let cursor = mgr.h2g_consumer.as_ref().unwrap().avail_cursor();
1478 let error = mgr.write_guest_function_call(&h2g_call(1)).unwrap_err();
1479
1480 assert!(error.to_string().contains("H2G capacity"), "{error:#}");
1481 assert_eq!(mgr.h2g_consumer.as_ref().unwrap().avail_cursor(), cursor);
1482 assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 2);
1483 }
1484
1485 #[test]
1486 fn writes_header_only_snapshot_checkpoint() {
1487 let case = TestCase::new();
1488 let mut mgr = manager(&case);
1489 let buffer = case.h2g_desc(0).addr;
1490
1491 let mbx = mgr.layout.mbx_scratch_offset();
1492 let cp = MailboxValue::CheckpointComplete.as_bytes();
1493
1494 mgr.scratch_mem.copy_from_slice(cp, mbx).unwrap();
1495 mgr.begin_snapshot_checkpoint().unwrap();
1496
1497 let wire = case.h2g_buffer(0, buffer);
1498 let header = MsgHeader::from_bytes(&wire).unwrap();
1499
1500 assert_eq!(wire.len(), MsgHeader::SIZE);
1501 assert_eq!(header.kind, MsgKind::SnapshotCheckpoint);
1502 assert_eq!(header.cid, 0);
1503 assert_eq!(header.payload_len, 0);
1504 assert_eq!(mgr.next_guest_cid, 1);
1505
1506 assert_eq!(
1507 MailboxValue::try_from(mgr.scratch_mem.read::<u64>(mbx).unwrap()).unwrap(),
1508 MailboxValue::CheckpointPending
1509 );
1510 }
1511
1512 #[test]
1513 fn incomplete_snapshot_checkpoint_is_fatal() {
1514 let case = TestCase::new();
1515 let mut mgr = manager(&case);
1516 mgr.g2h_consumer = Some(case.g2h_consumer());
1517 mgr.begin_snapshot_checkpoint().unwrap();
1518
1519 let error = mgr.finish_snapshot_checkpoint().unwrap_err();
1520
1521 assert!(matches!(error, HyperlightError::TransportError(_)));
1522 assert!(error.is_poison_error());
1523 }
1524
1525 #[test]
1526 fn reads_completed_snapshot_checkpoint_status() {
1527 let case = TestCase::new();
1528 let mut mgr = manager(&case);
1529 mgr.g2h_consumer = Some(case.g2h_consumer());
1530 mgr.begin_snapshot_checkpoint().unwrap();
1531 let mbx = mgr.layout.mbx_scratch_offset();
1532 mgr.scratch_mem
1533 .copy_from_slice(MailboxValue::CheckpointComplete.as_bytes(), mbx)
1534 .unwrap();
1535
1536 mgr.finish_snapshot_checkpoint().unwrap();
1537 let consumer = mgr.h2g_consumer.as_ref().unwrap();
1538 assert_eq!(consumer.avail_cursor().head(), 0);
1539 assert_eq!(consumer.used_cursor().head(), 0);
1540 }
1541
1542 #[test]
1543 fn invalid_checkpoint_status_is_fatal() {
1544 for status in [2, 3, 0xa000, u64::MAX - 1, u64::MAX] {
1545 let queue = TestCase::new();
1546 let mut mgr = manager(&queue);
1547 mgr.g2h_consumer = Some(queue.g2h_consumer());
1548 let mbx = mgr.layout.mbx_scratch_offset();
1549 mgr.scratch_mem.write::<u64>(mbx, status).unwrap();
1550 let error = mgr.finish_snapshot_checkpoint().unwrap_err();
1551
1552 assert!(matches!(error, HyperlightError::TransportError(_)));
1553 assert!(error.is_poison_error(), "{error}");
1554 }
1555 }
1556
1557 #[test]
1558 fn guest_cid_wraps_without_zero() {
1559 let case = TestCase::new();
1560 let mut mgr = manager(&case);
1561 mgr.next_guest_cid = u32::MAX;
1562
1563 assert_eq!(
1564 mgr.write_guest_function_call(&h2g_call(0)).unwrap(),
1565 u32::MAX
1566 );
1567 assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
1568 }
1569
1570 #[test]
1571 fn cloning_preserves_guest_cids_without_consumers() {
1572 let case = TestCase::new();
1573 let mut mgr = manager(&case);
1574 mgr.g2h_consumer = Some(case.g2h_consumer());
1575 mgr.write_guest_function_call(&h2g_call(0)).unwrap();
1576
1577 let cloned = mgr.clone();
1578
1579 assert!(cloned.g2h_consumer.is_none());
1580 assert!(cloned.h2g_consumer.is_none());
1581 assert_eq!(cloned.next_guest_cid, 2);
1582 assert!(mgr.g2h_consumer.is_some());
1583 assert!(mgr.h2g_consumer.is_some());
1584 }
1585
1586 #[test]
1587 fn restoring_transport_preserves_guest_cids() {
1588 let case = TestCase::new();
1589 let mut mgr = manager(&case);
1590 mgr.g2h_consumer = Some(case.g2h_consumer());
1591 let captured = VirtqSnapshot::capture(&mgr.layout, &mgr.scratch_mem).unwrap();
1592 assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
1593
1594 mgr.g2h_consumer = None;
1595 mgr.h2g_consumer = None;
1596 mgr.restore_virtq(&captured).unwrap();
1597
1598 assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 2);
1599 }
1600
1601 #[cfg(target_arch = "x86_64")]
1604 fn verify_page_tables(name: &str, config: SandboxConfiguration) {
1605 let path = simple_guest_as_pathbuf();
1606 let snapshot = Snapshot::from_env(GuestBinary::FilePath(path), config)
1607 .unwrap_or_else(|e| panic!("{}: failed to create snapshot: {}", name, e));
1608
1609 assert!(
1611 unsafe { hyperlight_common::vmem::virt_to_phys(&snapshot, 0, 1) }
1612 .next()
1613 .is_none(),
1614 "{}: NULL page (0x0) should NOT be mapped",
1615 name
1616 );
1617 }
1618
1619 #[test]
1620 #[cfg(target_arch = "x86_64")]
1621 fn test_page_tables_for_various_configurations() {
1622 let test_cases: [(&str, SandboxConfiguration); 4] = [
1623 ("default", { SandboxConfiguration::default() }),
1624 ("small (8MiB scratch)", {
1625 let mut cfg = SandboxConfiguration::default();
1626 cfg.set_scratch_size(SMALL_SCRATCH_SIZE);
1627 cfg
1628 }),
1629 ("medium (64MiB scratch)", {
1630 let mut cfg = SandboxConfiguration::default();
1631 cfg.set_scratch_size(MEDIUM_SCRATCH_SIZE);
1632 cfg
1633 }),
1634 ("large (256MiB scratch)", {
1635 let mut cfg = SandboxConfiguration::default();
1636 cfg.set_scratch_size(LARGE_SCRATCH_SIZE);
1637 cfg
1638 }),
1639 ];
1640
1641 for (name, config) in test_cases {
1642 verify_page_tables(name, config);
1643 }
1644 }
1645
1646 #[test]
1647 #[cfg(target_arch = "x86_64")]
1648 fn build_creates_virtq_consumers_before_initialization() {
1649 let path = simple_guest_as_pathbuf();
1650 let bin = GuestBinary::FilePath(path);
1651 let config = SandboxConfiguration::default();
1652
1653 let snapshot = Snapshot::from_env(bin, config).unwrap();
1654
1655 let mgr = SandboxMemoryManager::from_snapshot(&snapshot).unwrap();
1656 let (mgr, _) = mgr.build().unwrap();
1657
1658 assert!(mgr.g2h_consumer.is_some());
1659 assert!(mgr.h2g_consumer.is_some());
1660 }
1661
1662 #[test]
1663 fn snapshot_memory_backing_reads_across_layers() {
1664 let host_page_size = page_size::get();
1665 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1666 let scratch = base + (4 * host_page_size) as u64;
1667 let layer = |gpa_start: u64, value: u8| {
1668 let data_len = host_page_size;
1669 let mut storage = ExclusiveSharedMemory::new(data_len).unwrap();
1670 storage
1671 .copy_from_slice(&vec![value; host_page_size], 0)
1672 .unwrap();
1673 let storage = storage.freeze(data_len).unwrap();
1674 Arc::new(SnapshotBlob::new(storage, gpa_start, 0, scratch).unwrap())
1675 };
1676 let first = layer(base, 0x11);
1677 let second = layer(base + host_page_size as u64, 0x22);
1678 let memory = Arc::new(
1679 SnapshotMemory::new(
1680 Box::new([first, second]),
1681 crate::sandbox::snapshot::memory::tests::stub_page_tables(),
1682 )
1683 .unwrap(),
1684 );
1685 let (snapshot, _) = SnapshotMemoryBacking::from_snapshot(memory)
1686 .unwrap()
1687 .build();
1688 let mut bytes = [0; 2];
1689
1690 snapshot
1691 .read_snapshot_gpa(base + host_page_size as u64 - 1, &mut bytes)
1692 .unwrap();
1693
1694 assert_eq!(bytes, [0x11, 0x22]);
1695 assert!(
1696 snapshot
1697 .read_snapshot_gpa(base + 2 * host_page_size as u64 - 1, &mut bytes)
1698 .is_err()
1699 );
1700 }
1701
1702 fn virtual_reader_manager() -> (SandboxMemoryManager<HostSharedMemory>, u64, u64) {
1703 let cfg = SandboxConfiguration::default();
1704 let layout = SandboxMemoryLayout::new(cfg, PAGE_SIZE, 0, None).unwrap();
1705 let host_page_size = page_size::get();
1706 let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
1707 let second_gpa = base + host_page_size as u64;
1708 let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
1709 let scratch_gpa = scratch_base + layout.get_scratch_size() as u64 - 0x10000;
1710 let pt_base = layout.get_pt_base_gpa();
1711 let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
1712 let kind = MappingKind::Basic(BasicMapping {
1713 readable: true,
1714 writable: false,
1715 executable: false,
1716 });
1717 unsafe {
1719 vmem::map(
1720 &pt_buf,
1721 Mapping {
1722 phys_base: base,
1723 virt_base: base,
1724 len: PAGE_SIZE as u64,
1725 kind,
1726 },
1727 );
1728 vmem::map(
1729 &pt_buf,
1730 Mapping {
1731 phys_base: second_gpa,
1732 virt_base: base + PAGE_SIZE as u64,
1733 len: PAGE_SIZE as u64,
1734 kind,
1735 },
1736 );
1737 vmem::map(
1738 &pt_buf,
1739 Mapping {
1740 phys_base: scratch_gpa,
1741 virt_base: base + 2 * PAGE_SIZE as u64,
1742 len: PAGE_SIZE as u64,
1743 kind,
1744 },
1745 );
1746 }
1747 let page_tables = pt_buf.into_bytes();
1748 layout.ensure_page_tables_fit(page_tables.len()).unwrap();
1749
1750 let first_storage =
1751 ReadonlySharedMemory::from_bytes(&vec![0x11; host_page_size], host_page_size).unwrap();
1752 let first = Arc::new(SnapshotBlob::new(first_storage, base, 0, scratch_base).unwrap());
1753
1754 let second_storage =
1755 ReadonlySharedMemory::from_bytes(&vec![0x22; host_page_size], host_page_size).unwrap();
1756 let second =
1757 Arc::new(SnapshotBlob::new(second_storage, second_gpa, 0, scratch_base).unwrap());
1758 let memory = Arc::new(
1759 SnapshotMemory::new(
1760 Box::new([first, second]),
1761 crate::sandbox::snapshot::memory::tests::page_tables_from_bytes(&page_tables),
1762 )
1763 .unwrap(),
1764 );
1765 let manager = SandboxMemoryManager::new(
1766 layout,
1767 SnapshotMemoryBacking::from_snapshot(memory).unwrap(),
1768 ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap(),
1769 NextAction::None,
1770 );
1771 let (manager, _) = manager.build().unwrap();
1772 manager
1773 .scratch_mem
1774 .copy_from_slice(
1775 &vec![0x33; PAGE_SIZE],
1776 (scratch_gpa - scratch_base) as usize,
1777 )
1778 .unwrap();
1779 (manager, pt_base, base)
1780 }
1781
1782 #[test]
1783 fn virtual_reader_reads_across_snapshot_layers() {
1784 let (manager, pt_base, base) = virtual_reader_manager();
1785 let mut bytes = [0u8; 2];
1786
1787 manager
1788 .with_guest_virtual_memory_reader(pt_base, |reader| {
1789 reader.read_exact(base + PAGE_SIZE as u64 - 1, &mut bytes)
1790 })
1791 .unwrap();
1792
1793 assert_eq!(bytes, [0x11, 0x22]);
1794 }
1795
1796 #[test]
1797 fn virtual_reader_reads_snapshot_and_cow_scratch_across_pages() {
1798 let (manager, root, base) = virtual_reader_manager();
1799 let mut bytes = [0; 2];
1800 manager
1801 .with_guest_virtual_memory_reader(root, |reader| {
1802 reader.read_exact(base + 2 * PAGE_SIZE as u64 - 1, &mut bytes)
1803 })
1804 .unwrap();
1805 assert_eq!(bytes, [0x22, 0x33]);
1806 }
1807
1808 #[test]
1809 fn virtual_reader_rejects_unmapped_and_overflowing_ranges() {
1810 let (manager, root, base) = virtual_reader_manager();
1811 manager
1812 .with_guest_virtual_memory_reader(root, |reader| {
1813 assert!(
1814 reader
1815 .read_exact(base + 3 * PAGE_SIZE as u64, &mut [0])
1816 .is_err()
1817 );
1818 assert!(reader.read_exact(u64::MAX, &mut [0; 2]).is_err());
1819 assert!(reader.read_exact(u64::MAX, &mut []).is_ok());
1820 Ok(())
1821 })
1822 .unwrap();
1823 }
1824
1825 #[test]
1826 fn virtual_reader_reports_invalid_page_tables() {
1827 let (manager, _, base) = virtual_reader_manager();
1828 let error = manager
1829 .with_guest_virtual_memory_reader(u64::MAX, |reader| reader.read_exact(base, &mut [0]))
1830 .unwrap_err();
1831 assert!(error.to_string().contains("unbacked"));
1832 }
1833
1834 #[test]
1835 fn guest_physical_memory_view_resolves_scratch_and_dynamic_edges() {
1836 let host_page_size = page_size::get();
1837 let layout =
1838 SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
1839 let scratch_start = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
1840 let snapshot = Arc::new(flat_memory(
1841 &[0u8; PAGE_SIZE],
1842 &[0; PAGE_SIZE],
1843 SandboxMemoryLayout::BASE_ADDRESS as u64,
1844 scratch_start,
1845 ));
1846 let (snapshot, _) = SnapshotMemoryBacking::from_snapshot(snapshot)
1847 .unwrap()
1848 .build();
1849
1850 let mut scratch = ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap();
1851 scratch.copy_from_slice(&[0x11], 0).unwrap();
1852 scratch
1853 .copy_from_slice(&[0x22], layout.get_scratch_size() - 1)
1854 .unwrap();
1855 let (scratch, _) = scratch.build();
1856
1857 let dynamic_gpa = SandboxMemoryLayout::BASE_ADDRESS as u64 + host_page_size as u64;
1858 let mut dynamic = ExclusiveSharedMemory::new(host_page_size).unwrap();
1859 dynamic.copy_from_slice(&[0x33], 0).unwrap();
1860 dynamic
1861 .copy_from_slice(&[0x44], host_page_size - 1)
1862 .unwrap();
1863 let (dynamic, dynamic_guest) = dynamic.build();
1864 let dynamic_region = dynamic_guest.mapping_at(dynamic_gpa, MemoryRegionType::Scratch);
1865 let dynamic_regions = [dynamic_region];
1866 GuestPhysicalMemoryView::with_memory(
1867 &snapshot,
1868 &scratch,
1869 &dynamic_regions,
1870 layout,
1871 |view| {
1872 let mut byte = [0u8; 1];
1873
1874 assert_eq!(
1875 view.read(scratch_start, &mut byte).unwrap(),
1876 GuestBacking {
1877 source: BackingSource::Scratch,
1878 offset: 0,
1879 }
1880 );
1881 assert_eq!(byte, [0x11]);
1882 assert_eq!(
1883 view.read(
1884 scratch_start + layout.get_scratch_size() as u64 - 1,
1885 &mut byte,
1886 )
1887 .unwrap(),
1888 GuestBacking {
1889 source: BackingSource::Scratch,
1890 offset: layout.get_scratch_size() - 1,
1891 }
1892 );
1893 assert_eq!(byte, [0x22]);
1894 assert_eq!(
1895 view.read(dynamic_gpa, &mut byte).unwrap(),
1896 GuestBacking {
1897 source: BackingSource::Dynamic(0),
1898 offset: 0,
1899 }
1900 );
1901 assert_eq!(byte, [0x33]);
1902 assert_eq!(
1903 view.read(dynamic_gpa + host_page_size as u64 - 1, &mut byte)
1904 .unwrap(),
1905 GuestBacking {
1906 source: BackingSource::Dynamic(0),
1907 offset: host_page_size - 1,
1908 }
1909 );
1910 assert_eq!(byte, [0x44]);
1911 assert!(
1912 view.resolve(dynamic_gpa + host_page_size as u64 - 1, 2)
1913 .is_none()
1914 );
1915 assert!(
1916 view.resolve(scratch_start + layout.get_scratch_size() as u64 - 1, 2,)
1917 .is_none()
1918 );
1919 Ok(())
1920 },
1921 )
1922 .unwrap();
1923
1924 drop(dynamic);
1925 drop(dynamic_guest);
1926 }
1927}