MAVILERA RISC-V Laboratory: documentation

Interactive Microprocessor Architecture Laboratory: Visualize. Execute. Understand.

About RISC-V

RISC-V is an open instruction set architecture (ISA): the instructions, registers and memory model that software sees, which anyone may implement without paying a royalty. This laboratory runs RV32I, the 32-bit base integer instruction set, with the M extension for multiplication and division.

Krste Asanović and the graduate students Yunsup Lee and Andrew Waterman started RISC-V in May 2010 in the Parallel Computing Laboratory (Par Lab) of the University of California, Berkeley, which David Patterson directed; the first manual (2011) is by Waterman, Lee, Patterson and Asanović. The RISC-V Foundation was founded in 2015 with 36 founding members, and in March 2020 the RISC-V International Association was incorporated in Switzerland. RISC-V International maintains and ratifies the specifications.

Why it matters: an open, royalty-free ISA lets companies, universities and individuals design processors for it and share cores and tools, instead of licensing an instruction set from one company. Its base is small and regular, with standard extensions added as needed, which makes it practical for teaching processor design, as in this laboratory.

Where it is used, for example: Espressif's ESP32-C3 and ESP32-C6 microcontrollers have RISC-V processors; Raspberry Pi's RP2350 has two Hazard3 RISC-V cores beside two Arm Cortex-M33 cores; Western Digital announced its open-source SweRV RISC-V core in 2018, with the goal of moving one billion of its processor cores to RISC-V; NVIDIA presented in 2016 its plan to replace its Falcon controller with its own RISC-V core.

The architecture is specified in RISC-V International's manuals. They have no DOI; the links are the publishers' own pages.

• The RISC-V Instruction Set Manual, Volume I: Unprivileged ISA RISC-V International, ratified version 20260120: the instructions this laboratory runs.
• The RISC-V Instruction Set Manual, Volume II: Privileged Architecture Version 20260120: machine mode, CSRs, traps and interrupts.
• RISC-V ELF psABI The calling convention and the register names of the ABI.
• The RISC-V Instruction Set Manual, Volume I: Base User-Level ISA A. Waterman, Y. Lee, D. A. Patterson, K. Asanović. UC Berkeley, technical report UCB/EECS-2011-62, 2011: the first manual.
• Design of the RISC-V Instruction Set Architecture A. Waterman. PhD thesis, UC Berkeley, UCB/EECS-2016-1, 2016: the reasons behind the design.

Sources of the history and the examples:

• About RISC-V International History and governance.
• Espressif ESP32-C3
• Espressif ESP32-C6
• Raspberry Pi RP2350
• Western Digital press release, 4 December 2018
• NVIDIA RISC-V Story, 4th RISC-V Workshop, 2016

Overview

The RISC-V Laboratory, the first module of MAVILERA, is an assembler, simulator and teaching compiler for the RISC-V base integer instruction set (RV32I) with the multiply and divide extension (M), together with three processors that you can watch execute a program clock cycle by clock cycle: a single-cycle, a multicycle and a five-stage pipelined processor.

It is a static web page. Every computation runs in your browser; there is no account, no server-side processing, no telemetry, and nothing you write is uploaded.

Getting started

1. Open the application. The editor holds a short example program; Templates in the toolbar offers others, each showing one idea, with a note at the top on what to try.
2. Press Assemble (Ctrl+Enter). The listing shows each instruction with its address and machine word; errors are underlined in the editor and explained in the console with a hint.
3. Press Step (F10) a few times. The current instruction is marked in the editor and the listing; the register it wrote is marked ◆.
4. Press Step back (Shift+F10) to undo a step, or Run (F5) to run to the end or to a breakpoint.
5. Choose Pipelined at the top. The same program now runs on the pipelined processor: each step is one clock cycle, and the drawing shows which paths each instruction uses.

A program that should end cleanly finishes with the exit system call or with halt:

        .data
nums:   .word 3, -1, 4, 1
        .text
main:   la    t0, nums        # address of the array
        lw    a0, 0(t0)
        lw    t1, 4(t0)
        add   a0, a0, t1      # a0 = 3 + (-1)
        li    a7, 93          # exit, with the code in a0
        ecall

The workspace

The page is a workspace of panes, as in a code editor.

• Header: the views (ISA, Single-cycle, Multicycle, Pipelined, Compare); the View menu (show or hide panes, reset the layout); the theme (system, dark, light); projector mode; full screen; the keyboard summary; Help.
• Toolbar: Assemble (Compile for C), Run/Pause, Step back, Step, Step over, Step out, Run to cursor, Reset, the speed, the profile and the File menu. Each control has a tooltip with its name and shortcut.
• Editor: line numbers with a breakpoint gutter, error marks, completion of mnemonics and registers, and help when you point at an instruction. The status line shows the cursor position, the profile and whether the text is newer than the assembled program.
• Listing: address, machine word (hexadecimal, and binary grouped by field on request), instruction and source line. Further tabs show the data, the symbols and, for C, the assembly generated.
• Instruction inspector: the selected word split into its fields, named and shaded by role, the immediate as gathered and sign-extended, and the operation in register-transfer notation. At its top, Encode or decode turns one instruction into its word, or a word into its instruction.
• Registers: the PC and x0–x31 with their ABI names, in hexadecimal, signed, unsigned or binary, and in decimal; select one to see every format.
• Call stack, Counters (instructions by class, deepest stack use; cycles and CPI in the processor views), Memory (words or bytes, go to an address, a label or where a register points) and Console (program output and messages).

Layout

Every boundary between panes is a divider: drag it, or focus it with Tab and use the arrow keys (Shift for larger steps); Enter or a double click restores it. Panes fold with the chevron in their heading. Sizes are kept in the browser for each view; View ▸ Reset layout forgets them. Below 900 px the panes stack and the page scrolls.

Projector mode uses larger type and lines and keeps the editor, the main view and the registers open, with the other panes folded but reachable.

Assembly language

Profiles and memory

The profile decides which instructions are accepted and how memory is laid out.

The single-cycle view also offers a smaller instruction set and an extension with lbu, chosen beside the profile.

Registers

Directives

.text .data .rodata .bss choose the section; .word .half .byte place values; .ascii .asciz .string place text; .space reserves bytes; .align .balign align; .equ .set name a constant. Expressions may use numbers (decimal, 0x…, 0b…), labels, +, -, parentheses, %hi() and %lo().

Pseudo-instructions

System calls (ISA profile)

Several source files can be assembled together; labels are shared between them. GCC output made with gcc -S -march=rv32im -mabi=ilp32 (or rv32i) can be opened directly: it is adapted for the simulator, start-up code is added, and every change is listed in the console.

The C subset

Choose C under Language in the editor heading; Compile replaces Assemble. The compiler translates one statement at a time so that each line of C can be followed into its assembly: point at a line on either side to mark its counterpart.

• Types: int, unsigned, char, short, _Bool and the <stdint.h> types up to 32 bits; one-dimensional arrays; pointers.
• Statements: if/else, while, do–while, for, switch, break, continue, return; expressions with C's operators and precedence.
• Functions with up to eight arguments, following the standard calling convention; putchar and exit are built in.
• Preprocessor: comments, #include <stdint.h>, object-like #define, #undef, #if/#ifdef/#ifndef/#elif/#else/#endif, #error.
• Outside the subset: structures, floating point, 64-bit types, goto, function-like macros and the standard library. The compiler names such a construct when it meets one.

Translation: Plain keeps every variable in the stack frame, as an unoptimised compiler does; Register keeps scalar locals and parameters in s1–s11. ISA: on RV32I, which has no multiply or divide instructions, the program calls software routines for them. A real compiler such as GCC produces different code.

Running and debugging

• Breakpoints: click a line number in the editor, or an address in the listing (B on a row).
• Watchpoints: tick a register's eye to stop when it is written; double-click a memory word, or type an address or label and press Watch, to stop when that word is written.
• Call stack: each call in progress with its call site, return address and the argument registers a0–a7 as they were at the call.
• Calling-convention check: faults such as a procedure returning with a register changed that it must keep are reported in the console as they happen.
• Uninitialised values: a register read before anything wrote it since reset (other than zero and sp), or a stack word loaded before anything stored it, is reported in the console with a link to its line. This is the simulator's own check, with no reference model behind it; saving ra or s0–s11 on the stack in a prologue is not reported, since that is how a procedure keeps them.
• Endless loops: a run that does not halt stops after a large number of instructions and names the addresses it is looping between.
• Errors at run time (a misaligned access, an unknown system call, a jump into data) stop the run with a message and, where it helps, a hint.

Processor views

The three processor views share one layout: the datapath drawing, a row of details tabs below it, and the editor and registers beside it. One step is one clock cycle.

• The connections and elements that the current instruction (or state, or stage) uses are highlighted; the rest of the datapath stays visible, muted. Point at a connection or a control line for its value.
• Display: the signal flow after each clock edge (off, slow, normal, fast), moving arrows, all values on the drawing, decimal values, and export of the drawing as SVG or PNG.
• Preset highlights predefined sets of paths on the datapath.
• Enlarge gives the drawing the whole window; Esc restores it.
• Waveforms (a details tab): chosen signals over the clock cycles run so far, as a timing diagram — one-bit signals as a level, wider ones as a bus with its value. Choose the signals with Signals…; select a cycle, or use the cycle buttons, to go to it. The values are the same records as the VCD export; the axis orders cycles and is not hardware timing.
• Select an element of the drawing (or press Enter on it) to open its details. The Signals or Cycle tab lists every signal of the cycle as text, the same information as the drawing.

Single-cycle processor

Every instruction completes in one clock cycle. The tabs are:

• Cycle: what happens in this cycle, in words, and every signal with its value.
• Control: the main decoder, the ALU decoder and the branch condition, with the column or row in use marked.
• Timing: the critical path of each instruction class, the one that sets the clock period, and the delay table. Change a delay to see the critical paths and the clock period move; Critical path in Display draws the path of the current instruction. The delays are illustrative teaching values, not measurements of any technology.
• Data memory.

Multicycle processor

Each instruction takes several shorter clock cycles, steered by a state machine (a Moore machine: every output depends on the state alone).

• The drawing area shows the Datapath or the State diagram; the current state is filled and the transition taken into it is drawn heavy.
• Instruction ▶ (F11) runs the cycles of one instruction, up to the next FETCH; ◀ Instruction steps back to the FETCH of this instruction or the one before.
• Controller: the state-output table with the current state marked, and the decoders outside the state machine.
• Registers between steps: the non-architectural registers, what each holds, whether it is written at the next edge and why it is needed; and the architectural state written at the next edge.
• States over time: one row per instruction, one column per clock cycle; select a cell to go to that cycle.
• Step timing: the critical path of each step and the clock period they set.

Code and data share one memory, with data from 0x200. The multicycle processor of this edition has no state for jalr: a program that uses it stops at the jalr with a message.

Pipelined processor

A five-stage pipeline (IF, ID, EX, MEM, WB) with pipeline registers IF/ID, ID/EX, EX/MEM and MEM/WB. The drawing shows the instruction in each stage; forwarding multiplexers are part of the datapath.

Settings above the drawing

• Hazards: how far the hazard unit is built, from none to complete: Stub: none (no forwarding, no stall, no flush), forwarding from MEM only, forwarding from MEM and WB, forwarding with the load-use stall, and Complete (forwarding, load-use stall and flush). With an incomplete unit, stale values and instructions executed on the wrong path are shown and counted.
• Resolve in: branches and jumps resolved in EX (the reference design) or, as an extension, in ID, which costs one cycle per redirect instead of two.
• Predictor: none (every branch predicted not taken), a 1-bit or a 2-bit branch-history table with a chosen number of entries. While a predictor is selected, its fetch-stage hardware is added to the drawing.
• Stop on: a run stops at a stall, a flush or a misprediction, as ticked.

Details tabs

• Pipeline diagram: cycles left to right, instructions top to bottom; stalls (‖), flushes (✕), bubbles (○) and wrong-path instructions (!) are marked. Repeated loop iterations can be folded.
• Hazards: the outputs of the hazard unit in this cycle and, in words, why.
• Run summary: the cycles lost so far, by cause and by place in the program.
• Pipeline registers: the contents of each register in this cycle, and whether it is held or cleared.
• Predictor: the branch-history table, the lookup in IF and the update at the edge.
• CPI: cycles, instructions, stalls and redirects; the CPI from the pipeline model CPI = 1 + f_lu + f_br × m × p + f_j × p beside the measured CPI, and the CPI by component.
• Signals: every signal of the cycle, by stage.

Comparison

The Compare view runs the program of the editor to its halt on the three processors and tabulates the instructions N, the clock cycles, CPI, the clock period T_c, the time per instruction, the execution time N × CPI × T_c and the speed-up over the single-cycle processor, and whether the registers and data at the halt agree with the single-cycle run. The pipelined count includes four cycles of pipeline fill. The delays are illustrative, not hardware timing.

Memory and caches

The Memory button chooses the memory model: ideal memory (one cycle per access), main memory without a cache (every access waits), or main memory with an instruction cache (L1I) and a data cache (L1D), each with a size, block size, number of ways, replacement and write policy of your choice. The designs are illustrative, not those of any real processor. Any change restarts the program. The instruction-level view has no clock: its caches show what the program's accesses have done so far, with no timing.

The Cache tab of the Memory and cache panel shows the last access of each cache, how the address finds its line, the lines as sets and ways, and the counters. Under the last access an animation shows the access step by step: the address split into tag, index and offset, the set read and its tags compared, then a hit, or a miss followed by the eviction of a line, the write-back of a dirty block and the fill from main memory, and last the word itself. Replay, Next step and Show all steps control it; with reduced motion switched on in the system, all the steps are shown at once.

The templates of the group Caches and memory each set the memory model they need: spatial locality, stride, conflict misses, write-back, replacement, the pipeline waiting for memory, and the comparison of the processors under the three memory models.

Devices and traps

The profile ISA with traps and devices (Profile list, instruction-level view) adds the platform of the laboratory: a GPIO at 0x4000_0000 with eight LEDs, four switches and a push button, a machine timer at 0x4000_1000, and a UART at 0x4000_2000. The Zicsr instructions, mret and wfi are instructions; ecall, ebreak, a misaligned or protected access and an illegal instruction raise exceptions; the timer, the button and the UART can interrupt. The rules of the traps, the timer and the GPIO follow rvsim.py --priv, the reference model this laboratory is checked against; the UART, a simple model of this laboratory, is not in it. Compiled C programs and the exit and write calls of the plain ISA profile are not available here, because ecall is a trap.

The Peripherals tab of the Memory and cache panel draws the board: the LEDs glow with the GPIO output, the switches and the button can be operated with the mouse or the keyboard (Space or Enter), the timer's count fills against its compare value, and the interrupt lines to the processor light while a request is active. Below are the processor's mode and trap registers, every device register (read without side effects), the UART terminal, a table of the interrupts with the cycles from request to handler, and the stimulus script of pin events; each pin you change is added to the script at the current cycle, so Reset and Step back replay it. The model is abstract: one cycle per instruction, 3 to take a trap, 4 to send a UART byte; these are not measurements of a real core.

The pin script, the bytes you send to the UART and the settings are kept with the program: after a reload and in links and settings files. The settings hold the options of the reference model: how often MTIME advances, the cycles to take a trap, mtval always 0, and a trap check that reports an interrupt handler which does not give back every register or returns to the wrong place. With Platform devices on the bus switched on in the Memory setting, the single-cycle, multicycle and pipelined views get the same devices and board; a program polls them with lw and sw, and stepping back restores them. Interrupts and traps exist only in the profile with traps.

The templates of the group Devices and traps are a running light, switches and a button by polling, a button interrupt, the timer by polling and by interrupt, a system call as a trap, and a serial port.

Exercises

File ▸ Exercise… lists 14 practice exercises written for MAVILERA — bit counting, Gray code, clamping, greatest common divisor, digit sums, Collatz steps, integer square root, reversing an array, palindromes, polynomials, printing a number, and three in C — each with a starter program and tests; no solutions are included.

A teacher can also give a task with tests in a file. Open it with File ▸ Open (or File ▸ Exercise…): the task is shown, Run the tests runs them on the program in the editor, and each test lists what it checks, the expected value and your program's. The file is read in the browser and kept there until you close the exercise; nothing is uploaded, and MAVILERA itself contains no exercises or answers.

The file format, for teachers

A JSON file with "format": "risc-vista-exercise" and "version": 1:

{
  "format": "risc-vista-exercise", "version": 1,
  "title": "Sum of an array",
  "task": "Write a procedure sum that returns in a0 the sum of the a1 words at the address in a0.",
  "lang": "asm",                       // or "c"
  "starter": "...",                    // optional: a program to start from
  "entry": "sum",                      // optional: call this label as a procedure in each test
  "tests": [
    { "name": "four numbers",
      "registers": { "a0": "arr", "a1": 4 },          // numbers, or labels of the program
      "memory": [{ "at": "arr", "words": [1, 2, 3, 4] }],
      "expect": { "registers": { "a0": 10 }, "abi": true },
      "limit": 100000 }
  ]
}

Expectations may check registers, memory (words, halves or bytes at a label or address), the console output, the exit code, and "abi": true (the calling convention is kept). With entry, each test calls that procedure with the test's registers and stops at its return; without it, the program runs from its start to its exit. Tests run in the ISA profile; a C program is compiled with the editor's translation settings.

Files, sharing and examples

• Your work is kept in this browser. After a refresh or a closed tab the program comes back with its file name, the cursor and scroll position, breakpoints, watchpoints, data loaded with Data in and out… and the step or clock cycle you had reached (replayed from reset; a run of more than two million steps starts again from reset).
• Templates (toolbar): short programs grouped by view (instruction level, C, single-cycle, multicycle, pipelined, comparison), each opening in its view with its settings: a loop, procedures and the stack, recursion, a calling-convention fault, bit fields, endianness, overflow, a watchpoint, the two C translations, the critical path, CPI by class, forwarding, the load-use stall, the hazard unit part by part, branch prediction and its limits, the cost of jumps, and the speed-up of the three processors.
• File ▸ Open… reads .s, .c and settings files (.json). Save .s writes the source.
• File ▸ Copy share link puts the program, the view and its settings into a link, after the #, the part a browser never sends to a server. A program too long for a link is shared with Save program and settings…, a .json file. Opening a link or file keeps your previous text; Restore text before the link brings it back.
• File ▸ Examples… (or More examples… at the end of Templates) opens the templates and further example programs, grouped by topic and processor; each opens in the view of its processor.
• File ▸ Data in and out… loads a CSV, text or binary file into a data array of the program before a run, and saves a memory range as CSV or .bin.
• Import .hex/.bin… runs a memory image without source.

Exports

The run exports replay the program from reset to its halt; the session you are in is not changed.

Offline use and privacy

• After a first visit, the hosted application opens without a network connection: the browser keeps its files and checks for a new version when it can.
• The single-file version, offered on the home page, is one .html file that opens from the local disk and makes no network request.
• Browsers that support it can install the application as an app from their menu.
• No account, no tracking, no upload: programs, data files and exports never leave the browser.

Accessibility

• Every control works from the keyboard, with a visible focus.
• Every clock cycle of a processor view is also described in text (the Cycle or Signals tab), and every drawing has a title and a description.
• Control signals are drawn dashed, so they are told apart from data by more than colour. Text contrast in both themes is part of the automated scan. The signal flow is off when the system asks for reduced motion.
• The interface aims at WCAG 2.2 level AA outside the drawings. Each release is checked with an automated accessibility scan in the tested browsers, recorded in its validation record; no broader conformance is claimed.

Keyboard reference

Limits of the models

• The processors are teaching models of their datapaths and control. A simulation shows what the model does; it is not evidence of how any hardware implementation behaves.
• Delays, clock periods and execution times are computed from illustrative delay values.
• The processor views have small memories and implement a subset of RV32I; the ISA view runs the full RV32I and M instruction sets.
• The privileged architecture (CSRs, traps, interrupts) is not simulated in this version.
• What each release was checked against is listed in its validation record, linked from the home page.

Glossary

ABI

The calling convention: which registers carry arguments and results, and which a procedure must keep.

Bubble

An empty slot in a pipeline stage, inserted by a stall or left by a flush.

Clock period, T_c

The time of one clock cycle, set by the slowest path that must finish within it.

Control signal

An output of the control unit that sets a multiplexer, enables a write or selects an ALU operation.

CPI

Cycles per instruction: clock cycles divided by instructions completed.

Critical path

The slowest path through the logic between two clock edges.

Datapath

The registers, memories, ALU, adders and multiplexers that hold and move data.

Flush

Discarding instructions fetched on the wrong path after a jump or a mispredicted branch.

Forwarding

Passing a result to a later instruction before it is written to the register file.

Hazard

A case in which the next instruction in a pipeline cannot proceed as normal: a data dependence or a change of control flow.

Immediate

A constant encoded in the instruction word.

Load-use hazard

An instruction that needs the value of the load just before it; forwarding alone cannot supply it in time, so the pipeline stalls for one cycle.

Pipeline register

The register between two pipeline stages that carries an instruction's values to the next stage.

Pseudo-instruction

A convenient form that the assembler turns into one or more real instructions.

Stall

Holding an instruction in its stage for a cycle.

Licence

© 2026 Sajid Muhaimin Choudhury. MAVILERA, its content (processor drawings, tables, help texts, this documentation, example programs) and its logo artwork are licensed under the Apache License, Version 2.0. The names and the logo are not licensed as trademarks.

RISC-V® is a registered trademark of RISC-V International. MAVILERA is an independent educational project: it uses the name only to identify the instruction set it simulates, uses no RISC-V logo, and is not affiliated with or endorsed by RISC-V International. The RISC-V specifications are published by RISC-V International under the Creative Commons Attribution 4.0 International licence; this laboratory's assembler, simulator, drawings and texts are its own. Espressif, ESP32, Raspberry Pi, Western Digital, NVIDIA, Arm and Cortex are trademarks of their respective owners.