README 12.5 KiB 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)