diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..3124647 --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ +## asmlinator + +[](https://crates.io/crates/asmlinator) +[](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(®s).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. |