Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ xenevtchn = { version = "=0.2.0", optional = true }
xenvmevent-sys = { version = "=0.2.0", optional = true }
kvmi = { version = "=0.5.0", optional = true }
fdp = { version = "=0.3.0", optional = true }
vboxapi = { git = "https://github.com/Wenzel/rs-vboxapi", rev = "2c8292dbd48c576aa65d8a2bd12a907c860a5e62", optional = true }
vboxapi = { git = "https://github.com/Wenzel/rs-vboxapi", rev = "5ba8d86d1cc58a5935208588580782a31fb2d27c", optional = true }
vboxvmi = { git = "https://github.com/Wenzel/rs-vboxvmi", rev = "d0a64067a03282dc3c8f1aa1f663af3ae437a8e5", optional = true }
winapi = { version = "0.3", features = [
"tlhelp32",
Expand Down
8 changes: 5 additions & 3 deletions doc/src/reference/drivers/virtualbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,14 +56,16 @@ The client comes from the [vboxvmi](https://github.com/Wenzel/rs-vboxvmi) crate.

Uses VirtualBox's public `IMachineDebugger` API, loaded at runtime from the VirtualBox installation (no build-time dependency on VirtualBox).

Supported: reading guest physical memory, max physical address (end of the highest guest RAM range, so RAM above 4 GiB is included), pause/resume, vCPU count.
A read that hits an unreadable page (e.g. an MMIO hole) fails, with `bytes_read` set to the bytes read before that page.
Supported: reading guest physical memory, reading and writing the complete x86 register set,
max physical address (end of the highest guest RAM range, so RAM above 4 GiB is included),
pause/resume, and vCPU count. A memory read that hits an unreadable page (e.g. an MMIO hole)
fails, with `bytes_read` set to the bytes read before that page.
Pause is VirtualBox's own pause (the VM shows as Paused in the GUI and `VBoxManage`). It is synchronous, all vCPUs are stopped when it returns, and idempotent: pausing a paused VM succeeds, and one resume resumes it.
Pauses are not counted, also across clients: resume resumes the VM even if the GUI, `VBoxManage` or another tool paused it too.
Pause and resume fail while a live snapshot or teleport is in progress, during which VirtualBox controls the VM's run state.
With CPU hot-plug enabled, the vCPU count is the VM's maximum vCPU count, not the vCPUs currently plugged in.

Not implemented yet: registers, writes.
Not implemented yet: writing guest physical memory.

### Requirements

Expand Down
29 changes: 16 additions & 13 deletions examples/regs-dump.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
use clap::{App, Arg, ArgMatches};
use clap::{App, ArgMatches};

use microvmi::api::params::DriverInitParams;
use microvmi::api::Introspectable;
Expand All @@ -10,28 +10,31 @@ fn parse_args() -> ArgMatches<'static> {
.version("0.1")
.author("Mathieu Tarral")
.about("Dumps the state of registers on VCPU 0")
.arg(Arg::with_name("vm_name").index(1).required(true))
.args(DriverInitParams::to_clap_args().as_ref())
.get_matches()
}

fn main() {
fn main() -> Result<(), Box<dyn std::error::Error>> {
env_logger::init();

let matches = parse_args();
let init_params = DriverInitParams::from_matches(&matches);
let mut drv: Box<dyn Introspectable> =
microvmi::init(None, Some(init_params)).expect("Failed to init libmicrovmi");
let mut drv: Box<dyn Introspectable> = microvmi::init(None, Some(init_params))?;

println!("pausing the VM");
drv.pause().expect("Failed to pause VM");
let total_vcpu_count: u16 = drv.get_vcpu_count().expect("Failed to get vcpu count");
for vcpu in 0..total_vcpu_count {
println!("dumping registers on VCPU {}", vcpu);
let regs = drv.read_registers(vcpu).expect("Failed to read registers");
println!("{:#x?}", regs);
}
drv.pause()?;
let dump = (|| -> Result<(), Box<dyn std::error::Error>> {
let total_vcpu_count = drv.get_vcpu_count()?;
for vcpu in 0..total_vcpu_count {
println!("dumping registers on VCPU {}", vcpu);
println!("{:#x?}", drv.read_registers(vcpu)?);
}
Ok(())
})();

println!("resuming the VM");
drv.resume().expect("Failed to resume VM");
let resume = drv.resume();
dump?;
resume?;
Ok(())
}
8 changes: 4 additions & 4 deletions src/api/registers.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
///an x86 segment register
#[repr(C)]
#[derive(Debug, Default)]
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct SegmentReg {
///Stores the base address of a code segment
pub base: u64,
Expand All @@ -13,7 +13,7 @@ pub struct SegmentReg {
/// x86 System Table Registers
/// (GDTR, IDTR)
#[repr(C)]
#[derive(Debug, Default)]
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct SystemTableReg {
/// 32/64 bits linear base address
pub base: u64,
Expand All @@ -23,7 +23,7 @@ pub struct SystemTableReg {

///Represents all x86 registers on a specific VCPU
#[repr(C)]
#[derive(Debug, Default)]
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct X86Registers {
/// 8 byte general purpose register.
pub rax: u64,
Expand Down Expand Up @@ -106,7 +106,7 @@ pub struct X86Registers {
}

#[repr(C)]
#[derive(Debug)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Registers {
X86(X86Registers),
}
181 changes: 181 additions & 0 deletions src/driver/virtualbox_api.rs
Original file line number Diff line number Diff line change
@@ -1,16 +1,90 @@
//! VirtualBox driver, MachineDebugger access method: VirtualBox's `IMachineDebugger` API.
use std::collections::HashMap;
use std::convert::TryFrom;
use std::error::Error;

use vboxapi::Vm;

use crate::api::params::DriverInitParams;
use crate::api::registers::{Registers, SegmentReg, SystemTableReg, X86Registers};
use crate::api::{DriverType, Introspectable, PAGE_SIZE};

#[derive(thiserror::Error, Debug)]
pub enum VBoxApiDriverError {
#[error("VirtualBox driver requires a VM name parameter")]
MissingVMName,
#[error("no registers for vCPU {0}")]
NoSuchVcpu(u16),
#[error("register {name}: missing or unparseable value {value:?}")]
BadRegister {
name: &'static str,
value: Option<String>,
},
}

/// `X86Registers` fields as DBGF register names (`IMachineDebugger` register names) and values.
/// Segment selectors are the bare segment names (`cs`).
fn dbgf_registers(r: &X86Registers) -> Vec<(&'static str, u64)> {
let mut regs = vec![
("rax", r.rax),
("rbx", r.rbx),
("rcx", r.rcx),
("rdx", r.rdx),
("rsi", r.rsi),
("rdi", r.rdi),
("rsp", r.rsp),
("rbp", r.rbp),
("r8", r.r8),
("r9", r.r9),
("r10", r.r10),
("r11", r.r11),
("r12", r.r12),
("r13", r.r13),
("r14", r.r14),
("r15", r.r15),
("rip", r.rip),
("rflags", r.rflags),
("cr0", r.cr0),
("cr2", r.cr2),
("cr3", r.cr3),
("cr4", r.cr4),
("sysenter_cs", r.sysenter_cs),
("sysenter_esp", r.sysenter_esp),
("sysenter_eip", r.sysenter_eip),
("efer", r.msr_efer),
("star", r.msr_star),
("lstar", r.msr_lstar),
("efer", r.efer),
("apic_base", r.apic_base),
("gdtr_base", r.gdt.base),
("gdtr_lim", r.gdt.limit.into()),
("idtr_base", r.idt.base),
("idtr_lim", r.idt.limit.into()),
];
for (name, seg) in SEGMENTS.iter().zip(segments(r)) {
regs.extend([
(name[0], seg.selector.into()),
(name[1], seg.base),
(name[2], seg.limit.into()),
]);
}
regs
}

/// DBGF names of each segment register's selector, base and limit, in `segments` order.
const SEGMENTS: [[&str; 3]; 8] = [
["cs", "cs_base", "cs_lim"],
["ds", "ds_base", "ds_lim"],
["es", "es_base", "es_lim"],
["fs", "fs_base", "fs_lim"],
["gs", "gs_base", "gs_lim"],
["ss", "ss_base", "ss_lim"],
["tr", "tr_base", "tr_lim"],
["ldtr", "ldtr_base", "ldtr_lim"],
];

fn segments(r: &X86Registers) -> [&SegmentReg; 8] {
[&r.cs, &r.ds, &r.es, &r.fs, &r.gs, &r.ss, &r.tr, &r.ldt]
}

/// Not `Send`: the VirtualBox session must stay on the thread that opened it, which
Expand Down Expand Up @@ -70,6 +144,113 @@ impl Introspectable for VBoxApi {
Ok(self.vm.write_physical(paddr, buf)?)
}

/// One `getRegisters` call. The MSRs `X86Registers` has (EFER, STAR, LSTAR, SYSENTER_*,
/// APIC base) are all read; `efer` and `msr_efer` are both EFER.
fn read_registers(&self, vcpu: u16) -> Result<Registers, Box<dyn Error>> {
let prefix = format!("cpu{}.", vcpu);
let values: HashMap<String, String> = self
.vm
.registers(vcpu.into())?
.into_iter()
.filter_map(|(name, value)| Some((name.strip_prefix(&prefix)?.to_string(), value)))
.collect();
if values.is_empty() {
return Err(VBoxApiDriverError::NoSuchVcpu(vcpu).into());
}
// integers are formatted as 0x-prefixed hex
let get = |name: &'static str| -> Result<u64, VBoxApiDriverError> {
let value = values.get(name);
value
.and_then(|v| u64::from_str_radix(v.strip_prefix("0x")?, 16).ok())
.ok_or_else(|| VBoxApiDriverError::BadRegister {
name,
value: value.cloned(),
})
};
// values come from registers of that width
let seg =
|[selector, base, limit]: [&'static str; 3]| -> Result<SegmentReg, VBoxApiDriverError> {
Ok(SegmentReg {
base: get(base)?,
limit: get(limit)? as u32,
selector: get(selector)? as u16,
})
};
let [cs, ds, es, fs, gs, ss, tr, ldt] = SEGMENTS;
Ok(Registers::X86(X86Registers {
rax: get("rax")?,
rbx: get("rbx")?,
rcx: get("rcx")?,
rdx: get("rdx")?,
rsi: get("rsi")?,
rdi: get("rdi")?,
rsp: get("rsp")?,
rbp: get("rbp")?,
r8: get("r8")?,
r9: get("r9")?,
r10: get("r10")?,
r11: get("r11")?,
r12: get("r12")?,
r13: get("r13")?,
r14: get("r14")?,
r15: get("r15")?,
rip: get("rip")?,
rflags: get("rflags")?,
cr0: get("cr0")?,
cr2: get("cr2")?,
cr3: get("cr3")?,
cr4: get("cr4")?,
sysenter_cs: get("sysenter_cs")?,
sysenter_esp: get("sysenter_esp")?,
sysenter_eip: get("sysenter_eip")?,
msr_efer: get("efer")?,
msr_star: get("star")?,
msr_lstar: get("lstar")?,
efer: get("efer")?,
apic_base: get("apic_base")?,
cs: seg(cs)?,
ds: seg(ds)?,
es: seg(es)?,
fs: seg(fs)?,
gs: seg(gs)?,
ss: seg(ss)?,
tr: seg(tr)?,
ldt: seg(ldt)?,
idt: SystemTableReg {
base: get("idtr_base")?,
limit: get("idtr_lim")? as u16,
},
gdt: SystemTableReg {
base: get("gdtr_base")?,
limit: get("gdtr_lim")? as u16,
},
}))
}

/// Writes only the registers that differ from the current ones, in one `setRegisters` call,
/// so unchanged control registers and MSRs are not reloaded. Segment selectors, bases and
/// limits are written as raw debugger state. Pause the VM first: on a running VM the
/// registers are not written all at once. Not atomic: on error, the registers before the
/// failing one stay written.
fn write_registers(&self, vcpu: u16, reg: Registers) -> Result<(), Box<dyn Error>> {
let Registers::X86(new) = reg;
let Registers::X86(old) = self.read_registers(vcpu)?;
let mut changed = Vec::new();
for ((name, value), (_, old_value)) in
dbgf_registers(&new).into_iter().zip(dbgf_registers(&old))
{
if value == old_value {
continue;
}
changed.push((name, format!("{:#x}", value)));
}
if changed.is_empty() {
return Ok(());
}
let changed: Vec<(&str, &str)> = changed.iter().map(|(n, v)| (*n, v.as_str())).collect();
Ok(self.vm.set_registers(vcpu.into(), &changed)?)
}

fn get_vcpu_count(&self) -> Result<u16, Box<dyn Error>> {
Ok(u16::try_from(self.vm.cpu_count())?)
}
Expand Down
2 changes: 1 addition & 1 deletion tests/common/virtualbox.rs
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ fn bin(name: &str) -> PathBuf {
.unwrap_or_else(|| PathBuf::from(name))
}

pub(crate) fn try_vboxmanage(args: &[&str]) -> Result<String, String> {
pub fn try_vboxmanage(args: &[&str]) -> Result<String, String> {
debug!("VBoxManage {}", args.join(" "));
let out = Command::new(bin("VBoxManage"))
.args(args)
Expand Down
Loading
Loading