# p/moul/x/vm/riscv
RV32IM in gno: 48 instructions that `rustc`, `clang`, TinyGo and Zig already
emit. A guest here is not written in a new language and is not translated by
anything of mine. It arrives compiled by the real compiler and optimized by the
real optimizer, and this package is a decode loop.
Live demo: [`r/moul/x/vm/riscvdemo`](/r/moul/x/vm/riscvdemo/v0).
Second guest on [`vmkit`](../vmkit), which is the only way to find out whether
the host ABI was shaped around the first one. It was not: `riscv` implements
`vmkit.Machine` unchanged and shares the fuel meter, the snapshot codec and the
instance store with [`bf`](../bf).
```go
m, err := riscv.NewMachine(image, 0x1000) // image is a flat .text blob
if err != nil { return err }
used, status := m.Step(host, 50_000) // running, halted, trapped, out of fuel
snap := m.Snapshot() // resume in a later transaction
```
## Does it clear the bar
The design issue set a kill criterion before any code existed: **above roughly
15,000 gas per RV32I instruction the track is a curiosity, not a substrate**, on
the reasoning that a guest would then get about 200k instructions per block,
which is a token transfer and not a program anyone would write without thinking
about it.
Measured 2026-09-25 with `gno test -v` (`--- GAS:`), `gno` built from
`gnolang/gno` master. The figure is a slope from two loop sizes, 4,006 and
16,006 instructions, so the fixed per-test overhead cancels. The slope is
stable to a few gas between runs; the fixed term is not, which is why it is a
slope:
| rung | what changed | gas / instruction |
|---|---|---:|
| 0 | `decode.gno`'s helpers called per instruction | 33,992 |
| 1 | field extraction and the fetch inlined into the dispatch loop | 18,834 |
| 2 | predecode once at load, dispatch on a frequency-ordered opcode | **8,487** |
**It clears the bar with a 1.8x margin**, which works out to about **354,000
guest instructions per block**. The ladder is worth 4.0x end to end, and all of
it came from moving work off the per-instruction path rather than from doing
anything clever with the instruction set.
Reproduce with `gno test -v .` and read `TestBenchRV32I1000` and
`TestBenchRV32I4000`.
Be careful what that number is not. 354k instructions is a real program and a
small one: a sort, a parser, a state machine, a few thousand iterations of a
loop. It is not a signature verification, which is millions of instructions, and
the chain already has secp256k1 natively for that reason.
## Conformance
The official [riscv-tests](https://github.com/riscv-software-src/riscv-tests)
suite passes: **all 42 `rv32ui` cases and all 8 `rv32um`**, embedded in
`conformance_test.gno` and run on every `gno test`.
This is the only thing here a third party wrote. Everything in `riscv_test.gno`
checks that the emulator agrees with its author's reading of the spec; this
checks that it agrees with the people who wrote the spec, using their
assertions, compiled from their source.
One case is skipped and the skip is declared rather than omitted:
**`rv32ui-fence_i`**. `FENCE.I` exists to make writes to the instruction stream
visible, and this machine predecodes its text and refuses stores into it, so
there is nothing to make visible. Self-modifying code is not unimplemented here,
it is excluded.
The suite's own environment sets up `mtvec`, delegates exceptions and enters
through `mret`, none of which exists on a hart with no CSRs. The corpus was
therefore built against a replacement `riscv_test.h` that keeps the `_start`
symbol and `TESTNUM` in `gp` and drops the machine-mode ceremony. **The exit
convention is the suite's own, untouched**: it already spells pass and fail as
`li a7, 93; ecall`, which is this host's exit syscall. What was replaced is how
a case starts and hands back its verdict, not what it checks. Rebuild it with
[`tools/riscv-guests/conformance`](../../../../tools/riscv-guests/conformance).
Two faults were injected to confirm the suite bites rather than merely passing:
SRAI as a logical shift takes out `rv32ui-srai` and `rv32ui-lui` at case 3, and
REMU by zero returning 0 takes out `rv32um-remu` at case 8. Both are recorded in
the test file, and the harness's own pass and fail decoding is pinned by two
tests so a change that made every case report success would not read as green.
## Guests a compiler produced
The claim this package rests on is that a program arrives compiled by the real
compiler, so two of them are shipped compiled and nothing is trusted to stand in
for that. Both are rebuildable: source, linker script and exact command are in
[`tools/riscv-guests`](../../../../tools/riscv-guests), and the committed words
were verified to match a fresh build.
| | language | words | what it does |
|---|---|---:|---|
| `riscv.GuestFNV()` | C, clang 19.1.7 | 49 | hashes the call input with FNV-1a |
| `riscv.GuestLedger()` | Rust, rustc 1.98.1, `#![no_std]` | 1,959 | mint, send and burn from a script |
```go
m, _ := riscv.NewMachine(riscv.GuestLedger(), riscv.DefaultEntry)
m.Step(host, 50_000)
// input: "mint alice 100\nmint bob 50\nsend alice bob 30\n"
// output: "alice 70\nbob 80\n"
```
Between them they exercise what a hand-written program does not: a real function
prologue spilling `ra` and `s0` to a stack the host set up, `.bss` addressed far
above a text segment the host refuses stores into, LLVM materializing constants
through `lui`/`addi` pairs at the sign-extension boundary that bit this package
twice, and `MUL` in an inner loop.
**The Rust one goes further, and that is why it is worth its size.** It links
Rust's real `core` and `compiler_builtins`, which it never calls directly: a
bounds check reaches `core::panicking`, and the balances are 64-bit, so a divide
reaches `__udivdi3` because **RV32 has no 64-bit divide instruction**. The
emulator is running the standard library's own software arithmetic, not only
what the compiler emitted for my source. `TestRustLedgerDoes64BitArithmetic`
pins a balance past 2^32 to keep that path live.
Both pause and resume correctly when sliced, the Rust one seventeen instructions
at a time, in the middle of a library routine it never asked to call. That is
the property a realm depends on and the one most likely to break on code nobody
wrote to be sliceable.
A refusal from the ledger is **halted, not trapped**: `line 2: insufficient
balance`, exit code 1. The program said no and the machine did not break, and a
chain has to be able to tell a user which happened.
The memory layout is not incidental. W xor X means a guest whose writable data
shared a page with its code would trap on its first store, so the linker script
is part of the ABI and each guest pins its own: the addresses in it are baked
into the instruction stream as `lui` immediates, so a shared script edited for
one guest would silently invalidate every image built against the old one.
## What the GnoVM charges for, measured
The rungs above are not classic interpreter optimizations. They are answers to
how *this* host executes code, and `switchcost_test.gno` measures it directly,
200,000 iterations per figure:
| what | gas each |
|---|---:|
| one elementary operation, from the loop control | ~280 |
| a function call | 466 |
| a call through a table indexed by opcode | 727 |
| `switch`, hitting the **first** case | 292 |
| `switch`, hitting the **48th** case | 13,358 |
| **each case label scanned on the way** | **278** |
| `make([]byte, n)`, for any n | 655,224, flat |
Two of these decided the design:
1. **The GnoVM scans switch cases in source order.** Case 47 costs 45x case 0.
So the internal opcodes in `predecode.gno` are ordered by how often compiled
code executes them, and that ordering is load-bearing: sorting that list
alphabetically would make the interpreter slower. It also means a flat
48-case switch is only a win if the common instructions are near the top,
and that a table of function values (727 gas, position independent) beats a
switch for anything past the third case.
2. **`make` does not charge for size.** A megabyte costs what four kilobytes
costs. The flat 1 MiB address space is therefore free at load, and the thing
to economize is per-word work, not bytes.
## The cost on the other side: predecode
Predecoding is **19,623 gas per word**, paid at load and again on every resume,
because the arrays are not in the snapshot: only the memory pages are.
That is 2.3x what executing an instruction costs, which is high enough to state
plainly rather than bury:
- **It pays for itself once a slice executes about 1.9 instructions per word of
its text** (`19,623 / (18,834 - 8,487)`). Any loop clears that immediately.
Straight-line code run once does not, and for that shape rung 1 is the faster
interpreter.
- **A large binary pays it every transaction.** A 64 KiB text segment is 16,384
words, so a resume costs about 321M gas, roughly 11% of a block, before the
guest executes anything.
The fix is known and not done here: decode a word the first time it is reached
rather than all of them at load, keyed on a sentinel opcode. That costs one
comparison per instruction (~280 gas, about 3%) and charges only for code the
guest actually runs. Worth doing when a real binary shows up; not worth
guessing at now.
Merging the immediate decoder into the opcode switch already took predecode from
31,432 to 19,623 gas per word. The two were separate functions, and the second
one had a `case` clause listing 22 opcodes, every label of which was scanned.
## Semantics
**W xor X.** A store into the text segment traps. Predecoding is only sound if
the code cannot change under the arrays, and refusing is also what an ELF text
segment does, so self-modifying code is not a thing this VM has. `FENCE.I` is
therefore unnecessary and `FENCE` is a no-op, which is what it architecturally
is on a machine with one hart.
**`exit(1)` halts, it does not trap.** A program that returns non-zero said no;
it did not break. A chain that conflates "your code failed" with "the VM failed"
cannot tell a user which one happened.
**An unknown syscall traps** rather than returning zero, so a guest built
against a newer syscall table fails loudly on an older host instead of silently
reading a success it never got.
**The M extension's edge cases return values, they do not trap.** Division by
zero gives all ones, and `INT_MIN / -1` gives `INT_MIN`. The spec defines both
precisely, which is exactly what a chain needs: there is no host arithmetic
exception left to differ between nodes.
**No F, no D, no C, no A.** No floats means no rounding mode and nothing that
can differ between nodes. No compressed instructions means every instruction is
4 bytes and `(pc - base) >> 2` is the whole fetch. No atomics because there is
one hart.
**Misaligned is a trap, out of range is a trap.** RISC-V leaves an access
outside physical memory to the platform, and a chain has to pick the behaviour
that cannot differ between nodes. Refusing is deterministic; wrapping would let
a guest alias two addresses and get different answers from different memory
sizes.
## Snapshots
A 1 MiB address space that serialized in full on every pause would make
continuations cost more than re-running, which is the kill criterion `vmkit` set
for them. Memory is snapshotted by **dirty page**: a guest that has written two
pages pauses in about 8 KiB regardless of how much memory it was given, and
`TestSnapshotCarriesOnlyTouchedPages` asserts the proportionality rather than a
magic number.
The program is not written twice. It is in the memory pages already, marked
dirty by `WriteImage`, so a snapshot carries the text extent and re-derives the
predecode from the restored pages.
## The syscall table
Eight calls, in the RISC-V Linux register convention a compiler already knows:
`a7` selects, `a0`..`a3` carry arguments, `a0` receives the result. A no_std
guest needs three lines of inline assembly and no gno-specific runtime.
| a7 | call | maps to |
|---:|---|---|
| 93 | `exit(status)` | halts the machine |
| 64 | `write(fd, buf, len)` | `Host.Output` |
| 63 | `read(fd, buf, len)` | `Host.Input` |
| 90 | `height()` | block height |
| 91 | `now()` | block time, Unix seconds |
| 92 | `caller(buf, len)` | the calling address |
| 94 | `log(buf, len)` | `Host.Log` |
| 95 | `emit(type, typelen, body, bodylen)` | `Host.Emit` |
Deliberately small, and every one of them is something `vmkit.Host` already
offers. The Host is the audited surface; a syscall that reached past it would be
a second, unreviewed one. One call's buffer is capped at 64 KiB, because a guest
asking to write a gigabyte has found the host's allocator, not something to say.
## Tests
The assembler in `riscv_test.gno` is written from the spec independently of the
decoders in `decode.gno`, so a field in the wrong place fails unless both files
put it in the same wrong place. `decode_test.gno` round-trips all five immediate
formats at their sign boundaries, which is where this went wrong twice while it
was being written: a 12-bit immediate makes `addi x8, x0, 4000` load **-96**,
and a 13-bit B-type immediate makes a hand-written `-8` branch jump forward by
4,088.
<!-- BEGIN GNOCONTRACTS FOOTER (generated by `make readmes`; do not edit below) -->
---
Part of **[moul/gno-contracts](https://github.com/moul/gno-contracts)** — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.
**Dependency graph:**
> 🧪 **Highly experimental — potentially vibe-coded.** Not audited; may break, change, or be removed at any time. Do not use with anything of value. Full disclaimer: [DISCLAIMER](https://github.com/moul/gno-contracts/blob/main/DISCLAIMER.md).
<!-- END GNOCONTRACTS FOOTER -->
Signatures reconstructed verbatim from vm/qfuncs — interface params keep their inline definitions.