Skip to content

Terminal UI

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

Terminal UI

The terminal interface (number_system_converter) is built with FTXUI v7.0.0 and runs entirely in the terminal with no system dependencies beyond a C++20 compiler and CMake.

Launch

./cmake-build-debug/number_system_converter

Requires a terminal with ANSI escape code support (256 colors recommended). Does not work in bare cmd.exe on Windows without a compatibility layer.

Tab overview

Navigate tabs with Tab / Shift+Tab or the mouse.

Tab 0 — Number Converter

Real-time base conversion. Type a value in any field; the other two update instantly.

  • Binary — unsigned 64-bit binary string
  • Hexadecimal — 0x-prefixed or bare hex digits
  • Decimal — unsigned decimal

Input is validated on each keystroke. Invalid characters are rejected without clearing the field. Internally all three representations share a single uint64_t.

Tab 1 — CPU Dashboard

The main CPU visualization. From top to bottom:

Datapath panel — current PC, raw instruction word, cycle counter, and CPU mode (single-cycle or pipelined). Shows a snapshot of control signals at each stage: IF fetch address, ID register reads, EX ALU operation, MEM access type, WB destination.

Pipeline strip — a horizontal row of five labeled boxes (IF · ID · EX · MEM · WB), each showing the instruction currently in that stage. Color coding:

Color Meaning
Green Normal advance
Yellow Stall / bubble
Red Flushed (branch/jump)
Cyan Forwarding path active

Inline badges appear to the right of each stage box: [STALL], [FWD→EX], [FWD←MEM], [FLUSH].

Hazard & forwarding panel — text breakdown of which hazard conditions fired this cycle, which forwarding paths are active, and which registers are involved.

Register file panel — all 32 MIPS registers in a two-column grid. Shows both the ABI name ($t0, $sp, etc.) and the register number. The last-written register is highlighted. Values are shown in hexadecimal with a signed-decimal annotation.

Execution trace — last 8 committed instructions in order (WB stage sourced), scrollable.

Telemetry panel — live gauges:

Gauge Display
Cycles Running cycle count
Stalls Stall bubbles inserted
Forwards Forwarding operations
Flushes Stages flushed
CPI Current cycles-per-instruction

Execution controls:

Key Action
Space Single step
R Toggle auto-run
H Run to halt
X Reset CPU
+ / - Increase / decrease run speed

Speed slider range: 10 ms/cycle (fastest) to 1000 ms/cycle (slowest). The pipeline flow canvas animates only while auto-run is active.

Tab 2 — CPU Config

Switch the active CPU backend without restarting. Options:

  • Single-cycle — one instruction per clock, no pipeline registers
  • Pipelined — full 5-stage pipeline with hazard handling

Switching resets the CPU state and clears telemetry counters. The loaded program is preserved.

Tab 3 — Program Loader

Enter MIPS instruction words as 32-bit hex values, one per line:

00401000
00602020
8C620000
AC620004
08000006

Press Load to transfer the program to the CPU. The memory panel in Tab 1 updates immediately. The CPU is reset to PC = 0 before the new program runs.

To decode a single instruction without loading a full program, switch to Tab 0 and enter the word in the hex field — the instruction decode panel in Tab 1 updates whenever the hex value changes.

Tab 4 — Signal Monitor

An oscilloscope-style animation that shows signal activity while the CPU runs. Waveforms pulse with each clock cycle during auto-run. The panel is read-only and primarily decorative / motivational — it gives a sense of live activity without requiring a real hardware interface.

The startup splash animation plays here before the CPU is first stepped.

Known terminal quirks

  • Emoji in layout-critical positions cause border misalignment in some terminals. FTXUI's IsFullWidth() table does not classify most emoji as double-width, so they consume one column visually but the layout engine allocates two. The UI avoids emoji in tab bars and headers for this reason.

  • Tab focus routing — FTXUI's Container::Tab wraps focus index modulo the child count. An earlier bug caused tabs 4–5 to alias onto tabs 0–1's interactive components. This was fixed by ensuring the container child count exactly matches tab_labels.size() at construction. A regression guard is planned (see Roadmap).

Clone this wiki locally