README.md

juicebox-asm

An x64 jit assembler for learning purpose with the following two main goals:

• Learn about x64 instruction encoding.
• Learn how to use the rust type system to disallow invalid operands.

Example

use juicebox_asm::insn::*;
use juicebox_asm::Runtime;
use juicebox_asm::{Asm, Imm32, Label, Reg32::*};

fn main() {
    let mut asm = Asm::new();

    // Reference implementation
    //   int ret = 0;
    //   int n   = 42;
    //
    // loop:
    //   ret += n;
    //   --n;
    //   if (n != 0) goto loop;
    //
    //   return;

    let mut lp = Label::new();

    asm.mov(eax, Imm32::from(0));
    asm.mov(ecx, Imm32::from(42));

    asm.bind(&mut lp);
    asm.add(eax, ecx);
    asm.dec(ecx);
    asm.test(ecx, ecx);
    asm.jnz(&mut lp);

    asm.ret();

    let mut rt = Runtime::new();
    let func = unsafe { rt.add_code::<extern "C" fn() -> u32>(&asm.into_code()) };
    assert_eq!(func(), (0..=42).into_iter().sum());
}

The examples/ folder provides additional examples:

• fib.rs jit compiles a function to compute the fibonacci sequence.
• add.rs jit compiles a function calling another function compiled into the example binary.
• tiny_vm.rs defines a minimal virtual machine (VM) with registers, instructions, data & instruction memory. The VM demonstrates a simple jit compiler which has a jit cache and translates each basic block on first execution when running a VM guest image. For reference an interepter is also implemented.

git hook for local development

The ci/ checks can be run automatically during local development by installing the following pre-commit git hook.

echo 'make -C ci' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

License

This project is licensed under the MIT license.