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    /// Delay between interrupt retries. This duration specifies how long to wait
51    /// between attempts to send signals to the thread running the sandbox's VCPU.
52    /// Multiple retries may be necessary because signals only interrupt the VCPU
53    /// thread when the vcpu thread is in kernel space. There's a narrow window during which a
54    /// signal can be delivered to the thread, but the thread may not yet
55    /// have entered kernel space.
56    interrupt_retry_delay: Duration,
57    /// Offset from `SIGRTMIN` used to determine the signal number for interrupting
58    /// the VCPU thread. The actual signal sent is `SIGRTMIN + interrupt_vcpu_sigrtmin_offset`.
59    ///
60    /// This signal must fall within the valid real-time signal range supported by the host.
61    ///
62    /// Note: Since real-time signals can vary across platforms, ensure that the offset
63    /// results in a signal number that is not already in use by other components of the system.
64    interrupt_vcpu_sigrtmin_offset: u8,
65    /// How much writable memory to offer the guest
66    scratch_size: usize,
67    /// The maximum log level enabled for guest code execution.
68    ///
69    /// If unset, the level is determined from the `RUST_LOG` environment
70    /// variable, defaulting to [`LevelFilter::ERROR`] when no level is found.
71    /// Stored as the guest ABI's numeric log-filter value, with `u64::MAX`
72    /// representing an unset value, to keep this `#[repr(C)]` struct FFI-safe.
73    max_guest_log_level: u64,
74    /// Number of descriptors in the G2H virtqueue.
75    g2h_queue_size: usize,
76    /// Number of descriptors in the H2G virtqueue.
77    h2g_queue_size: usize,
78    /// Capacity of each G2H upper-tier buffer.
79    g2h_buffer_size: usize,
80    /// Capacity of each H2G buffer.
81    h2g_buffer_size: usize,
82    /// Number of pages in the G2H buffer pool.
83    g2h_pool_pages: usize,
84    /// Number of pages in the H2G buffer pool.
85    h2g_pool_pages: usize,
86    /// Declared guest MSRs, stored inline to keep this type `Copy`.
87    #[cfg(target_arch = "x86_64")]
88    guest_msrs: [u32; Self::MAX_GUEST_MSRS],
89    /// Number of valid entries in `guest_msrs`.
90    #[cfg(target_arch = "x86_64")]
91    guest_msrs_count: usize,
92}
93
94impl SandboxConfiguration {
95    /// The default interrupt retry delay
96    pub const DEFAULT_INTERRUPT_RETRY_DELAY: Duration = Duration::from_micros(500);
97    /// The default signal offset from `SIGRTMIN` used to determine the signal number for interrupting
98    pub const INTERRUPT_VCPU_SIGRTMIN_OFFSET: u8 = 0;
99    /// Scratch backs the guest heap and stack, transport pools, page
100    /// tables, and exception stack.
101    /// The size is 16 KiB aligned for macOS hosts.
102    /// TODO: revisit when https://github.com/hyperlight-dev/hyperlight/issues/1925 is fixed
103    pub const DEFAULT_SCRATCH_SIZE: usize = 0x64000;
104    /// The default G2H virtqueue descriptor count.
105    pub const DEFAULT_G2H_QUEUE_SIZE: usize = 64;
106    /// The default H2G virtqueue descriptor count.
107    pub const DEFAULT_H2G_QUEUE_SIZE: usize = 32;
108    /// The default G2H upper-tier buffer size.
109    pub const DEFAULT_G2H_BUFFER_SIZE: usize = PAGE_SIZE;
110    /// The default H2G buffer size.
111    pub const DEFAULT_H2G_BUFFER_SIZE: usize = PAGE_SIZE;
112    /// The default total number of G2H pool pages.
113    pub const DEFAULT_G2H_POOL_PAGES: usize = 12;
114    /// The default total number of H2G pool pages.
115    pub const DEFAULT_H2G_POOL_PAGES: usize = 8;
116    /// The minimum G2H virtqueue descriptor count.
117    const MIN_QUEUE_SIZE: usize = 2;
118    /// The maximum G2H virtqueue descriptor count.
119    const MAX_QUEUE_SIZE: usize = 32_768;
120    /// The minimum configured transport buffer size.
121    const MIN_BUFFER_SIZE: usize = G2H_LOWER_SLOT_SIZE;
122    /// The maximum configured transport buffer size.
123    const MAX_BUFFER_SIZE: usize = u32::MAX as usize;
124    /// Maximum number of distinct guest MSRs that can be declared.
125    /// KVM supports at most 16 MSR filter ranges. Each index may require its
126    /// own range, so 16 is the portable limit across backends.
127    #[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    /// Create a new configuration for a sandbox with the given sizes.
132    #[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    /// Sets the interrupt retry delay
163    #[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    /// Get the delay between retries for interrupts
169    #[cfg(any(kvm, mshv3, hvf))]
170    pub fn get_interrupt_retry_delay(&self) -> Duration {
171        self.interrupt_retry_delay
172    }
173
174    /// Get the signal offset from `SIGRTMIN` used to determine the signal number for interrupting the VCPU thread
175    #[cfg(target_os = "linux")]
176    pub fn get_interrupt_vcpu_sigrtmin_offset(&self) -> u8 {
177        self.interrupt_vcpu_sigrtmin_offset
178    }
179
180    /// Declares the MSRs the guest depends on.
181    ///
182    /// A declared MSR's value is part of the sandbox's saved state: captured by
183    /// [`Sandbox::snapshot`](crate::Sandbox::snapshot) and written
184    /// back on [`Sandbox::restore`](crate::Sandbox::restore). Every
185    /// MSR you do not declare is reset to a clean default on each restore.
186    ///
187    /// If this method is not called, only a small core of essential CPU state
188    /// (kernel GS base, TSC) is saved and restored.
189    ///
190    /// # Platform-specific behavior
191    ///
192    /// * On KVM, declaring an MSR is also what lets the guest access it. The
193    ///   guest faults on any `RDMSR`/`WRMSR` of an undeclared MSR.
194    /// * On MSHV and WHP there is no such enforcement, so declaration only
195    ///   controls what is saved and restored, not what the guest may touch.
196    ///
197    /// Duplicate indices, within the slice or against the existing set, are
198    /// ignored and do not count toward capacity.
199    ///
200    /// # Errors
201    ///
202    /// Returns [`GuestMsrError::CapacityExceeded`] if the distinct entries
203    /// would exceed [`Self::MAX_GUEST_MSRS`]. The declared set is unchanged on
204    /// error.
205    #[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    /// Returns the declared guest MSRs.
231    #[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    /// Sets the offset from `SIGRTMIN` to determine the real-time signal used for
238    /// interrupting the VCPU thread.
239    ///
240    /// The final signal number is computed as `SIGRTMIN + offset`, and it must fall within
241    /// the valid range of real-time signals supported by the host system.
242    ///
243    /// Returns Ok(()) if the offset is valid, or an error if it exceeds the maximum real-time signal number.
244    #[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    /// Toggles the guest core dump generation for a sandbox
257    /// Setting this to false disables the core dump generation
258    /// This is only used when the `crashdump` feature is enabled
259    #[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    /// Sets the configuration for the guest debug
266    #[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    /// Set how much writable memory to offer the guest. Scratch backs the
278    /// guest heap and stack.
279    #[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    /// Sets the maximum log level for guest code execution.
285    ///
286    /// If not set, the level is determined from the `RUST_LOG` environment
287    /// variable, defaulting to [`LevelFilter::ERROR`] when no level is found.
288    #[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    /// Get the G2H virtqueue descriptor count.
304    #[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    /// Set the G2H virtqueue descriptor count.
310    ///
311    /// Values are rounded up to a power of two in `2..=32768`.
312    #[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    /// Get the H2G virtqueue descriptor count.
318    #[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    /// Set the H2G virtqueue descriptor count.
324    ///
325    /// Values are rounded up to a power of two in `2..=32768`.
326    #[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    /// Get the capacity of each G2H upper-tier buffer.
332    #[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    /// Set the capacity of each G2H upper-tier buffer.
338    ///
339    /// Values are clamped to `256..=u32::MAX`.
340    #[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    /// Get the capacity of each H2G buffer.
350    #[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    /// Set the capacity of each H2G buffer.
356    ///
357    /// Values are clamped to `256..=u32::MAX`.
358    #[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    /// Get the total number of G2H pool pages.
368    #[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    /// Set the total number of G2H pool pages.
374    ///
375    /// The pool contains one lower-tier page and at least one upper buffer.
376    #[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    /// Get the total number of H2G pool pages.
382    #[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    /// Set the total number of H2G pool pages.
388    ///
389    /// The pool contains at least one H2G buffer.
390    #[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        // 0x10 already present, 0x20 and 0x30 added once each in first-seen order.
507        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        // One slot remains. Three copies of one new index count as a single
517        // distinct entry and fit.
518        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}