StudyRISC-V reference

riscvsim executes RV32I and RV32M instructions on a five-stage pipeline. The browser and CLI use the same Rust engine.

addi x1, x0, 5
addi x2, x1, 3
add  x3, x2, x1

Install

Quick install

curl -fsSL https://studyriscv.com/install.sh | sh

Homebrew

brew tap rawcache/riscvsim
brew install riscvsim

CLI

run

riscvsim run program.s
riscvsim run program.s --verbose
riscvsim run program.s --max-cycles 5000000

Interactive session

riscvsim

Running riscvsim with no arguments opens the interactive session: the pipeline, register, memory, and output views, plus a slash-command prompt. Anything not starting with / is assembled and run as RISC-V source.

tui

riscvsim tui
riscvsim tui program.s
riscvsim tui program.s --tour

Opens the same interactive session with a file preloaded. --tour replays the first-run walkthrough.

serve

riscvsim serve program.s
riscvsim serve program.s --port 4300

Starts an in-memory local session and serves the browser interface. Closing the process ends the session. This stays available as a top-level command for scripting; /serve inside the interactive session does the same thing for the program you already have loaded.

doctor

riscvsim doctor

Reports the active executable, every PATH-visible copy, likely install methods, versions, and the latest published release.

Assembly syntax

.data
values: .word 1, 2, 3
label:  .asciz "ok"

.text
main:
  la   t0, values
  lw   a0, 0(t0)
  ret

RV32IM instructions

Pseudo-instructions such as li, la, mv, j, call, and ret expand during assembly.

Memory map

0x00000000  text segment
0x10000000  data segment
0x7ffffffc  initial stack pointer

The stack grows toward lower addresses. Loads and stores use little-endian byte order.

Pipeline

IF -> ID -> EX -> MEM -> WB

The engine implements forwarding, a one-cycle load-use stall, and a two-bit branch predictor. A misprediction flushes two younger instructions.

Rust engine

use sim_engine::{assemble, Pipeline};

let program = assemble(source)?;
let mut pipeline = Pipeline::new(program);
pipeline.step_cycle();
let snapshot = pipeline.snapshot();

pub fn assemble(source: &str) -> Result<Program, Vec<AsmError>>
pub fn c_to_asm(source: &str) -> Result<String, TranslateError>
pub fn asm_to_c(source: &str) -> Result<String, TranslateError>

WASM interface

import init, { assemble_pipeline } from "./riscvsim_core.js";

await init();
const sim = assemble_pipeline(source);
sim.step_cycle();
const snapshot = sim.snapshot();
const bytes = sim.read_memory(0x10000000, 16);

Translation interface

const assembly = translate_c_to_asm(cSource);
const illustrative = translate_asm_to_c(assemblySource);

translate_c_to_asm compiles the supported C subset to runnable RV32IM assembly.

translate_asm_to_c returns illustrative pseudocode. Its output is not compilable C.