Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Jul 2, 2026 · 9 revisions

clearCore

clearCore is an educational MIPS CPU simulator built in C++20 — not a binary-compatible emulator. It models the internal microarchitectural behavior of two textbook datapaths cycle by cycle, making processor internals visible and interactive for students learning computer architecture.

The project ships two primary interfaces over identical core logic: a lightweight terminal UI (FTXUI) and a full Qt6 desktop GUI. Both let you step through instructions, watch the pipeline fill and drain, and inspect every register and memory word at each cycle. An experimental Qt Quick/QML interface (clearCore-quick) also builds by default alongside them — see Qt6 GUI for its status.

What it does

  • Number system conversion — real-time binary / hexadecimal / decimal conversion backed by a single uint64_t value
  • MIPS instruction decoder — enter any 32-bit word and see opcode, register fields, and reconstructed assembly text
  • Single-cycle CPU — classic non-pipelined datapath; one instruction from fetch to writeback per clock
  • 5-stage pipelined CPU — concurrent IF/ID/EX/MEM/WB execution with load-use stall detection, EX/MEM and MEM/WB forwarding, and branch/jump flush handling
  • Live hazard visualization — stall, forward, and flush badges inline in the pipeline strip
  • Telemetry — running cycle count, CPI, stall/forward/flush tallies
  • In-app MIPS assembler — the Qt6 Code Editor assembles labeled assembly source directly into loadable instruction words (no external toolchain)
  • Differential testing — the tests/golden/ suite cross-checks both CPU models against MARS, the classroom-standard MIPS simulator

Quick navigation

Page Description
Getting Started Build instructions, dependencies, first run
Architecture Module layout, IProcessor interface, design pillars
MIPS CPU Simulator Pipeline stages, hazard detection, forwarding, ISA subset
Terminal UI FTXUI interface — tabs, controls, visualizations
Qt6 GUI Desktop interface — views, signal flow, thread safety
Roadmap Stage-by-stage feature status and upcoming work
Contributing Code style, testing conventions, PR workflow

At a glance

C++20 · CMake 3.20+ · MIT license
FTXUI v7.0.0 (auto-fetched) · Qt6 (Widgets + Quick, both optional) · Nyxstone/LLVM (optional)
Five core CTest suites + a Qt smoke-test suite + MARS differential tests

Build presets: debug, release, asan, core-only (TUI-only, no Qt/LLVM). See Getting Started.

Topics: simulator cpu mips cpp cpp20 educational computer-architecture terminal-ui qt6

Note on "emulator" vs. "simulator": clearCore models the Harris & Harris / Patterson & Hennessy textbook datapaths — it does not aim for binary compatibility with real MIPS silicon. The project intentionally calls itself a simulator throughout its documentation; if you see "emulator" anywhere in older material, that's the term this wiki update is retiring.

Clone this wiki locally