asmlinator

just enough glue on top of KVM to get a VM with one CPU set up to execute x86_64 instructions.

usage

use asmlinator::x86_64::VcpuExit;

let mem_size = 1024 * 1024;
let mut vm = asmlinator::x86_64::Vm::create(mem_size)
    .expect("can create the VM");

let mut regs = vm.get_regs().unwrap();

// program VM with "xor eax, eax; hlt"
vm.program(&[0x33, 0xc0, 0xf4], &mut regs);
vm.set_regs(&regs).unwrap();

let res = vm.run().expect("can run cpu");
assert_eq!(res, VcpuExit::Hlt);

let regs = vm.get_regs().unwrap();
eprintln!("ending rip: {:016x}", regs.rip);
eprintln!("ending rax: {:016x}", regs.rax);

design

it's just a glorified virtual CPU wrapper. there is no device emulation, there is no interrupt controller, there's only one CPU, etc. the plan is to support ad-hoc questions about x86 behavior rather than a general VMM. more "run this function in that address space" and "single-step these instructions" than "call into a library".

you could imagine this as a more opinionated and much smaller hyperlight, without any support for IPC into or out of the VM. i don't.

i consider this closer to a missing OS primitive. the OS knows how to boot itself on native hardware, it knows how to create a virtual machine, it should be able to create exactly this kind of partially-initialized VM that does not require setting up an IDT, GDT, paging, ...

future

it'd be nice to set up aarch64 processors for code execution too. and 32-bit/16-bit x86. and to do all this on other OSes with other VM APIs.

there should be an option to set up syscall/sysenter and handle such instructions as a VcpuExit::Syscall, but i won't need that for a bit.

it would probably nice to expose a C ffi to embed this into other programs! such an ffi interface should be straightforward. i haven't needed one yet.

mirrors

the canonical copy of asmlinator is at https://git.iximeow.net/asmlinator/.

asmlinator is also mirrored on Codeberg at https://codeberg.org/iximeow/asmlinator.

changelog

a changelog across crate versions is maintained in the CHANGELOG file located in the repo.

contributing

unfortunately, pushing commits to the canonical repo at git.iximeow.net is impossible. if you'd like to contribute - thank you! - please send patches to emails iximeow has committed under or by opening PRs against the Codeberg mirror. both remotes are kept in sync.