Overview
This is a browser-based RISC-V emulator that runs entirely in your web browser using
Pyodide (Python compiled to WebAssembly).
It's based on the riscv-python
Python emulator, adapted to work in the browser environment.
Getting Started
- Wait for Pyodide to load (status bar shows progress)
- Click Load ELF/BIN and select a RISC-V executable (.elf or .bin file)
- Configure options and toggles as needed
- Click Run to start execution
Control Buttons
Load ELF/BIN
Loads a RISC-V executable file into the emulator. Supports:
- ELF files (.elf) - Full symbol information, stack/heap layout
- Binary files (.bin) - Raw binary loaded at address 0x00000000
Loading a file always performs full reinitialization with current UI settings.
Run / Resume
Starts or resumes execution:
- Run - Starts from entry point (after load/reset/program exit)
- Resume - Continues from current PC (after stop)
Button text changes to indicate which action will be performed.
Stop
Pauses execution at current PC. Use Resume to continue from where you stopped.
Reset
Performs full reinitialization with current UI settings and reloads the current file.
Use this to apply toggle changes that require reload (marked with ⟳).
Tracing Options
Enable debug output in the terminal. Changes take effect immediately (no reload required).
Syscalls
Traces system calls (read, write, exit, sbrk, etc.) with arguments and return values.
Traps
Traces trap/exception handling (interrupts, illegal instructions, etc.).
Functions
Traces function entry points using ELF symbol information.
Only available for ELF files with symbols.
Checking Options
Runtime verification checks. Most require reload to take effect.
Invariants
Checks program invariants during execution (x0=0, PC in bounds, stack/heap separation, etc.).
Changes take effect immediately.
Not compatible with multi-tasking programs (scheduler, threads).
Memory bounds ⟳
Enables bounds checking on all memory accesses (uses SafeRAM implementation).
Requires reset/reload to take effect.
Text integrity ⟳
Verifies that the code segment (.text) is not modified during execution.
Only available for ELF files. Requires reset/reload to take effect.
Features
CPU extensions and hardware features. Require reload to take effect.
Timer (CSR) ⟳
Enables the timer peripheral with mtime and mtimecmp CSRs.
Required for programs that use timer interrupts.
Requires reset/reload to take effect.
RVC (Compressed) ⟳
Enables RISC-V Compressed (RVC) instruction set extension.
Supports 16-bit compressed instructions mixed with 32-bit instructions.
Requires reset/reload to take effect.
Options
Raw terminal ⟳
Enables raw TTY mode (character-at-a-time input without echo).
Requires reset/reload to take effect.
Registers
Comma-separated list of registers to trace (e.g., pc,sp,ra,a0).
Shows register values before each instruction.
Changes take effect immediately after field loses focus.
RAM Size (KB) ⟳
Configures emulated RAM size.
Default: 1024KB (1MB).
Requires reset/reload to take effect.
File Type Compatibility
ELF Files (.elf)
- Full symbol information available
- Stack and heap layout from symbols (
__stack_top, __heap_start)
- Function tracing available
- Text integrity checking available
- Entry point from ELF header
Binary Files (.bin)
- Raw binary loaded at address 0x00000000
- Entry point at 0x00000000
- No symbol information (function tracing disabled)
- No text integrity checking (disabled)
- Programs must manage their own stack/heap
Performance Stats
- Instructions - Total instructions executed since start
- IPS - Instructions per second (averaged over last 500ms)
Notes
- Use Stop/Resume for debugging or examining state at specific points
- Use Reset after changing toggles marked with ⟳
- Check RAM requirements: If you get "Access out of bounds" errors, increase RAM size and reload
- Enable Tracing options to debug program behavior in the terminal
- Raw terminal mode is needed for interactive programs (REPLs)
- Invariant checking helps catch bugs but doesn't work with multi-tasking programs
Source Code
Original Python emulator:
github.com/ccattuto/riscv-python