Crate kvm_ioctls

A safe wrapper around the kernel’s KVM interface.

This crate offers safe wrappers for:

• system ioctls using the Kvm structure
• VM ioctls using the VmFd structure
• vCPU ioctls using the VcpuFd structure
• device ioctls using the DeviceFd structure

Platform support

• x86_64
• arm64 (experimental)

NOTE: The list of available ioctls is not extensive.

Example - Running a VM on x86_64

In this example we are creating a Virtual Machine (VM) with one vCPU. On the vCPU we are running machine specific code. This example is based on the LWN article on using the KVM API. The aarch64 example was modified accordingly.

To get code running on the vCPU we are going through the following steps:

1. Instantiate KVM. This is used for running system specific ioctls.
2. Use the KVM object to create a VM. The VM is used for running VM specific ioctls.
3. Initialize the guest memory for the created VM. In this dummy example we are adding only one memory region and write the code in one memory page.
4. Create a vCPU using the VM object. The vCPU is used for running vCPU specific ioctls.
5. Setup architectural specific general purpose registers and special registers. For details about how and why these registers are set, please check the LWN article on which this example is built.
6. Run the vCPU code in a loop and check the exit reasons.

extern crate kvm_ioctls;
extern crate kvm_bindings;

use kvm_ioctls::VcpuExit;
use kvm_ioctls::{Kvm, VcpuFd, VmFd};

fn main() {
    use std::io::Write;
    use std::ptr::null_mut;
    use std::slice;

    use kvm_bindings::kvm_userspace_memory_region;
    use kvm_bindings::KVM_MEM_LOG_DIRTY_PAGES;

    let mem_size = 0x4000;
    let guest_addr = 0x1000;
    let asm_code: &[u8];

    // Setting up architectural dependent values.
    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    {
        asm_code = &[
            0xba, 0xf8, 0x03, /* mov $0x3f8, %dx */
            0x00, 0xd8, /* add %bl, %al */
            0x04, b'0', /* add $'0', %al */
            0xee, /* out %al, %dx */
            0xec, /* in %dx, %al */
            0xc6, 0x06, 0x00, 0x80,
            0x00, /* movl $0, (0x8000); This generates a MMIO Write. */
            0x8a, 0x16, 0x00, 0x80, /* movl (0x8000), %dl; This generates a MMIO Read. */
            0xf4, /* hlt */
        ];
    }
    #[cfg(target_arch = "aarch64")]
    {
        asm_code = &[
            0x01, 0x00, 0x00, 0x10, /* adr x1, <this address> */
            0x22, 0x10, 0x00, 0xb9, /* str w2, [x1, #16]; write to this page */
            0x02, 0x00, 0x00, 0xb9, /* str w2, [x0]; This generates a MMIO Write. */
            0x00, 0x00, 0x00,
            0x14, /* b <this address>; shouldn't get here, but if so loop forever */
        ];
    }

    // 1. Instantiate KVM.
    let kvm = Kvm::new().unwrap();

    // 2. Create a VM.
    let vm = kvm.create_vm().unwrap();

    // 3. Initialize Guest Memory.
    let load_addr: *mut u8 = unsafe {
        libc::mmap(
            null_mut(),
            mem_size,
            libc::PROT_READ | libc::PROT_WRITE,
            libc::MAP_ANONYMOUS | libc::MAP_SHARED | libc::MAP_NORESERVE,
            -1,
            0,
        ) as *mut u8
    };

    let slot = 0;
    // When initializing the guest memory slot specify the
    // `KVM_MEM_LOG_DIRTY_PAGES` to enable the dirty log.
    let mem_region = kvm_userspace_memory_region {
        slot,
        guest_phys_addr: guest_addr,
        memory_size: mem_size as u64,
        userspace_addr: load_addr as u64,
        flags: KVM_MEM_LOG_DIRTY_PAGES,
    };
    unsafe { vm.set_user_memory_region(mem_region).unwrap() };

    // Write the code in the guest memory. This will generate a dirty page.
    unsafe {
        let mut slice = slice::from_raw_parts_mut(load_addr, mem_size);
        slice.write(&asm_code).unwrap();
    }

    // 4. Create one vCPU.
    let mut vcpu_fd = vm.create_vcpu(0).unwrap();

    // 5. Initialize general purpose and special registers.
    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    {
        // x86_64 specific registry setup.
        let mut vcpu_sregs = vcpu_fd.get_sregs().unwrap();
        vcpu_sregs.cs.base = 0;
        vcpu_sregs.cs.selector = 0;
        vcpu_fd.set_sregs(&vcpu_sregs).unwrap();

        let mut vcpu_regs = vcpu_fd.get_regs().unwrap();
        vcpu_regs.rip = guest_addr;
        vcpu_regs.rax = 2;
        vcpu_regs.rbx = 3;
        vcpu_regs.rflags = 2;
        vcpu_fd.set_regs(&vcpu_regs).unwrap();
    }

    #[cfg(target_arch = "aarch64")]
    {
        // aarch64 specific registry setup.
        let mut kvi = kvm_bindings::kvm_vcpu_init::default();
        vm.get_preferred_target(&mut kvi).unwrap();
        vcpu_fd.vcpu_init(&kvi).unwrap();

        let core_reg_base: u64 = 0x6030_0000_0010_0000;
        let mmio_addr: u64 = guest_addr + mem_size as u64;
        // set PC
        vcpu_fd.set_one_reg(core_reg_base + 2 * 32, &guest_addr.to_le_bytes());
        // set X0
        vcpu_fd.set_one_reg(core_reg_base + 2 * 0, &mmio_addr.to_le_bytes());
    }

    // 6. Run code on the vCPU.
    loop {
        match vcpu_fd.run().expect("run failed") {
            VcpuExit::IoIn(addr, data) => {
                println!(
                    "Received an I/O in exit. Address: {:#x}. Data: {:#x}",
                    addr, data[0],
                );
            }
            VcpuExit::IoOut(addr, data) => {
                println!(
                    "Received an I/O out exit. Address: {:#x}. Data: {:#x}",
                    addr, data[0],
                );
            }
            VcpuExit::MmioRead(addr, data) => {
                println!("Received an MMIO Read Request for the address {:#x}.", addr,);
            }
            VcpuExit::MmioWrite(addr, data) => {
                println!("Received an MMIO Write Request to the address {:#x}.", addr,);
                // The code snippet dirties 1 page when it is loaded in memory
                let dirty_pages_bitmap = vm.get_dirty_log(slot, mem_size).unwrap();
                let dirty_pages = dirty_pages_bitmap
                    .into_iter()
                    .map(|page| page.count_ones())
                    .fold(0, |dirty_page_count, i| dirty_page_count + i);
                assert_eq!(dirty_pages, 1);
                // Since on aarch64 there is not halt instruction,
                // we break immediately after the last known instruction
                // of the asm code example so that we avoid an infinite loop.
                #[cfg(target_arch = "aarch64")]
                break;
            }
            VcpuExit::Hlt => {
                break;
            }
            r => panic!("Unexpected exit reason: {:?}", r),
        }
    }
}

Structs

• DeviceFd
  Wrapper over the file descriptor obtained when creating an emulated device in the kernel.
• Error
  Wrapper over errno.
• HypercallExit
  Information about a VcpuExit triggered by an Hypercall (KVM_EXIT_HYPERCALL).
• Kvm
  Wrapper over KVM system ioctls.
• KvmRunWrapper
  Example
• MsrExitReason
  The reason for a VcpuExit::X86Rdmsr orVcpuExit::X86Wrmsr. This is also used when enabling Cap::X86UserSpaceMsr to specify which reasons should be forwarded to the user via those exits.
• NoDatamatch
  Helper structure for disabling datamatch.
• ReadMsrExit
  Information about a VcpuExit triggered by an MSR read (KVM_EXIT_X86_RDMSR).
• VcpuFd
  Wrapper over KVM vCPU ioctls.
• VmFd
  Wrapper over KVM VM ioctls.
• WriteMsrExit
  Information about a VcpuExit triggered by an MSR write (KVM_EXIT_X86_WRMSR).

Enums

• Cap
  Capabilities exposed by KVM.
• IoEventAddress
  An address either in programmable I/O space or in memory mapped I/O space.
• SyncReg
  KVM Sync Registers used to tell KVM which registers to sync
• VcpuExit
  Reasons for vCPU exits.