RISC-V Emulator Reference

This document describes the supported instruction set and runtime behavior for the RISC-V emulator.

Quick Start

To run your first RISC-V program:

ADDI x1, x0, 5
ADDI x2, x0, 10
JAL x5, sum_func
SW x3, 3(x1)
ECALL

sum_func:
  ADD x3, x1, x2
  JALR x0, 0(x5)

Address Range: 0x0000–0x0FFF (4096 bytes, 1024 words)
Word Size: 4 bytes
Alignment: LH/LHU → 2-byte aligned; LW/SW → 4-byte aligned.
Out-of-Range: Accesses beyond 0x0FFF show [Warning] Memory access out of bounds.
Stack Pointer (sp): Initialized to end of memory (0x0FFC). Stack grows downward.

32 general-purpose 32-bit registers (x0–x31).
x0 is hard-wired to 0 and cannot be written.
Program Counter (PC): 32-bit; increments by +4 unless modified by branch/jump.
ABI Aliases: Standard ABI register names are supported.

ABI Name	x#	Description
zero	x0	Constant zero
ra	x1	Return address
sp	x2	Stack pointer (0x0FFC)
gp	x3	Global pointer (0x0800)
tp	x4	Thread pointer
t0–t6	x5–x7, x28–x31	Temporaries
s0–s11	x8–x9, x18–x27	Saved registers
a0–a7	x10–x17	Function arguments / return values

Use either numeric (x5) or ABI (t0) notation — both are supported interchangeably.

Pseudo	Equivalent Expansion / Behavior
`LI rd, imm`	If `−2048 ≤ imm ≤ 2047`: `ADDI rd, x0, imm` Otherwise: `LUI rd, upper(imm)` + `ADDI rd, rd, lower(imm)`
`MV rd, rs`	`ADDI rd, rs, 0`
`J label`	`JAL x0, label`
`JR rs`	`JALR x0, 0(rs)`
`RET`	`JALR x0, 0(x1)` (return to caller)
`LA rd, label`	Computes the address of `label` using `LUI + ADDI` with sign-extension.

Implements the RV32I base integer instruction set as defined by the RISC-V Foundation.

For detailed bit fields and encodings, see the Official RISC-V Reference Card (PDF).

Arithmetic & Logic: ADD, SUB, AND, OR, XOR, SLL, SRL, SRA, SLT, SLTU, plus immediate variants.
Load/Store: LB/LBU, LH/LHU, LW, SB, SH, SW.
Branch/Jump: BEQ, BNE, BLT, BGE, BLTU, BGEU, JAL, JALR.
Upper-Immediate: LUI, AUIPC.
System: ECALL (halts program).

Darrel Wihandi
RISC-V Web Emulator Project
Built with C++ (Emscripten) + HTML/JS Frontend

Based on the RISC-V Reference Card (RV32I Base) by the RISC-V Foundation.

Last Updated: