Trait hypervisor::Vm

pub trait Vm: Send {
    // Required methods
    fn try_clone(&self) -> Result<Self>
       where Self: Sized;
    fn check_capability(&self, c: VmCap) -> bool;
    fn get_guest_phys_addr_bits(&self) -> u8;
    fn get_memory(&self) -> &GuestMemory;
    fn add_memory_region(
        &mut self,
        guest_addr: GuestAddress,
        mem_region: Box<dyn MappedRegion>,
        read_only: bool,
        log_dirty_pages: bool,
        cache: MemCacheType
    ) -> Result<MemSlot>;
    fn msync_memory_region(
        &mut self,
        slot: MemSlot,
        offset: usize,
        size: usize
    ) -> Result<()>;
    fn madvise_pageout_memory_region(
        &mut self,
        slot: MemSlot,
        offset: usize,
        size: usize
    ) -> Result<()>;
    fn madvise_remove_memory_region(
        &mut self,
        slot: MemSlot,
        offset: usize,
        size: usize
    ) -> Result<()>;
    fn remove_memory_region(
        &mut self,
        slot: MemSlot
    ) -> Result<Box<dyn MappedRegion>>;
    fn create_device(&self, kind: DeviceKind) -> Result<SafeDescriptor>;
    fn get_dirty_log(&self, slot: MemSlot, dirty_log: &mut [u8]) -> Result<()>;
    fn register_ioevent(
        &mut self,
        evt: &Event,
        addr: IoEventAddress,
        datamatch: Datamatch
    ) -> Result<()>;
    fn unregister_ioevent(
        &mut self,
        evt: &Event,
        addr: IoEventAddress,
        datamatch: Datamatch
    ) -> Result<()>;
    fn handle_io_events(&self, addr: IoEventAddress, data: &[u8]) -> Result<()>;
    fn get_pvclock(&self) -> Result<ClockState>;
    fn set_pvclock(&self, state: &ClockState) -> Result<()>;
    fn add_fd_mapping(
        &mut self,
        slot: u32,
        offset: usize,
        size: usize,
        fd: &dyn AsRawDescriptor,
        fd_offset: u64,
        prot: Protection
    ) -> Result<()>;
    fn remove_mapping(
        &mut self,
        slot: u32,
        offset: usize,
        size: usize
    ) -> Result<()>;
    fn handle_balloon_event(&mut self, event: BalloonEvent) -> Result<()>;

    // Provided method
    fn enable_capability(&self, _capability: VmCap, _flags: u32) -> Result<bool> { ... }
}

A wrapper for using a VM and getting/setting its state.

Required Methods

fn try_clone(&self) -> Result<Self>

where Self: Sized,

Makes a shallow clone of this Vm.

fn check_capability(&self, c: VmCap) -> bool

Checks if a particular VmCap is available.

This is distinct from the Hypervisor version of this method because some extensions depend on the particular Vm instance. This method is encouraged because it more accurately reflects the usable capabilities.

fn get_guest_phys_addr_bits(&self) -> u8

Get the guest physical address size in bits.

fn get_memory(&self) -> &GuestMemory

Gets the guest-mapped memory for the Vm.

fn add_memory_region( &mut self, guest_addr: GuestAddress, mem_region: Box<dyn MappedRegion>, read_only: bool, log_dirty_pages: bool, cache: MemCacheType ) -> Result<MemSlot>

Inserts the given MappedRegion into the VM’s address space at guest_addr.

The slot that was assigned the memory mapping is returned on success. The slot can be given to Vm::remove_memory_region to remove the memory from the VM’s address space and take back ownership of mem_region.

Note that memory inserted into the VM’s address space must not overlap with any other memory slot’s region.

If read_only is true, the guest will be able to read the memory as normal, but attempts to write will trigger a mmio VM exit, leaving the memory untouched.

If log_dirty_pages is true, the slot number can be used to retrieve the pages written to by the guest with get_dirty_log.

cache can be used to set guest mem cache attribute if supported. Default is cache coherent memory. Noncoherent memory means this memory might not be coherent from all access points, e.g this could be the case when host GPU doesn’t set the memory to be coherent with CPU access. Setting this attribute would allow hypervisor to adjust guest mem control to ensure synchronized guest access in noncoherent DMA case.

fn msync_memory_region( &mut self, slot: MemSlot, offset: usize, size: usize ) -> Result<()>

Does a synchronous msync of the memory mapped at slot, syncing size bytes starting at offset from the start of the region. offset must be page aligned.

fn madvise_pageout_memory_region( &mut self, slot: MemSlot, offset: usize, size: usize ) -> Result<()>

Gives a MADV_PAGEOUT advice to the memory region mapped at slot, with the address range starting at offset from the start of the region, and with size size. offset must be page aligned.

fn madvise_remove_memory_region( &mut self, slot: MemSlot, offset: usize, size: usize ) -> Result<()>

Gives a MADV_REMOVE advice to the memory region mapped at slot, with the address range starting at offset from the start of the region, and with size size. offset must be page aligned.

fn remove_memory_region( &mut self, slot: MemSlot ) -> Result<Box<dyn MappedRegion>>

Removes and drops the UserMemoryRegion that was previously added at the given slot.

fn create_device(&self, kind: DeviceKind) -> Result<SafeDescriptor>

Creates an emulated device.

fn get_dirty_log(&self, slot: MemSlot, dirty_log: &mut [u8]) -> Result<()>

Gets the bitmap of dirty pages since the last call to get_dirty_log for the memory at slot. Only works on VMs that support VmCap::DirtyLog.

The size of dirty_log must be at least as many bits as there are pages in the memory region slot represents. For example, if the size of slot is 16 pages, dirty_log must be 2 bytes or greater.

fn register_ioevent( &mut self, evt: &Event, addr: IoEventAddress, datamatch: Datamatch ) -> Result<()>

Registers an event to be signaled whenever a certain address is written to.

The datamatch parameter can be used to limit signaling evt to only the cases where the value being written is equal to datamatch. Note that the size of datamatch is important and must match the expected size of the guest’s write.

In all cases where evt is signaled, the ordinary vmexit to userspace that would be triggered is prevented.

fn unregister_ioevent( &mut self, evt: &Event, addr: IoEventAddress, datamatch: Datamatch ) -> Result<()>

Unregisters an event previously registered with register_ioevent.

The evt, addr, and datamatch set must be the same as the ones passed into register_ioevent.

fn handle_io_events(&self, addr: IoEventAddress, data: &[u8]) -> Result<()>

Trigger any matching registered io events based on an MMIO or PIO write at addr. The data slice represents the contents and length of the write, which is used to compare with the registered io events’ Datamatch values. If the hypervisor does in-kernel IO event delivery, this is a no-op.

fn get_pvclock(&self) -> Result<ClockState>

Retrieves the current timestamp of the paravirtual clock as seen by the current guest. Only works on VMs that support VmCap::PvClock.

fn set_pvclock(&self, state: &ClockState) -> Result<()>

Sets the current timestamp of the paravirtual clock as seen by the current guest. Only works on VMs that support VmCap::PvClock.

fn add_fd_mapping( &mut self, slot: u32, offset: usize, size: usize, fd: &dyn AsRawDescriptor, fd_offset: u64, prot: Protection ) -> Result<()>

Maps size bytes starting at fs_offset bytes from within the given fd at offset bytes from the start of the arena with prot protections. offset must be page aligned.

Arguments

• offset - Page aligned offset into the arena in bytes.
• size - Size of memory region in bytes.
• fd - File descriptor to mmap from.
• fd_offset - Offset in bytes from the beginning of fd to start the mmap.
• prot - Protection (e.g. readable/writable) of the memory region.

fn remove_mapping( &mut self, slot: u32, offset: usize, size: usize ) -> Result<()>

Remove size-byte mapping starting at offset.

fn handle_balloon_event(&mut self, event: BalloonEvent) -> Result<()>

Events from virtio-balloon that affect the state for guest memory and host memory.

Provided Methods

fn enable_capability(&self, _capability: VmCap, _flags: u32) -> Result<bool>

Enable the VM capabilities.

Implementors

impl Vm for KvmVm