RADIANT RISC-V EMULATOR

A RISC-V RV64I emulator with an x86-64 JIT compiler, interactive TUI
debugger, and headless execution mode. Part of the Radiant project.

Supports the RV64I base integer instruction set, M (multiply/divide)
extension, and F (single-precision floating-point) extension.

BUILDING

    $ make

  Requires `clang` and `lld`. The binary is written to `bin/emulator`.

INSTALLATION

    $ make install

  Installed as `~/bin/emulator` by default. Can be overridden via the `PREFIX`
  variable.

USAGE

  Interactive (TUI):

    $ bin/emulator <program.bin>

  Headless:

    $ bin/emulator -run <program.bin> [<option>..]

  The emulator loads a flat binary along with optional data sections:

    <program.bin>           Program text (machine instructions)
    <program.bin>.ro.data   Read-only data section
    <program.bin>.rw.data   Read-write data section
    <program.bin>.debug     Debug info (optional, for source locations)


OPTIONS

    -run                    Run headless (no TUI).
    -debug                  Load debug info for source-level diagnostics.
    -no-jit                 Disable the JIT compiler; interpret only.
    -memory-size=KB         Physical memory size in KB (default 128 MB).
    -data-size=KB           Data memory size in KB.
    -stack-size=KB          Stack size in KB (default 256 KB).
    -no-guard-stack         Disable stack guard zones (enabled by default, 16 bytes).
    -no-validate            Disable memory bounds checking.
    -trace                  Enable instruction tracing.
    -trace-headless         Enable instruction tracing in headless mode.
    -trace-instructions     Print each instruction during headless tracing.
    -trace-depth=N          Number of trace entries to display on fault.
    -max-steps=N            Maximum steps before timeout in headless mode.
    -count-instructions     Print instruction count on exit.
    -watch=ADDR             Set a memory watchpoint at ADDR.
    -watch-size=BYTES       Size of watched region (default 4).
    -watch-arm-pc=ADDR      Only trigger watchpoint after reaching ADDR.
    -watch-zero-only        Only trigger on zero-value stores.
    -watch-skip=N           Skip the first N watchpoint hits.
    -watch-backtrace        Print backtrace on watchpoint hit.
    -watch-bt-depth=N       Backtrace depth (default 8).

MEMORY LAYOUT

    0x00010000                 Read-only data (.ro.data)
    Program base               Program text (instructions)
    0x00FFFFF0                 Read-write data (.rw.data)
    Memory top - stack size    Stack
    Memory top                 Top of memory

ARCHITECTURE

  The emulator operates in two execution modes:

    Interpreter    Steps through instructions one at a time. Used for the
                   TUI debugger, ecalls, ebreak, and as a fallback.

    JIT            Translates basic blocks of RV64I instructions to native
                   x86-64 machine code. Blocks are compiled on first
                   encounter and cached (16 MB code cache, up to 256K
                   blocks). Falls back to the interpreter for system
                   calls and faults.

  The TUI debugger supports single-stepping, reverse execution (via
  snapshots), register and stack inspection, and memory watchpoints.

LICENSE

  Licensed under the MIT License,
  Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer)