riscv/
.clang-format
570 B
.gitignore
5 B
.gitsigners
112 B
LICENSE
1.1 KiB
Makefile
1.1 KiB
README
3.4 KiB
color.h
567 B
emulator.c
83.2 KiB
io.c
1.1 KiB
io.h
444 B
jit.c
32.6 KiB
jit.h
5.0 KiB
riscv.c
12.0 KiB
riscv.h
12.0 KiB
types.h
1.0 KiB
README
raw
| 1 | |
| 2 | RADIANT RISC-V EMULATOR |
| 3 | |
| 4 | A RISC-V RV64I emulator with an x86-64 JIT compiler, interactive TUI |
| 5 | debugger, and headless execution mode. Part of the Radiant project. |
| 6 | |
| 7 | Supports the RV64I base integer instruction set, M (multiply/divide) |
| 8 | extension, and F (single-precision floating-point) extension. |
| 9 | |
| 10 | BUILDING |
| 11 | |
| 12 | $ make |
| 13 | |
| 14 | Requires `clang` and `lld`. The binary is written to `bin/emulator`. |
| 15 | |
| 16 | INSTALLATION |
| 17 | |
| 18 | $ make install |
| 19 | |
| 20 | Installed as `~/bin/emulator` by default. Can be overridden via the `PREFIX` |
| 21 | variable. |
| 22 | |
| 23 | USAGE |
| 24 | |
| 25 | Interactive (TUI): |
| 26 | |
| 27 | $ bin/emulator <program.bin> |
| 28 | |
| 29 | Headless: |
| 30 | |
| 31 | $ bin/emulator -run <program.bin> [<option>..] |
| 32 | |
| 33 | The emulator loads a self-contained Radiance RV64 image: |
| 34 | |
| 35 | Header "RAD0", version, and section sizes |
| 36 | Text Machine instructions |
| 37 | Read-only data Loaded at 0x00010000 |
| 38 | Read-write data Loaded at 0x00FFFFF0 |
| 39 | |
| 40 | Legacy flat binaries with optional `.ro.data` and `.rw.data` sidecars remain |
| 41 | supported. A `<program>.debug` sidecar may be used for source locations. |
| 42 | |
| 43 | |
| 44 | OPTIONS |
| 45 | |
| 46 | -run Run headless (no TUI). |
| 47 | -debug Load debug info for source-level diagnostics. |
| 48 | -no-jit Disable the JIT compiler; interpret only. |
| 49 | -memory-size=KB Physical memory size in KB (default 128 MB). |
| 50 | -data-size=KB Data memory size in KB. |
| 51 | -stack-size=KB Stack size in KB (default 256 KB). |
| 52 | -no-guard-stack Disable stack guard zones (enabled by default, 16 bytes). |
| 53 | -no-validate Disable memory bounds checking. |
| 54 | -trace Enable instruction tracing. |
| 55 | -trace-headless Enable instruction tracing in headless mode. |
| 56 | -trace-instructions Print each instruction during headless tracing. |
| 57 | -trace-depth=N Number of trace entries to display on fault. |
| 58 | -max-steps=N Maximum steps before timeout in headless mode. |
| 59 | -count-instructions Print instruction count on exit. |
| 60 | -watch=ADDR Set a memory watchpoint at ADDR. |
| 61 | -watch-size=BYTES Size of watched region (default 4). |
| 62 | -watch-arm-pc=ADDR Only trigger watchpoint after reaching ADDR. |
| 63 | -watch-zero-only Only trigger on zero-value stores. |
| 64 | -watch-skip=N Skip the first N watchpoint hits. |
| 65 | -watch-backtrace Print backtrace on watchpoint hit. |
| 66 | -watch-bt-depth=N Backtrace depth (default 8). |
| 67 | |
| 68 | MEMORY LAYOUT |
| 69 | |
| 70 | 0x00010000 Read-only data (.ro.data) |
| 71 | Program base Program text (instructions) |
| 72 | 0x00FFFFF0 Read-write data (.rw.data) |
| 73 | Memory top - stack size Stack |
| 74 | Memory top Top of memory |
| 75 | |
| 76 | ARCHITECTURE |
| 77 | |
| 78 | The emulator operates in two execution modes: |
| 79 | |
| 80 | Interpreter Steps through instructions one at a time. Used for the |
| 81 | TUI debugger, ecalls, ebreak, and as a fallback. |
| 82 | |
| 83 | JIT Translates basic blocks of RV64I instructions to native |
| 84 | x86-64 machine code. Blocks are compiled on first |
| 85 | encounter and cached (16 MB code cache, up to 256K |
| 86 | blocks). Falls back to the interpreter for system |
| 87 | calls and faults. |
| 88 | |
| 89 | The TUI debugger supports single-stepping, reverse execution (via |
| 90 | snapshots), register and stack inspection, and memory watchpoints. |
| 91 | |
| 92 | LICENSE |
| 93 | |
| 94 | Licensed under the MIT License, |
| 95 | Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer) |