Skip to main content

hyperlight_host/sandbox/
config.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4use 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/// Used for passing debug configuration to a sandbox
16#[cfg(gdb)]
17#[derive(Copy, Clone, Debug, Eq, PartialEq)]
18pub struct DebugInfo {
19    /// Guest debug port
20    pub port: u16,
21}
22
23/// Errors returned when declaring guest MSRs.
24#[cfg(target_arch = "x86_64")]
25#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
26pub enum GuestMsrError {
27    /// The declared MSR set exceeds its fixed capacity.
28    #[error("declared guest MSRs exceed the maximum of {maximum} distinct entries")]
29    CapacityExceeded {
30        /// Maximum number of distinct declared MSRs.
31        maximum: usize,
32    },
33}
34
35/// The complete set of configuration needed to create a Sandbox
36#[derive(Copy, Clone, Debug, Eq, PartialEq)]
37#[repr(C)]
38pub struct SandboxConfiguration {
39    /// Guest core dump output directory
40    /// This field is by default set to true which means the value core dumps will be placed in:
41    /// - HYPERLIGHT_CORE_DUMP_DIR environment variable if it is set
42    /// - default value of the temporary directory
43    ///
44    /// The core dump files generation can be disabled by setting this field to false.
45    #[cfg(crashdump)]
46    guest_core_dump: bool,
47    /// Guest gdb debug port
48    #[cfg(gdb)]
49    guest_debug_info: Option<DebugInfo>,
50    /// The heap size to use in the guest sandbox. If set to 0, the heap
51    /// size will be determined from the PE file header
52    ///
53    /// Note: this is a C-compatible struct, so even though this optional
54    /// field should be represented as an `Option`, that type is not
55    /// FFI-safe, so it cannot be.
56    heap_size_override: u64,
57    /// Delay between interrupt retries. This duration specifies how long to wait
58    /// between attempts to send signals to the thread running the sandbox's VCPU.
59    /// Multiple retries may be necessary because signals only interrupt the VCPU
60    /// thread when the vcpu thread is in kernel space. There's a narrow window during which a
61    /// signal can be delivered to the thread, but the thread may not yet
62    /// have entered kernel space.
63    interrupt_retry_delay: Duration,
64    /// Offset from `SIGRTMIN` used to determine the signal number for interrupting
65    /// the VCPU thread. The actual signal sent is `SIGRTMIN + interrupt_vcpu_sigrtmin_offset`.
66    ///
67    /// This signal must fall within the valid real-time signal range supported by the host.
68    ///
69    /// Note: Since real-time signals can vary across platforms, ensure that the offset
70    /// results in a signal number that is not already in use by other components of the system.
71    interrupt_vcpu_sigrtmin_offset: u8,
72    /// How much writable memory to offer the guest
73    scratch_size: usize,
74    /// The maximum log level enabled for guest code execution.
75    ///
76    /// If unset, the level is determined from the `RUST_LOG` environment
77    /// variable, defaulting to [`LevelFilter::ERROR`] when no level is found.
78    /// Stored as the guest ABI's numeric log-filter value, with `u64::MAX`
79    /// representing an unset value, to keep this `#[repr(C)]` struct FFI-safe.
80    max_guest_log_level: u64,
81    /// Number of descriptors in the G2H virtqueue.
82    g2h_queue_size: usize,
83    /// Number of descriptors in the H2G virtqueue.
84    h2g_queue_size: usize,
85    /// Capacity of each G2H upper-tier buffer.
86    g2h_buffer_size: usize,
87    /// Capacity of each H2G buffer.
88    h2g_buffer_size: usize,
89    /// Number of pages in the G2H buffer pool.
90    g2h_pool_pages: usize,
91    /// Number of pages in the H2G buffer pool.
92    h2g_pool_pages: usize,
93    /// Declared guest MSRs, stored inline to keep this type `Copy`.
94    #[cfg(target_arch = "x86_64")]
95    guest_msrs: [u32; Self::MAX_GUEST_MSRS],
96    /// Number of valid entries in `guest_msrs`.
97    #[cfg(target_arch = "x86_64")]
98    guest_msrs_count: usize,
99}
100
101impl SandboxConfiguration {
102    /// The default interrupt retry delay
103    pub const DEFAULT_INTERRUPT_RETRY_DELAY: Duration = Duration::from_micros(500);
104    /// The default signal offset from `SIGRTMIN` used to determine the signal number for interrupting
105    pub const INTERRUPT_VCPU_SIGRTMIN_OFFSET: u8 = 0;
106    /// The default heap size of a hyperlight sandbox
107    pub const DEFAULT_HEAP_SIZE: u64 = 131072;
108    /// Scratch backs the default heap, transport pools, page tables, and exception stack.
109    /// The size is 16 KiB aligned for macOS hosts.
110    /// TODO: revisit when https://github.com/hyperlight-dev/hyperlight/issues/1925 is fixed
111    pub const DEFAULT_SCRATCH_SIZE: usize = 0x64000;
112    /// The default G2H virtqueue descriptor count.
113    pub const DEFAULT_G2H_QUEUE_SIZE: usize = 64;
114    /// The default H2G virtqueue descriptor count.
115    pub const DEFAULT_H2G_QUEUE_SIZE: usize = 32;
116    /// The default G2H upper-tier buffer size.
117    pub const DEFAULT_G2H_BUFFER_SIZE: usize = PAGE_SIZE;
118    /// The default H2G buffer size.
119    pub const DEFAULT_H2G_BUFFER_SIZE: usize = PAGE_SIZE;
120    /// The default total number of G2H pool pages.
121    pub const DEFAULT_G2H_POOL_PAGES: usize = 12;
122    /// The default total number of H2G pool pages.
123    pub const DEFAULT_H2G_POOL_PAGES: usize = 8;
124    /// The minimum G2H virtqueue descriptor count.
125    const MIN_QUEUE_SIZE: usize = 2;
126    /// The maximum G2H virtqueue descriptor count.
127    const MAX_QUEUE_SIZE: usize = 32_768;
128    /// The minimum configured transport buffer size.
129    const MIN_BUFFER_SIZE: usize = G2H_LOWER_SLOT_SIZE;
130    /// The maximum configured transport buffer size.
131    const MAX_BUFFER_SIZE: usize = u32::MAX as usize;
132    /// Maximum number of distinct guest MSRs that can be declared.
133    /// KVM supports at most 16 MSR filter ranges. Each index may require its
134    /// own range, so 16 is the portable limit across backends.
135    #[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    /// Create a new configuration for a sandbox with the given sizes.
140    #[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    /// Set the heap size to use in the guest sandbox. If set to 0, the heap size will be determined from the PE file header
173    #[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    /// Sets the interrupt retry delay
179    #[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    /// Get the delay between retries for interrupts
185    #[cfg(any(kvm, mshv3, hvf))]
186    pub fn get_interrupt_retry_delay(&self) -> Duration {
187        self.interrupt_retry_delay
188    }
189
190    /// Get the signal offset from `SIGRTMIN` used to determine the signal number for interrupting the VCPU thread
191    #[cfg(target_os = "linux")]
192    pub fn get_interrupt_vcpu_sigrtmin_offset(&self) -> u8 {
193        self.interrupt_vcpu_sigrtmin_offset
194    }
195
196    /// Declares the MSRs the guest depends on.
197    ///
198    /// A declared MSR's value is part of the sandbox's saved state: captured by
199    /// [`Sandbox::snapshot`](crate::Sandbox::snapshot) and written
200    /// back on [`Sandbox::restore`](crate::Sandbox::restore). Every
201    /// MSR you do not declare is reset to a clean default on each restore.
202    ///
203    /// If this method is not called, only a small core of essential CPU state
204    /// (kernel GS base, TSC) is saved and restored.
205    ///
206    /// # Platform-specific behavior
207    ///
208    /// * On KVM, declaring an MSR is also what lets the guest access it. The
209    ///   guest faults on any `RDMSR`/`WRMSR` of an undeclared MSR.
210    /// * On MSHV and WHP there is no such enforcement, so declaration only
211    ///   controls what is saved and restored, not what the guest may touch.
212    ///
213    /// Duplicate indices, within the slice or against the existing set, are
214    /// ignored and do not count toward capacity.
215    ///
216    /// # Errors
217    ///
218    /// Returns [`GuestMsrError::CapacityExceeded`] if the distinct entries
219    /// would exceed [`Self::MAX_GUEST_MSRS`]. The declared set is unchanged on
220    /// error.
221    #[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    /// Returns the declared guest MSRs.
247    #[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    /// Sets the offset from `SIGRTMIN` to determine the real-time signal used for
254    /// interrupting the VCPU thread.
255    ///
256    /// The final signal number is computed as `SIGRTMIN + offset`, and it must fall within
257    /// the valid range of real-time signals supported by the host system.
258    ///
259    /// Returns Ok(()) if the offset is valid, or an error if it exceeds the maximum real-time signal number.
260    #[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    /// Toggles the guest core dump generation for a sandbox
273    /// Setting this to false disables the core dump generation
274    /// This is only used when the `crashdump` feature is enabled
275    #[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    /// Sets the configuration for the guest debug
282    #[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    /// Set the size of the scratch regiong
294    #[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    /// Sets the maximum log level for guest code execution.
300    ///
301    /// If not set, the level is determined from the `RUST_LOG` environment
302    /// variable, defaulting to [`LevelFilter::ERROR`] when no level is found.
303    #[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    /// Get the G2H virtqueue descriptor count.
319    #[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    /// Set the G2H virtqueue descriptor count.
325    ///
326    /// Values are rounded up to a power of two in `2..=32768`.
327    #[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    /// Get the H2G virtqueue descriptor count.
333    #[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    /// Set the H2G virtqueue descriptor count.
339    ///
340    /// Values are rounded up to a power of two in `2..=32768`.
341    #[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    /// Get the capacity of each G2H upper-tier buffer.
347    #[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    /// Set the capacity of each G2H upper-tier buffer.
353    ///
354    /// Values are clamped to `256..=u32::MAX`.
355    #[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    /// Get the capacity of each H2G buffer.
365    #[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    /// Set the capacity of each H2G buffer.
371    ///
372    /// Values are clamped to `256..=u32::MAX`.
373    #[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    /// Get the total number of G2H pool pages.
383    #[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    /// Set the total number of G2H pool pages.
389    ///
390    /// The pool contains one lower-tier page and at least one upper buffer.
391    #[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    /// Get the total number of H2G pool pages.
397    #[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    /// Set the total number of H2G pool pages.
403    ///
404    /// The pool contains at least one H2G buffer.
405    #[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    /// If self.heap_size_override is non-zero, return it. Otherwise,
428    /// return exe_info.heap_reserve()
429    #[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        // 0x10 already present, 0x20 and 0x30 added once each in first-seen order.
536        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        // One slot remains. Three copies of one new index count as a single
546        // distinct entry and fit.
547        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}