pub struct SandboxConfiguration { /* private fields */ }Expand description
The complete set of configuration needed to create a Sandbox
Implementations§
Source§impl SandboxConfiguration
impl SandboxConfiguration
Sourcepub const DEFAULT_INTERRUPT_RETRY_DELAY: Duration
pub const DEFAULT_INTERRUPT_RETRY_DELAY: Duration
The default interrupt retry delay
Sourcepub const INTERRUPT_VCPU_SIGRTMIN_OFFSET: u8 = 0
pub const INTERRUPT_VCPU_SIGRTMIN_OFFSET: u8 = 0
The default signal offset from SIGRTMIN used to determine the signal number for interrupting
Sourcepub const DEFAULT_HEAP_SIZE: u64 = 131072
pub const DEFAULT_HEAP_SIZE: u64 = 131072
The default heap size of a hyperlight sandbox
Sourcepub const DEFAULT_SCRATCH_SIZE: usize = 0x64000
pub const DEFAULT_SCRATCH_SIZE: usize = 0x64000
Scratch backs the default heap, transport pools, page tables, and exception stack. The size is 16 KiB aligned for macOS hosts. TODO: revisit when https://github.com/hyperlight-dev/hyperlight/issues/1925 is fixed
Sourcepub const DEFAULT_G2H_QUEUE_SIZE: usize = 64
pub const DEFAULT_G2H_QUEUE_SIZE: usize = 64
The default G2H virtqueue descriptor count.
Sourcepub const DEFAULT_H2G_QUEUE_SIZE: usize = 32
pub const DEFAULT_H2G_QUEUE_SIZE: usize = 32
The default H2G virtqueue descriptor count.
Sourcepub const DEFAULT_G2H_BUFFER_SIZE: usize = PAGE_SIZE
pub const DEFAULT_G2H_BUFFER_SIZE: usize = PAGE_SIZE
The default G2H upper-tier buffer size.
Sourcepub const DEFAULT_H2G_BUFFER_SIZE: usize = PAGE_SIZE
pub const DEFAULT_H2G_BUFFER_SIZE: usize = PAGE_SIZE
The default H2G buffer size.
Sourcepub const DEFAULT_G2H_POOL_PAGES: usize = 12
pub const DEFAULT_G2H_POOL_PAGES: usize = 12
The default total number of G2H pool pages.
Sourcepub const DEFAULT_H2G_POOL_PAGES: usize = 8
pub const DEFAULT_H2G_POOL_PAGES: usize = 8
The default total number of H2G pool pages.
Sourcepub const MAX_GUEST_MSRS: usize = 16
pub const MAX_GUEST_MSRS: usize = 16
Maximum number of distinct guest MSRs that can be declared. KVM supports at most 16 MSR filter ranges. Each index may require its own range, so 16 is the portable limit across backends.
Sourcepub fn set_heap_size(&mut self, heap_size: u64)
pub fn set_heap_size(&mut self, heap_size: u64)
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
Sourcepub fn set_interrupt_retry_delay(&mut self, delay: Duration)
pub fn set_interrupt_retry_delay(&mut self, delay: Duration)
Sets the interrupt retry delay
Sourcepub fn get_interrupt_retry_delay(&self) -> Duration
pub fn get_interrupt_retry_delay(&self) -> Duration
Get the delay between retries for interrupts
Sourcepub fn get_interrupt_vcpu_sigrtmin_offset(&self) -> u8
pub fn get_interrupt_vcpu_sigrtmin_offset(&self) -> u8
Get the signal offset from SIGRTMIN used to determine the signal number for interrupting the VCPU thread
Sourcepub fn guest_msrs(
&mut self,
indices: &[u32],
) -> Result<&mut Self, GuestMsrError>
pub fn guest_msrs( &mut self, indices: &[u32], ) -> Result<&mut Self, GuestMsrError>
Declares the MSRs the guest depends on.
A declared MSR’s value is part of the sandbox’s saved state: captured by
Sandbox::snapshot and written
back on Sandbox::restore. Every
MSR you do not declare is reset to a clean default on each restore.
If this method is not called, only a small core of essential CPU state (kernel GS base, TSC) is saved and restored.
§Platform-specific behavior
- On KVM, declaring an MSR is also what lets the guest access it. The
guest faults on any
RDMSR/WRMSRof an undeclared MSR. - On MSHV and WHP there is no such enforcement, so declaration only controls what is saved and restored, not what the guest may touch.
Duplicate indices, within the slice or against the existing set, are ignored and do not count toward capacity.
§Errors
Returns GuestMsrError::CapacityExceeded if the distinct entries
would exceed Self::MAX_GUEST_MSRS. The declared set is unchanged on
error.
Sourcepub fn set_interrupt_vcpu_sigrtmin_offset(&mut self, offset: u8) -> Result<()>
pub fn set_interrupt_vcpu_sigrtmin_offset(&mut self, offset: u8) -> Result<()>
Sets the offset from SIGRTMIN to determine the real-time signal used for
interrupting the VCPU thread.
The final signal number is computed as SIGRTMIN + offset, and it must fall within
the valid range of real-time signals supported by the host system.
Returns Ok(()) if the offset is valid, or an error if it exceeds the maximum real-time signal number.
Sourcepub fn set_scratch_size(&mut self, scratch_size: usize)
pub fn set_scratch_size(&mut self, scratch_size: usize)
Set the size of the scratch regiong
Sourcepub fn set_max_guest_log_level(&mut self, log_level: LevelFilter)
pub fn set_max_guest_log_level(&mut self, log_level: LevelFilter)
Sets the maximum log level for guest code execution.
If not set, the level is determined from the RUST_LOG environment
variable, defaulting to LevelFilter::ERROR when no level is found.
Sourcepub fn get_g2h_queue_size(&self) -> usize
pub fn get_g2h_queue_size(&self) -> usize
Get the G2H virtqueue descriptor count.
Sourcepub fn set_g2h_queue_size(&mut self, size: usize)
pub fn set_g2h_queue_size(&mut self, size: usize)
Set the G2H virtqueue descriptor count.
Values are rounded up to a power of two in 2..=32768.
Sourcepub fn get_h2g_queue_size(&self) -> usize
pub fn get_h2g_queue_size(&self) -> usize
Get the H2G virtqueue descriptor count.
Sourcepub fn set_h2g_queue_size(&mut self, size: usize)
pub fn set_h2g_queue_size(&mut self, size: usize)
Set the H2G virtqueue descriptor count.
Values are rounded up to a power of two in 2..=32768.
Sourcepub fn get_g2h_buffer_size(&self) -> usize
pub fn get_g2h_buffer_size(&self) -> usize
Get the capacity of each G2H upper-tier buffer.
Sourcepub fn set_g2h_buffer_size(&mut self, size: usize)
pub fn set_g2h_buffer_size(&mut self, size: usize)
Set the capacity of each G2H upper-tier buffer.
Values are clamped to 256..=u32::MAX.
Sourcepub fn get_h2g_buffer_size(&self) -> usize
pub fn get_h2g_buffer_size(&self) -> usize
Get the capacity of each H2G buffer.
Sourcepub fn set_h2g_buffer_size(&mut self, size: usize)
pub fn set_h2g_buffer_size(&mut self, size: usize)
Set the capacity of each H2G buffer.
Values are clamped to 256..=u32::MAX.
Sourcepub fn get_g2h_pool_pages(&self) -> usize
pub fn get_g2h_pool_pages(&self) -> usize
Get the total number of G2H pool pages.
Sourcepub fn set_g2h_pool_pages(&mut self, pages: usize)
pub fn set_g2h_pool_pages(&mut self, pages: usize)
Set the total number of G2H pool pages.
The pool contains one lower-tier page and at least one upper buffer.
Sourcepub fn get_h2g_pool_pages(&self) -> usize
pub fn get_h2g_pool_pages(&self) -> usize
Get the total number of H2G pool pages.
Sourcepub fn set_h2g_pool_pages(&mut self, pages: usize)
pub fn set_h2g_pool_pages(&mut self, pages: usize)
Set the total number of H2G pool pages.
The pool contains at least one H2G buffer.