Struct Kvm

pub struct Kvm { /* private fields */ }

Represents the kernel’s whole KVM subsystem.

This is the entry point for obtaining all other KVM objects, whether directly or indirectly.

Implementations

impl Kvm

pub fn open() -> Result<Self>

Opens the KVM device /dev/kvm and returns a Kvm instance wrapping it.

Fails with an error on a system where /dev/kvm doesn’t exist for some reason, such as if KVM is not enabled in the kernel.

Warning: The safety of this function relies on there being a reasonable device node at /dev/kvm. If the target system has some other unrelated device node or a non-device entry at that location then the returned object will allow issuing ioctl requests to that file that may cause memory corruption depending on how the opened device reacts to the KVM ioctl numbers.

This function is not marked as unsafe because a system configured in that way is considered unreasonable, and this crate is optimized for reasonable Linux configurations that follow the filesystem layout given in the kernel documentation.

Examples found in repository

examples/kvm-vm-setup.rs (line 8)

fn run() -> linux_io::result::Result<()> {
    let kvm = Kvm::open()?;
    println!("opened KVM subsystem: {:?}", &kvm);
    let version = kvm.get_api_version()?;
    if version != 12 {
        eprintln!("unsupported KVM API version {}", version);
        return Err(linux_io::result::Error::new(25));
    }
    let mut vm = kvm.create_vm()?;
    println!("created a VM: {:?}", &vm);

    let mut mem = MemoryRegion::new(0x1000)?;
    println!("created a memory region: {:?}", &mem);

    {
        let mem_data = mem.as_mut_slice();

        #[cfg(target_arch = "x86_64")]
        {
            // "UD2" explicitly-undefined instruction
            mem_data[0] = 0x0f;
            mem_data[1] = 0x0b;
        }

        #[cfg(target_arch = "aarch64")]
        {
            // "udf" explicitly-undefined instruction
            mem_data[0] = 0x01;
            mem_data[1] = 0x00;
            mem_data[2] = 0x00;
            mem_data[3] = 0x00;
        }
    }

    vm.set_guest_memory_region(0, KVM_MEM_READONLY, 0x1000, &mut mem)?;
    println!("registered the memory region with the VM");

    let cpu = vm.create_vcpu(0)?;
    println!("created a VCPU: {:?}", &cpu);
    let mut runner = cpu.to_runner()?;
    println!("created a VCPU runner: {:?}", &runner);
    runner.with_raw_run_state(|state| println!("run state: {:?}", &state));

    runner.modify_regs(|regs| {
        #[cfg(target_arch = "x86_64")]
        {
            regs.rip = 0x1000;
        }
        #[cfg(target_arch = "aarch64")]
        {
            regs.regs.pc = 0x1000;
        }
    })?;
    println!("set initial register values");

    #[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
    {
        runner.run_raw()?;
        runner.with_raw_run_state(|state| println!("run state after running: {:?}", &state));
        let regs = runner.get_regs()?;
        println!("registers after running: {:?}", &regs)
    }

    Ok(())
}

pub const fn from_file(f: File<KvmSystem>) -> Self

Wraps the given already-opened file in a Kvm object.

pub fn get_api_version(&self) -> Result<int>

Identifies the version of the KVM API used by the current kernel.

The stable API always returns version 12. The kernel documentation suggests that applications should always call this and refuse to run if it returns any value other than that; the version number is not expected to change in the future because future API additions will use Self::check_extension instead.

Examples found in repository

examples/kvm-vm-setup.rs (line 10)

fn run() -> linux_io::result::Result<()> {
    let kvm = Kvm::open()?;
    println!("opened KVM subsystem: {:?}", &kvm);
    let version = kvm.get_api_version()?;
    if version != 12 {
        eprintln!("unsupported KVM API version {}", version);
        return Err(linux_io::result::Error::new(25));
    }
    let mut vm = kvm.create_vm()?;
    println!("created a VM: {:?}", &vm);

    let mut mem = MemoryRegion::new(0x1000)?;
    println!("created a memory region: {:?}", &mem);

    {
        let mem_data = mem.as_mut_slice();

        #[cfg(target_arch = "x86_64")]
        {
            // "UD2" explicitly-undefined instruction
            mem_data[0] = 0x0f;
            mem_data[1] = 0x0b;
        }

        #[cfg(target_arch = "aarch64")]
        {
            // "udf" explicitly-undefined instruction
            mem_data[0] = 0x01;
            mem_data[1] = 0x00;
            mem_data[2] = 0x00;
            mem_data[3] = 0x00;
        }
    }

    vm.set_guest_memory_region(0, KVM_MEM_READONLY, 0x1000, &mut mem)?;
    println!("registered the memory region with the VM");

    let cpu = vm.create_vcpu(0)?;
    println!("created a VCPU: {:?}", &cpu);
    let mut runner = cpu.to_runner()?;
    println!("created a VCPU runner: {:?}", &runner);
    runner.with_raw_run_state(|state| println!("run state: {:?}", &state));

    runner.modify_regs(|regs| {
        #[cfg(target_arch = "x86_64")]
        {
            regs.rip = 0x1000;
        }
        #[cfg(target_arch = "aarch64")]
        {
            regs.regs.pc = 0x1000;
        }
    })?;
    println!("set initial register values");

    #[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
    {
        runner.run_raw()?;
        runner.with_raw_run_state(|state| println!("run state after running: {:?}", &state));
        let regs = runner.get_regs()?;
        println!("registers after running: {:?}", &regs)
    }

    Ok(())
}

pub fn check_extension(&self, ext: int) -> Result<int>

Query whether the KVM subsystem in the current kernel supports a particular extension.

A result of zero indicates a lack of support while nonzero indicates support. The nonzero value may carry additional meanings for some extensions.

pub fn create_vm(&self) -> Result<VirtualMachine<'_>>

Create a new virtual machine.

Examples found in repository

examples/kvm-vm-setup.rs (line 15)

fn run() -> linux_io::result::Result<()> {
    let kvm = Kvm::open()?;
    println!("opened KVM subsystem: {:?}", &kvm);
    let version = kvm.get_api_version()?;
    if version != 12 {
        eprintln!("unsupported KVM API version {}", version);
        return Err(linux_io::result::Error::new(25));
    }
    let mut vm = kvm.create_vm()?;
    println!("created a VM: {:?}", &vm);

    let mut mem = MemoryRegion::new(0x1000)?;
    println!("created a memory region: {:?}", &mem);

    {
        let mem_data = mem.as_mut_slice();

        #[cfg(target_arch = "x86_64")]
        {
            // "UD2" explicitly-undefined instruction
            mem_data[0] = 0x0f;
            mem_data[1] = 0x0b;
        }

        #[cfg(target_arch = "aarch64")]
        {
            // "udf" explicitly-undefined instruction
            mem_data[0] = 0x01;
            mem_data[1] = 0x00;
            mem_data[2] = 0x00;
            mem_data[3] = 0x00;
        }
    }

    vm.set_guest_memory_region(0, KVM_MEM_READONLY, 0x1000, &mut mem)?;
    println!("registered the memory region with the VM");

    let cpu = vm.create_vcpu(0)?;
    println!("created a VCPU: {:?}", &cpu);
    let mut runner = cpu.to_runner()?;
    println!("created a VCPU runner: {:?}", &runner);
    runner.with_raw_run_state(|state| println!("run state: {:?}", &state));

    runner.modify_regs(|regs| {
        #[cfg(target_arch = "x86_64")]
        {
            regs.rip = 0x1000;
        }
        #[cfg(target_arch = "aarch64")]
        {
            regs.regs.pc = 0x1000;
        }
    })?;
    println!("set initial register values");

    #[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
    {
        runner.run_raw()?;
        runner.with_raw_run_state(|state| println!("run state after running: {:?}", &state));
        let regs = runner.get_regs()?;
        println!("registers after running: {:?}", &regs)
    }

    Ok(())
}

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

Determine the size of the shared memory regions that will be used between kernel and userspace for each VCPU.

Trait Implementations

impl Debug for Kvm

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

Formats the value using the given formatter.