Skip to content

Roadmap

Jump to bottom
Kevin Henderson edited this page Jul 1, 2026 · 5 revisions

Roadmap

The project follows a staged development plan. Each stage builds on the previous without breaking existing functionality.

Completed

Stage 0 — Foundations

  • Instruction decoder (R/I/J formats, opcode + funct → mnemonic)
  • ALU control block and execute (arithmetic, logic, shifts, overflow flags)
  • Live MIPS decode in converter UI
  • RegisterFile (32 × uint32_t, $zero hardwired)
  • Memory (byte-addressable, word/half/byte access, alignment checking)

Stage 1 — Single-Cycle Datapath

  • SingleCycleCpu: fetch → decode → control → execute → memory → writeback in one cycle
  • Full control unit signals (RegWrite, MemRead, MemWrite, Branch, Jump, ALUSrc, ALUOp, MemToReg, RegDst)
  • ISA subset: arithmetic, logic, shifts, loads, stores, branches, jumps
  • Program loader for flat instruction arrays
  • 38 unit tests on known programs

Stage 1.5 — IProcessor Refactor & Pipelined Backend

  • Abstract IProcessor interface (Ripes/DrMIPS pattern)
  • PipelineState observable struct (IF/ID/EX/MEM/WB snapshots, forwarding flags, hazard indicators)
  • SingleCycleCpu refactored to implement IProcessor
  • PipelinedCpu: full 5-stage concurrent pipeline
  • Forwarding unit (EX/MEM → EX, MEM/WB → EX)
  • Hazard detection (load-use stall, branch/jump flush)
  • Polymorphic test harness (95 checks across both implementations)
  • Backward-compat shim: using Cpu = SingleCycleCpu

Stage 2 — TUI Execution Visualizer

  • CPU mode switcher (single-cycle ↔ pipelined at runtime)
  • Register file panel with last-written highlight and signed-decimal annotation
  • Datapath panel (PC, instruction, cycle count, per-stage control signal snapshot)
  • Pipeline strip with inline stall/forward/flush badges
  • Memory panel (hex dump, PC-highlighted row, PgUp/PgDn/Home-to-PC navigation)
  • Instruction decode panel (per-field color coding, reconstructed assembly, raw binary)
  • Execution speed control (single-step, auto-run, run-to-halt, speed slider 10–1000 ms/cycle)
  • Hazard visualization panel (Arches-style: stall/forward/flush inline + dedicated status panel)
  • 8-entry execution trace (last committed instructions, WB-stage sourced)
  • Telemetry panel (live stalls / forwards / flushes / CPI gauges)
  • Oscilloscope startup splash and ambient pipeline flow animation
  • Fixed Container::Tab focus-routing bug (tabs 4–5 aliasing onto 0–1's interactive components)
  • Fixed emoji double-width misalignment in tab bar and headers

In progress / upcoming

Stage 3 — Assembler & Program Composition

The next unstarted milestone. No assembler.h or assembler.cpp exists yet.

Recommended first increment — narrow scope to what the decoder already understands:

  • Single-pass assembler: R/I-format instructions only, no labels or pseudo-instructions
  • Output: std::vector<uint32_t> loadable by IProcessor::load()
  • assembler_test.cpp in tests/mips/ before expanding scope

Full Stage 3 scope:

  • Two-pass assembler with symbol table (EduMIPS64 pattern)
  • Label resolution for forward and backward branches (BEQ/BNE) and jumps (J/JAL)
  • Pseudo-instructions: li, move, la, nop with expansion rules
  • Directive support: .word, .ascii, .data, .text
  • Inline editor in TUI (earmarked for the current "Utility Tools" placeholder tab)
  • Syntax validation with line-by-line error reporting and invalid-token highlighting
  • Symbol export for inspection in Stage 2 visualizer

Reference: EduMIPS64 — GNU assembler directives, case-insensitive mnemonics, forward-reference support.

Stage 4 — Advanced Visualizations & Telemetry

Partially started: live CPI and stall/forward/flush counters are already displayed in the Stage 2 dashboard. Remaining work:

  • Instruction × Cycle Grid (WebRISC-V pattern) — visual table of instruction vs. pipeline stage per cycle
  • Performance Summary Panel — post-run snapshot of counters captured on StepResult::Halt
  • Per-instruction-type hazard breakout (not just per-cycle totals)
  • Cycle-by-cycle breakdown panel — annotate each cycle with reason (normal / stall type / flush type)
  • "Squashed Loops" mode (WebRISC-V) — compact view for repetitive loop execution

Smallest next step toward Stage 4: capture a snapshot of the telemetry counters when the CPU halts and render a static end-of-run summary, before tackling the heavier Instruction × Cycle Grid.

Stage 5 — Branch Prediction & Speculative Execution

  • 1-bit predictor (always predict not-taken, flip on misprediction)
  • 2-bit saturating counter predictor (Patterson & Hennessy §4.7)
  • Branch Target Buffer (BTB) — associative cache of recent branch targets
  • Return Address Stack — for JAL/JR call/return prediction
  • Misprediction visualization — flushed instructions labeled "prediction wrong" in pipeline
  • Prediction accuracy metrics (correct/incorrect counts, per-branch breakdown)
  • Pattern analyzer — identify branch correlations and loop-invariant conditions

Reference: SimpleScalar — implement at increasing sophistication levels, each selectable for teaching.

Stretch goals

Core extensibility

  • RISC-V backend (implements IProcessor; reuses all existing visualizers)
  • Configurable datapath — load processor config from JSON/YAML to swap components
  • Cache simulator — configurable L1/L2, replacement policies, coherence (EduMIPS64 + Dinero pattern)

System integration

  • Memory-mapped I/O — console output via syscalls, breakpoint support
  • Linux ABI (O32) — syscall emulation (read, write, exit) for running real MIPS programs
  • WebAssembly build — port to WASM for browser deployment (Ripes / QtMips pattern)

Advanced educational

  • Breakpoints and watchpoints — pause on address or register-value change
  • Reverse execution — undo previous cycles for post-mortem analysis (DrMIPS feature)
  • Snapshot/restore — save and reload execution states for comparison

Regression / quality

  • UI smoke test guarding Container::Tab child count against tab_labels.size() (prevents reintroduction of the tab/focus aliasing bug)
  • Regression test for per-instruction-type telemetry breakout

Academic publication path

Venue Target milestone
ACM WCAE (Workshop on Computer Architecture Education) Stage 2 completion
IEEE Transactions on Education Full pipeline + telemetry (Stage 4)

Cross-cite with Ripes, WebRISC-V, and Arches in any submission.

Clone this wiki locally