1use std::cmp::max;
5use std::time::Duration;
6
7use hyperlight_common::log_level::GuestLogFilter;
8use hyperlight_common::virtq::G2H_LOWER_SLOT_SIZE;
9use hyperlight_common::vmem::PAGE_SIZE;
10#[cfg(target_os = "linux")]
11use libc::c_int;
12use tracing::{Span, instrument};
13use tracing_core::LevelFilter;
14
15#[cfg(gdb)]
17#[derive(Copy, Clone, Debug, Eq, PartialEq)]
18pub struct DebugInfo {
19 pub port: u16,
21}
22
23#[cfg(target_arch = "x86_64")]
25#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
26pub enum GuestMsrError {
27 #[error("declared guest MSRs exceed the maximum of {maximum} distinct entries")]
29 CapacityExceeded {
30 maximum: usize,
32 },
33}
34
35#[derive(Copy, Clone, Debug, Eq, PartialEq)]
37#[repr(C)]
38pub struct SandboxConfiguration {
39 #[cfg(crashdump)]
46 guest_core_dump: bool,
47 #[cfg(gdb)]
49 guest_debug_info: Option<DebugInfo>,
50 interrupt_retry_delay: Duration,
57 interrupt_vcpu_sigrtmin_offset: u8,
65 scratch_size: usize,
67 max_guest_log_level: u64,
74 g2h_queue_size: usize,
76 h2g_queue_size: usize,
78 g2h_buffer_size: usize,
80 h2g_buffer_size: usize,
82 g2h_pool_pages: usize,
84 h2g_pool_pages: usize,
86 #[cfg(target_arch = "x86_64")]
88 guest_msrs: [u32; Self::MAX_GUEST_MSRS],
89 #[cfg(target_arch = "x86_64")]
91 guest_msrs_count: usize,
92}
93
94impl SandboxConfiguration {
95 pub const DEFAULT_INTERRUPT_RETRY_DELAY: Duration = Duration::from_micros(500);
97 pub const INTERRUPT_VCPU_SIGRTMIN_OFFSET: u8 = 0;
99 pub const DEFAULT_SCRATCH_SIZE: usize = 0x64000;
104 pub const DEFAULT_G2H_QUEUE_SIZE: usize = 64;
106 pub const DEFAULT_H2G_QUEUE_SIZE: usize = 32;
108 pub const DEFAULT_G2H_BUFFER_SIZE: usize = PAGE_SIZE;
110 pub const DEFAULT_H2G_BUFFER_SIZE: usize = PAGE_SIZE;
112 pub const DEFAULT_G2H_POOL_PAGES: usize = 12;
114 pub const DEFAULT_H2G_POOL_PAGES: usize = 8;
116 const MIN_QUEUE_SIZE: usize = 2;
118 const MAX_QUEUE_SIZE: usize = 32_768;
120 const MIN_BUFFER_SIZE: usize = G2H_LOWER_SLOT_SIZE;
122 const MAX_BUFFER_SIZE: usize = u32::MAX as usize;
124 #[cfg(target_arch = "x86_64")]
128 pub const MAX_GUEST_MSRS: usize = 16;
129 const MAX_GUEST_LOG_LEVEL_UNSET: u64 = u64::MAX;
130
131 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
133 fn new(
134 scratch_size: usize,
135 interrupt_retry_delay: Duration,
136 interrupt_vcpu_sigrtmin_offset: u8,
137 #[cfg(gdb)] guest_debug_info: Option<DebugInfo>,
138 #[cfg(crashdump)] guest_core_dump: bool,
139 ) -> Self {
140 Self {
141 scratch_size,
142 max_guest_log_level: Self::MAX_GUEST_LOG_LEVEL_UNSET,
143 g2h_queue_size: Self::DEFAULT_G2H_QUEUE_SIZE,
144 h2g_queue_size: Self::DEFAULT_H2G_QUEUE_SIZE,
145 g2h_buffer_size: Self::DEFAULT_G2H_BUFFER_SIZE,
146 h2g_buffer_size: Self::DEFAULT_H2G_BUFFER_SIZE,
147 g2h_pool_pages: Self::DEFAULT_G2H_POOL_PAGES,
148 h2g_pool_pages: Self::DEFAULT_H2G_POOL_PAGES,
149 interrupt_retry_delay,
150 interrupt_vcpu_sigrtmin_offset,
151 #[cfg(gdb)]
152 guest_debug_info,
153 #[cfg(crashdump)]
154 guest_core_dump,
155 #[cfg(target_arch = "x86_64")]
156 guest_msrs: [0; Self::MAX_GUEST_MSRS],
157 #[cfg(target_arch = "x86_64")]
158 guest_msrs_count: 0,
159 }
160 }
161
162 #[cfg(any(kvm, mshv3, hvf))]
164 pub fn set_interrupt_retry_delay(&mut self, delay: Duration) {
165 self.interrupt_retry_delay = delay;
166 }
167
168 #[cfg(any(kvm, mshv3, hvf))]
170 pub fn get_interrupt_retry_delay(&self) -> Duration {
171 self.interrupt_retry_delay
172 }
173
174 #[cfg(target_os = "linux")]
176 pub fn get_interrupt_vcpu_sigrtmin_offset(&self) -> u8 {
177 self.interrupt_vcpu_sigrtmin_offset
178 }
179
180 #[cfg(target_arch = "x86_64")]
206 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
207 pub fn guest_msrs(&mut self, indices: &[u32]) -> Result<&mut Self, GuestMsrError> {
208 let additional = indices
209 .iter()
210 .enumerate()
211 .filter(|(position, index)| {
212 !self.guest_msrs[..self.guest_msrs_count].contains(index)
213 && !indices[..*position].contains(index)
214 })
215 .count();
216 if additional > Self::MAX_GUEST_MSRS - self.guest_msrs_count {
217 return Err(GuestMsrError::CapacityExceeded {
218 maximum: Self::MAX_GUEST_MSRS,
219 });
220 }
221 for &index in indices {
222 if !self.guest_msrs[..self.guest_msrs_count].contains(&index) {
223 self.guest_msrs[self.guest_msrs_count] = index;
224 self.guest_msrs_count += 1;
225 }
226 }
227 Ok(self)
228 }
229
230 #[cfg(target_arch = "x86_64")]
232 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
233 pub(crate) fn get_guest_msrs(&self) -> &[u32] {
234 &self.guest_msrs[..self.guest_msrs_count]
235 }
236
237 #[cfg(target_os = "linux")]
245 pub fn set_interrupt_vcpu_sigrtmin_offset(&mut self, offset: u8) -> crate::Result<()> {
246 if libc::SIGRTMIN() + offset as c_int > libc::SIGRTMAX() {
247 return Err(crate::new_error!(
248 "Invalid SIGRTMIN offset: {}. It exceeds the maximum real-time signal number.",
249 offset
250 ));
251 }
252 self.interrupt_vcpu_sigrtmin_offset = offset;
253 Ok(())
254 }
255
256 #[cfg(crashdump)]
260 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
261 pub fn set_guest_core_dump(&mut self, enable: bool) {
262 self.guest_core_dump = enable;
263 }
264
265 #[cfg(gdb)]
267 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
268 pub fn set_guest_debug_info(&mut self, debug_info: DebugInfo) {
269 self.guest_debug_info = Some(debug_info);
270 }
271
272 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
273 pub(crate) fn get_scratch_size(&self) -> usize {
274 self.scratch_size
275 }
276
277 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
280 pub fn set_scratch_size(&mut self, scratch_size: usize) {
281 self.scratch_size = scratch_size;
282 }
283
284 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
289 pub fn set_max_guest_log_level(&mut self, log_level: LevelFilter) {
290 self.max_guest_log_level = GuestLogFilter::from(log_level).into();
291 }
292
293 pub(crate) fn get_max_guest_log_level(&self) -> Option<LevelFilter> {
294 if self.max_guest_log_level == Self::MAX_GUEST_LOG_LEVEL_UNSET {
295 None
296 } else {
297 GuestLogFilter::try_from(self.max_guest_log_level)
298 .ok()
299 .map(Into::into)
300 }
301 }
302
303 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
305 pub fn get_g2h_queue_size(&self) -> usize {
306 self.g2h_queue_size
307 }
308
309 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
313 pub fn set_g2h_queue_size(&mut self, size: usize) {
314 self.g2h_queue_size = Self::normalize_queue_size(size);
315 }
316
317 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
319 pub fn get_h2g_queue_size(&self) -> usize {
320 self.h2g_queue_size
321 }
322
323 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
327 pub fn set_h2g_queue_size(&mut self, size: usize) {
328 self.h2g_queue_size = Self::normalize_queue_size(size);
329 }
330
331 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
333 pub fn get_g2h_buffer_size(&self) -> usize {
334 self.g2h_buffer_size
335 }
336
337 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
341 pub fn set_g2h_buffer_size(&mut self, size: usize) {
342 self.g2h_buffer_size = size.clamp(Self::MIN_BUFFER_SIZE, Self::MAX_BUFFER_SIZE);
343 self.g2h_pool_pages = max(
344 self.g2h_pool_pages,
345 Self::min_g2h_pool_pages(self.g2h_buffer_size),
346 );
347 }
348
349 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
351 pub fn get_h2g_buffer_size(&self) -> usize {
352 self.h2g_buffer_size
353 }
354
355 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
359 pub fn set_h2g_buffer_size(&mut self, size: usize) {
360 self.h2g_buffer_size = size.clamp(Self::MIN_BUFFER_SIZE, Self::MAX_BUFFER_SIZE);
361 self.h2g_pool_pages = max(
362 self.h2g_pool_pages,
363 Self::min_h2g_pool_pages(self.h2g_buffer_size),
364 );
365 }
366
367 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
369 pub fn get_g2h_pool_pages(&self) -> usize {
370 self.g2h_pool_pages
371 }
372
373 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
377 pub fn set_g2h_pool_pages(&mut self, pages: usize) {
378 self.g2h_pool_pages = max(pages, Self::min_g2h_pool_pages(self.g2h_buffer_size));
379 }
380
381 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
383 pub fn get_h2g_pool_pages(&self) -> usize {
384 self.h2g_pool_pages
385 }
386
387 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
391 pub fn set_h2g_pool_pages(&mut self, pages: usize) {
392 self.h2g_pool_pages = max(pages, Self::min_h2g_pool_pages(self.h2g_buffer_size));
393 }
394
395 #[cfg(crashdump)]
396 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
397 pub(crate) fn get_guest_core_dump(&self) -> bool {
398 self.guest_core_dump
399 }
400
401 #[cfg(gdb)]
402 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
403 pub(crate) fn get_guest_debug_info(&self) -> Option<DebugInfo> {
404 self.guest_debug_info
405 }
406
407 fn normalize_queue_size(size: usize) -> usize {
408 size.clamp(Self::MIN_QUEUE_SIZE, Self::MAX_QUEUE_SIZE)
409 .next_power_of_two()
410 }
411
412 fn min_g2h_pool_pages(buffer_size: usize) -> usize {
413 1 + Self::min_h2g_pool_pages(buffer_size)
414 }
415
416 fn min_h2g_pool_pages(buffer_size: usize) -> usize {
417 buffer_size.div_ceil(PAGE_SIZE)
418 }
419}
420
421impl Default for SandboxConfiguration {
422 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
423 fn default() -> Self {
424 Self::new(
425 Self::DEFAULT_SCRATCH_SIZE,
426 Self::DEFAULT_INTERRUPT_RETRY_DELAY,
427 Self::INTERRUPT_VCPU_SIGRTMIN_OFFSET,
428 #[cfg(gdb)]
429 None,
430 #[cfg(crashdump)]
431 true,
432 )
433 }
434}
435
436#[cfg(test)]
437mod tests {
438 use hyperlight_common::vmem::PAGE_SIZE;
439 use tracing_core::LevelFilter;
440
441 #[cfg(target_arch = "x86_64")]
442 use super::GuestMsrError;
443 use super::SandboxConfiguration;
444
445 #[test]
446 fn max_guest_log_level_defaults_to_none_and_round_trips_all_levels() {
447 let mut cfg = SandboxConfiguration::default();
448 assert_eq!(cfg.get_max_guest_log_level(), None);
449
450 for level in [
451 LevelFilter::OFF,
452 LevelFilter::ERROR,
453 LevelFilter::WARN,
454 LevelFilter::INFO,
455 LevelFilter::DEBUG,
456 LevelFilter::TRACE,
457 ] {
458 cfg.set_max_guest_log_level(level);
459 assert_eq!(cfg.get_max_guest_log_level(), Some(level));
460 }
461 }
462
463 #[test]
464 fn default_scratch_size_supports_16k_pages() {
465 let cfg = SandboxConfiguration::default();
466 assert!(cfg.get_scratch_size().is_multiple_of(16 * 1024));
467 }
468
469 #[test]
470 #[cfg(target_arch = "x86_64")]
471 fn guest_msrs_reports_overflow() {
472 let mut cfg = SandboxConfiguration::default();
473 for index in 0..SandboxConfiguration::MAX_GUEST_MSRS as u32 {
474 cfg.guest_msrs(&[index]).unwrap();
475 }
476
477 cfg.guest_msrs(&[0]).unwrap();
478 assert_eq!(
479 cfg.guest_msrs(&[SandboxConfiguration::MAX_GUEST_MSRS as u32]),
480 Err(GuestMsrError::CapacityExceeded {
481 maximum: SandboxConfiguration::MAX_GUEST_MSRS,
482 })
483 );
484 }
485
486 #[test]
487 #[cfg(target_arch = "x86_64")]
488 fn bulk_guest_msrs_overflow_is_atomic() {
489 let mut cfg = SandboxConfiguration::default();
490 cfg.guest_msrs(&[1, 2]).unwrap();
491 let oversized: Vec<u32> = (3..=SandboxConfiguration::MAX_GUEST_MSRS as u32 + 1).collect();
492
493 assert!(matches!(
494 cfg.guest_msrs(&oversized),
495 Err(GuestMsrError::CapacityExceeded { .. })
496 ));
497 assert_eq!(cfg.get_guest_msrs(), &[1, 2]);
498 }
499
500 #[test]
501 #[cfg(target_arch = "x86_64")]
502 fn guest_msrs_dedups_and_preserves_order() {
503 let mut cfg = SandboxConfiguration::default();
504 cfg.guest_msrs(&[0x10]).unwrap();
505 cfg.guest_msrs(&[0x20, 0x20, 0x10, 0x30, 0x20]).unwrap();
506 assert_eq!(cfg.get_guest_msrs(), &[0x10, 0x20, 0x30]);
508 }
509
510 #[test]
511 #[cfg(target_arch = "x86_64")]
512 fn guest_msrs_duplicates_do_not_count_toward_capacity() {
513 let mut cfg = SandboxConfiguration::default();
514 let fill: Vec<u32> = (0..SandboxConfiguration::MAX_GUEST_MSRS as u32 - 1).collect();
515 cfg.guest_msrs(&fill).unwrap();
516 cfg.guest_msrs(&[u32::MAX, u32::MAX, u32::MAX]).unwrap();
519 assert_eq!(
520 cfg.get_guest_msrs().len(),
521 SandboxConfiguration::MAX_GUEST_MSRS
522 );
523 }
524
525 #[test]
526 fn overrides() {
527 const SCRATCH_SIZE_OVERRIDE: usize = 0x60000;
528 let mut cfg = SandboxConfiguration::new(
529 SCRATCH_SIZE_OVERRIDE,
530 SandboxConfiguration::DEFAULT_INTERRUPT_RETRY_DELAY,
531 SandboxConfiguration::INTERRUPT_VCPU_SIGRTMIN_OFFSET,
532 #[cfg(gdb)]
533 None,
534 #[cfg(crashdump)]
535 true,
536 );
537
538 let scratch_size = cfg.get_scratch_size();
539 assert_eq!(SCRATCH_SIZE_OVERRIDE, scratch_size);
540
541 cfg.scratch_size = 0x40000;
542 assert_eq!(0x40000, cfg.scratch_size);
543 assert_eq!(
544 SandboxConfiguration::DEFAULT_G2H_QUEUE_SIZE,
545 cfg.get_g2h_queue_size()
546 );
547 assert_eq!(
548 SandboxConfiguration::DEFAULT_H2G_QUEUE_SIZE,
549 cfg.get_h2g_queue_size()
550 );
551 assert_eq!(
552 SandboxConfiguration::DEFAULT_G2H_BUFFER_SIZE,
553 cfg.get_g2h_buffer_size()
554 );
555 assert_eq!(
556 SandboxConfiguration::DEFAULT_H2G_BUFFER_SIZE,
557 cfg.get_h2g_buffer_size()
558 );
559 assert_eq!(
560 SandboxConfiguration::DEFAULT_G2H_POOL_PAGES,
561 cfg.get_g2h_pool_pages()
562 );
563 assert_eq!(
564 SandboxConfiguration::DEFAULT_H2G_POOL_PAGES,
565 cfg.get_h2g_pool_pages()
566 );
567 }
568
569 #[test]
570 fn queue_sizes_are_normalized() {
571 let mut cfg = SandboxConfiguration::default();
572 for (size, expected) in [
573 (0, 2),
574 (1, 2),
575 (2, 2),
576 (3, 4),
577 (32_767, 32_768),
578 (32_768, 32_768),
579 (32_769, 32_768),
580 (usize::MAX, 32_768),
581 ] {
582 cfg.set_g2h_queue_size(size);
583 cfg.set_h2g_queue_size(size);
584 assert_eq!(expected, cfg.get_g2h_queue_size());
585 assert_eq!(expected, cfg.get_h2g_queue_size());
586 }
587 }
588
589 #[test]
590 fn buffer_sizes_are_normalized_without_page_rounding() {
591 let mut cfg = SandboxConfiguration::default();
592
593 cfg.set_g2h_buffer_size(0);
594 cfg.set_h2g_buffer_size(0);
595 assert_eq!(256, cfg.get_g2h_buffer_size());
596 assert_eq!(256, cfg.get_h2g_buffer_size());
597
598 cfg.set_g2h_buffer_size(3000);
599 cfg.set_h2g_buffer_size(3001);
600 assert_eq!(3000, cfg.get_g2h_buffer_size());
601 assert_eq!(3001, cfg.get_h2g_buffer_size());
602
603 cfg.set_g2h_buffer_size(usize::MAX);
604 cfg.set_h2g_buffer_size(usize::MAX);
605 assert_eq!(u32::MAX as usize, cfg.get_g2h_buffer_size());
606 assert_eq!(u32::MAX as usize, cfg.get_h2g_buffer_size());
607 }
608
609 #[test]
610 fn pool_page_counts_are_normalized() {
611 let mut cfg = SandboxConfiguration::default();
612
613 cfg.set_g2h_pool_pages(0);
614 cfg.set_h2g_pool_pages(0);
615 assert_eq!(2, cfg.get_g2h_pool_pages());
616 assert_eq!(1, cfg.get_h2g_pool_pages());
617
618 cfg.set_g2h_buffer_size(PAGE_SIZE + 1);
619 cfg.set_h2g_buffer_size(PAGE_SIZE + 1);
620 assert_eq!(3, cfg.get_g2h_pool_pages());
621 assert_eq!(2, cfg.get_h2g_pool_pages());
622
623 cfg.set_g2h_pool_pages(2);
624 cfg.set_h2g_pool_pages(1);
625 assert_eq!(3, cfg.get_g2h_pool_pages());
626 assert_eq!(2, cfg.get_h2g_pool_pages());
627
628 cfg.set_g2h_pool_pages(4);
629 cfg.set_h2g_pool_pages(3);
630 assert_eq!(4, cfg.get_g2h_pool_pages());
631 assert_eq!(3, cfg.get_h2g_pool_pages());
632 }
633
634 #[cfg(gdb)]
635 mod proptests {
636 use proptest::prelude::*;
637
638 use super::SandboxConfiguration;
639 use crate::sandbox::config::DebugInfo;
640
641 proptest! {
642 #[test]
643 fn guest_debug_info(port in 9000..=u16::MAX) {
644 let mut cfg = SandboxConfiguration::default();
645 let debug_info = DebugInfo { port };
646 cfg.set_guest_debug_info(debug_info);
647 prop_assert_eq!(debug_info, *cfg.get_guest_debug_info().as_ref().unwrap());
648 }
649 }
650 }
651}