Struct VirtualMachineInstance 

pub struct VirtualMachineInstance<Gic> { /* private fields */ }

Represents the unique virtual machine instance of the current process.

This object can be safely shared among threads and guarantees the VM to exist as long as this handle does.

Implementations

impl VirtualMachineInstance<GicEnabled>

pub fn gic_reset(&self) -> Result<()>

Resets the GIC device.

Discussion

When the virtual machine is being reset, call this function to reset the GIC distributor, redistributor registers and the internal state of the device.

pub fn gic_state_create(&self) -> Result<GicState>

Creates a global interrupt controller configuration object.

pub fn gic_set_spi(&self, intid: u32, level: bool) -> Result<()>

Trigger a Shared Peripheral Interrupt (SPI).

pub fn gic_send_msi(&self, address: hv_ipa_t, intid: u32) -> Result<()>

Send a Message Signaled Interrupt (MSI).

pub fn gic_get_distributor_reg(&self, reg: GicDistributorReg) -> Result<u64>

Read a GIC distributor register.

pub fn gic_set_distributor_reg( &self, reg: GicDistributorReg, value: u64, ) -> Result<()>

Write a GIC distributor register.

pub fn gic_get_msi_reg(&self, reg: GicMsiReg) -> Result<u64>

Read a GIC distributor MSI register.

pub fn gic_set_msi_reg(&self, reg: GicMsiReg, value: u64) -> Result<()>

Write a GIC distributor MSI register.

impl<Gic> VirtualMachineInstance<Gic>

pub fn vcpu_create(&self) -> Result<Vcpu>

Creates a new vCPU.

Example

use applevisor::prelude::*;

let vcpu = vm.vcpu_create()?;

pub fn vcpu_with_config(&self, config: VcpuConfig) -> Result<Vcpu>

Creates a new vCPU with a user-provided config.

Example

use applevisor::prelude::*;

let vcpu_config = VcpuConfig::default();
let vcpu = vm.vcpu_with_config(vcpu_config)?;

pub fn vcpus_exit(&self, vcpus: &[VcpuHandle]) -> Result<()>

Stops all vCPUs corresponding to the VcpuHandles of the vcpu input array.

Example

use applevisor::prelude::*;

let thread_count = 3;
let (tx, rx) = mpsc::channel();

thread::scope(|s| {
    // Each thread will have a Vcpu looping indefinitely.
    for i in 0..thread_count {
        let vm_thread = vm.clone();
        let tx_thread = tx.clone();
        s.spawn(move || {
            // Create the vCPU and memory region that will hold the infinite loop
            // instruction.
            let vcpu = vm_thread.vcpu_create().unwrap();

            // Write the instruction that while loop indefinitely.
            let mut mem = vm_thread.memory_create(PAGE_SIZE).unwrap();
            let addr = (PAGE_SIZE * i) as u64;
            mem.map(addr, MemPerms::ReadWriteExec).unwrap();
            mem.write_u32(addr, 0x14000000).unwrap();

            // Set PC to the loop address.
            vcpu.set_reg(Reg::PC, 0x10000).unwrap();

            // Sending the vCPU handle back to the main thread.
            let handle = vcpu.get_handle();
            tx_thread.send(handle).unwrap();

            // Starting the VCPU, we should loop indefinitely here.
            vcpu.run().unwrap();
        });
    }
    // Wait for the vCPU handles from each thread.
    let mut handles = vec![];
    for _ in 0..thread_count {
        handles.push(rx.recv().unwrap());
    }
    // Make the vCPU of each thread exit.
    vm.vcpus_exit(&handles).unwrap();
});

pub fn memory_create(&self, size: usize) -> Result<Memory>

Creates a memory object.

Discussion

The size provided must be aligned to PAGE_SIZE.

Example

use applevisor::prelude::*;

let vm = VirtualMachine::new()?;
let mem = vm.memory_create(PAGE_SIZE * 10)?;

Trait Implementations

impl<Gic: Clone> Clone for VirtualMachineInstance<Gic>

fn clone(&self) -> VirtualMachineInstance<Gic>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Gic: Debug> Debug for VirtualMachineInstance<Gic>

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

Formats the value using the given formatter.

impl<Gic> Drop for VirtualMachineInstance<Gic>

Destroys the virtual machine context of the current process.

fn drop(&mut self)

Executes the destructor for this type.

impl From<VirtualMachineInstance<GicEnabled>> for VirtualMachineInstance<GicDisabled>

Available on crate feature macos-15-0 only.

Transformes a GicEnabled instance into a GicDisabled one. The underlying object still has a GIC instance, but related APIs can’t be called.

fn from(value: VirtualMachineInstance<GicEnabled>) -> Self

Converts to this type from the input type.