Internals

RISC-V runner

The RISC-V VM core: a #![no_std] Rust RV64GC interpreter compiled to WebAssembly, following Fabrice Bellard’s approach to high-performance interpreters.

Design principles

  • Monolithic exec() — dense dispatch compiles to a WASM br_table (O(1) jump tables). Source is split across files with #[inline(always)]; fat LTO fuses everything into a single function.
  • #![no_std] Rust — no standard library, no heap allocation in the hot path, one small no_std dependency (vte, for the terminal parser).
  • Minimal host boundary — a handful of WASM imports, ~30 exports; filesystem I/O goes through shared memory, not per-instruction callbacks.
  • Cooperative threading — clone / futex multithreading with context switching at syscall boundaries, using the atomics the shared WASM memory enables.

Execution model

The interpreter fetches and decodes one instruction at a time and dispatches through the br_table. It runs uninterrupted until it hits a syscall boundary, where control returns to the host only if the syscall needs it.

Memory

Guest memory is a flat region managed with brk and mmap. A bump allocator handles the VM’s own small allocations; the guest program manages its own heap exactly as it would on real Linux.

The VM struct

The whole machine state is a single #[repr(C)] struct — 12,680 bytes — holding registers, CSRs, the memory map, the thread table and FS state. Its offsets are shared between the Rust interpreter and the JS host.

File
Responsibility
runners/riscv/src/cpu.rs
RV64GC interpreter loop
runners/riscv/src/decode.rs
instruction field extraction
runners/riscv/src/syscall.rs
Linux syscall dispatch (~80)
runners/riscv/src/mem.rs
guest memory read / write
runners/riscv/src/elf.rs
ELF loader (segments, argv/envp/auxv)
runners/riscv/src/term.rs
terminal (vte) model — ANSI parser + cell grid
runners/riscv/src/tty.rs
in-VM tty line discipline + stdin ring
runners/riscv/src/types.rs
the 12,680-byte VM struct
The browser wrapper lives in runners/riscv/host/ (nanovm.mjs, memfs.mjs). See the CLI & JS API and Host API pages.
← Previous
Architecture
Next →
Virtual server