.githooks/
riscv/
test/
.clang-format
570 B
.gitignore
5 B
.gitsigners
112 B
AGENTS.md
227 B
LICENSE
1.1 KiB
Makefile
3.5 KiB
README
12.5 KiB
STYLE
781 B
abi_host.c
12.2 KiB
abi_linux.c
3.7 KiB
bitmanip.h
5.8 KiB
color.h
567 B
debug_map.c
5.1 KiB
debug_map.h
1.3 KiB
emulator.c
87.3 KiB
host.h
5.5 KiB
host_posix.c
11.2 KiB
hosted.h
5.7 KiB
image_native.c
4.6 KiB
image_rad0.c
2.7 KiB
image_raw.c
2.6 KiB
io.c
1.1 KiB
io.h
444 B
jit.c
99.2 KiB
jit.h
7.8 KiB
machine.c
4.4 KiB
machine.h
2.1 KiB
machine_cpu.c
13.6 KiB
machine_csr.c
4.6 KiB
machine_devices.c
10.8 KiB
machine_fdt.c
8.7 KiB
machine_internal.h
7.4 KiB
muldiv.h
1.0 KiB
profile.c
17.5 KiB
profile.h
1.4 KiB
riscv.c
755 B
riscv.h
4.3 KiB
types.h
1019 B
vector.c
54.0 KiB
vector.h
1.3 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 and the M (multiply/divide) |
| 8 | extension. Machine mode adds the A extension, Zicsr and Zifencei. |
| 9 | |
| 10 | BUILDING |
| 11 | |
| 12 | $ make |
| 13 | |
| 14 | Requires `clang`, `lld`, `pkg-config`, and the BLAKE3 C library |
| 15 | (`libblake3`). The binary is written to `bin/emulator`. |
| 16 | |
| 17 | INSTALLATION |
| 18 | |
| 19 | $ make install |
| 20 | |
| 21 | Installed as `~/bin/emulator` by default. Can be overridden via the `PREFIX` |
| 22 | variable. |
| 23 | |
| 24 | USAGE |
| 25 | |
| 26 | Interactive (TUI): |
| 27 | |
| 28 | $ bin/emulator <program.bin> |
| 29 | |
| 30 | Headless: |
| 31 | |
| 32 | $ bin/emulator -run <program.bin> [<option>..] |
| 33 | |
| 34 | The emulator loads two image formats. The native format of current |
| 35 | compilers has a 48-byte little-endian header followed by the bytes of |
| 36 | three segments placed at their own addresses: |
| 37 | |
| 38 | 0 "RADIANCE" |
| 39 | 8 code address (u64), size (u32) |
| 40 | 20 read-only data address (u64), size (u32) |
| 41 | 32 read-write data address (u64), size (u32), zero-filled tail (u32) |
| 42 | 48 code, read-only data and read-write data bytes |
| 43 | |
| 44 | Execution starts at the code address. Code and read-only data occupy |
| 45 | exactly their size. Read-write data is followed by its zero-filled tail. |
| 46 | Each segment must lie inside the memory of the mode, and the file must be |
| 47 | exactly 48 plus the three sizes. Nothing else is checked. |
| 48 | |
| 49 | Images of older compilers also load in hosted mode, so that programs from |
| 50 | every release run unchanged. The format is recognized by its magic bytes: |
| 51 | |
| 52 | "RAD0" version 1 Section sizes and fixed load addresses: read-only data |
| 53 | at 0x00010000, then text, then read-write data at |
| 54 | 0x00FFFFF0. See image_rad0.c. |
| 55 | no magic The file is the text. Optional sidecar files |
| 56 | `<program>.ro.data` and `<program>.rw.data` hold the |
| 57 | data, at the same addresses. See image_raw.c. |
| 58 | |
| 59 | Machine mode loads only the native format. Each format is loaded by its own |
| 60 | file, image_native.c, image_rad0.c and image_raw.c. |
| 61 | |
| 62 | A `<program>.debug` sidecar may be used for source locations. |
| 63 | |
| 64 | |
| 65 | OPTIONS |
| 66 | |
| 67 | -run Run headless (no TUI). |
| 68 | -debug Load debug info for source-level diagnostics. |
| 69 | -machine Run RV64IMA M/U machine images, always headless. |
| 70 | Disables hosted calls, JIT, stack guards and TUI. |
| 71 | -harts=N Enable 1..8 independent machine harts (default 1). |
| 72 | -irq=N Inject one PLIC edge on source 1..31, excluding 10. |
| 73 | -irq-at=N Virtual tick of the one-shot edge (default 0). |
| 74 | -no-jit Disable the JIT compiler; interpret only. |
| 75 | -memory-size=KB Physical memory size in KB (default 128 MB). |
| 76 | -data-size=KB Data memory size in KB. |
| 77 | -stack-size=KB Stack size in KB (default 256 KB). |
| 78 | -no-guard-stack Disable stack guard zones (enabled by default, 16 bytes). |
| 79 | -no-validate Disable memory bounds checking. |
| 80 | -trace Enable instruction tracing. |
| 81 | -trace-instructions Print each instruction during headless tracing. |
| 82 | -trace-depth=N Number of trace entries to display on fault. |
| 83 | -max-steps=N Maximum steps before timeout in headless mode. |
| 84 | -count-instructions Print instruction count on exit. |
| 85 | -watch=ADDR Set a memory watchpoint at ADDR. |
| 86 | -watch-size=BYTES Size of watched region (default 4). |
| 87 | -watch-arm-pc=ADDR Only trigger watchpoint after reaching ADDR. |
| 88 | -watch-zero-only Only trigger on zero-value stores. |
| 89 | -watch-skip=N Skip the first N watchpoint hits. |
| 90 | -watch-backtrace Print backtrace on watchpoint hit. |
| 91 | -watch-bt-depth=N Backtrace depth (default 8). |
| 92 | |
| 93 | HOSTED SYSTEM CALLS |
| 94 | |
| 95 | Hosted programs call the emulator with `ecall`: the call number in a7, |
| 96 | arguments in a0..a3 and the result in a0. A negative result is an error |
| 97 | code. Memory is little-endian. Paths are (pointer, length) pairs without a |
| 98 | terminating zero. A range outside guest memory faults the guest. |
| 99 | |
| 100 | 0x400 exit(status) Does not return. |
| 101 | 0x401 read(fd, ptr, len) Bytes read, zero at end of file. |
| 102 | 0x402 write(fd, ptr, len) Bytes written. |
| 103 | 0x403 open(path, len, mode) Mode 0 reads; mode 1 creates or |
| 104 | truncates for writing. |
| 105 | 0x404 close(fd) Descriptors 0..2 stay open. |
| 106 | 0x405 stat(path, len, out) Writes size (u64), kind (u32: |
| 107 | 1 file, 2 directory, 3 other) |
| 108 | and u32 padding. |
| 109 | 0x406 makeDir(path, len) |
| 110 | 0x407 remove(path, len) A file or an empty directory. |
| 111 | 0x408 rename(from, flen, to, tlen) |
| 112 | 0x409 listDir(path, len, buf, blen) Names, each followed by a zero |
| 113 | byte, without "." and "..". |
| 114 | 0x40A spawn(spec) Runs an RV64 image in a child |
| 115 | emulator; returns a child handle. |
| 116 | 0x40B wait(child, out) Writes the outcome (kind u32: |
| 117 | 0 exited, 1 step limit, 2 fault; |
| 118 | code i32). |
| 119 | 0x40C waitAny(out) Returns the handle that ended. |
| 120 | 0x40D exchange(left, llen, right, rlen) Atomically swaps two existing |
| 121 | entries on the same filesystem. |
| 122 | |
| 123 | Errors: -1 NotFound, -2 Exists, -3 Denied, -4 NotEmpty, -5 Invalid (also |
| 124 | any other call number from 0x400), -6 TooLarge, -7 Limit, -8 Io. |
| 125 | |
| 126 | `spawn` takes a 128-byte record with the image path, the arguments, the |
| 127 | destinations of standard output and error, the mode (hosted or machine), |
| 128 | the machine and memory sizes, and the step budget. The child runs this |
| 129 | executable again with the matching options; its standard input is empty. |
| 130 | At most 64 children run at once. The children still running when the guest |
| 131 | ends are terminated. A child reports how it ended through the internal |
| 132 | option `-outcome-fd=N`, which is not meant to be passed by hand. |
| 133 | |
| 134 | The full specification is `.ai/decisions/2026-10-28-host-abi` in the |
| 135 | Radiance repository. Everything that touches the host operating system is |
| 136 | behind `host.h`; `host_posix.c` implements it for Linux and macOS. |
| 137 | |
| 138 | LINUX SYSTEM CALLS |
| 139 | |
| 140 | Programs built before the host ABI, up to October 2026, call the emulator |
| 141 | with Linux RV64 numbers. They run unchanged: numbers below 0x400 are Linux |
| 142 | calls and numbers from 0x400 are host calls, in the same run. See |
| 143 | abi_linux.c. |
| 144 | |
| 145 | 56 openat(dirfd, path, flags) Zero-terminated path; `dirfd` is ignored. |
| 146 | Flags O_RDONLY, or O_WRONLY | O_CREAT | |
| 147 | O_TRUNC. Returns a descriptor or -1. |
| 148 | 57 close(fd) Zero, or -1. |
| 149 | 63 read(fd, ptr, len) Bytes read; zero on failure. |
| 150 | 64 write(fd, ptr, len) Bytes written; zero on failure. |
| 151 | 93 exit(status) Does not return. |
| 152 | |
| 153 | Any other number returns -38 (ENOSYS). |
| 154 | |
| 155 | MEMORY LAYOUT |
| 156 | |
| 157 | 0x00010000 Read-only data |
| 158 | Program base Program text (instructions) |
| 159 | 0x00FFFFF0 Read-write data |
| 160 | Memory top - stack size Stack |
| 161 | Memory top Top of memory |
| 162 | |
| 163 | ARCHITECTURE |
| 164 | |
| 165 | The emulator operates in two execution modes: |
| 166 | |
| 167 | Interpreter Steps through instructions one at a time. Used for the |
| 168 | TUI debugger, ecalls, ebreak, and as a fallback. |
| 169 | |
| 170 | JIT Translates basic blocks of RV64I instructions to native |
| 171 | x86-64 machine code. Blocks are compiled on first |
| 172 | encounter and cached (16 MB code cache, up to 256K |
| 173 | blocks). Falls back to the interpreter for system |
| 174 | calls and faults. |
| 175 | |
| 176 | The TUI debugger supports single-stepping, reverse execution (via |
| 177 | snapshots), register and stack inspection, and memory watchpoints. |
| 178 | |
| 179 | MACHINE PLATFORM |
| 180 | |
| 181 | Machine execution is a separate RV64IMA + Zicsr + Zifencei interpreter, without |
| 182 | floating point, compressed instructions, page translation or PMP. Each hart |
| 183 | has independent registers, privilege, CSRs, traps, WFI and LR/SC reservation. |
| 184 | Harts are selected round-robin; one instruction or trap boundary advances |
| 185 | shared mtime by one tick. RAM and MMIO are strongly ordered, AMOs indivisible, |
| 186 | and every overlapping store invalidates LR reservations. FENCE ordering is |
| 187 | inherent; FENCE.I observes uncached instruction fetches. |
| 188 | |
| 189 | WFI sleeps until a locally enabled interrupt is pending, independently of the |
| 190 | global MIE bit. It never exits the emulator. When all harts sleep, virtual time |
| 191 | jumps to the next timer/input event or -max-steps deadline; idle ticks count |
| 192 | toward this bound. External, software, then timer is the M interrupt priority. |
| 193 | mtvec supports direct and vectored interrupts. Synchronous U faults trap to M. |
| 194 | |
| 195 | Physical devices (all other aperture offsets/widths fault): |
| 196 | |
| 197 | 0x02000000..0x02010000 CLINT: MSIP words at +4*hart; mtimecmp at |
| 198 | +0x4000+8*hart; mtime at +0xbff8. Timers accept |
| 199 | aligned 32-bit halves or 64-bit accesses. |
| 200 | 0x0c000000..0x10000000 PLIC: 31 sources, priorities 0..7 at +4*source, |
| 201 | pending at +0x1000, enable at +0x2000+0x80*hart, |
| 202 | threshold/claim/complete at +0x200000+0x1000*hart |
| 203 | and +4. Every register is 32-bit. M context=hart. |
| 204 | 0x10000000..0x10001000 Transmit-only 16550 UART: byte registers THR +0 |
| 205 | (stdout), IER +1 (only THRE, bit 1), IIR +2 and |
| 206 | LSR +5 (read only, always ready). Source 10 on the |
| 207 | PLIC is the level-sensitive THRE interrupt. |
| 208 | 0x10001000..0x10002000 Finish: 32-bit register at +0, writable in M and |
| 209 | U. Write 0x5555 for success, 0xNNNN3333 for |
| 210 | failure. Other writes fault. Reads return zero. |
| 211 | |
| 212 | RAM is [0x80000000,0x80000000+memory-size), above every device aperture. |
| 213 | Naturally aligned fetches/loads/stores are checked even with -no-validate. |
| 214 | The hosted stack and frame-pointer checks do not apply. Instructions may |
| 215 | execute anywhere in RAM, including admitted images outside the original text. |
| 216 | U stores to the original text and rodata are rejected as an optional ROM |
| 217 | defense, not memory isolation. |
| 218 | |
| 219 | Boot and FDT: |
| 220 | |
| 221 | Every hart starts at the loaded text entry in M mode. a0 and mhartid are its |
| 222 | zero-based ID; a1 is the FDT address, 0x80800000. sp is the 16-byte aligned |
| 223 | top of RAM minus hart*stack-size. Each full stack is reserved; all other |
| 224 | registers start zero. -stack-size applies independently to every hart. |
| 225 | |
| 226 | FDT v17 is stored in the fixed 64 KiB reservation [0x80800000,0x80810000). |
| 227 | Image or stack overlap with this reservation is rejected. The memory node |
| 228 | starts at 0x80000000. CPU interrupt-controller phandles are hart+1; |
| 229 | the PLIC phandle is 0x100. CLINT extended pairs are (hart+1,3),(hart+1,7); |
| 230 | PLIC contexts are ordered (hart+1,11). UART interrupt-parent is 0x100. |
| 231 | The timebase is 10 MHz. The finish compatible string is "radiant,finish". |
| 232 | |
| 233 | /chosen has radiance,kernel-entry (u64), radiance,kernel-text, |
| 234 | radiance,kernel-rodata, radiance,kernel-rwdata, radiance,fdt-reservation |
| 235 | (each address-u64,size-u64), and radiance,kernel-stacks (one such pair per |
| 236 | hart). Exact loaded sections, every initial stack, FDT storage and full |
| 237 | MMIO apertures appear in both the reservation map and reserved-memory |
| 238 | no-map nodes. Empty loaded sections have size zero in /chosen and are |
| 239 | omitted from reservations. |
| 240 | |
| 241 | -trace prints hart-tagged instructions and traps. -count-instructions reports |
| 242 | retired instructions separately from elapsed virtual ticks. Hosted source |
| 243 | debugging and watchpoints are rejected in machine mode. Process results are |
| 244 | 0 for explicit success, 1 for guest failure, and 2 for timeout/configuration or |
| 245 | host UART output failure. No host time, stdin polling or host threads affect |
| 246 | guest execution. This is not a cycle-accurate model of UART wire timing. |
| 247 | |
| 248 | The platform is exercised by the Radiance test suite (`make test` in the |
| 249 | Radiance repository, with `RAD_EMULATOR` set to this binary). |
| 250 | |
| 251 | LICENSE |
| 252 | |
| 253 | Licensed under the MIT License, |
| 254 | Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer) |