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 heap_size_override: u64,
57 interrupt_retry_delay: Duration,
64 interrupt_vcpu_sigrtmin_offset: u8,
72 scratch_size: usize,
74 max_guest_log_level: u64,
81 g2h_queue_size: usize,
83 h2g_queue_size: usize,
85 g2h_buffer_size: usize,
87 h2g_buffer_size: usize,
89 g2h_pool_pages: usize,
91 h2g_pool_pages: usize,
93 #[cfg(target_arch = "x86_64")]
95 guest_msrs: [u32; Self::MAX_GUEST_MSRS],
96 #[cfg(target_arch = "x86_64")]
98 guest_msrs_count: usize,
99}
100
101impl SandboxConfiguration {
102 pub const DEFAULT_INTERRUPT_RETRY_DELAY: Duration = Duration::from_micros(500);
104 pub const INTERRUPT_VCPU_SIGRTMIN_OFFSET: u8 = 0;
106 pub const DEFAULT_HEAP_SIZE: u64 = 131072;
108 pub const DEFAULT_SCRATCH_SIZE: usize = 0x64000;
112 pub const DEFAULT_G2H_QUEUE_SIZE: usize = 64;
114 pub const DEFAULT_H2G_QUEUE_SIZE: usize = 32;
116 pub const DEFAULT_G2H_BUFFER_SIZE: usize = PAGE_SIZE;
118 pub const DEFAULT_H2G_BUFFER_SIZE: usize = PAGE_SIZE;
120 pub const DEFAULT_G2H_POOL_PAGES: usize = 12;
122 pub const DEFAULT_H2G_POOL_PAGES: usize = 8;
124 const MIN_QUEUE_SIZE: usize = 2;
126 const MAX_QUEUE_SIZE: usize = 32_768;
128 const MIN_BUFFER_SIZE: usize = G2H_LOWER_SLOT_SIZE;
130 const MAX_BUFFER_SIZE: usize = u32::MAX as usize;
132 #[cfg(target_arch = "x86_64")]
136 pub const MAX_GUEST_MSRS: usize = 16;
137 const MAX_GUEST_LOG_LEVEL_UNSET: u64 = u64::MAX;
138
139 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
141 fn new(
142 heap_size_override: Option<u64>,
143 scratch_size: usize,
144 interrupt_retry_delay: Duration,
145 interrupt_vcpu_sigrtmin_offset: u8,
146 #[cfg(gdb)] guest_debug_info: Option<DebugInfo>,
147 #[cfg(crashdump)] guest_core_dump: bool,
148 ) -> Self {
149 Self {
150 heap_size_override: heap_size_override.unwrap_or(0),
151 scratch_size,
152 max_guest_log_level: Self::MAX_GUEST_LOG_LEVEL_UNSET,
153 g2h_queue_size: Self::DEFAULT_G2H_QUEUE_SIZE,
154 h2g_queue_size: Self::DEFAULT_H2G_QUEUE_SIZE,
155 g2h_buffer_size: Self::DEFAULT_G2H_BUFFER_SIZE,
156 h2g_buffer_size: Self::DEFAULT_H2G_BUFFER_SIZE,
157 g2h_pool_pages: Self::DEFAULT_G2H_POOL_PAGES,
158 h2g_pool_pages: Self::DEFAULT_H2G_POOL_PAGES,
159 interrupt_retry_delay,
160 interrupt_vcpu_sigrtmin_offset,
161 #[cfg(gdb)]
162 guest_debug_info,
163 #[cfg(crashdump)]
164 guest_core_dump,
165 #[cfg(target_arch = "x86_64")]
166 guest_msrs: [0; Self::MAX_GUEST_MSRS],
167 #[cfg(target_arch = "x86_64")]
168 guest_msrs_count: 0,
169 }
170 }
171
172 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
174 pub fn set_heap_size(&mut self, heap_size: u64) {
175 self.heap_size_override = heap_size;
176 }
177
178 #[cfg(any(kvm, mshv3, hvf))]
180 pub fn set_interrupt_retry_delay(&mut self, delay: Duration) {
181 self.interrupt_retry_delay = delay;
182 }
183
184 #[cfg(any(kvm, mshv3, hvf))]
186 pub fn get_interrupt_retry_delay(&self) -> Duration {
187 self.interrupt_retry_delay
188 }
189
190 #[cfg(target_os = "linux")]
192 pub fn get_interrupt_vcpu_sigrtmin_offset(&self) -> u8 {
193 self.interrupt_vcpu_sigrtmin_offset
194 }
195
196 #[cfg(target_arch = "x86_64")]
222 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
223 pub fn guest_msrs(&mut self, indices: &[u32]) -> Result<&mut Self, GuestMsrError> {
224 let additional = indices
225 .iter()
226 .enumerate()
227 .filter(|(position, index)| {
228 !self.guest_msrs[..self.guest_msrs_count].contains(index)
229 && !indices[..*position].contains(index)
230 })
231 .count();
232 if additional > Self::MAX_GUEST_MSRS - self.guest_msrs_count {
233 return Err(GuestMsrError::CapacityExceeded {
234 maximum: Self::MAX_GUEST_MSRS,
235 });
236 }
237 for &index in indices {
238 if !self.guest_msrs[..self.guest_msrs_count].contains(&index) {
239 self.guest_msrs[self.guest_msrs_count] = index;
240 self.guest_msrs_count += 1;
241 }
242 }
243 Ok(self)
244 }
245
246 #[cfg(target_arch = "x86_64")]
248 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
249 pub(crate) fn get_guest_msrs(&self) -> &[u32] {
250 &self.guest_msrs[..self.guest_msrs_count]
251 }
252
253 #[cfg(target_os = "linux")]
261 pub fn set_interrupt_vcpu_sigrtmin_offset(&mut self, offset: u8) -> crate::Result<()> {
262 if libc::SIGRTMIN() + offset as c_int > libc::SIGRTMAX() {
263 return Err(crate::new_error!(
264 "Invalid SIGRTMIN offset: {}. It exceeds the maximum real-time signal number.",
265 offset
266 ));
267 }
268 self.interrupt_vcpu_sigrtmin_offset = offset;
269 Ok(())
270 }
271
272 #[cfg(crashdump)]
276 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
277 pub fn set_guest_core_dump(&mut self, enable: bool) {
278 self.guest_core_dump = enable;
279 }
280
281 #[cfg(gdb)]
283 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
284 pub fn set_guest_debug_info(&mut self, debug_info: DebugInfo) {
285 self.guest_debug_info = Some(debug_info);
286 }
287
288 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
289 pub(crate) fn get_scratch_size(&self) -> usize {
290 self.scratch_size
291 }
292
293 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
295 pub fn set_scratch_size(&mut self, scratch_size: usize) {
296 self.scratch_size = scratch_size;
297 }
298
299 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
304 pub fn set_max_guest_log_level(&mut self, log_level: LevelFilter) {
305 self.max_guest_log_level = GuestLogFilter::from(log_level).into();
306 }
307
308 pub(crate) fn get_max_guest_log_level(&self) -> Option<LevelFilter> {
309 if self.max_guest_log_level == Self::MAX_GUEST_LOG_LEVEL_UNSET {
310 None
311 } else {
312 GuestLogFilter::try_from(self.max_guest_log_level)
313 .ok()
314 .map(Into::into)
315 }
316 }
317
318 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
320 pub fn get_g2h_queue_size(&self) -> usize {
321 self.g2h_queue_size
322 }
323
324 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
328 pub fn set_g2h_queue_size(&mut self, size: usize) {
329 self.g2h_queue_size = Self::normalize_queue_size(size);
330 }
331
332 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
334 pub fn get_h2g_queue_size(&self) -> usize {
335 self.h2g_queue_size
336 }
337
338 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
342 pub fn set_h2g_queue_size(&mut self, size: usize) {
343 self.h2g_queue_size = Self::normalize_queue_size(size);
344 }
345
346 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
348 pub fn get_g2h_buffer_size(&self) -> usize {
349 self.g2h_buffer_size
350 }
351
352 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
356 pub fn set_g2h_buffer_size(&mut self, size: usize) {
357 self.g2h_buffer_size = size.clamp(Self::MIN_BUFFER_SIZE, Self::MAX_BUFFER_SIZE);
358 self.g2h_pool_pages = max(
359 self.g2h_pool_pages,
360 Self::min_g2h_pool_pages(self.g2h_buffer_size),
361 );
362 }
363
364 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
366 pub fn get_h2g_buffer_size(&self) -> usize {
367 self.h2g_buffer_size
368 }
369
370 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
374 pub fn set_h2g_buffer_size(&mut self, size: usize) {
375 self.h2g_buffer_size = size.clamp(Self::MIN_BUFFER_SIZE, Self::MAX_BUFFER_SIZE);
376 self.h2g_pool_pages = max(
377 self.h2g_pool_pages,
378 Self::min_h2g_pool_pages(self.h2g_buffer_size),
379 );
380 }
381
382 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
384 pub fn get_g2h_pool_pages(&self) -> usize {
385 self.g2h_pool_pages
386 }
387
388 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
392 pub fn set_g2h_pool_pages(&mut self, pages: usize) {
393 self.g2h_pool_pages = max(pages, Self::min_g2h_pool_pages(self.g2h_buffer_size));
394 }
395
396 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
398 pub fn get_h2g_pool_pages(&self) -> usize {
399 self.h2g_pool_pages
400 }
401
402 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
406 pub fn set_h2g_pool_pages(&mut self, pages: usize) {
407 self.h2g_pool_pages = max(pages, Self::min_h2g_pool_pages(self.h2g_buffer_size));
408 }
409
410 #[cfg(crashdump)]
411 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
412 pub(crate) fn get_guest_core_dump(&self) -> bool {
413 self.guest_core_dump
414 }
415
416 #[cfg(gdb)]
417 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
418 pub(crate) fn get_guest_debug_info(&self) -> Option<DebugInfo> {
419 self.guest_debug_info
420 }
421
422 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
423 fn heap_size_override_opt(&self) -> Option<u64> {
424 (self.heap_size_override > 0).then_some(self.heap_size_override)
425 }
426
427 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
430 pub(crate) fn get_heap_size(&self) -> u64 {
431 self.heap_size_override_opt()
432 .unwrap_or(Self::DEFAULT_HEAP_SIZE)
433 }
434
435 fn normalize_queue_size(size: usize) -> usize {
436 size.clamp(Self::MIN_QUEUE_SIZE, Self::MAX_QUEUE_SIZE)
437 .next_power_of_two()
438 }
439
440 fn min_g2h_pool_pages(buffer_size: usize) -> usize {
441 1 + Self::min_h2g_pool_pages(buffer_size)
442 }
443
444 fn min_h2g_pool_pages(buffer_size: usize) -> usize {
445 buffer_size.div_ceil(PAGE_SIZE)
446 }
447}
448
449impl Default for SandboxConfiguration {
450 #[instrument(skip_all, parent = Span::current(), level= "Trace")]
451 fn default() -> Self {
452 Self::new(
453 None,
454 Self::DEFAULT_SCRATCH_SIZE,
455 Self::DEFAULT_INTERRUPT_RETRY_DELAY,
456 Self::INTERRUPT_VCPU_SIGRTMIN_OFFSET,
457 #[cfg(gdb)]
458 None,
459 #[cfg(crashdump)]
460 true,
461 )
462 }
463}
464
465#[cfg(test)]
466mod tests {
467 use hyperlight_common::vmem::PAGE_SIZE;
468 use tracing_core::LevelFilter;
469
470 #[cfg(target_arch = "x86_64")]
471 use super::GuestMsrError;
472 use super::SandboxConfiguration;
473
474 #[test]
475 fn max_guest_log_level_defaults_to_none_and_round_trips_all_levels() {
476 let mut cfg = SandboxConfiguration::default();
477 assert_eq!(cfg.get_max_guest_log_level(), None);
478
479 for level in [
480 LevelFilter::OFF,
481 LevelFilter::ERROR,
482 LevelFilter::WARN,
483 LevelFilter::INFO,
484 LevelFilter::DEBUG,
485 LevelFilter::TRACE,
486 ] {
487 cfg.set_max_guest_log_level(level);
488 assert_eq!(cfg.get_max_guest_log_level(), Some(level));
489 }
490 }
491
492 #[test]
493 fn default_scratch_size_supports_16k_pages() {
494 let cfg = SandboxConfiguration::default();
495 assert!(cfg.get_scratch_size().is_multiple_of(16 * 1024));
496 }
497
498 #[test]
499 #[cfg(target_arch = "x86_64")]
500 fn guest_msrs_reports_overflow() {
501 let mut cfg = SandboxConfiguration::default();
502 for index in 0..SandboxConfiguration::MAX_GUEST_MSRS as u32 {
503 cfg.guest_msrs(&[index]).unwrap();
504 }
505
506 cfg.guest_msrs(&[0]).unwrap();
507 assert_eq!(
508 cfg.guest_msrs(&[SandboxConfiguration::MAX_GUEST_MSRS as u32]),
509 Err(GuestMsrError::CapacityExceeded {
510 maximum: SandboxConfiguration::MAX_GUEST_MSRS,
511 })
512 );
513 }
514
515 #[test]
516 #[cfg(target_arch = "x86_64")]
517 fn bulk_guest_msrs_overflow_is_atomic() {
518 let mut cfg = SandboxConfiguration::default();
519 cfg.guest_msrs(&[1, 2]).unwrap();
520 let oversized: Vec<u32> = (3..=SandboxConfiguration::MAX_GUEST_MSRS as u32 + 1).collect();
521
522 assert!(matches!(
523 cfg.guest_msrs(&oversized),
524 Err(GuestMsrError::CapacityExceeded { .. })
525 ));
526 assert_eq!(cfg.get_guest_msrs(), &[1, 2]);
527 }
528
529 #[test]
530 #[cfg(target_arch = "x86_64")]
531 fn guest_msrs_dedups_and_preserves_order() {
532 let mut cfg = SandboxConfiguration::default();
533 cfg.guest_msrs(&[0x10]).unwrap();
534 cfg.guest_msrs(&[0x20, 0x20, 0x10, 0x30, 0x20]).unwrap();
535 assert_eq!(cfg.get_guest_msrs(), &[0x10, 0x20, 0x30]);
537 }
538
539 #[test]
540 #[cfg(target_arch = "x86_64")]
541 fn guest_msrs_duplicates_do_not_count_toward_capacity() {
542 let mut cfg = SandboxConfiguration::default();
543 let fill: Vec<u32> = (0..SandboxConfiguration::MAX_GUEST_MSRS as u32 - 1).collect();
544 cfg.guest_msrs(&fill).unwrap();
545 cfg.guest_msrs(&[u32::MAX, u32::MAX, u32::MAX]).unwrap();
548 assert_eq!(
549 cfg.get_guest_msrs().len(),
550 SandboxConfiguration::MAX_GUEST_MSRS
551 );
552 }
553
554 #[test]
555 fn overrides() {
556 const HEAP_SIZE_OVERRIDE: u64 = 0x50000;
557 const SCRATCH_SIZE_OVERRIDE: usize = 0x60000;
558 let mut cfg = SandboxConfiguration::new(
559 Some(HEAP_SIZE_OVERRIDE),
560 SCRATCH_SIZE_OVERRIDE,
561 SandboxConfiguration::DEFAULT_INTERRUPT_RETRY_DELAY,
562 SandboxConfiguration::INTERRUPT_VCPU_SIGRTMIN_OFFSET,
563 #[cfg(gdb)]
564 None,
565 #[cfg(crashdump)]
566 true,
567 );
568
569 let heap_size = cfg.get_heap_size();
570 let scratch_size = cfg.get_scratch_size();
571 assert_eq!(HEAP_SIZE_OVERRIDE, heap_size);
572 assert_eq!(SCRATCH_SIZE_OVERRIDE, scratch_size);
573
574 cfg.heap_size_override = 2048;
575 cfg.scratch_size = 0x40000;
576 assert_eq!(2048, cfg.heap_size_override);
577 assert_eq!(0x40000, cfg.scratch_size);
578 assert_eq!(
579 SandboxConfiguration::DEFAULT_G2H_QUEUE_SIZE,
580 cfg.get_g2h_queue_size()
581 );
582 assert_eq!(
583 SandboxConfiguration::DEFAULT_H2G_QUEUE_SIZE,
584 cfg.get_h2g_queue_size()
585 );
586 assert_eq!(
587 SandboxConfiguration::DEFAULT_G2H_BUFFER_SIZE,
588 cfg.get_g2h_buffer_size()
589 );
590 assert_eq!(
591 SandboxConfiguration::DEFAULT_H2G_BUFFER_SIZE,
592 cfg.get_h2g_buffer_size()
593 );
594 assert_eq!(
595 SandboxConfiguration::DEFAULT_G2H_POOL_PAGES,
596 cfg.get_g2h_pool_pages()
597 );
598 assert_eq!(
599 SandboxConfiguration::DEFAULT_H2G_POOL_PAGES,
600 cfg.get_h2g_pool_pages()
601 );
602 }
603
604 #[test]
605 fn queue_sizes_are_normalized() {
606 let mut cfg = SandboxConfiguration::default();
607 for (size, expected) in [
608 (0, 2),
609 (1, 2),
610 (2, 2),
611 (3, 4),
612 (32_767, 32_768),
613 (32_768, 32_768),
614 (32_769, 32_768),
615 (usize::MAX, 32_768),
616 ] {
617 cfg.set_g2h_queue_size(size);
618 cfg.set_h2g_queue_size(size);
619 assert_eq!(expected, cfg.get_g2h_queue_size());
620 assert_eq!(expected, cfg.get_h2g_queue_size());
621 }
622 }
623
624 #[test]
625 fn buffer_sizes_are_normalized_without_page_rounding() {
626 let mut cfg = SandboxConfiguration::default();
627
628 cfg.set_g2h_buffer_size(0);
629 cfg.set_h2g_buffer_size(0);
630 assert_eq!(256, cfg.get_g2h_buffer_size());
631 assert_eq!(256, cfg.get_h2g_buffer_size());
632
633 cfg.set_g2h_buffer_size(3000);
634 cfg.set_h2g_buffer_size(3001);
635 assert_eq!(3000, cfg.get_g2h_buffer_size());
636 assert_eq!(3001, cfg.get_h2g_buffer_size());
637
638 cfg.set_g2h_buffer_size(usize::MAX);
639 cfg.set_h2g_buffer_size(usize::MAX);
640 assert_eq!(u32::MAX as usize, cfg.get_g2h_buffer_size());
641 assert_eq!(u32::MAX as usize, cfg.get_h2g_buffer_size());
642 }
643
644 #[test]
645 fn pool_page_counts_are_normalized() {
646 let mut cfg = SandboxConfiguration::default();
647
648 cfg.set_g2h_pool_pages(0);
649 cfg.set_h2g_pool_pages(0);
650 assert_eq!(2, cfg.get_g2h_pool_pages());
651 assert_eq!(1, cfg.get_h2g_pool_pages());
652
653 cfg.set_g2h_buffer_size(PAGE_SIZE + 1);
654 cfg.set_h2g_buffer_size(PAGE_SIZE + 1);
655 assert_eq!(3, cfg.get_g2h_pool_pages());
656 assert_eq!(2, cfg.get_h2g_pool_pages());
657
658 cfg.set_g2h_pool_pages(2);
659 cfg.set_h2g_pool_pages(1);
660 assert_eq!(3, cfg.get_g2h_pool_pages());
661 assert_eq!(2, cfg.get_h2g_pool_pages());
662
663 cfg.set_g2h_pool_pages(4);
664 cfg.set_h2g_pool_pages(3);
665 assert_eq!(4, cfg.get_g2h_pool_pages());
666 assert_eq!(3, cfg.get_h2g_pool_pages());
667 }
668
669 mod proptests {
670 use proptest::prelude::*;
671
672 use super::SandboxConfiguration;
673 #[cfg(gdb)]
674 use crate::sandbox::config::DebugInfo;
675
676 proptest! {
677 #[test]
678 fn heap_size_override(size in 0x1000..=0x10000u64) {
679 let mut cfg = SandboxConfiguration::default();
680 cfg.set_heap_size(size);
681 prop_assert_eq!(size, cfg.heap_size_override);
682 }
683
684 #[test]
685 #[cfg(gdb)]
686 fn guest_debug_info(port in 9000..=u16::MAX) {
687 let mut cfg = SandboxConfiguration::default();
688 let debug_info = DebugInfo { port };
689 cfg.set_guest_debug_info(debug_info);
690 prop_assert_eq!(debug_info, *cfg.get_guest_debug_info().as_ref().unwrap());
691 }
692 }
693 }
694}