Struct kvm_ioctls::Kvm

pub struct Kvm { /* fields omitted */ }

Wrapper over KVM system ioctls.

Methods

impl Kvm

pub fn new() -> Result<Self>

Opens /dev/kvm and returns a Kvm object on success.

Example

use kvm_ioctls::Kvm;
let kvm = Kvm::new().unwrap();

pub unsafe fn new_with_fd_number(fd: RawFd) -> Self

Creates a new Kvm object assuming fd represents an existing open file descriptor associated with /dev/kvm.

For usage examples check open_with_cloexec().

Arguments

• fd - File descriptor for /dev/kvm.

pub fn open_with_cloexec(close_on_exec: bool) -> Result<RawFd>

Opens /dev/kvm and returns the fd number on success.

One usecase for this method is opening /dev/kvm before exec-ing into a process with seccomp filters enabled that blacklist the sys_open syscall. For this usecase open_with_cloexec must be called with the close_on_exec parameter set to false.

Arguments

• close_on_exec: If true opens /dev/kvm using the O_CLOEXEC flag.

Example

let kvm_fd = Kvm::open_with_cloexec(false).unwrap();
// The `kvm_fd` can now be passed to another process where we can use
// `new_with_fd_number` for creating a `Kvm` object:
let kvm = unsafe { Kvm::new_with_fd_number(kvm_fd) };

pub fn get_api_version(&self) -> i32

Returns the KVM API version.

See the documentation for KVM_GET_API_VERSION.

Example

let kvm = Kvm::new().unwrap();
assert_eq!(kvm.get_api_version(), 12);

pub fn check_extension(&self, c: Cap) -> bool

Checks if a particular Cap is available.

Returns true if the capability is supported and false otherwise. See the documentation for KVM_CHECK_EXTENSION.

Arguments

• c - KVM capability to check.

Example

use kvm_ioctls::Cap;

let kvm = Kvm::new().unwrap();
// Check if `KVM_CAP_USER_MEMORY` is supported.
assert!(kvm.check_extension(Cap::UserMemory));

pub fn get_vcpu_mmap_size(&self) -> Result<usize>

Returns the size of the memory mapping required to use the vcpu's kvm_run structure.

See the documentation for KVM_GET_VCPU_MMAP_SIZE.

Example

let kvm = Kvm::new().unwrap();
assert!(kvm.get_vcpu_mmap_size().unwrap() > 0);

pub fn get_nr_vcpus(&self) -> usize

Gets the recommended number of VCPUs per VM.

See the documentation for KVM_CAP_NR_VCPUS. Default to 4 when KVM_CAP_NR_VCPUS is not implemented.

Example

let kvm = Kvm::new().unwrap();
// We expect the number of vCPUs to be > 0 as per KVM API documentation.
assert!(kvm.get_nr_vcpus() > 0);

pub fn get_nr_memslots(&self) -> usize

Returns the maximum allowed memory slots per VM.

KVM reports the number of available memory slots (KVM_CAP_NR_MEMSLOTS) using the extension interface. Both x86 and s390 implement this, ARM and powerpc do not yet enable it. Default to 32 when KVM_CAP_NR_MEMSLOTS is not implemented.

Example

let kvm = Kvm::new().unwrap();
assert!(kvm.get_nr_memslots() > 0);

pub fn get_max_vcpus(&self) -> usize

Gets the recommended maximum number of VCPUs per VM.

See the documentation for KVM_CAP_MAX_VCPUS. Returns get_nr_vcpus() when KVM_CAP_MAX_VCPUS is not implemented.

Example

let kvm = Kvm::new().unwrap();
assert!(kvm.get_max_vcpus() > 0);

pub fn get_emulated_cpuid(&self, max_entries_count: usize) -> Result<CpuId>

X86 specific call to get the system emulated CPUID values.

See the documentation for KVM_GET_EMULATED_CPUID.

Arguments

• max_entries_count - Maximum number of CPUID entries. This function can return less than this when the hardware does not support so many CPUID entries.

Example

use kvm_ioctls::{Kvm, MAX_KVM_CPUID_ENTRIES};

let kvm = Kvm::new().unwrap();
let mut cpuid = kvm.get_emulated_cpuid(MAX_KVM_CPUID_ENTRIES).unwrap();
let cpuid_entries = cpuid.mut_entries_slice();
assert!(cpuid_entries.len() <= MAX_KVM_CPUID_ENTRIES);

pub fn get_supported_cpuid(&self, max_entries_count: usize) -> Result<CpuId>

X86 specific call to get the system supported CPUID values.

See the documentation for KVM_GET_SUPPORTED_CPUID.

Arguments

• max_entries_count - Maximum number of CPUID entries. This function can return less than this when the hardware does not support so many CPUID entries.

Example

use kvm_ioctls::{Kvm, MAX_KVM_CPUID_ENTRIES};

let kvm = Kvm::new().unwrap();
let mut cpuid = kvm.get_emulated_cpuid(MAX_KVM_CPUID_ENTRIES).unwrap();
let cpuid_entries = cpuid.mut_entries_slice();
assert!(cpuid_entries.len() <= MAX_KVM_CPUID_ENTRIES);

pub fn get_msr_index_list(&self) -> Result<Vec<u32>>

X86 specific call to get list of supported MSRS

See the documentation for KVM_GET_MSR_INDEX_LIST.

Example

use kvm_ioctls::{Kvm, MAX_KVM_CPUID_ENTRIES};

let kvm = Kvm::new().unwrap();
let msr_index_list = kvm.get_msr_index_list().unwrap();

pub fn create_vm(&self) -> Result<VmFd>

Creates a VM fd using the KVM fd.

See the documentation for KVM_CREATE_VM. A call to this function will also initialize the size of the vcpu mmap area using the KVM_GET_VCPU_MMAP_SIZE ioctl.

Example

let kvm = Kvm::new().unwrap();
let vm = kvm.create_vm().unwrap();
// Check that the VM mmap size is the same reported by `KVM_GET_VCPU_MMAP_SIZE`.
assert!(vm.run_size() == kvm.get_vcpu_mmap_size().unwrap());

Trait Implementations

impl AsRawFd for Kvm

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.