Crate Addition Request: extend vmm-vcpu to Hypervisor crate #50
Description
Crate Name
Hypervisor
Short Description
vmm-vcpu has made Vcpu handling be hypervisor agnostic. But there are still
some works to do to make whole rust-vmm be hypervisor agnostic. So here is
a proposal to extend vmm-vcpu to Hypervisor crate to make rust-vmm be
hypervisor agnostic. There has been an issue to discuss this:
rust-vmm/vmm-vcpu#5.
To make larger audience see this, I create this new issue here per Jenny's
suggestion.
Hypervisor crate abstracts different hypervisors interfaces (e.g. kvm ioctls) to
provide unified interfaces to upper layer. The concrete hypervisor (e.g. Kvm/
HyperV) implements the traits to provide hypervisor specific functions.
The upper layer (e.g. Vmm) creates Hypervisor instance which links to the
running hypervisor. Then, it calls running hypervisor interfaces through
Hypervisor instance to make the upper layer be hypervisor agnostic.
Why is this crate relevant to the rust-vmm project?
Rust-vmm should be workable for all hypervisors, e.g. KVM/HyperV/etc. So the
hypervisor abstraction crate is necessary to encapsulate the hypervisor specific
operations so that the upper layer can simplify the implementations to be
hypervisor agnostic.
Design
Relationships of crates
Compilation arguments
Create concrete hypervisor instance for Hypervisor users (e.g. Vmm) through
compilation argument. Because only one hypervisor is running for cloud scenario.
Hypervisor crate
This crate itself is simple to expose three public traits Hypervisor, Vm and Vcpu.
This crate is used by KVM/HyperV/etc. The interfaces defined below are used to
show the mechanism. They are got from Firecracker. They are more Kvm specific.
We may change them per requirements.
Note: The Vcpu part refers the [1] and [2] with some changes.
pub trait Hypervsior {
pub fn create_vm(&self) -> Box<Vm>;
pub fn get_api_version(&self) -> i32;
pub fn check_extension(&self, c: Cap) -> bool;
pub fn get_vcpu_mmap_size(&self) -> Result<usize>;
pub fn get_supported_cpuid(&self, max_entries_count: usize) -> Result<CpuId>;
}
pub trait Vm {
pub fn create_vcpu(&self, id: u8) -> Box<Vcpu>;
pub fn set_user_memory_region(&self,
slot: u32,
guest_phys_addr: u64,
memory_size: u64,
userspace_addr: u64,
flags: u32) -> Result<()>;
pub fn set_tss_address(&self, offset: usize) -> Result<()>;
pub fn create_irq_chip(&self) -> Result<()>;
pub fn create_pit2(&self, pit_config: PitConfig) -> Result<()>;
pub fn register_irqfd(&self, evt: &EventFd, gsi: u32) -> Result<()>;
}
pub trait Vcpu {
pub fn get_regs(&self) -> Result<VmmRegs>;
pub fn set_regs(&self, regs: &VmmRegs) -> Result<()>;
pub fn get_sregs(&self) -> Result<SpecialRegisters>;
pub fn set_sregs(&self, sregs: &SpecialRegisters) -> Result<()>;
pub fn get_fpu(&self) -> Result<Fpu>;
pub fn set_fpu(&self, fpu: &Fpu) -> Result<()>;
pub fn set_cpuid2(&self, cpuid: &CpuId) -> Result<()>;
pub fn get_lapic(&self) -> Result<LApicState>;
pub fn set_lapic(&self, klapic: &LApicState) -> Result<()>;
pub fn get_msrs(&self, msrs: &mut MsrEntries) -> Result<(i32)>;
pub fn set_msrs(&self, msrs: &MsrEntries) -> Result<()>;
pub fn run(&self) -> Result<VcpuExit>;
}
[1] While the data types themselves (VmmRegs, SpecialRegisters, etc) are
exposed via the trait with generic names, under the hood they can be
kvm_bindings data structures, which are also exposed from the same crate
via public redefinitions:
pub use kvm_bindings::kvm_regs as VmmRegs;
pub use kvm_bindings::kvm_sregs as SpecialRegisters;
// ...
Sample codes to show how it works
Kvm crate
Below are sample codes in Kvm crate to show how to implement above traits.
pub struct Kvm {
kvm: File,
}
impl Hypervisor for Kvm {
pub fn create_vm(&self) -> Box<Vm> {
let ret = unsafe { ioctl(&self.kvm, KVM_CREATE_VM()) };
let vm_file = unsafe { File::from_raw_fd(ret) };
Box::new(KvmVmFd { vm: vm_file, ...})
}
...
}
struct KvmVmFd {
vm: File,
...
}
impl Vm for KvmVmFd {
pub fn create_irq_chip(&self) -> Result<()> {
let ret = unsafe { ioctl(self, KVM_CREATE_IRQCHIP()) };
...
}
pub fn create_vcpu(&self, id: u8) -> Result<Vcpu> {
let vcpu_fd = unsafe { ioctl_with_val(&self.vm,
KVM_CREATE_VCPU(),
id as c_ulong) };
...
let vcpu = unsafe { File::from_raw_fd(vcpu_fd) };
...
Ok(Box::new(KvmVcpuFd { vcpu, ... }))
}
...
}
pub struct KvmVcpuFd {
vcpu: File,
...
}
impl Vcpu for KvmVcpuFd {
...
}
Vmm crate
Below are sample codes in Vmm crate to show how to work with Hypervisor
crate.
struct Vmm {
hyp: Box<Hypervisor>,
...
}
impl Vmm {
fn new(h: Box<Hypervisor>, ...) -> Self {
Vmm {hyp: h}
...
}
...
}
pub struct GuestVm {
fd: Box<Vm>,
...
}
impl GuestVm {
pub fn new(hyp: Box<Hypervisor>) -> Result<Self> {
let vm_fd = hyp.create_vm();
...
let cpuid = hyp.get_supported_cpuid(MAX_CPUID_ENTRIES);
...
Ok(GuestVm {
fd: vm_fd,
supported_cpuid: cpuid,
guest_mem: None,
})
}
...
}
pub struct GuestVcpu {
fd: Box<Vcpu>,
...
}
impl GuestVcpu {
pub fn new(id: u8, vm: &GuestVm) -> Result<Self> {
let vcpu = vm.fd.create_vcpu(id);
Ok(GuestVcpu { fd: vcpu, ... }
}
...
}
When start Vmm, create concrete hypervisor instance according to compilation
argument. Then, set it to Vmm and start the flow: create guest vm -> create guest
vcpus -> run.
References:
[1] #40
[2] https://github.com/rust-vmm/vmm-vcpu