Struct MachineBuilder 

pub struct MachineBuilder { /* private fields */ }

Builder for machine configuration (vCPUs, memory, etc.).

Example

VmBuilder::new()
    .machine(|m| {
        m.vcpus(4)
            .memory_mib(2048)
            .hyperthreading(true)
            .nested_virt(true)
    });

Implementations

impl MachineBuilder

pub fn new() -> Self

Create a new machine builder with defaults.

pub fn vcpus(self, count: u8) -> Self

Set the number of virtual CPUs.

pub fn memory_mib(self, mib: usize) -> Self

Set the memory size in MiB.

pub fn max_vcpus(self, count: u8) -> Self

Set the maximum possible virtual CPUs.

The VM boots with this full topology described to the guest but only vcpus online (maxcpus= boot parameter); the guest can online the remaining CPUs later through CPU hotplug. Defaults to the effective vCPU count, which reserves no extra capacity.

pub fn max_memory_mib(self, mib: usize) -> Self

Set the maximum guest memory in MiB reserved for future memory hotplug.

Currently configuration plumbing only: capacity above memory_mib is validated and recorded but not yet consumed until the virtio-mem device lands. Defaults to the effective memory size, which reserves no extra capacity.

pub fn hyperthreading(self, enabled: bool) -> Self

Enable or disable hyperthreading.

pub fn nested_virt(self, enabled: bool) -> Self

Enable or disable nested virtualization.

pub fn split_irqchip(self, enabled: bool) -> Self

Enable the userspace split irqchip on x86_64.

The default in-kernel IOAPIC is hardcoded by KVM to 24 pins, leaving only 11 IRQs for virtio-mmio devices. The userspace split irqchip emulates a larger IOAPIC (256 pins) and raises the usable range to 219 IRQs, which is needed for VMs with many virtio-mmio devices (e.g. lots of virtio-fs mounts or block devices). No effect on aarch64 or riscv64.

pub fn vsock(self, enabled: bool) -> Self

Force-attach a virtio-vsock device to the guest.

By default, vsock is only attached when needed as a TSI transport (no virtio-net → HIJACK_INET, or single root virtio-fs on Linux → HIJACK_UNIX). Set this to true when the guest needs a vsock for its own purposes even though TSI would not otherwise require one.

pub fn balloon(self, enabled: bool) -> Self

Enable or disable the virtio-balloon device.

The device is enabled by default for general-purpose VMs. Latency-sensitive guests that never resize memory can disable it to avoid one virtio-mmio device and its guest-side probe.

pub fn balloon_stats_interval(self, interval: Option<Duration>) -> Self

Set the virtio-balloon guest memory statistics polling interval.

Some(interval) advertises and drives the stats queue at the requested cadence. None disables balloon stats polling while still allowing the balloon device itself to be attached.

pub fn rng(self, enabled: bool) -> Self

Enable or disable the virtio-rng device.

The device is enabled by default. Guests with a known nonblocking boot path can disable it to remove one virtio-mmio device from cold start.

pub fn msb_metrics(self, enabled: bool) -> Self

Enable or disable the private microsandbox metrics virtio device.

The device is enabled by default so protected guest filesystem metrics are available for bundled microsandbox kernels.

pub fn enable_inet_hijack(self, enabled: bool) -> Self

Enable the automatic TSI INET hijack fallback.

When set to true and no virtio-net device is configured, TsiFlags::HIJACK_INET is enabled so the guest’s INET socket calls are transparently bridged to the host through vsock. This is useful for guests that need outbound connectivity without the caller setting up a virtio-net backend.

Defaults to false — guests with no virtio-net are air-gapped by default. Callers must opt in to TSI when they want host network access without an explicit network device.

Note: HIJACK_UNIX (used by virtio-fs on Linux for AF_UNIX hijack) is gated on HIJACK_INET already being set, so leaving INET hijack off also leaves the UNIX hijack auto-enable path off.

Trait Implementations

impl Clone for MachineBuilder

fn clone(&self) -> MachineBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MachineBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MachineBuilder

fn default() -> Self

Returns the “default value” for a type.