use std::fmt::Debug;
use std::mem::size_of;
use hyperlight_common::layout::{QueueDims, TransportArena};
use hyperlight_common::mem::HyperlightPEB;
use hyperlight_common::vmem::PAGE_SIZE;
use tracing::{Span, instrument};
use super::memory_region::MemoryRegionType::{Code, InitData, Peb};
use super::memory_region::{
DEFAULT_GUEST_BLOB_MEM_FLAGS, GuestMemoryRegion, MemoryRegion_, MemoryRegionFlags,
MemoryRegionVecBuilder,
};
use crate::error::HyperlightError::{MemoryRequestTooBig, MemoryRequestTooSmall};
use crate::sandbox::SandboxConfiguration;
use crate::{Result, new_error};
#[derive(Copy, Clone)]
pub(crate) struct SandboxMemoryLayout {
code_size: usize,
code_gva: usize,
init_data_size: usize,
init_data_permissions: Option<MemoryRegionFlags>,
scratch_size: usize,
g2h_dims: QueueDims,
h2g_dims: QueueDims,
g2h_buffer_size: usize,
h2g_buffer_size: usize,
transport_arena: TransportArena,
}
impl Debug for SandboxMemoryLayout {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let mut ff = f.debug_struct("SandboxMemoryLayout");
ff.field(
"Total Memory Size",
&format_args!("{:#x}", self.get_memory_size().unwrap_or(0)),
)
.field("Code Size", &format_args!("{:#x}", self.code_size))
.field("Code GVA", &format_args!("{:#x}", self.code_gva))
.field(
"Init Data Size",
&format_args!("{:#x}", self.init_data_size),
)
.field("Scratch Size", &format_args!("{:#x}", self.scratch_size))
.field("G2H Queue Size", &self.get_g2h_queue_size())
.field("H2G Queue Size", &self.get_h2g_queue_size())
.field("G2H Buffer Size", &self.g2h_buffer_size)
.field("H2G Buffer Size", &self.h2g_buffer_size)
.field("G2H Pool Pages", &self.get_g2h_pool_pages())
.field("H2G Pool Pages", &self.get_h2g_pool_pages())
.field(
"Guest Code Offset",
&format_args!("{:#x}", self.guest_code_offset()),
)
.field("PEB Offset", &format_args!("{:#x}", self.peb_offset()))
.field("PEB Address", &format_args!("{:#x}", self.peb_address()))
.field(
"Init Data Offset",
&format_args!("{:#x}", self.init_data_offset()),
)
.finish()
}
}
impl SandboxMemoryLayout {
pub(crate) const MAX_MEMORY_SIZE: usize = (16 * 1024 * 1024 * 1024) - Self::BASE_ADDRESS;
pub(crate) const BASE_ADDRESS: usize = 0x4000;
#[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn new(
cfg: SandboxConfiguration,
code_size: usize,
init_data_size: usize,
init_data_permissions: Option<MemoryRegionFlags>,
) -> Result<Self> {
let scratch_size = cfg.get_scratch_size();
if scratch_size > Self::MAX_MEMORY_SIZE {
return Err(MemoryRequestTooBig(scratch_size, Self::MAX_MEMORY_SIZE));
}
if !scratch_size.is_multiple_of(PAGE_SIZE) {
return Err(new_error!(
"scratch size {scratch_size} must be a multiple of {PAGE_SIZE}"
));
}
let g2h_queue_size = cfg.get_g2h_queue_size();
let h2g_queue_size = cfg.get_h2g_queue_size();
let g2h_buffer_size = cfg.get_g2h_buffer_size();
let h2g_buffer_size = cfg.get_h2g_buffer_size();
let g2h_pool_pages = cfg.get_g2h_pool_pages();
let h2g_pool_pages = cfg.get_h2g_pool_pages();
let g2h_dims = QueueDims::new(g2h_queue_size, g2h_pool_pages)
.ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
let h2g_dims = QueueDims::new(h2g_queue_size, h2g_pool_pages)
.ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
let transport_arena = Self::transport_arena_for(g2h_dims, h2g_dims)
.ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
let min_scratch_size = Self::min_scratch_for(&transport_arena);
if scratch_size < min_scratch_size {
return Err(MemoryRequestTooSmall(
scratch_size,
min_scratch_size.next_multiple_of(Self::host_page_size()),
));
}
let ret = Self {
code_size,
code_gva: Self::BASE_ADDRESS,
init_data_size,
init_data_permissions,
scratch_size,
g2h_dims,
h2g_dims,
g2h_buffer_size,
h2g_buffer_size,
transport_arena,
};
ret.get_memory_size()?;
Ok(ret)
}
pub(crate) fn host_page_size() -> usize {
PAGE_SIZE.max(page_size::get())
}
fn min_scratch_for(arena: &TransportArena) -> usize {
hyperlight_common::layout::min_scratch_size(
arena
.size()
.saturating_add(hyperlight_common::layout::SCRATCH_TRANSPORT_GAP_PAGES * PAGE_SIZE),
)
}
pub(crate) fn min_scratch(&self) -> usize {
Self::min_scratch_for(&self.transport_arena)
}
fn transport_arena_for(g2h: QueueDims, h2g: QueueDims) -> Option<TransportArena> {
let len = TransportArena::new(0, g2h, h2g)?.size() as u64;
let base = hyperlight_common::layout::scratch_transport_end_gpa().checked_sub(len)?;
TransportArena::new(base, g2h, h2g)
}
pub(crate) fn with_scratch_size(&self, scratch_size: usize) -> Result<Self> {
if scratch_size > Self::MAX_MEMORY_SIZE {
return Err(MemoryRequestTooBig(scratch_size, Self::MAX_MEMORY_SIZE));
}
let page = Self::host_page_size();
let min = self.min_scratch().next_multiple_of(page);
if scratch_size < min {
return Err(MemoryRequestTooSmall(scratch_size, min));
}
if !scratch_size.is_multiple_of(page) {
return Err(new_error!(
"scratch size {scratch_size} must be a multiple of {page}"
));
}
let mut ret = *self;
ret.scratch_size = scratch_size;
Ok(ret)
}
pub(crate) fn arena_scratch_offset(&self) -> usize {
debug_assert!(
self.transport_arena.base_addr()
> hyperlight_common::layout::scratch_base_gpa(self.scratch_size),
"the minimum scratch size keeps the arena above the scratch base"
);
(self.transport_arena.base_addr()
- hyperlight_common::layout::scratch_base_gpa(self.scratch_size)) as usize
}
pub(crate) fn mbx_scratch_offset(&self) -> usize {
self.arena_scratch_offset() + self.transport_arena.mbx_offset()
}
pub(crate) fn code_size(&self) -> usize {
self.code_size
}
pub(crate) fn init_data_size(&self) -> usize {
self.init_data_size
}
pub(crate) fn init_data_permissions(&self) -> Option<MemoryRegionFlags> {
self.init_data_permissions
}
pub(crate) fn get_scratch_size(&self) -> usize {
self.scratch_size
}
pub(crate) fn get_g2h_queue_size(&self) -> usize {
usize::from(self.g2h_dims.size().get())
}
pub(crate) fn get_h2g_queue_size(&self) -> usize {
usize::from(self.h2g_dims.size().get())
}
pub(crate) fn get_g2h_buffer_size(&self) -> usize {
self.g2h_buffer_size
}
pub(crate) fn get_h2g_buffer_size(&self) -> usize {
self.h2g_buffer_size
}
pub(crate) fn get_g2h_pool_pages(&self) -> usize {
self.g2h_dims.pool_pages().get()
}
pub(crate) fn get_h2g_pool_pages(&self) -> usize {
self.h2g_dims.pool_pages().get()
}
pub(crate) fn get_g2h_queue_dims(&self) -> QueueDims {
self.g2h_dims
}
pub(crate) fn get_h2g_queue_dims(&self) -> QueueDims {
self.h2g_dims
}
pub(crate) fn ensure_page_tables_fit(&self, page_table_len: usize) -> Result<()> {
let min_scratch = self.min_scratch().saturating_add(page_table_len);
if self.scratch_size < min_scratch {
let page = Self::host_page_size();
return Err(MemoryRequestTooSmall(
self.scratch_size,
min_scratch.next_multiple_of(page),
));
}
Ok(())
}
pub(crate) fn get_memory_regions(&self) -> Result<Vec<MemoryRegion_<GuestMemoryRegion>>> {
let mut builder = MemoryRegionVecBuilder::new(Self::BASE_ADDRESS, Self::BASE_ADDRESS);
let peb_offset = builder.push_page_aligned(
self.code_size,
MemoryRegionFlags::READ | MemoryRegionFlags::WRITE | MemoryRegionFlags::EXECUTE,
Code,
);
let expected_peb_offset = TryInto::<usize>::try_into(self.peb_offset())?;
if peb_offset != expected_peb_offset {
return Err(new_error!(
"PEB offset does not match expected PEB offset expected: {}, actual: {}",
expected_peb_offset,
peb_offset
));
}
let init_data_offset =
builder.push_page_aligned(size_of::<HyperlightPEB>(), MemoryRegionFlags::READ, Peb);
let expected_init_data_offset = TryInto::<usize>::try_into(self.init_data_offset())?;
if init_data_offset != expected_init_data_offset {
return Err(new_error!(
"Init Data offset does not match expected Init Data offset expected: {}, actual: {}",
expected_init_data_offset,
init_data_offset
));
}
let after_init_offset = if self.init_data_size > 0 {
let mem_flags = self
.init_data_permissions
.unwrap_or(DEFAULT_GUEST_BLOB_MEM_FLAGS);
builder.push_page_aligned(self.init_data_size, mem_flags, InitData)
} else {
init_data_offset
};
let final_offset = after_init_offset;
let expected_final_offset = TryInto::<usize>::try_into(self.get_memory_size()?)?;
let final_offset = final_offset.next_multiple_of(page_size::get());
let expected_final_offset =
expected_final_offset.next_multiple_of(hyperlight_common::vmem::PAGE_SIZE);
if final_offset != expected_final_offset {
return Err(new_error!(
"Final offset does not match expected Final offset expected: {}, actual: {}",
expected_final_offset,
final_offset
));
}
let mut regions = builder.build();
for region in &mut regions {
if region.region_type == Code {
let end = self
.code_gva
.checked_add(region.guest_region.len())
.ok_or_else(|| {
new_error!(
"code mapping overflow: base {:#x} + size {:#x}",
self.code_gva,
region.guest_region.len()
)
})?;
region.guest_region = self.code_gva..end;
}
}
Ok(regions)
}
pub(crate) fn set_code_gva(&mut self, code_gva: u64) -> Result<()> {
let code_gva = usize::try_from(code_gva)?;
let code_end = code_gva
.checked_add(self.code_size.next_multiple_of(PAGE_SIZE))
.ok_or_else(|| {
new_error!(
"code mapping overflow: base {:#x} + size {:#x}",
code_gva,
self.code_size
)
})?;
for region in self.get_memory_regions()? {
if region.region_type == Code {
continue;
}
if code_gva < region.guest_region.end && region.guest_region.start < code_end {
return Err(new_error!(
"code mapping [{:#x}, {:#x}) conflicts with {:?} region [{:#x}, {:#x})",
code_gva,
code_end,
region.region_type,
region.guest_region.start,
region.guest_region.end,
));
}
}
self.code_gva = code_gva;
Ok(())
}
#[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn write_init_data(&self, out: &mut [u8], bytes: &[u8]) -> Result<()> {
out[self.init_data_offset()..self.init_data_offset() + self.init_data_size]
.copy_from_slice(bytes);
Ok(())
}
#[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn write_peb(&self, mem: &mut [u8]) -> Result<()> {
use hyperlight_common::mem::GuestMemoryRegion;
let guest_base = Self::BASE_ADDRESS as u64;
let peb = HyperlightPEB {
init_data: GuestMemoryRegion {
size: (self.get_unaligned_memory_size() - self.init_data_offset()) as u64,
ptr: guest_base + self.init_data_offset() as u64,
},
};
let offset = self.peb_offset();
let bytes = bytemuck::bytes_of(&peb);
let end = offset + bytes.len();
let mem_len = mem.len();
let dst = mem.get_mut(offset..end).ok_or_else(|| {
new_error!(
"memory too small to write PEB: need {} bytes at offset {:#x}, have {} bytes",
bytes.len(),
offset,
mem_len
)
})?;
dst.copy_from_slice(bytes);
Ok(())
}
}
impl SandboxMemoryLayout {
pub(crate) fn peb_offset(&self) -> usize {
self.code_size.next_multiple_of(PAGE_SIZE)
}
pub(crate) fn peb_address(&self) -> usize {
Self::BASE_ADDRESS + self.peb_offset()
}
pub(crate) fn init_data_offset(&self) -> usize {
(self.peb_offset() + size_of::<HyperlightPEB>()).next_multiple_of(PAGE_SIZE)
}
pub(crate) fn guest_code_offset(&self) -> usize {
0
}
pub(crate) fn get_guest_code_gpa(&self) -> usize {
Self::BASE_ADDRESS + self.guest_code_offset()
}
pub(crate) fn get_guest_code_gva(&self) -> usize {
self.code_gva
}
pub(crate) fn get_pt_base_scratch_offset(&self) -> usize {
0
}
pub(crate) fn get_pt_base_gpa(&self) -> u64 {
hyperlight_common::layout::scratch_base_gpa(self.scratch_size)
}
pub(crate) fn get_transport_arena(&self) -> TransportArena {
self.transport_arena
}
fn get_unaligned_memory_size(&self) -> usize {
self.init_data_offset() + self.init_data_size
}
pub(crate) fn get_memory_size(&self) -> Result<usize> {
let total_memory = self.get_unaligned_memory_size();
let remainder = total_memory % page_size::get();
let multiples = total_memory / page_size::get();
let size = match remainder {
0 => total_memory,
_ => (multiples + 1) * page_size::get(),
};
if size > Self::MAX_MEMORY_SIZE {
Err(MemoryRequestTooBig(size, Self::MAX_MEMORY_SIZE))
} else {
Ok(size)
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn get_expected_memory_size(layout: &SandboxMemoryLayout) -> usize {
let mut expected_size = 0;
expected_size += layout.code_size;
let peb_and_array = size_of::<HyperlightPEB>();
expected_size += peb_and_array.next_multiple_of(PAGE_SIZE);
expected_size.next_multiple_of(page_size::get())
}
#[test]
fn test_get_memory_size() {
let sbox_cfg = SandboxConfiguration::default();
let sbox_mem_layout = SandboxMemoryLayout::new(sbox_cfg, 4096, 0, None).unwrap();
assert_eq!(
sbox_mem_layout.get_memory_size().unwrap(),
get_expected_memory_size(&sbox_mem_layout)
);
}
#[test]
fn transport_arena_sits_below_the_reserved_top() {
let cfg = SandboxConfiguration::default();
let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
let arena = layout.get_transport_arena();
let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
assert_eq!(
arena.end_addr()
+ (hyperlight_common::layout::SCRATCH_TRANSPORT_GAP_PAGES * PAGE_SIZE) as u64,
hyperlight_common::layout::scratch_reserved_top_gpa()
);
assert_eq!(layout.get_pt_base_gpa(), scratch_base);
assert_eq!(layout.get_pt_base_scratch_offset(), 0);
layout.ensure_page_tables_fit(PAGE_SIZE).unwrap();
assert_eq!(layout.get_transport_arena(), arena);
}
#[test]
fn resizing_scratch_keeps_the_transport_arena() {
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(4 << 20);
let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
let page = SandboxMemoryLayout::host_page_size();
let half = (layout.get_scratch_size() / 2).next_multiple_of(page);
let smaller = layout.with_scratch_size(half).unwrap();
assert_eq!(smaller.get_transport_arena(), layout.get_transport_arena());
assert_eq!(
smaller.get_pt_base_gpa(),
hyperlight_common::layout::scratch_base_gpa(half)
);
assert_eq!(
smaller.mbx_scratch_offset() + (layout.get_scratch_size() - half),
layout.mbx_scratch_offset()
);
assert!(matches!(
layout.with_scratch_size(layout.min_scratch() - 1),
Err(MemoryRequestTooSmall(..))
));
assert!(layout.with_scratch_size(half + 1).is_err());
assert!(matches!(
layout.with_scratch_size(
SandboxMemoryLayout::MAX_MEMORY_SIZE.next_multiple_of(page) + page
),
Err(MemoryRequestTooBig(..))
));
let larger = layout
.with_scratch_size(layout.get_scratch_size() * 2)
.unwrap();
assert_eq!(larger.get_transport_arena(), layout.get_transport_arena());
assert_eq!(
larger.mbx_scratch_offset(),
layout.mbx_scratch_offset() + layout.get_scratch_size()
);
}
#[test]
fn transport_memory_is_part_of_minimum_scratch_size() {
let mut cfg = SandboxConfiguration::default();
let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
let minimum = layout.min_scratch();
cfg.set_scratch_size(minimum);
let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
assert!(matches!(
layout.ensure_page_tables_fit(PAGE_SIZE),
Err(MemoryRequestTooSmall(..))
));
}
#[test]
fn transport_minimum_rejects_capacity_overflow() {
for (g2h_pages, h2g_pages) in [
(usize::MAX, 4),
(8, usize::MAX),
(usize::MAX / PAGE_SIZE, 1),
] {
let mut cfg = SandboxConfiguration::default();
cfg.set_g2h_pool_pages(g2h_pages);
cfg.set_h2g_pool_pages(h2g_pages);
let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None);
assert!(matches!(layout, Err(MemoryRequestTooSmall(_, usize::MAX))));
}
}
#[test]
fn rejects_unaligned_scratch_size() {
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(SandboxConfiguration::DEFAULT_SCRATCH_SIZE + 1);
let error = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap_err();
assert_eq!(
error.to_string(),
format!(
"scratch size {} must be a multiple of {PAGE_SIZE}",
SandboxConfiguration::DEFAULT_SCRATCH_SIZE + 1
)
);
}
#[test]
fn code_gva_updates_code_region() {
let mut layout =
SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
let code_gva = 0x100_0000;
layout.set_code_gva(code_gva).unwrap();
assert_eq!(
layout.get_guest_code_gpa(),
SandboxMemoryLayout::BASE_ADDRESS
);
assert_eq!(layout.get_guest_code_gva(), code_gva as usize);
let code = layout
.get_memory_regions()
.unwrap()
.into_iter()
.find(|region| region.region_type == Code)
.unwrap();
assert_eq!(code.host_region.start, SandboxMemoryLayout::BASE_ADDRESS);
assert_eq!(code.guest_region.start, code_gva as usize);
}
#[test]
fn code_gva_rejects_overlap() {
let mut layout =
SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
assert!(layout.set_code_gva(layout.peb_address() as u64).is_err());
}
#[test]
fn test_max_memory_sandbox() {
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(17 * 1024 * 1024 * 1024);
let layout = SandboxMemoryLayout::new(cfg, 4096, 4096, None);
assert!(matches!(layout.unwrap_err(), MemoryRequestTooBig(..)));
}
#[test]
fn layout_offsets_are_pinned() {
macro_rules! pin_eq {
($left:expr, $right:expr) => {
assert_eq!(
$left, $right,
"snapshot ABI changed: this breaks loading of existing snapshots. \
Do not just update the expected value to make this compile. \
See docs/snapshot-versioning.md."
);
};
}
#[cfg(target_arch = "x86_64")]
{
pin_eq!(
hyperlight_common::layout::SCRATCH_TOP_GVA,
0xffff_ffff_ffff_efff
);
pin_eq!(
hyperlight_common::layout::SCRATCH_TOP_GPA,
0x0000_000f_ffff_ffff
);
}
#[cfg(target_arch = "aarch64")]
{
pin_eq!(
hyperlight_common::layout::SCRATCH_TOP_GVA,
0x0000_ffff_ffff_dfff
);
pin_eq!(
hyperlight_common::layout::SCRATCH_TOP_GPA,
0x0000_000f_ffff_bfff
);
}
#[cfg(target_arch = "x86_64")]
pin_eq!(hyperlight_common::layout::io_page(), None);
#[cfg(target_arch = "aarch64")]
pin_eq!(
hyperlight_common::layout::io_page(),
Some((0x0000_000f_ffff_f000, 0x0000_ffff_ffff_e000))
);
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(0x30000);
let layout = SandboxMemoryLayout::new(cfg, 0x1000, 0, None).unwrap();
pin_eq!(layout.guest_code_offset(), 0);
pin_eq!(layout.peb_offset(), 0x1000);
pin_eq!(layout.peb_address(), 0x5000);
pin_eq!(layout.init_data_offset(), 0x2000);
pin_eq!(
layout.get_memory_size().unwrap(),
0x2000_usize.next_multiple_of(page_size::get())
);
pin_eq!(layout.get_scratch_size(), 0x30000);
pin_eq!(layout.get_pt_base_scratch_offset(), 0);
let arena = layout.get_transport_arena();
let scratch_top = hyperlight_common::layout::SCRATCH_TOP_GPA as u64 + 1;
pin_eq!(scratch_top - arena.g2h_ring_addr(), 0x22000);
pin_eq!(arena.h2g_ring_addr() - arena.g2h_ring_addr(), 0x410);
pin_eq!(arena.mbx_addr() - arena.g2h_ring_addr(), 0x618);
pin_eq!(arena.g2h_pool_addr() - arena.g2h_ring_addr(), 0x1000);
pin_eq!(arena.h2g_pool_addr() - arena.g2h_ring_addr(), 0xd000);
pin_eq!(scratch_top - arena.end_addr(), 0xd000);
pin_eq!(
layout.get_pt_base_gpa(),
hyperlight_common::layout::scratch_base_gpa(0x30000)
);
let mut cfg = SandboxConfiguration::default();
cfg.set_scratch_size(0x40000);
let layout = SandboxMemoryLayout::new(cfg, 0x3000, 0, None).unwrap();
pin_eq!(layout.guest_code_offset(), 0);
pin_eq!(layout.peb_offset(), 0x3000);
pin_eq!(layout.peb_address(), 0x7000);
pin_eq!(layout.init_data_offset(), 0x4000);
pin_eq!(
layout.get_memory_size().unwrap(),
0x4000_usize.next_multiple_of(page_size::get())
);
pin_eq!(layout.get_scratch_size(), 0x40000);
pin_eq!(layout.get_pt_base_scratch_offset(), 0);
let arena = layout.get_transport_arena();
let scratch_top = hyperlight_common::layout::SCRATCH_TOP_GPA as u64 + 1;
pin_eq!(scratch_top - arena.g2h_ring_addr(), 0x22000);
pin_eq!(arena.h2g_ring_addr() - arena.g2h_ring_addr(), 0x410);
pin_eq!(arena.mbx_addr() - arena.g2h_ring_addr(), 0x618);
pin_eq!(arena.g2h_pool_addr() - arena.g2h_ring_addr(), 0x1000);
pin_eq!(arena.h2g_pool_addr() - arena.g2h_ring_addr(), 0xd000);
pin_eq!(scratch_top - arena.end_addr(), 0xd000);
pin_eq!(
layout.get_pt_base_gpa(),
hyperlight_common::layout::scratch_base_gpa(0x40000)
);
}
}