0dMIPS

MIPS64r6 SoC implementation with a 5-stage in-order pipeline (2-cycle MEM stage) and peripheral components, simulated and tested with Verilator.

Dependenices

• mips64el-linux-gnu-binutils toolchains(as and objdump), they're under mips64el-linux-gnu-binutils in Arch Linux.
• verilator https://github.com/verilator/verilator for simulations and tests.
• googletest https://github.com/google/googletest for test framework.
• [OPTIONAL] Vivado https://www.amd.com/en/products/software/adaptive-socs-and-fpgas/vivado.html I upload vivado projects under boards/.
• [OPTIONAL] If you like to write C directly, I mainly use mips64el-linux-gnu-gcc-bootstrap with musl as sysroot. Use scripts/install_mips64el_musl.sh to download musl and mips64el-linux-gnu-gcc-bootstrap.
• [OPTIONAL] sdl3 https://github.com/libsdl-org/SDL for any simulation with VGA output.
• [OPTIONAL] lcov https://github.com/linux-test-project/lcov for gather coverage data.
• [OPTIONAL] ftxui https://github.com/ArthurSonzogni/FTXUI for building the debugger TUI.
• [OPTIONAL] capstone https://github.com/capstone-engine/capstone for show disassembly in debugger TUI.

How to run

1. cmake -B build .
2. cmake --build build -j ${$(nproc)-1} to build all. All binaries are placed under build/bin.
3. cmake --build build --target allTests to build all tests.
4. ./runAllTests.sh to run all generated tests under build/bin(by cmake), and use DUMP_COV=1 ./runAllTests.sh to dump coverage data.
5. cmake --build build --target <script_name> to compile script into memory.dat, e.g. hello_world_c.

Features

• 5-stage in-order pipeline with forwarding and hazard detection
• L1 instruction & data cache with arbiter
• CP0 coprocessor: timer interrupt, syscall, break, overflow exception
• Peripherals via MMIO: VGA (640×480 @ 72Hz, deprecated), Timer, LED, mock stdout (simulation only)
• TUI GDB-style debugger with pipeline state, registers, memory, and peripheral views

Roadmap

See open milestones for planned features.

Demo

Hello world with debugger (asciinema)

Simulation file structure

• debugger_tui GDB-style TUI debugger with information about pipeline(disassembly by capstone), registers, memory, peripherals.
• SOC_debug enable debug print and press any key to step.
• SOC_sim run simulation under info log.
• SOC_run_sim run simulation without info log.
• SOC_VGA_sim run simulation with VGA output(provided by SDL3).
• VGA_sim run demo VGA simulation.

Schematic diagram

Schematic diagrams, synthesized and generated by Vivado

more in here