emuko

A RISC-V emulator in Rust. It boots Linux.

emuko.dev

The machine implements RV64IMAFDC with M/S/U privilege levels and Sv39 virtual memory. It runs a JIT on ARM64 and x86_64 hosts, falling back to an interpreter when needed. The peripherals are UART 16550, CLINT, PLIC, and SBI 1.0. There is one external dependency: zstd.

It is not the fastest emulator. In interpreter mode it runs about three times slower than QEMU. In JIT mode, about twenty-nine times slower. Code block chaining is not yet implemented; that will help. We say this plainly because you should know what you are getting.

What it does well: it is simple to operate, it exposes an HTTP API for machine control, it can execute a bare-metal ELF without a kernel, and it can save and restore the full machine state. These are useful things for systems work and for testing.

Build

cargo build --release

The binary is target/release/emuko. Make an alias.

alias emuko=target/release/emuko

Quick Start

Get a kernel

emuko dow

Downloads a Debian RISC-V netboot kernel and initrd to ~/.emuko/. SHA256 is verified. No kernel of your own is required.

Boot Linux

emuko start

The emulator runs as a daemon. You are attached to its console. You will see the kernel boot. You will get a shell.

Control a running machine

emuko start            # reattach console
emuko dump             # print CPU state
emuko stop             # pause execution
emuko con              # continue
emuko step 1000        # single-step N instructions
emuko snap             # take a snapshot
emuko kill             # shut down

The daemon listens on http://127.0.0.1:7788/v1/api/ and accepts WebSocket console connections at ws://127.0.0.1:7788/v1/ws/uart. Both are usable from scripts.

Bare-Metal ELF Execution

Sometimes you do not want an operating system. You want the machine, a binary, and nothing else between them.

emuko run ./my_program.elf

The daemon resets the machine, loads the ELF segments at their physical addresses, and begins execution. Output arrives over the UART console. The daemon must already be running.

To write to the console from bare metal: store a byte at 0x1000_0000.

Examples

The examples/ directory contains programs that run this way.

A RISC-V cross-compiler is required to build them. On macOS: brew install riscv64-elf-gcc. On Linux: apt install gcc-riscv64-linux-gnu.

emuko start
cd examples/bare_printf
make run

Snapshots

The machine state — registers, memory, everything — can be saved and restored.

emuko snap                  # snapshot now
emuko snap 5000000          # auto-snapshot every 5M steps
emuko snap stop             # stop auto-snapshots
emuko ls                    # list snapshots
emuko restore <snapshot>    # restore

Memory Map

The virtual machine uses a fixed MMIO layout compatible with the QEMU RISC-V virt platform.

RAM layout at Linux boot

With default settings (load_addr=0x80200000, 1 GiB RAM):

0x8000_0000  ── RAM base
                (gap — usable by bare-metal programs)
0x8020_0000  ── Kernel image
                │  .text / .rodata / .data / .bss
                └─ kernel end
                (free)
             ── initrd
             ── DTB
             ── EFI region    (128 KiB, PE/UEFI kernels only)
0xBFFF_FFFF  ── RAM end

DTB, initrd, and EFI are placed downward from the top of RAM. The emulator checks for overlap with the kernel at boot and stops with a clear error if RAM is too small.

RAM layout for bare-metal ELF

ELF PT_LOAD segments are placed at their p_vaddr addresses. bare_printf links at 0x8000_0000:

0x8000_0000  ── .text
             ── .rodata
             ── .data
             ── .bss   (zeroed by start.S)
             ── stack  (16 KiB above BSS)

No kernel. No initrd. No DTB. Registers start at zero except sp, which the emulator sets to ram_base + 0x100000 before start.S takes over.

Configuration

Options may be passed on the command line, set as environment variables, or placed in emuko.yml.

Comparison

Direct comparison with commonly-used RISC-V emulators. ✅ = supported and documented. — = not built in.

Sources: QEMU virt · Spike · Renode

License

Apache 2.0. See LICENSE.