## asmlinator

[![crate](https://img.shields.io/crates/v/asmlinator.svg?logo=rust)](https://crates.io/crates/asmlinator)
[![documentation](https://docs.rs/asmlinator/badge.svg)](https://docs.rs/asmlinator)

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

### usage

```rust
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/](https://git.iximeow.net/asmlinator).

`asmlinator` is also mirrored on Codeberg at [https://codeberg.org/iximeow/asmlinator](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](https://codeberg.org/iximeow/asmlinator). both remotes are kept in
sync.