use std::cmp::max;
use std::time::Duration;
use hyperlight_common::log_level::GuestLogFilter;
use hyperlight_common::virtq::G2H_LOWER_SLOT_SIZE;
use hyperlight_common::vmem::PAGE_SIZE;
#[cfg(target_os = "linux")]
use libc::c_int;
use tracing::{Span, instrument};
use tracing_core::LevelFilter;
#[cfg(gdb)]
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub struct DebugInfo {
pub port: u16,
}
#[cfg(target_arch = "x86_64")]
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum GuestMsrError {
#[error("declared guest MSRs exceed the maximum of {maximum} distinct entries")]
CapacityExceeded {
maximum: usize,
},
}
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
#[repr(C)]
pub struct SandboxConfiguration {
#[cfg(crashdump)]
guest_core_dump: bool,
#[cfg(gdb)]
guest_debug_info: Option<DebugInfo>,
interrupt_retry_delay: Duration,
interrupt_vcpu_sigrtmin_offset: u8,
scratch_size: usize,
max_guest_log_level: u64,
g2h_queue_size: usize,
h2g_queue_size: usize,
g2h_buffer_size: usize,
h2g_buffer_size: usize,
g2h_pool_pages: usize,
h2g_pool_pages: usize,
#[cfg(target_arch = "x86_64")]
guest_msrs: [u32; Self::MAX_GUEST_MSRS],
#[cfg(target_arch = "x86_64")]
guest_msrs_count: usize,
}
impl SandboxConfiguration {
pub const DEFAULT_INTERRUPT_RETRY_DELAY: Duration = Duration::from_micros(500);
pub const INTERRUPT_VCPU_SIGRTMIN_OFFSET: u8 = 0;
pub const DEFAULT_SCRATCH_SIZE: usize = 0x64000;
pub const DEFAULT_G2H_QUEUE_SIZE: usize = 64;
pub const DEFAULT_H2G_QUEUE_SIZE: usize = 32;
pub const DEFAULT_G2H_BUFFER_SIZE: usize = PAGE_SIZE;
pub const DEFAULT_H2G_BUFFER_SIZE: usize = PAGE_SIZE;
pub const DEFAULT_G2H_POOL_PAGES: usize = 12;
pub const DEFAULT_H2G_POOL_PAGES: usize = 8;
const MIN_QUEUE_SIZE: usize = 2;
const MAX_QUEUE_SIZE: usize = 32_768;
const MIN_BUFFER_SIZE: usize = G2H_LOWER_SLOT_SIZE;
const MAX_BUFFER_SIZE: usize = u32::MAX as usize;
#[cfg(target_arch = "x86_64")]
pub const MAX_GUEST_MSRS: usize = 16;
const MAX_GUEST_LOG_LEVEL_UNSET: u64 = u64::MAX;
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
fn new(
scratch_size: usize,
interrupt_retry_delay: Duration,
interrupt_vcpu_sigrtmin_offset: u8,
#[cfg(gdb)] guest_debug_info: Option<DebugInfo>,
#[cfg(crashdump)] guest_core_dump: bool,
) -> Self {
Self {
scratch_size,
max_guest_log_level: Self::MAX_GUEST_LOG_LEVEL_UNSET,
g2h_queue_size: Self::DEFAULT_G2H_QUEUE_SIZE,
h2g_queue_size: Self::DEFAULT_H2G_QUEUE_SIZE,
g2h_buffer_size: Self::DEFAULT_G2H_BUFFER_SIZE,
h2g_buffer_size: Self::DEFAULT_H2G_BUFFER_SIZE,
g2h_pool_pages: Self::DEFAULT_G2H_POOL_PAGES,
h2g_pool_pages: Self::DEFAULT_H2G_POOL_PAGES,
interrupt_retry_delay,
interrupt_vcpu_sigrtmin_offset,
#[cfg(gdb)]
guest_debug_info,
#[cfg(crashdump)]
guest_core_dump,
#[cfg(target_arch = "x86_64")]
guest_msrs: [0; Self::MAX_GUEST_MSRS],
#[cfg(target_arch = "x86_64")]
guest_msrs_count: 0,
}
}
#[cfg(any(kvm, mshv3, hvf))]
pub fn set_interrupt_retry_delay(&mut self, delay: Duration) {
self.interrupt_retry_delay = delay;
}
#[cfg(any(kvm, mshv3, hvf))]
pub fn get_interrupt_retry_delay(&self) -> Duration {
self.interrupt_retry_delay
}
#[cfg(target_os = "linux")]
pub fn get_interrupt_vcpu_sigrtmin_offset(&self) -> u8 {
self.interrupt_vcpu_sigrtmin_offset
}
#[cfg(target_arch = "x86_64")]
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn guest_msrs(&mut self, indices: &[u32]) -> Result<&mut Self, GuestMsrError> {
let additional = indices
.iter()
.enumerate()
.filter(|(position, index)| {
!self.guest_msrs[..self.guest_msrs_count].contains(index)
&& !indices[..*position].contains(index)
})
.count();
if additional > Self::MAX_GUEST_MSRS - self.guest_msrs_count {
return Err(GuestMsrError::CapacityExceeded {
maximum: Self::MAX_GUEST_MSRS,
});
}
for &index in indices {
if !self.guest_msrs[..self.guest_msrs_count].contains(&index) {
self.guest_msrs[self.guest_msrs_count] = index;
self.guest_msrs_count += 1;
}
}
Ok(self)
}
#[cfg(target_arch = "x86_64")]
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn get_guest_msrs(&self) -> &[u32] {
&self.guest_msrs[..self.guest_msrs_count]
}
#[cfg(target_os = "linux")]
pub fn set_interrupt_vcpu_sigrtmin_offset(&mut self, offset: u8) -> crate::Result<()> {
if libc::SIGRTMIN() + offset as c_int > libc::SIGRTMAX() {
return Err(crate::new_error!(
"Invalid SIGRTMIN offset: {}. It exceeds the maximum real-time signal number.",
offset
));
}
self.interrupt_vcpu_sigrtmin_offset = offset;
Ok(())
}
#[cfg(crashdump)]
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_guest_core_dump(&mut self, enable: bool) {
self.guest_core_dump = enable;
}
#[cfg(gdb)]
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_guest_debug_info(&mut self, debug_info: DebugInfo) {
self.guest_debug_info = Some(debug_info);
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn get_scratch_size(&self) -> usize {
self.scratch_size
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_scratch_size(&mut self, scratch_size: usize) {
self.scratch_size = scratch_size;
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_max_guest_log_level(&mut self, log_level: LevelFilter) {
self.max_guest_log_level = GuestLogFilter::from(log_level).into();
}
pub(crate) fn get_max_guest_log_level(&self) -> Option<LevelFilter> {
if self.max_guest_log_level == Self::MAX_GUEST_LOG_LEVEL_UNSET {
None
} else {
GuestLogFilter::try_from(self.max_guest_log_level)
.ok()
.map(Into::into)
}
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn get_g2h_queue_size(&self) -> usize {
self.g2h_queue_size
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_g2h_queue_size(&mut self, size: usize) {
self.g2h_queue_size = Self::normalize_queue_size(size);
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn get_h2g_queue_size(&self) -> usize {
self.h2g_queue_size
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_h2g_queue_size(&mut self, size: usize) {
self.h2g_queue_size = Self::normalize_queue_size(size);
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn get_g2h_buffer_size(&self) -> usize {
self.g2h_buffer_size
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_g2h_buffer_size(&mut self, size: usize) {
self.g2h_buffer_size = size.clamp(Self::MIN_BUFFER_SIZE, Self::MAX_BUFFER_SIZE);
self.g2h_pool_pages = max(
self.g2h_pool_pages,
Self::min_g2h_pool_pages(self.g2h_buffer_size),
);
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn get_h2g_buffer_size(&self) -> usize {
self.h2g_buffer_size
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_h2g_buffer_size(&mut self, size: usize) {
self.h2g_buffer_size = size.clamp(Self::MIN_BUFFER_SIZE, Self::MAX_BUFFER_SIZE);
self.h2g_pool_pages = max(
self.h2g_pool_pages,
Self::min_h2g_pool_pages(self.h2g_buffer_size),
);
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn get_g2h_pool_pages(&self) -> usize {
self.g2h_pool_pages
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_g2h_pool_pages(&mut self, pages: usize) {
self.g2h_pool_pages = max(pages, Self::min_g2h_pool_pages(self.g2h_buffer_size));
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn get_h2g_pool_pages(&self) -> usize {
self.h2g_pool_pages
}
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub fn set_h2g_pool_pages(&mut self, pages: usize) {
self.h2g_pool_pages = max(pages, Self::min_h2g_pool_pages(self.h2g_buffer_size));
}
#[cfg(crashdump)]
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn get_guest_core_dump(&self) -> bool {
self.guest_core_dump
}
#[cfg(gdb)]
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
pub(crate) fn get_guest_debug_info(&self) -> Option<DebugInfo> {
self.guest_debug_info
}
fn normalize_queue_size(size: usize) -> usize {
size.clamp(Self::MIN_QUEUE_SIZE, Self::MAX_QUEUE_SIZE)
.next_power_of_two()
}
fn min_g2h_pool_pages(buffer_size: usize) -> usize {
1 + Self::min_h2g_pool_pages(buffer_size)
}
fn min_h2g_pool_pages(buffer_size: usize) -> usize {
buffer_size.div_ceil(PAGE_SIZE)
}
}
impl Default for SandboxConfiguration {
#[instrument(skip_all, parent = Span::current(), level= "Trace")]
fn default() -> Self {
Self::new(
Self::DEFAULT_SCRATCH_SIZE,
Self::DEFAULT_INTERRUPT_RETRY_DELAY,
Self::INTERRUPT_VCPU_SIGRTMIN_OFFSET,
#[cfg(gdb)]
None,
#[cfg(crashdump)]
true,
)
}
}
#[cfg(test)]
mod tests {
use hyperlight_common::vmem::PAGE_SIZE;
use tracing_core::LevelFilter;
#[cfg(target_arch = "x86_64")]
use super::GuestMsrError;
use super::SandboxConfiguration;
#[test]
fn max_guest_log_level_defaults_to_none_and_round_trips_all_levels() {
let mut cfg = SandboxConfiguration::default();
assert_eq!(cfg.get_max_guest_log_level(), None);
for level in [
LevelFilter::OFF,
LevelFilter::ERROR,
LevelFilter::WARN,
LevelFilter::INFO,
LevelFilter::DEBUG,
LevelFilter::TRACE,
] {
cfg.set_max_guest_log_level(level);
assert_eq!(cfg.get_max_guest_log_level(), Some(level));
}
}
#[test]
fn default_scratch_size_supports_16k_pages() {
let cfg = SandboxConfiguration::default();
assert!(cfg.get_scratch_size().is_multiple_of(16 * 1024));
}
#[test]
#[cfg(target_arch = "x86_64")]
fn guest_msrs_reports_overflow() {
let mut cfg = SandboxConfiguration::default();
for index in 0..SandboxConfiguration::MAX_GUEST_MSRS as u32 {
cfg.guest_msrs(&[index]).unwrap();
}
cfg.guest_msrs(&[0]).unwrap();
assert_eq!(
cfg.guest_msrs(&[SandboxConfiguration::MAX_GUEST_MSRS as u32]),
Err(GuestMsrError::CapacityExceeded {
maximum: SandboxConfiguration::MAX_GUEST_MSRS,
})
);
}
#[test]
#[cfg(target_arch = "x86_64")]
fn bulk_guest_msrs_overflow_is_atomic() {
let mut cfg = SandboxConfiguration::default();
cfg.guest_msrs(&[1, 2]).unwrap();
let oversized: Vec<u32> = (3..=SandboxConfiguration::MAX_GUEST_MSRS as u32 + 1).collect();
assert!(matches!(
cfg.guest_msrs(&oversized),
Err(GuestMsrError::CapacityExceeded { .. })
));
assert_eq!(cfg.get_guest_msrs(), &[1, 2]);
}
#[test]
#[cfg(target_arch = "x86_64")]
fn guest_msrs_dedups_and_preserves_order() {
let mut cfg = SandboxConfiguration::default();
cfg.guest_msrs(&[0x10]).unwrap();
cfg.guest_msrs(&[0x20, 0x20, 0x10, 0x30, 0x20]).unwrap();
assert_eq!(cfg.get_guest_msrs(), &[0x10, 0x20, 0x30]);
}
#[test]
#[cfg(target_arch = "x86_64")]
fn guest_msrs_duplicates_do_not_count_toward_capacity() {
let mut cfg = SandboxConfiguration::default();
let fill: Vec<u32> = (0..SandboxConfiguration::MAX_GUEST_MSRS as u32 - 1).collect();
cfg.guest_msrs(&fill).unwrap();
cfg.guest_msrs(&[u32::MAX, u32::MAX, u32::MAX]).unwrap();
assert_eq!(
cfg.get_guest_msrs().len(),
SandboxConfiguration::MAX_GUEST_MSRS
);
}
#[test]
fn overrides() {
const SCRATCH_SIZE_OVERRIDE: usize = 0x60000;
let mut cfg = SandboxConfiguration::new(
SCRATCH_SIZE_OVERRIDE,
SandboxConfiguration::DEFAULT_INTERRUPT_RETRY_DELAY,
SandboxConfiguration::INTERRUPT_VCPU_SIGRTMIN_OFFSET,
#[cfg(gdb)]
None,
#[cfg(crashdump)]
true,
);
let scratch_size = cfg.get_scratch_size();
assert_eq!(SCRATCH_SIZE_OVERRIDE, scratch_size);
cfg.scratch_size = 0x40000;
assert_eq!(0x40000, cfg.scratch_size);
assert_eq!(
SandboxConfiguration::DEFAULT_G2H_QUEUE_SIZE,
cfg.get_g2h_queue_size()
);
assert_eq!(
SandboxConfiguration::DEFAULT_H2G_QUEUE_SIZE,
cfg.get_h2g_queue_size()
);
assert_eq!(
SandboxConfiguration::DEFAULT_G2H_BUFFER_SIZE,
cfg.get_g2h_buffer_size()
);
assert_eq!(
SandboxConfiguration::DEFAULT_H2G_BUFFER_SIZE,
cfg.get_h2g_buffer_size()
);
assert_eq!(
SandboxConfiguration::DEFAULT_G2H_POOL_PAGES,
cfg.get_g2h_pool_pages()
);
assert_eq!(
SandboxConfiguration::DEFAULT_H2G_POOL_PAGES,
cfg.get_h2g_pool_pages()
);
}
#[test]
fn queue_sizes_are_normalized() {
let mut cfg = SandboxConfiguration::default();
for (size, expected) in [
(0, 2),
(1, 2),
(2, 2),
(3, 4),
(32_767, 32_768),
(32_768, 32_768),
(32_769, 32_768),
(usize::MAX, 32_768),
] {
cfg.set_g2h_queue_size(size);
cfg.set_h2g_queue_size(size);
assert_eq!(expected, cfg.get_g2h_queue_size());
assert_eq!(expected, cfg.get_h2g_queue_size());
}
}
#[test]
fn buffer_sizes_are_normalized_without_page_rounding() {
let mut cfg = SandboxConfiguration::default();
cfg.set_g2h_buffer_size(0);
cfg.set_h2g_buffer_size(0);
assert_eq!(256, cfg.get_g2h_buffer_size());
assert_eq!(256, cfg.get_h2g_buffer_size());
cfg.set_g2h_buffer_size(3000);
cfg.set_h2g_buffer_size(3001);
assert_eq!(3000, cfg.get_g2h_buffer_size());
assert_eq!(3001, cfg.get_h2g_buffer_size());
cfg.set_g2h_buffer_size(usize::MAX);
cfg.set_h2g_buffer_size(usize::MAX);
assert_eq!(u32::MAX as usize, cfg.get_g2h_buffer_size());
assert_eq!(u32::MAX as usize, cfg.get_h2g_buffer_size());
}
#[test]
fn pool_page_counts_are_normalized() {
let mut cfg = SandboxConfiguration::default();
cfg.set_g2h_pool_pages(0);
cfg.set_h2g_pool_pages(0);
assert_eq!(2, cfg.get_g2h_pool_pages());
assert_eq!(1, cfg.get_h2g_pool_pages());
cfg.set_g2h_buffer_size(PAGE_SIZE + 1);
cfg.set_h2g_buffer_size(PAGE_SIZE + 1);
assert_eq!(3, cfg.get_g2h_pool_pages());
assert_eq!(2, cfg.get_h2g_pool_pages());
cfg.set_g2h_pool_pages(2);
cfg.set_h2g_pool_pages(1);
assert_eq!(3, cfg.get_g2h_pool_pages());
assert_eq!(2, cfg.get_h2g_pool_pages());
cfg.set_g2h_pool_pages(4);
cfg.set_h2g_pool_pages(3);
assert_eq!(4, cfg.get_g2h_pool_pages());
assert_eq!(3, cfg.get_h2g_pool_pages());
}
#[cfg(gdb)]
mod proptests {
use proptest::prelude::*;
use super::SandboxConfiguration;
use crate::sandbox::config::DebugInfo;
proptest! {
#[test]
fn guest_debug_info(port in 9000..=u16::MAX) {
let mut cfg = SandboxConfiguration::default();
let debug_info = DebugInfo { port };
cfg.set_guest_debug_info(debug_info);
prop_assert_eq!(debug_info, *cfg.get_guest_debug_info().as_ref().unwrap());
}
}
}
}