use flatbuffers::FlatBufferBuilder;
use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCall;
use hyperlight_common::flatbuffer_wrappers::function_types::FunctionCallResult;
use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
use hyperlight_common::flatbuffer_wrappers::util::estimate_flatbuffer_capacity;
use hyperlight_common::log_level::GuestLogFilter;
use hyperlight_common::transport::{Buf, EncodedMessage, ExternalValues, MailboxValue, MsgKind};
use hyperlight_common::virtq::ReplyChain;
use hyperlight_common::vmem::{self, PAGE_TABLE_SIZE};
#[cfg(crashdump)]
use hyperlight_common::vmem::{BasicMapping, MappingKind};
use tracing::{Span, instrument};
use super::layout::SandboxMemoryLayout;
use super::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, HostSharedMemory, SharedMemory};
use super::virtq::{self, G2hConsumer, H2gConsumer, VirtqSnapshot};
use crate::hypervisor::regs::CommonSpecialRegisters;
use crate::mem::memory_region::MemoryRegion;
#[cfg(crashdump)]
use crate::mem::memory_region::{CrashDumpRegion, MemoryRegionFlags, MemoryRegionType};
use crate::sandbox::snapshot::{NextAction, Snapshot, SnapshotMemoryBacking};
use crate::{HyperlightError, Result, new_error};
#[cfg(crashdump)]
fn mapping_kind_to_flags(kind: &MappingKind) -> (MemoryRegionFlags, MemoryRegionType) {
match kind {
MappingKind::Basic(BasicMapping {
readable,
writable,
executable,
}) => {
let mut flags = MemoryRegionFlags::empty();
if *readable {
flags |= MemoryRegionFlags::READ;
}
if *writable {
flags |= MemoryRegionFlags::WRITE;
}
if *executable {
flags |= MemoryRegionFlags::EXECUTE;
}
(flags, MemoryRegionType::Snapshot)
}
MappingKind::Cow(cow) => {
let mut flags = MemoryRegionFlags::empty();
if cow.readable {
flags |= MemoryRegionFlags::READ;
}
if cow.executable {
flags |= MemoryRegionFlags::EXECUTE;
}
(flags, MemoryRegionType::Scratch)
}
MappingKind::Unmapped => (MemoryRegionFlags::empty(), MemoryRegionType::Snapshot),
MappingKind::ZeroInit(bm) => {
let mut flags = MemoryRegionFlags::empty();
if bm.readable {
flags |= MemoryRegionFlags::READ;
}
if bm.writable {
flags |= MemoryRegionFlags::WRITE;
}
if bm.executable {
flags |= MemoryRegionFlags::EXECUTE;
}
(flags, MemoryRegionType::Snapshot)
}
}
}
#[cfg(crashdump)]
fn try_coalesce_region(
regions: &mut [CrashDumpRegion],
virt_base: usize,
virt_end: usize,
host_base: usize,
flags: MemoryRegionFlags,
) -> bool {
if let Some(last) = regions.last_mut()
&& last.guest_region.end == virt_base
&& last.host_region.end == host_base
&& last.flags == flags
{
last.guest_region.end = virt_end;
last.host_region.end = host_base + (virt_end - virt_base);
return true;
}
false
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum BackingSource {
Snapshot(usize),
Scratch,
Dynamic(usize),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct GuestBacking {
pub(crate) source: BackingSource,
pub(crate) offset: usize,
}
pub(crate) struct GuestPhysicalMemoryView<'a> {
snapshot: &'a SnapshotMemoryBacking<HostSharedMemory>,
scratch: &'a [u8],
dynamic: &'a [MemoryRegion],
layout: SandboxMemoryLayout,
}
impl<'a> GuestPhysicalMemoryView<'a> {
pub(crate) fn with_memory<T>(
snapshot: &SnapshotMemoryBacking<HostSharedMemory>,
scratch: &HostSharedMemory,
dynamic: &[MemoryRegion],
layout: SandboxMemoryLayout,
f: impl FnOnce(&GuestPhysicalMemoryView<'_>) -> Result<T>,
) -> Result<T> {
scratch.with_exclusive_contents(|scratch| {
f(&GuestPhysicalMemoryView {
snapshot,
scratch,
dynamic,
layout,
})
})?
}
pub(crate) fn snapshot(&self) -> &'a SnapshotMemoryBacking<HostSharedMemory> {
self.snapshot
}
pub(crate) fn resolve(&self, gpa: u64, len: usize) -> Option<GuestBacking> {
let end = gpa.checked_add(u64::try_from(len).ok()?)?;
let scratch_start =
hyperlight_common::layout::scratch_base_gpa(self.layout.get_scratch_size());
let scratch_end = scratch_start.checked_add(self.layout.get_scratch_size() as u64)?;
if scratch_start <= gpa && end <= scratch_end {
return Some(GuestBacking {
source: BackingSource::Scratch,
offset: usize::try_from(gpa - scratch_start).ok()?,
});
}
if let Some((layer_index, offset)) = self.snapshot.resolve(gpa, len) {
return Some(GuestBacking {
source: BackingSource::Snapshot(layer_index),
offset,
});
}
self.dynamic
.iter()
.enumerate()
.find_map(|(region_index, region)| {
let start = u64::try_from(region.guest_region.start).ok()?;
let region_end = u64::try_from(region.guest_region.end).ok()?;
if start <= gpa && end <= region_end {
Some(GuestBacking {
source: BackingSource::Dynamic(region_index),
offset: usize::try_from(gpa - start).ok()?,
})
} else {
None
}
})
}
pub(crate) fn read(&self, gpa: u64, destination: &mut [u8]) -> Result<GuestBacking> {
let backing = self
.resolve(gpa, destination.len())
.ok_or_else(|| new_error!("GPA range is not backed: {gpa:#x}"))?;
self.read_backing(backing, destination)?;
Ok(backing)
}
pub(crate) fn read_backing(&self, backing: GuestBacking, destination: &mut [u8]) -> Result<()> {
let offset = backing.offset;
match backing.source {
BackingSource::Snapshot(layer_index) => {
self.snapshot
.copy_layer_to_slice(layer_index, destination, offset)?
}
BackingSource::Scratch => {
let source = offset
.checked_add(destination.len())
.and_then(|end| self.scratch.get(offset..end))
.ok_or_else(|| new_error!("scratch read range is out of bounds"))?;
destination.copy_from_slice(source);
}
BackingSource::Dynamic(region_index) => {
let region = &self.dynamic[region_index];
#[allow(clippy::useless_conversion)]
let host_start: usize = region.host_region.start.into();
#[allow(clippy::useless_conversion)]
let host_end: usize = region.host_region.end.into();
let source_end = offset
.checked_add(destination.len())
.ok_or_else(|| new_error!("dynamic memory read range overflows"))?;
let host_len = host_end
.checked_sub(host_start)
.ok_or_else(|| new_error!("dynamic memory host range is invalid"))?;
if source_end > host_len {
return Err(new_error!("dynamic memory read range is out of bounds"));
}
let source_start = host_start
.checked_add(offset)
.ok_or_else(|| new_error!("dynamic memory host address overflows"))?;
unsafe {
std::ptr::copy(
source_start as *const u8,
destination.as_mut_ptr(),
destination.len(),
)
};
}
}
Ok(())
}
#[cfg(crashdump)]
fn host_range(&self, gpa: u64, len: usize) -> Result<std::ops::Range<usize>> {
let backing = self
.resolve(gpa, len)
.ok_or_else(|| new_error!("GPA range is not backed: {gpa:#x}"))?;
let offset = backing.offset;
let (base, backing_len) = match backing.source {
BackingSource::Snapshot(layer_index) => self.snapshot.host_range(layer_index)?,
BackingSource::Scratch => (self.scratch.as_ptr() as usize, self.scratch.len()),
BackingSource::Dynamic(region_index) => {
let region = &self.dynamic[region_index];
#[allow(clippy::useless_conversion)]
let start: usize = region.host_region.start.into();
#[allow(clippy::useless_conversion)]
let end: usize = region.host_region.end.into();
(start, end - start)
}
};
let end_offset = offset
.checked_add(len)
.filter(|end| *end <= backing_len)
.ok_or_else(|| new_error!("resolved GPA range is out of bounds"))?;
let start = base
.checked_add(offset)
.ok_or_else(|| new_error!("resolved host address overflows"))?;
let end = base
.checked_add(end_offset)
.ok_or_else(|| new_error!("resolved host address overflows"))?;
Ok(start..end)
}
}
#[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
pub(crate) struct GuestVirtualMemoryReader<'a> {
memory: &'a GuestPhysicalMemoryView<'a>,
root_pt: u64,
cached_page: Option<(u64, u64)>,
}
#[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
impl<'a> GuestVirtualMemoryReader<'a> {
fn new(memory: &'a GuestPhysicalMemoryView<'a>, root_pt: u64) -> Self {
Self {
memory,
root_pt,
cached_page: None,
}
}
fn translate_page(&mut self, page_gva: u64) -> Result<u64> {
if let Some((cached_gva, cached_gpa)) = self.cached_page
&& cached_gva == page_gva
{
return Ok(cached_gpa);
}
use crate::sandbox::snapshot::PageTableReader;
let pt_buf = PageTableReader::new(self.memory, self.root_pt);
let mapping = unsafe {
hyperlight_common::vmem::virt_to_phys(
&pt_buf,
page_gva,
hyperlight_common::vmem::PAGE_SIZE as u64,
)
}
.next();
pt_buf.finish()?;
let mapping = mapping.ok_or_else(|| new_error!("GVA page is not mapped: {page_gva:#x}"))?;
let mapping_offset = page_gva
.checked_sub(mapping.virt_base)
.ok_or_else(|| new_error!("page-table mapping starts after requested GVA"))?;
if mapping
.len
.checked_sub(mapping_offset)
.is_none_or(|len| len < hyperlight_common::vmem::PAGE_SIZE as u64)
{
return Err(new_error!(
"page-table mapping does not cover requested GVA page"
));
}
let page_gpa = mapping
.phys_base
.checked_add(mapping_offset)
.ok_or_else(|| new_error!("guest physical address overflows"))?;
self.cached_page = Some((page_gva, page_gpa));
Ok(page_gpa)
}
pub(crate) fn read_exact(&mut self, gva: u64, destination: &mut [u8]) -> Result<()> {
gva.checked_add(u64::try_from(destination.len())?)
.ok_or_else(|| new_error!("guest virtual address overflows"))?;
let mut copied = 0usize;
while copied < destination.len() {
let current_gva = gva
.checked_add(u64::try_from(copied)?)
.ok_or_else(|| new_error!("guest virtual address overflows"))?;
let page_gva = current_gva / hyperlight_common::vmem::PAGE_SIZE as u64
* hyperlight_common::vmem::PAGE_SIZE as u64;
let page_offset = usize::try_from(current_gva - page_gva)?;
let chunk_len =
(destination.len() - copied).min(hyperlight_common::vmem::PAGE_SIZE - page_offset);
let gpa = self
.translate_page(page_gva)?
.checked_add(u64::try_from(page_offset)?)
.ok_or_else(|| new_error!("guest physical address overflows"))?;
self.memory
.read(gpa, &mut destination[copied..copied + chunk_len])?;
copied += chunk_len;
}
Ok(())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ExecutionMode {
Unrestricted,
Restricted,
}
const GUEST_REQUEST_OFFSETS: [u64; 2] = [
hyperlight_common::layout::SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
hyperlight_common::layout::SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
];
pub(crate) struct SandboxMemoryManager<S: SharedMemory> {
pub(crate) shared_mem: SnapshotMemoryBacking<S>,
pub(crate) scratch_mem: S,
pub(crate) layout: SandboxMemoryLayout,
pub(crate) next_action: NextAction,
pub(crate) original_entrypoint: u64,
pub(crate) abort_buffer: Vec<u8>,
pub(crate) execution_mode: ExecutionMode,
pub(crate) snapshot_count: u64,
pub(crate) g2h_consumer: Option<G2hConsumer>,
pub(crate) h2g_consumer: Option<H2gConsumer>,
next_guest_cid: u32,
}
impl<S: Clone + SharedMemory> Clone for SandboxMemoryManager<S> {
fn clone(&self) -> Self {
Self {
shared_mem: self.shared_mem.clone(),
scratch_mem: self.scratch_mem.clone(),
layout: self.layout,
next_action: self.next_action,
original_entrypoint: self.original_entrypoint,
abort_buffer: self.abort_buffer.clone(),
execution_mode: self.execution_mode,
snapshot_count: self.snapshot_count,
g2h_consumer: None,
h2g_consumer: None,
next_guest_cid: self.next_guest_cid,
}
}
}
pub(crate) struct GuestPageTableBuffer {
buffer: std::cell::RefCell<Vec<u8>>,
phys_base: usize,
root: std::cell::Cell<u64>,
}
impl vmem::TableReadOps for GuestPageTableBuffer {
type TableAddr = u64;
fn entry_addr(addr: u64, offset: u64) -> u64 {
addr + offset
}
unsafe fn read_entry(&self, addr: u64) -> vmem::PageTableEntry {
let buffer = self.buffer.borrow();
let byte_offset = addr as usize - self.phys_base;
let pte_size = core::mem::size_of::<vmem::PageTableEntry>();
let Some(bytes) = buffer.get(byte_offset..byte_offset + pte_size) else {
return 0;
};
let mut buf = [0u8; 8];
buf[..pte_size].copy_from_slice(bytes);
vmem::PageTableEntry::from_le_bytes(buf[..pte_size].try_into().unwrap_or_default())
}
fn to_phys(addr: u64) -> vmem::PhysAddr {
addr as vmem::PhysAddr
}
fn from_phys(addr: vmem::PhysAddr) -> u64 {
#[allow(clippy::unnecessary_cast)]
{
addr as u64
}
}
fn root_table(&self) -> u64 {
self.root.get()
}
}
impl vmem::TableOps for GuestPageTableBuffer {
type TableMovability = vmem::MayNotMoveTable;
unsafe fn alloc_table(&self) -> u64 {
let mut b = self.buffer.borrow_mut();
let offset = b.len();
b.resize(offset + PAGE_TABLE_SIZE, 0);
(self.phys_base + offset) as u64
}
unsafe fn write_entry(&self, addr: u64, entry: vmem::PageTableEntry) -> Option<vmem::Void> {
let mut b = self.buffer.borrow_mut();
let byte_offset = addr as usize - self.phys_base;
let pte_size = core::mem::size_of::<vmem::PageTableEntry>();
if let Some(slice) = b.get_mut(byte_offset..byte_offset + pte_size) {
slice.copy_from_slice(&entry.to_le_bytes()[..pte_size]);
}
None
}
unsafe fn update_root(&self, impossible: vmem::Void) {
match impossible {}
}
}
impl core::convert::AsRef<GuestPageTableBuffer> for GuestPageTableBuffer {
fn as_ref(&self) -> &Self {
self
}
}
impl GuestPageTableBuffer {
pub(crate) fn new(phys_base: usize) -> Self {
GuestPageTableBuffer {
buffer: std::cell::RefCell::new(vec![0u8; PAGE_TABLE_SIZE]),
phys_base,
root: std::cell::Cell::new(phys_base as u64),
}
}
pub(crate) fn set_root(&self, addr: u64) {
self.root.set(addr);
}
pub(crate) fn initial_root(&self) -> u64 {
self.phys_base as u64
}
#[cfg(test)]
#[allow(dead_code)]
pub(crate) fn size(&self) -> usize {
self.buffer.borrow().len()
}
pub(crate) fn into_bytes(self) -> Box<[u8]> {
self.buffer.into_inner().into_boxed_slice()
}
}
impl<S> SandboxMemoryManager<S>
where
S: SharedMemory,
{
pub(crate) fn first_free_scratch_gpa(&self) -> u64 {
self.layout.get_pt_base_gpa() + self.shared_mem.page_table_len() as u64
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn new(
layout: SandboxMemoryLayout,
shared_mem: SnapshotMemoryBacking<S>,
scratch_mem: S,
next_action: NextAction,
) -> Self {
Self {
layout,
shared_mem,
scratch_mem,
next_action,
original_entrypoint: 0,
abort_buffer: Vec::new(),
execution_mode: ExecutionMode::Unrestricted,
snapshot_count: 0,
g2h_consumer: None,
h2g_consumer: None,
next_guest_cid: 1,
}
}
pub(crate) fn get_abort_buffer_mut(&mut self) -> &mut Vec<u8> {
&mut self.abort_buffer
}
}
impl SandboxMemoryManager<ExclusiveSharedMemory> {
pub(crate) fn from_snapshot(s: &Snapshot) -> Result<Self> {
let layout = *s.layout();
let shared_mem = SnapshotMemoryBacking::from_snapshot(s.snapshot_memory().clone())?;
let scratch_mem = ExclusiveSharedMemory::new(s.layout().get_scratch_size())?;
let next_action = s.next_action();
let mut mgr = Self::new(layout, shared_mem, scratch_mem, next_action);
mgr.original_entrypoint = s.original_entrypoint();
mgr.snapshot_count = s.snapshot_generation();
Ok(mgr)
}
pub fn build(
self,
) -> Result<(
SandboxMemoryManager<HostSharedMemory>,
SandboxMemoryManager<GuestSharedMemory>,
)> {
let (hshm, gshm) = self.shared_mem.build();
let (hscratch, gscratch) = self.scratch_mem.build();
let mut host_mgr = SandboxMemoryManager {
shared_mem: hshm,
scratch_mem: hscratch,
layout: self.layout,
next_action: self.next_action,
original_entrypoint: self.original_entrypoint,
abort_buffer: self.abort_buffer,
execution_mode: self.execution_mode,
snapshot_count: self.snapshot_count,
g2h_consumer: None,
h2g_consumer: None,
next_guest_cid: self.next_guest_cid,
};
let guest_mgr = SandboxMemoryManager {
shared_mem: gshm,
scratch_mem: gscratch,
layout: self.layout,
next_action: self.next_action,
original_entrypoint: self.original_entrypoint,
abort_buffer: Vec::new(), execution_mode: self.execution_mode,
snapshot_count: self.snapshot_count,
g2h_consumer: None,
h2g_consumer: None,
next_guest_cid: self.next_guest_cid,
};
host_mgr.update_scratch_bookkeeping()?;
if matches!(host_mgr.next_action, NextAction::Initialise(_)) {
let cp = MailboxValue::CheckpointPending.as_bytes();
let mbx = host_mgr.layout.mbx_scratch_offset();
host_mgr.scratch_mem.copy_from_slice(cp, mbx)?;
host_mgr.create_virtq_consumers()?;
}
Ok((host_mgr, guest_mgr))
}
}
impl SandboxMemoryManager<HostSharedMemory> {
pub(crate) fn with_guest_memory<T>(
&self,
dynamic: &[MemoryRegion],
f: impl FnOnce(&GuestPhysicalMemoryView<'_>) -> Result<T>,
) -> Result<T> {
GuestPhysicalMemoryView::with_memory(
&self.shared_mem,
&self.scratch_mem,
dynamic,
self.layout,
f,
)
}
#[cfg(any(feature = "mem_profile", feature = "trace_guest", test))]
pub(crate) fn with_guest_virtual_memory_reader<T>(
&self,
root_pt: u64,
f: impl FnOnce(&mut GuestVirtualMemoryReader<'_>) -> Result<T>,
) -> Result<T> {
self.with_guest_memory(&[], |memory| {
f(&mut GuestVirtualMemoryReader::new(memory, root_pt))
})
}
#[allow(clippy::too_many_arguments)]
pub(crate) fn snapshot(
&mut self,
mapped_regions: Vec<MemoryRegion>,
root_pt_gpas: &[u64],
rsp_gva: u64,
sregs: CommonSpecialRegisters,
#[cfg(target_arch = "x86_64")] msrs: Vec<crate::hypervisor::regs::MsrEntry>,
next_action: NextAction,
host_functions: HostFunctionDetails,
scratch_size: usize,
) -> Result<Snapshot> {
let virtq = match (&self.g2h_consumer, &self.h2g_consumer) {
(Some(_), Some(_)) => Some(VirtqSnapshot::capture(&self.layout, &self.scratch_mem)?),
(None, None) => None,
_ => return Err(new_error!("virtqueue consumer ownership is incomplete")),
};
let layout = self.layout;
let original_entrypoint = self.original_entrypoint;
let snapshot_generation = self.snapshot_count + 1;
let snapshot = self.with_guest_memory(&mapped_regions, |memory| {
Snapshot::new(
memory,
layout,
crate::mem::exe::LoadInfo::dummy(),
root_pt_gpas,
rsp_gva,
sregs,
#[cfg(target_arch = "x86_64")]
msrs,
next_action,
original_entrypoint,
snapshot_generation,
host_functions,
virtq,
scratch_size,
)
})?;
self.snapshot_count = snapshot.snapshot_generation();
Ok(snapshot)
}
fn create_virtq_consumers(&mut self) -> Result<()> {
if self.g2h_consumer.is_some() || self.h2g_consumer.is_some() {
return Err(new_error!("virtqueue consumers already exist"));
}
let (g2h, h2g) = virtq::create_consumers(&self.layout, &self.scratch_mem)?;
self.g2h_consumer = Some(g2h);
self.h2g_consumer = Some(h2g);
Ok(())
}
pub(crate) fn restore_virtq(&mut self, snapshot: &VirtqSnapshot) -> Result<()> {
if self.g2h_consumer.is_some() || self.h2g_consumer.is_some() {
return Err(new_error!("virtqueue consumers are already attached"));
}
let (g2h, h2g) = snapshot.restore(&self.layout, &self.scratch_mem)?;
self.g2h_consumer = Some(g2h);
self.h2g_consumer = Some(h2g);
Ok(())
}
#[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn write_guest_function_call(&mut self, call: &FunctionCall) -> Result<u32> {
let cid = self.next_guest_cid;
let params = call.parameters.as_deref().unwrap_or_default();
let cap = estimate_flatbuffer_capacity(&call.function_name, params);
let mut builder = FlatBufferBuilder::with_capacity(cap);
let mut externals = ExternalValues::new();
let control = call.encode(&mut builder, &mut externals)?;
let Some(msg) = EncodedMessage::new(MsgKind::Request, cid, control, externals) else {
return Err(new_error!("H2G request exceeds the wire payload limit"));
};
self.write_h2g_message(&msg)?;
self.next_guest_cid = cid.wrapping_add(1);
if self.next_guest_cid == 0 {
self.next_guest_cid = 1;
}
Ok(cid)
}
fn write_h2g_message(&mut self, message: &EncodedMessage<'_>) -> Result<()> {
let consumer = self.h2g_consumer.as_mut().ok_or_else(|| {
HyperlightError::TransportError("H2G consumer is not attached".into())
})?;
let buffer_size = self.layout.get_h2g_buffer_size();
let buffer_count = message.total_len().div_ceil(buffer_size);
let control_reserve = usize::from(message.external_len() != 0);
let maybe_buffers = consumer
.poll_batch(buffer_count, control_reserve, 0)
.map_err(|error| {
HyperlightError::TransportError(format!("H2G poll failed: {error}"))
})?;
let Some(buffers) = maybe_buffers else {
return Err(new_error!(
"H2G capacity cannot provide {buffer_count} buffers with {control_reserve} spare"
));
};
let mut message = message.as_buf();
for (recv, reply) in buffers {
let ReplyChain::Writable(mut buffer) = reply else {
return Err(HyperlightError::TransportError(
"H2G receive buffer is not writable".into(),
));
};
if buffer.desc_count() != 1 || buffer.capacity() != buffer_size {
return Err(HyperlightError::TransportError(
"H2G receive buffer has an invalid shape".into(),
));
}
while message.has_remaining() && buffer.remaining() != 0 {
let written = buffer.write(message.chunk()).map_err(|err| {
HyperlightError::TransportError(format!("H2G write failed: {err}"))
})?;
message.advance(written);
}
consumer.complete(recv, buffer).map_err(|err| {
HyperlightError::TransportError(format!("H2G completion failed: {err}"))
})?;
}
debug_assert!(!message.has_remaining());
Ok(())
}
#[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn read_h2g_result_from_g2h(&mut self, cid: u32) -> Result<FunctionCallResult> {
let max_recv_len = self.layout.get_g2h_queue_dims().pool_len();
let Some(consumer) = self.g2h_consumer.as_mut() else {
return Err(HyperlightError::TransportError(
"G2H consumer is not attached".into(),
));
};
loop {
let maybe_next = consumer.poll(max_recv_len).map_err(|err| {
HyperlightError::TransportError(format!("G2H poll failed: {err}"))
})?;
let Some((mut recv, reply)) = maybe_next else {
return Err(HyperlightError::TransportError(
"G2H has no guest function result after halt".into(),
));
};
let header = virtq::read_message_header(&mut recv).map_err(|err| {
HyperlightError::TransportError(format!("Failed to read G2H result header: {err}"))
})?;
if !matches!(&reply, ReplyChain::Ack(_)) {
return Err(HyperlightError::TransportError(
"G2H result entry has writable buffers".into(),
));
}
match header.kind {
MsgKind::Log => {
if header.cid != 0 {
return Err(HyperlightError::TransportError(
"G2H log has a correlation ID".into(),
));
}
let log = virtq::read_guest_log_data(&mut recv).map_err(|err| {
HyperlightError::TransportError(format!("Failed to read G2H log: {err}"))
})?;
consumer.complete(recv, reply).map_err(|err| {
HyperlightError::TransportError(format!(
"Failed to complete G2H log: {err}"
))
})?;
crate::sandbox::outb::emit_guest_log(&log);
}
MsgKind::Response => {
if header.cid != cid {
return Err(HyperlightError::TransportError(
"G2H guest function result correlation ID mismatch".into(),
));
}
let result = virtq::read_guest_function_call_result(&mut recv);
consumer.complete(recv, reply).map_err(|err| {
HyperlightError::TransportError(format!(
"Failed to complete G2H guest function result: {err}"
))
})?;
return result.map_err(|err| {
HyperlightError::TransportError(format!(
"Failed to decode G2H guest function result: {err}"
))
});
}
kind => {
return Err(HyperlightError::TransportError(format!(
"Expected G2H guest function result, got {kind:?}"
)));
}
}
}
}
pub(crate) fn begin_snapshot_checkpoint(&mut self) -> Result<()> {
let offset = self.layout.mbx_scratch_offset();
let cp = MailboxValue::CheckpointPending.as_bytes();
self.scratch_mem.copy_from_slice(cp, offset)?;
let message = EncodedMessage::new_snapshot_cp();
self.write_h2g_message(&message)
}
pub(crate) fn finish_snapshot_checkpoint(&mut self) -> Result<()> {
let Some(g2h) = self.g2h_consumer.as_mut() else {
return Err(new_error!("G2H consumer is not attached"));
};
let Some(h2g) = self.h2g_consumer.as_mut() else {
return Err(new_error!("H2G consumer is not attached"));
};
g2h.reset()?;
h2g.reset()?;
let status = self
.scratch_mem
.read::<u64>(self.layout.mbx_scratch_offset())
.map_err(|error| HyperlightError::TransportError(error.to_string()))?;
match MailboxValue::try_from(status) {
Ok(MailboxValue::CheckpointComplete) => Ok(()),
Ok(MailboxValue::CheckpointPending) => Err(HyperlightError::TransportError(
"Guest did not publish snapshot checkpoint status".into(),
)),
Err(_) => Err(HyperlightError::TransportError(format!(
"Guest published invalid snapshot checkpoint status {status:#x}"
))),
}
}
fn replace_snapshot_memory(
&mut self,
snapshot: &Snapshot,
) -> Result<SnapshotMemoryBacking<GuestSharedMemory>> {
let new_snapshot_mem =
SnapshotMemoryBacking::from_snapshot(snapshot.snapshot_memory().clone())?;
let (hsnapshot, gsnapshot) = new_snapshot_mem.build();
self.shared_mem = hsnapshot;
Ok(gsnapshot)
}
fn apply_snapshot_metadata(&mut self, snapshot: &Snapshot) {
self.layout = *snapshot.layout();
self.snapshot_count = snapshot.snapshot_generation();
self.original_entrypoint = snapshot.original_entrypoint();
}
pub(crate) fn install_captured_snapshot(
&mut self,
snapshot: &Snapshot,
) -> Result<(
SnapshotMemoryBacking<GuestSharedMemory>,
Option<GuestSharedMemory>,
)> {
if snapshot.layout().get_scratch_size() != self.scratch_mem.mem_size() {
let requests = self.guest_requests()?;
let memory = self.restore_snapshot(snapshot)?;
self.set_guest_requests(requests)?;
return Ok(memory);
}
let used_scratch_end = self.used_scratch_end_gpa()?;
let gsnapshot = self.replace_snapshot_memory(snapshot)?;
self.apply_snapshot_metadata(snapshot);
self.update_snapshot_scratch_bookkeeping()?;
self.zero_freed_scratch(used_scratch_end)?;
Ok((gsnapshot, None))
}
fn used_scratch_end_gpa(&self) -> Result<u64> {
let offset = self.scratch_mem.mem_size()
- hyperlight_common::layout::SCRATCH_TOP_ALLOCATOR_OFFSET as usize;
let end = self.scratch_mem.read::<u64>(offset)?;
Ok(end.min(self.layout.get_transport_arena().base_addr()))
}
pub(crate) fn scratch_allocated_bytes(&self) -> Result<u64> {
Ok(self
.used_scratch_end_gpa()?
.saturating_sub(self.first_free_scratch_gpa()))
}
fn zero_freed_scratch(&mut self, end: u64) -> Result<()> {
let scratch_base = hyperlight_common::layout::scratch_base_gpa(self.scratch_mem.mem_size());
let start = self.first_free_scratch_gpa();
if end <= start {
return Ok(());
}
let start = usize::try_from(start - scratch_base)?;
let end = usize::try_from(end - scratch_base)?;
self.scratch_mem
.with_exclusivity(|scratch| scratch.as_mut_slice()[start..end].fill(0))?;
Ok(())
}
pub(crate) fn restore_snapshot(
&mut self,
snapshot: &Snapshot,
) -> Result<(
SnapshotMemoryBacking<GuestSharedMemory>,
Option<GuestSharedMemory>,
)> {
let virtq = snapshot.virtq();
if virtq.is_none() && matches!(snapshot.next_action(), NextAction::Call(_)) {
return Err(new_error!(
"running snapshot has no canonical transport state"
));
}
self.g2h_consumer = None;
self.h2g_consumer = None;
self.execution_mode = ExecutionMode::Unrestricted;
self.execution_mode = ExecutionMode::Unrestricted;
let gsnapshot = self.replace_snapshot_memory(snapshot)?;
let new_scratch_size = snapshot.layout().get_scratch_size();
let gscratch = if new_scratch_size == self.scratch_mem.mem_size() {
self.scratch_mem.zero_or_replace()?
} else {
let new_scratch_mem = ExclusiveSharedMemory::new(new_scratch_size)?;
let (hscratch, gscratch) = new_scratch_mem.build();
self.scratch_mem = hscratch;
Some(gscratch)
};
self.apply_snapshot_metadata(snapshot);
self.update_scratch_bookkeeping()?;
if let Some(virtq) = virtq {
self.restore_virtq(virtq)?;
} else if matches!(snapshot.next_action(), NextAction::Initialise(_)) {
self.scratch_mem.copy_from_slice(
MailboxValue::CheckpointPending.as_bytes(),
self.layout.mbx_scratch_offset(),
)?;
self.create_virtq_consumers()?;
}
Ok((gsnapshot, gscratch))
}
#[inline]
fn update_scratch_bookkeeping_item(&mut self, offset: u64, value: u64) -> Result<()> {
let scratch_size = self.scratch_mem.mem_size();
let base_offset = scratch_size - offset as usize;
self.scratch_mem
.write::<u64>(base_offset, value)
.map_err(From::from)
}
fn guest_requests(&self) -> Result<[u64; 2]> {
let scratch_size = self.scratch_mem.mem_size();
let mut values = [0; 2];
for (value, offset) in values.iter_mut().zip(GUEST_REQUEST_OFFSETS) {
*value = self
.scratch_mem
.read::<u64>(scratch_size - offset as usize)?;
}
Ok(values)
}
fn set_guest_requests(&mut self, values: [u64; 2]) -> Result<()> {
for (value, offset) in values.into_iter().zip(GUEST_REQUEST_OFFSETS) {
self.update_scratch_bookkeeping_item(offset, value)?;
}
Ok(())
}
pub(crate) fn request_libc_rng_reseed(&mut self, seed: u32) -> Result<()> {
self.update_scratch_bookkeeping_item(
hyperlight_common::layout::SCRATCH_TOP_LIBC_RNG_SEED_OFFSET,
(1_u64 << 32) | u64::from(seed),
)
}
pub(crate) fn request_guest_log_level_update(
&mut self,
log_level: tracing_core::LevelFilter,
) -> Result<()> {
self.update_scratch_bookkeeping_item(
hyperlight_common::layout::SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET,
(hyperlight_common::log_level::GUEST_LOG_FILTER_UPDATE_PENDING)
| u64::from(GuestLogFilter::from(log_level)),
)
}
fn update_scratch_bookkeeping(&mut self) -> Result<()> {
use hyperlight_common::layout::*;
let scratch_size = self.scratch_mem.mem_size();
self.update_scratch_bookkeeping_item(SCRATCH_TOP_SIZE_OFFSET, scratch_size as u64)?;
self.update_snapshot_scratch_bookkeeping()?;
Ok(())
}
fn update_snapshot_scratch_bookkeeping(&mut self) -> Result<()> {
use hyperlight_common::layout::*;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_ALLOCATOR_OFFSET,
self.first_free_scratch_gpa(),
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET,
self.layout.get_pt_base_gpa(),
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET,
self.snapshot_count,
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_HEAP_EXECUTABLE_OFFSET,
cfg!(feature = "executable_heap") as u64,
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_G2H_QUEUE_SIZE_OFFSET,
u64::try_from(self.layout.get_g2h_queue_size())?,
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_G2H_POOL_PAGES_OFFSET,
u64::try_from(self.layout.get_g2h_pool_pages())?,
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_G2H_BUFFER_SIZE_OFFSET,
u64::try_from(self.layout.get_g2h_buffer_size())?,
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET,
u64::try_from(self.layout.get_h2g_queue_size())?,
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_H2G_POOL_PAGES_OFFSET,
u64::try_from(self.layout.get_h2g_pool_pages())?,
)?;
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_H2G_BUFFER_SIZE_OFFSET,
u64::try_from(self.layout.get_h2g_buffer_size())?,
)?;
let transport_arena = self.layout.get_transport_arena();
self.update_scratch_bookkeeping_item(
SCRATCH_TOP_TRANSPORT_ARENA_GPA_OFFSET,
transport_arena.base_addr(),
)?;
let page_tables = self.shared_mem.page_table_bytes();
let offset = self.layout.get_pt_base_scratch_offset();
self.scratch_mem
.with_exclusivity(|scratch| scratch.copy_from_slice(page_tables, offset))??;
Ok(())
}
#[cfg(crashdump)]
pub(crate) fn get_guest_memory_regions(
&mut self,
root_pt: u64,
mmap_regions: &[MemoryRegion],
) -> Result<Vec<CrashDumpRegion>> {
use crate::sandbox::snapshot::PageTableReader;
let len = hyperlight_common::layout::SCRATCH_TOP_GVA;
self.with_guest_memory(mmap_regions, |memory| {
let pt_buf = PageTableReader::new(memory, root_pt);
let mut regions: Vec<CrashDumpRegion> = Vec::new();
let mut saw_mapping = false;
for mapping in unsafe { hyperlight_common::vmem::virt_to_phys(&pt_buf, 0, len as u64) }
{
saw_mapping = true;
let (flags, region_type) = mapping_kind_to_flags(&mapping.kind);
let mut mapped = 0usize;
let mapping_len = usize::try_from(mapping.len)?;
while mapped < mapping_len {
let chunk_len = (mapping_len - mapped).min(hyperlight_common::vmem::PAGE_SIZE);
let gpa = mapping
.phys_base
.checked_add(u64::try_from(mapped)?)
.ok_or_else(|| new_error!("crash-dump GPA overflows"))?;
let Some(host_region) = memory.host_range(gpa, chunk_len).ok() else {
mapped += chunk_len;
continue;
};
let virt_base = usize::try_from(mapping.virt_base)?
.checked_add(mapped)
.ok_or_else(|| new_error!("crash-dump GVA overflows"))?;
let virt_end = virt_base
.checked_add(chunk_len)
.ok_or_else(|| new_error!("crash-dump GVA range overflows"))?;
if !try_coalesce_region(
&mut regions,
virt_base,
virt_end,
host_region.start,
flags,
) {
regions.push(CrashDumpRegion {
guest_region: virt_base..virt_end,
host_region,
flags,
region_type,
});
}
mapped += chunk_len;
}
}
if !saw_mapping {
return Err(new_error!("No page table mappings found (len {len})",));
}
Ok(regions)
})
}
#[cfg(feature = "trace_guest")]
pub(crate) fn read_guest_memory_by_gva(
&self,
gva: u64,
len: usize,
root_pt: u64,
) -> Result<Vec<u8>> {
let mut result = vec![0; len];
self.with_guest_virtual_memory_reader(root_pt, |reader| {
reader.read_exact(gva, &mut result)
})?;
Ok(result)
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCallType;
use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterValue, ReturnType};
use hyperlight_common::transport::{
MsgHeader, SIZE_PREFIX_LEN, size_prefix_payload_len, size_prefixed_len,
};
use hyperlight_common::virtq::DescFlags;
use hyperlight_common::vmem::{self, BasicMapping, Mapping, MappingKind, PAGE_SIZE};
#[cfg(target_arch = "x86_64")]
use hyperlight_testing::sandbox_sizes::{
LARGE_SCRATCH_SIZE, MEDIUM_SCRATCH_SIZE, SMALL_SCRATCH_SIZE,
};
#[cfg(target_arch = "x86_64")]
use hyperlight_testing::simple_guest_as_pathbuf;
use super::*;
#[cfg(target_arch = "x86_64")]
use crate::GuestBinary;
use crate::mem::layout::SandboxMemoryLayout;
use crate::mem::memory_region::MemoryRegionType;
use crate::mem::shared_mem::{ExclusiveSharedMemory, ReadonlySharedMemory};
use crate::mem::virtq::tests::{H2G_BUFFER_SIZE, SCRATCH_SIZE, TestCase, memory_layout};
use crate::sandbox::SandboxConfiguration;
#[cfg(target_arch = "x86_64")]
use crate::sandbox::snapshot::Snapshot;
use crate::sandbox::snapshot::memory::tests::flat_memory;
use crate::sandbox::snapshot::{SnapshotBlob, SnapshotMemory};
fn manager(case: &TestCase) -> SandboxMemoryManager<HostSharedMemory> {
let host_page_size = page_size::get();
let layout = memory_layout();
let snapshot = Arc::new(flat_memory(
&vec![0; host_page_size],
&[0; PAGE_SIZE],
SandboxMemoryLayout::BASE_ADDRESS as u64,
hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size()),
));
let mut mgr = SandboxMemoryManager::new(
layout,
SnapshotMemoryBacking::from_snapshot(snapshot)
.unwrap()
.build()
.0,
case.scratch.clone(),
NextAction::None,
);
mgr.h2g_consumer = Some(case.h2g_consumer());
mgr
}
fn h2g_call(bytes: usize) -> FunctionCall {
let params = (bytes != 0).then(|| vec![ParameterValue::VecBytes(vec![0xa5; bytes])]);
FunctionCall::new(
"call".to_string(),
params,
FunctionCallType::Guest,
ReturnType::Void,
)
}
#[test]
fn rejects_invalid_h2g_descriptors() {
for (len, expected) in [
(H2G_BUFFER_SIZE as u32, "Payload data too large"),
(0, "not writable"),
] {
let case = TestCase::new();
let mut mgr = manager(&case);
let mut desc = case.h2g_desc(0);
desc.flags &= !DescFlags::WRITE.bits();
desc.len = len;
case.set_h2g_desc(0, desc);
let error = mgr.write_guest_function_call(&h2g_call(0)).unwrap_err();
assert!(error.to_string().contains(expected), "{error:#}");
assert!(error.is_poison_error());
assert!(matches!(error, HyperlightError::TransportError(_)));
}
}
#[test]
fn partial_h2g_write_is_fatal() {
let case = TestCase::new();
let mut mgr = manager(&case);
let mut desc = case.h2g_desc(1);
desc.addr = hyperlight_common::layout::scratch_base_gva(SCRATCH_SIZE) + SCRATCH_SIZE as u64;
case.set_h2g_desc(1, desc);
let error = mgr
.write_guest_function_call(&h2g_call(H2G_BUFFER_SIZE + 1024))
.unwrap_err();
assert!(error.to_string().contains("Memory write"), "{error:#}");
assert!(error.is_poison_error());
assert!(matches!(error, HyperlightError::TransportError(_)));
assert_eq!(mgr.h2g_consumer.as_ref().unwrap().used_cursor().head(), 1);
}
#[test]
fn insufficient_h2g_capacity_rolls_back() {
let case = TestCase::new();
let mut mgr = manager(&case);
let cursor = mgr.h2g_consumer.as_ref().unwrap().avail_cursor();
let error = mgr
.write_guest_function_call(&h2g_call(H2G_BUFFER_SIZE * 4))
.unwrap_err();
assert!(error.to_string().contains("H2G capacity"), "{error:#}");
assert!(!error.is_poison_error());
assert_eq!(mgr.h2g_consumer.as_ref().unwrap().avail_cursor(), cursor);
assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
}
#[test]
fn missing_g2h_result_is_fatal() {
let case = TestCase::new();
let mut mgr = manager(&case);
mgr.g2h_consumer = Some(case.g2h_consumer());
let Err(error) = mgr.read_h2g_result_from_g2h(1) else {
panic!("expected missing G2H result");
};
assert!(
error
.to_string()
.contains("G2H has no guest function result")
);
assert!(error.is_poison_error());
assert!(matches!(error, HyperlightError::TransportError(_)));
}
#[test]
fn writes_dense_h2g_request_and_reserves_control_buffer() {
let case = TestCase::new();
let mut mgr = manager(&case);
let external_len = H2G_BUFFER_SIZE * 2;
let buffers: Vec<_> = (0..4).map(|index| case.h2g_desc(index).addr).collect();
let cid = mgr
.write_guest_function_call(&h2g_call(external_len))
.unwrap();
let used = mgr.h2g_consumer.as_ref().unwrap().avail_cursor().head();
let wire: Vec<u8> = (0..used)
.flat_map(|index| case.h2g_buffer(index, buffers[index as usize]))
.collect();
let header = MsgHeader::from_bytes(&wire[..MsgHeader::SIZE]).unwrap();
assert_eq!(header.kind, MsgKind::Request);
assert_eq!(header.cid, cid);
assert_eq!(header.payload_len as usize, wire.len() - MsgHeader::SIZE);
let control =
size_prefix_payload_len(&wire[MsgHeader::SIZE..MsgHeader::SIZE + SIZE_PREFIX_LEN])
.unwrap();
let control_len = size_prefixed_len(control).unwrap();
let external = &wire[MsgHeader::SIZE + control_len..];
assert_eq!(external, vec![0xa5; external_len]);
let cursor = mgr.h2g_consumer.as_ref().unwrap().avail_cursor();
let error = mgr.write_guest_function_call(&h2g_call(1)).unwrap_err();
assert!(error.to_string().contains("H2G capacity"), "{error:#}");
assert_eq!(mgr.h2g_consumer.as_ref().unwrap().avail_cursor(), cursor);
assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 2);
}
#[test]
fn writes_header_only_snapshot_checkpoint() {
let case = TestCase::new();
let mut mgr = manager(&case);
let buffer = case.h2g_desc(0).addr;
let mbx = mgr.layout.mbx_scratch_offset();
let cp = MailboxValue::CheckpointComplete.as_bytes();
mgr.scratch_mem.copy_from_slice(cp, mbx).unwrap();
mgr.begin_snapshot_checkpoint().unwrap();
let wire = case.h2g_buffer(0, buffer);
let header = MsgHeader::from_bytes(&wire).unwrap();
assert_eq!(wire.len(), MsgHeader::SIZE);
assert_eq!(header.kind, MsgKind::SnapshotCheckpoint);
assert_eq!(header.cid, 0);
assert_eq!(header.payload_len, 0);
assert_eq!(mgr.next_guest_cid, 1);
assert_eq!(
MailboxValue::try_from(mgr.scratch_mem.read::<u64>(mbx).unwrap()).unwrap(),
MailboxValue::CheckpointPending
);
}
#[test]
fn incomplete_snapshot_checkpoint_is_fatal() {
let case = TestCase::new();
let mut mgr = manager(&case);
mgr.g2h_consumer = Some(case.g2h_consumer());
mgr.begin_snapshot_checkpoint().unwrap();
let error = mgr.finish_snapshot_checkpoint().unwrap_err();
assert!(matches!(error, HyperlightError::TransportError(_)));
assert!(error.is_poison_error());
}
#[test]
fn reads_completed_snapshot_checkpoint_status() {
let case = TestCase::new();
let mut mgr = manager(&case);
mgr.g2h_consumer = Some(case.g2h_consumer());
mgr.begin_snapshot_checkpoint().unwrap();
let mbx = mgr.layout.mbx_scratch_offset();
mgr.scratch_mem
.copy_from_slice(MailboxValue::CheckpointComplete.as_bytes(), mbx)
.unwrap();
mgr.finish_snapshot_checkpoint().unwrap();
let consumer = mgr.h2g_consumer.as_ref().unwrap();
assert_eq!(consumer.avail_cursor().head(), 0);
assert_eq!(consumer.used_cursor().head(), 0);
}
#[test]
fn invalid_checkpoint_status_is_fatal() {
for status in [2, 3, 0xa000, u64::MAX - 1, u64::MAX] {
let queue = TestCase::new();
let mut mgr = manager(&queue);
mgr.g2h_consumer = Some(queue.g2h_consumer());
let mbx = mgr.layout.mbx_scratch_offset();
mgr.scratch_mem.write::<u64>(mbx, status).unwrap();
let error = mgr.finish_snapshot_checkpoint().unwrap_err();
assert!(matches!(error, HyperlightError::TransportError(_)));
assert!(error.is_poison_error(), "{error}");
}
}
#[test]
fn guest_cid_wraps_without_zero() {
let case = TestCase::new();
let mut mgr = manager(&case);
mgr.next_guest_cid = u32::MAX;
assert_eq!(
mgr.write_guest_function_call(&h2g_call(0)).unwrap(),
u32::MAX
);
assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
}
#[test]
fn cloning_preserves_guest_cids_without_consumers() {
let case = TestCase::new();
let mut mgr = manager(&case);
mgr.g2h_consumer = Some(case.g2h_consumer());
mgr.write_guest_function_call(&h2g_call(0)).unwrap();
let cloned = mgr.clone();
assert!(cloned.g2h_consumer.is_none());
assert!(cloned.h2g_consumer.is_none());
assert_eq!(cloned.next_guest_cid, 2);
assert!(mgr.g2h_consumer.is_some());
assert!(mgr.h2g_consumer.is_some());
}
#[test]
fn restoring_transport_preserves_guest_cids() {
let case = TestCase::new();
let mut mgr = manager(&case);
mgr.g2h_consumer = Some(case.g2h_consumer());
let captured = VirtqSnapshot::capture(&mgr.layout, &mgr.scratch_mem).unwrap();
assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 1);
mgr.g2h_consumer = None;
mgr.h2g_consumer = None;
mgr.restore_virtq(&captured).unwrap();
assert_eq!(mgr.write_guest_function_call(&h2g_call(0)).unwrap(), 2);
}
#[cfg(target_arch = "x86_64")]
fn verify_page_tables(name: &str, config: SandboxConfiguration) {
let path = simple_guest_as_pathbuf();
let snapshot = Snapshot::from_env(GuestBinary::FilePath(path), config)
.unwrap_or_else(|e| panic!("{}: failed to create snapshot: {}", name, e));
assert!(
unsafe { hyperlight_common::vmem::virt_to_phys(&snapshot, 0, 1) }
.next()
.is_none(),
"{}: NULL page (0x0) should NOT be mapped",
name
);
}
#[test]
#[cfg(target_arch = "x86_64")]
fn test_page_tables_for_various_configurations() {
let test_cases: [(&str, SandboxConfiguration); 4] = [
("default", { SandboxConfiguration::default() }),
("small (8MiB scratch)", {
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(SMALL_SCRATCH_SIZE);
cfg
}),
("medium (64MiB scratch)", {
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(MEDIUM_SCRATCH_SIZE);
cfg
}),
("large (256MiB scratch)", {
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(LARGE_SCRATCH_SIZE);
cfg
}),
];
for (name, config) in test_cases {
verify_page_tables(name, config);
}
}
#[test]
#[cfg(target_arch = "x86_64")]
fn build_creates_virtq_consumers_before_initialization() {
let path = simple_guest_as_pathbuf();
let bin = GuestBinary::FilePath(path);
let config = SandboxConfiguration::default();
let snapshot = Snapshot::from_env(bin, config).unwrap();
let mgr = SandboxMemoryManager::from_snapshot(&snapshot).unwrap();
let (mgr, _) = mgr.build().unwrap();
assert!(mgr.g2h_consumer.is_some());
assert!(mgr.h2g_consumer.is_some());
}
#[test]
fn snapshot_memory_backing_reads_across_layers() {
let host_page_size = page_size::get();
let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
let scratch = base + (4 * host_page_size) as u64;
let layer = |gpa_start: u64, value: u8| {
let data_len = host_page_size;
let mut storage = ExclusiveSharedMemory::new(data_len).unwrap();
storage
.copy_from_slice(&vec![value; host_page_size], 0)
.unwrap();
let storage = storage.freeze(data_len).unwrap();
Arc::new(SnapshotBlob::new(storage, gpa_start, 0, scratch).unwrap())
};
let first = layer(base, 0x11);
let second = layer(base + host_page_size as u64, 0x22);
let memory = Arc::new(
SnapshotMemory::new(
Box::new([first, second]),
crate::sandbox::snapshot::memory::tests::stub_page_tables(),
)
.unwrap(),
);
let (snapshot, _) = SnapshotMemoryBacking::from_snapshot(memory)
.unwrap()
.build();
let mut bytes = [0; 2];
snapshot
.read_snapshot_gpa(base + host_page_size as u64 - 1, &mut bytes)
.unwrap();
assert_eq!(bytes, [0x11, 0x22]);
assert!(
snapshot
.read_snapshot_gpa(base + 2 * host_page_size as u64 - 1, &mut bytes)
.is_err()
);
}
fn virtual_reader_manager() -> (SandboxMemoryManager<HostSharedMemory>, u64, u64) {
let cfg = SandboxConfiguration::default();
let layout = SandboxMemoryLayout::new(cfg, PAGE_SIZE, 0, None).unwrap();
let host_page_size = page_size::get();
let base = SandboxMemoryLayout::BASE_ADDRESS as u64;
let second_gpa = base + host_page_size as u64;
let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
let scratch_gpa = scratch_base + layout.get_scratch_size() as u64 - 0x10000;
let pt_base = layout.get_pt_base_gpa();
let pt_buf = GuestPageTableBuffer::new(pt_base as usize);
let kind = MappingKind::Basic(BasicMapping {
readable: true,
writable: false,
executable: false,
});
unsafe {
vmem::map(
&pt_buf,
Mapping {
phys_base: base,
virt_base: base,
len: PAGE_SIZE as u64,
kind,
},
);
vmem::map(
&pt_buf,
Mapping {
phys_base: second_gpa,
virt_base: base + PAGE_SIZE as u64,
len: PAGE_SIZE as u64,
kind,
},
);
vmem::map(
&pt_buf,
Mapping {
phys_base: scratch_gpa,
virt_base: base + 2 * PAGE_SIZE as u64,
len: PAGE_SIZE as u64,
kind,
},
);
}
let page_tables = pt_buf.into_bytes();
layout.ensure_page_tables_fit(page_tables.len()).unwrap();
let first_storage =
ReadonlySharedMemory::from_bytes(&vec![0x11; host_page_size], host_page_size).unwrap();
let first = Arc::new(SnapshotBlob::new(first_storage, base, 0, scratch_base).unwrap());
let second_storage =
ReadonlySharedMemory::from_bytes(&vec![0x22; host_page_size], host_page_size).unwrap();
let second =
Arc::new(SnapshotBlob::new(second_storage, second_gpa, 0, scratch_base).unwrap());
let memory = Arc::new(
SnapshotMemory::new(
Box::new([first, second]),
crate::sandbox::snapshot::memory::tests::page_tables_from_bytes(&page_tables),
)
.unwrap(),
);
let manager = SandboxMemoryManager::new(
layout,
SnapshotMemoryBacking::from_snapshot(memory).unwrap(),
ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap(),
NextAction::None,
);
let (manager, _) = manager.build().unwrap();
manager
.scratch_mem
.copy_from_slice(
&vec![0x33; PAGE_SIZE],
(scratch_gpa - scratch_base) as usize,
)
.unwrap();
(manager, pt_base, base)
}
#[test]
fn virtual_reader_reads_across_snapshot_layers() {
let (manager, pt_base, base) = virtual_reader_manager();
let mut bytes = [0u8; 2];
manager
.with_guest_virtual_memory_reader(pt_base, |reader| {
reader.read_exact(base + PAGE_SIZE as u64 - 1, &mut bytes)
})
.unwrap();
assert_eq!(bytes, [0x11, 0x22]);
}
#[test]
fn virtual_reader_reads_snapshot_and_cow_scratch_across_pages() {
let (manager, root, base) = virtual_reader_manager();
let mut bytes = [0; 2];
manager
.with_guest_virtual_memory_reader(root, |reader| {
reader.read_exact(base + 2 * PAGE_SIZE as u64 - 1, &mut bytes)
})
.unwrap();
assert_eq!(bytes, [0x22, 0x33]);
}
#[test]
fn virtual_reader_rejects_unmapped_and_overflowing_ranges() {
let (manager, root, base) = virtual_reader_manager();
manager
.with_guest_virtual_memory_reader(root, |reader| {
assert!(
reader
.read_exact(base + 3 * PAGE_SIZE as u64, &mut [0])
.is_err()
);
assert!(reader.read_exact(u64::MAX, &mut [0; 2]).is_err());
assert!(reader.read_exact(u64::MAX, &mut []).is_ok());
Ok(())
})
.unwrap();
}
#[test]
fn virtual_reader_reports_invalid_page_tables() {
let (manager, _, base) = virtual_reader_manager();
let error = manager
.with_guest_virtual_memory_reader(u64::MAX, |reader| reader.read_exact(base, &mut [0]))
.unwrap_err();
assert!(error.to_string().contains("unbacked"));
}
#[test]
fn guest_physical_memory_view_resolves_scratch_and_dynamic_edges() {
let host_page_size = page_size::get();
let layout =
SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
let scratch_start = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
let snapshot = Arc::new(flat_memory(
&[0u8; PAGE_SIZE],
&[0; PAGE_SIZE],
SandboxMemoryLayout::BASE_ADDRESS as u64,
scratch_start,
));
let (snapshot, _) = SnapshotMemoryBacking::from_snapshot(snapshot)
.unwrap()
.build();
let mut scratch = ExclusiveSharedMemory::new(layout.get_scratch_size()).unwrap();
scratch.copy_from_slice(&[0x11], 0).unwrap();
scratch
.copy_from_slice(&[0x22], layout.get_scratch_size() - 1)
.unwrap();
let (scratch, _) = scratch.build();
let dynamic_gpa = SandboxMemoryLayout::BASE_ADDRESS as u64 + host_page_size as u64;
let mut dynamic = ExclusiveSharedMemory::new(host_page_size).unwrap();
dynamic.copy_from_slice(&[0x33], 0).unwrap();
dynamic
.copy_from_slice(&[0x44], host_page_size - 1)
.unwrap();
let (dynamic, dynamic_guest) = dynamic.build();
let dynamic_region = dynamic_guest.mapping_at(dynamic_gpa, MemoryRegionType::Scratch);
let dynamic_regions = [dynamic_region];
GuestPhysicalMemoryView::with_memory(
&snapshot,
&scratch,
&dynamic_regions,
layout,
|view| {
let mut byte = [0u8; 1];
assert_eq!(
view.read(scratch_start, &mut byte).unwrap(),
GuestBacking {
source: BackingSource::Scratch,
offset: 0,
}
);
assert_eq!(byte, [0x11]);
assert_eq!(
view.read(
scratch_start + layout.get_scratch_size() as u64 - 1,
&mut byte,
)
.unwrap(),
GuestBacking {
source: BackingSource::Scratch,
offset: layout.get_scratch_size() - 1,
}
);
assert_eq!(byte, [0x22]);
assert_eq!(
view.read(dynamic_gpa, &mut byte).unwrap(),
GuestBacking {
source: BackingSource::Dynamic(0),
offset: 0,
}
);
assert_eq!(byte, [0x33]);
assert_eq!(
view.read(dynamic_gpa + host_page_size as u64 - 1, &mut byte)
.unwrap(),
GuestBacking {
source: BackingSource::Dynamic(0),
offset: host_page_size - 1,
}
);
assert_eq!(byte, [0x44]);
assert!(
view.resolve(dynamic_gpa + host_page_size as u64 - 1, 2)
.is_none()
);
assert!(
view.resolve(scratch_start + layout.get_scratch_size() as u64 - 1, 2,)
.is_none()
);
Ok(())
},
)
.unwrap();
drop(dynamic);
drop(dynamic_guest);
}
}