Skip to content

Qt6 GUI

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

Qt6 GUI

The desktop interface (clearCore-gui) is built with Qt6 widgets. It shares no code with the FTXUI terminal UI — both compile from the same mips_core and nsc_core libraries.

Launch

cmake --build cmake-build-debug --target clearCore-gui
./cmake-build-debug/clearCore-gui

Qt6 must be installed on the system (see Getting Started).

Six tabbed views

Datapath

A clickable diagram of the 5-stage MIPS pipeline. Each stage box (IF, ID, EX, MEM, WB) is a button — clicking highlights that stage and shows its current pipeline register contents in a side panel.

Color coding follows the same convention as the TUI: green for normal advance, yellow for stall bubbles, red for flush, cyan when a forwarding path is active.

The diagram updates after every step().

Registers

All 32 MIPS registers in a scrollable table. Columns:

Column Content
Number $0 – $31
ABI name $zero, $at, $v0, …, $ra
Value (hex) 0x00000000
Value (signed) Decimal with sign

The row for the most recently written register is highlighted in the same color as the Datapath's WB stage.

Memory

A hex dump viewer of the 32-bit address space that the CPU has written to. Layout:

Address     +0       +4       +8       +C       ASCII
0x00000000  00401000 00602020 8C620000 AC620004  ................
0x00000010  08000006 00000000 00000000 00000000  ................

The row containing the current PC is highlighted. Keyboard navigation: PgUp / PgDn to scroll, Home to jump back to the PC row.

Pipeline Trace

An instruction × cycle grid (WebRISC-V style). Rows are instructions in program order; columns are clock cycles. Each cell shows which pipeline stage that instruction occupied during that cycle, or is blank if it had not yet entered the pipeline or had already committed.

Stall bubbles appear as gray cells. Flush events appear in red.

This view accumulates during a run. It resets when the CPU resets.

Code Editor

An inline MIPS assembler. Write assembly text in the left pane; the right pane shows the assembled instruction words in hex. Features:

  • Label definitions (loop:) and label references in branch/jump targets
  • Forward and backward branch resolution
  • Basic syntax error reporting with line numbers
  • Assemble & Load button — assembles and transfers the program to the CPU in one click

Supported pseudo-instructions and directives are limited to those the decoder already understands. Stage 3 work (two-pass assembler, pseudo-instructions, .data/.text directives) will expand this significantly — see Roadmap.

Statistics

A post-run summary dashboard. Panels:

Panel Content
Cycle count Total clock cycles
Instruction count Total committed instructions
CPI Cycles per instruction
Stalls Load-use stall bubbles
Forwards Forwarding operations
Flushes Branch/jump flushes

Hazard type breakdown (stall vs. flush vs. forward) shown as a proportional bar.

Architecture: SimulatorController

The CPU does not run on the main Qt thread. The SimulatorController class mediates:

QThread (CPU)                       Main thread (UI)
─────────────────                   ─────────────────
PipelinedCpu::step()
  → emit pipelineStateChanged()  ──→  Datapath tab updates
  → emit registersChanged()      ──→  Registers tab updates
  → emit memoryChanged()         ──→  Memory tab updates
  → emit traceRowAdded()         ──→  Pipeline Trace updates
  → emit statisticsChanged()     ──→  Statistics tab updates

Qt's event loop automatically marshals signals from the CPU thread to the UI thread. No mutexes are needed in widget code. The controller is the only object that touches the IProcessor from outside the CPU thread.

Thread safety rules

  • Widget paintEvent() and slot handlers run on the main thread — they may read cached copies of CPU state but must never call IProcessor methods directly.
  • SimulatorController slots that call step() are invoked via a QueuedConnection, ensuring they execute on the CPU thread.
  • Signal parameters are passed by value (not reference) to survive thread-boundary copying.

Build notes

CMakeLists.txt compiles both TUI and GUI targets by default. Building only the GUI:

cmake --build cmake-build-debug --target clearCore-gui

If Qt6 is not found during CMake configuration, the clearCore-gui target is silently skipped and the TUI target still builds. Pass -DBUILD_QT6_UI=OFF to suppress the Qt6 search entirely.

New .cpp or .h files added to nsc_qt/ must be registered in CMakeLists.txt — Qt's MOC (meta-object compiler) will not pick them up automatically and you will get a linker error.

QML (nsc_quick)

The src/nsc_quick and qml/ClearCore directories contain a QML-based interface that was developed in parallel with the Qt6 widget UI. It targets the same IProcessor backend. Status and scope are tracked in Roadmap.

Clone this wiki locally