Struct PetriVmBuilder 

pub struct PetriVmBuilder<T: PetriVmmBackend> { /* private fields */ }

Petri VM builder

Implementations

impl<T: PetriVmmBackend> PetriVmBuilder<T>

pub fn new( params: PetriTestParams<'_>, artifacts: PetriVmArtifacts<T>, driver: &DefaultDriver, ) -> Result<Self>

Create a new VM configuration.

pub fn minimal( params: PetriTestParams<'_>, artifacts: PetriVmArtifacts<T>, driver: &DefaultDriver, ) -> Result<Self>

Create a minimal VM builder with only the bare minimum device set.

Unlike new(), this constructor:

• Does not add default VMBus devices (shutdown IC, KVP, etc.)
• Does not add serial ports
• Does not add SCSI controllers or crash dump disks
• Does not verify save/restore on boot

Use builder methods to opt in to specific devices. Intended for performance tests where minimal overhead is critical.

pub fn is_minimal(&self) -> bool

Whether this builder is in minimal mode.

pub fn with_prebuilt_initrd(self, path: PathBuf) -> Self

Supply a pre-built initrd with pipette already injected.

When set, the builder skips the runtime gzip decompress/inject/ recompress cycle, using this initrd directly. Use prepare_initrd to build the initrd ahead of time.

pub fn prepare_initrd(&self) -> Result<TempPath>

Pre-build the modified initrd with pipette injected.

Reads the original initrd from the firmware artifacts, injects the pipette binary via CPIO, and writes the result to a temp file. Returns the path to the temp file. The caller must keep the TempPath alive until after the VM boots.

Call this once before timing, then pass the path to with_prebuilt_initrd for each iteration.

pub fn with_serial_output(self) -> Self

Enable serial port output even in minimal mode.

Useful for diagnostics — the serial device overhead is negligible; the cost comes from kernel console output, which is controlled via the kernel cmdline (quiet loglevel=0).

Note: this currently only affects LinuxDirect boot (kernel cmdline and emulated serial backends). UEFI paths are unaffected.

pub fn without_serial_output(self) -> Self

Disable serial port output.

Suppresses serial device creation, eliminating the [uefi] / [openhcl] log lines. Useful for performance tests where serial noise is unwanted.

pub fn without_screenshots(self) -> Self

Disable periodic framebuffer screenshots.

Suppresses the watchdog task that takes screenshots every 2 seconds, eliminating the “No change in framebuffer” debug log lines.

pub fn properties(&self) -> PetriVmProperties

Get properties about the vm for convenience

pub fn using_vtl0_pipette(&self) -> bool

Whether this VM is using pipette in VTL0

pub async fn run_without_agent(self) -> Result<PetriVm<T>>

Build and run the VM, then wait for the VM to emit the expected boot event (if configured). Does not configure and start pipette. Should only be used for testing platforms that pipette does not support.

pub async fn run(self) -> Result<(PetriVm<T>, PipetteClient)>

Build and run the VM, then wait for the VM to emit the expected boot event (if configured). Launches pipette and returns a client to it.

pub fn with_expect_boot_failure(self) -> Self

Configure the test to expect a boot failure from the VM. Useful for negative tests.

pub fn with_expect_no_boot_event(self) -> Self

Configure the test to not expect any boot event. Useful for tests that do not boot a VTL0 guest.

pub fn with_expect_reset(self) -> Self

Allow the VM to reset once at the beginning of the test. Should only be used if you are using a special VM configuration that causes the guest to reboot when it usually wouldn’t.

pub fn with_secure_boot(self) -> Self

Set the VM to enable secure boot and inject the templates per OS flavor.

pub fn with_windows_secure_boot_template(self) -> Self

Inject Windows secure boot templates into the VM’s UEFI.

pub fn with_uefi_ca_secure_boot_template(self) -> Self

Inject UEFI CA secure boot templates into the VM’s UEFI.

pub fn with_processor_topology(self, topology: ProcessorTopology) -> Self

Set the VM to use the specified processor topology.

pub fn with_memory(self, memory: MemoryConfig) -> Self

Set the VM to use the specified memory config.

pub fn with_vtl2_base_address_type( self, address_type: Vtl2BaseAddressType, ) -> Self

Sets a custom OpenHCL IGVM VTL2 address type. This controls the behavior of where VTL2 is placed in address space, and also the total size of memory allocated for VTL2. VTL2 start will fail if address_type is specified and leads to the loader allocating less memory than what is in the IGVM file.

pub fn with_custom_openhcl( self, artifact: ResolvedArtifact<impl IsOpenhclIgvm>, ) -> Self

Sets a custom OpenHCL IGVM file to use.

pub fn with_openhcl_command_line(self, additional_command_line: &str) -> Self

Append additional command line arguments to pass to the paravisor.

pub fn with_confidential_filtering(self) -> Self

Enable confidential filtering, even if the VM is not confidential.

pub fn with_openhcl_log_levels(self, levels: OpenvmmLogConfig) -> Self

Sets the command line parameters passed to OpenHCL related to logging.

pub fn with_host_log_levels(self, levels: OpenvmmLogConfig) -> Self

Sets the log levels for the host OpenVMM process. DEVNOTE: In the future, this could be generalized for both HyperV and OpenVMM. For now, this is only implemented for OpenVMM.

pub fn with_agent_file(self, name: &str, artifact: ResolvedArtifact) -> Self

Adds a file to the VM’s pipette agent image.

pub fn with_openhcl_agent_file( self, name: &str, artifact: ResolvedArtifact, ) -> Self

Adds a file to the paravisor’s pipette agent image.

pub fn with_uefi_frontpage(self, enable: bool) -> Self

Sets whether UEFI frontpage is enabled.

pub fn with_default_boot_always_attempt(self, enable: bool) -> Self

Sets whether UEFI should always attempt a default boot.

pub fn with_vmbus_redirect(self, enable: bool) -> Self

Run the VM with Enable VMBus relay enabled

pub fn with_guest_state_lifetime( self, guest_state_lifetime: PetriGuestStateLifetime, ) -> Self

Specify the guest state lifetime for the VM

pub fn with_guest_state_encryption( self, policy: GuestStateEncryptionPolicy, ) -> Self

Specify the guest state encryption policy for the VM

pub fn with_initial_vmgs(self, disk: ResolvedArtifact<impl IsTestVmgs>) -> Self

Use the specified backing VMGS file

pub fn with_persistent_vmgs(self, disk: impl AsRef<Path>) -> Self

Use the specified backing VMGS file

pub fn with_boot_device_type(self, boot: BootDeviceType) -> Self

Set the boot device type for the VM.

This overrides the default, which is determined by the firmware type.

pub fn with_tpm(self, enable: bool) -> Self

Enable the TPM for the VM.

pub fn with_tpm_state_persistence(self, tpm_state_persistence: bool) -> Self

Enable or disable the TPM state persistence for the VM.

pub fn with_custom_vtl2_settings( self, f: impl FnOnce(&mut Vtl2Settings) + 'static + Send + Sync, ) -> Self

Add custom VTL 2 settings.

pub fn add_vtl2_storage_controller(self, controller: StorageController) -> Self

Add a storage controller to VTL2

pub fn add_vmbus_storage_controller( self, id: &Guid, target_vtl: Vtl, controller_type: VmbusStorageType, ) -> Self

Add an additional SCSI controller to the VM.

pub fn add_vmbus_drive( self, drive: Drive, controller_id: &Guid, controller_location: Option<u32>, ) -> Self

Add a VMBus disk drive to the VM

pub fn add_ide_drive( self, drive: Drive, controller_number: u32, controller_location: u8, ) -> Self

Add a VMBus disk drive to the VM

pub fn os_flavor(&self) -> OsFlavor

Get VM’s guest OS flavor

pub fn is_openhcl(&self) -> bool

Get whether the VM will use OpenHCL

pub fn isolation(&self) -> Option<IsolationType>

Get the isolation type of the VM

pub fn arch(&self) -> MachineArch

Get the machine architecture

pub fn log_source(&self) -> &PetriLogSource

Get the log source for creating additional log files.

pub fn default_servicing_flags(&self) -> OpenHclServicingFlags

Get the default OpenHCL servicing flags for this config

pub fn modify_backend( self, f: impl FnOnce(T::VmmConfig) -> T::VmmConfig + 'static + Send, ) -> Self

Get the backend-specific config builder

Trait Implementations

impl<T: PetriVmmBackend> Debug for PetriVmBuilder<T>

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

Formats the value using the given formatter.