Jan-Peter von Hunnius 6636417d18 feat: Add real-time data display for CPU registers, RAM, and ROM

2026-02-26 19:36:59 +01:00

17 KiB

Raw Blame History

MCS-4 Emulator Codebase Analysis

Executive Summary

This document provides a comprehensive analysis of the MCS-4 emulator codebase structure, focusing on GUI, console output, configuration systems, and entry points. The analysis identifies specific locations for implementing ROM/RAM/CPU register display and Ctrl-Q keyboard handling.

1. GUI Structure Analysis

1.1 Framework and Architecture

Location: src/gui/mod.rs

The GUI is built using eframe/egui (Rust immediate mode GUI framework):

use eframe::egui;

Key Structure:

GuiApp - Main GUI application struct
- system: Option<Arc<Mutex<ConfigurableSystem>>> - Thread-safe system reference
- gui_state: state::GuiState - GUI state management
- components: components::GuiComponents - Component container

Entry Point: run_gui() function launches the GUI

1.2 State Management

Location: src/gui/state.rs

Key Structures:

Structure	Purpose	Location
`GuiState`	Main UI state container	Lines 12-29
`SystemInfo`	System metadata display	Lines 32-40
`ComponentStates`	Component running states	Lines 43-49
`MemoryState`	RAM contents display	Lines 52-57
`RegisterState`	CPU register display	Lines 60-67

Current State Fields:

pub struct MemoryState {
    pub ram_contents: Vec<[u8; 4]>,  // 4 banks of RAM data
    pub selected_bank: usize,
    pub selected_address: usize,
}

pub struct RegisterState {
    pub accumulator: u8,
    pub carry_flag: bool,
    pub program_counter: u16,
    pub index_registers: [u8; 16],  // R0-R15
    pub stack_pointer: u8,
}

State Update Method: update_from_system()

1.3 GUI Components

Location: src/gui/components.rs

Component	Purpose	Location
`GuiComponents`	Component container	Lines 72-84
`ControlPanel`	Start/Stop/Reset buttons	Lines 180-303
`MemoryViewer`	RAM display	Lines 305-428
`RegisterViewer`	CPU registers display	Lines 430-574
`RomLoader`	ROM file loading	Lines 576-671
`StatusBar`	System status	Lines 673-804

Where to Add ROM Display:

Create new RomViewer component similar to MemoryViewer
Add to GuiComponents struct
Render in render_gui()

1.4 Current Display Gaps

Missing ROM Display:

No ROM content viewer exists
Need to add ROM data retrieval from Intel4001 components

RAM Display Status:

MemoryState.ram_contents exists but uses placeholder data
update_from_system() does NOT populate actual RAM data
Need to add RAM data extraction from Intel4002 components

CPU Register Status:

RegisterState exists with all needed fields
update_from_system() does NOT populate actual CPU data
Need to add CPU data extraction from Intel4004 component

2. Console Output Analysis

2.1 Console Interface

Location: src/gui/console.rs

Framework: ratatui + crossterm (Terminal UI)

Key Structure:

pub struct ConsoleApp {
    system: Arc<Mutex<ConfigurableSystem>>,
    config: ConsoleConfig,
    running: bool,
    command_buffer: String,
    show_help: bool,
    selected_pane: usize,
}

2.2 Console Configuration

Location: src/gui/console.rs:35-58

pub struct ConsoleConfig {
    pub enabled: bool,
    pub refresh_rate_ms: u64,
    pub show_ram: bool,
    pub show_registers: bool,
    pub show_system_info: bool,
    pub ram_banks_per_row: usize,
    pub max_ram_rows: usize,
}

XML Config File: configs/console_config.xml

2.3 Current Console Display

RAM Display: draw_ram_contents()

Currently shows placeholder data (00 values)
Does NOT read actual RAM from Intel4002

CPU Register Display: draw_system_info()

Shows placeholder text: "see DEBUG output"
Does NOT read actual registers from Intel4004

ROM Display:

NOT implemented in console
Would need new draw_rom_contents() method

2.4 Input Handling

Location: handle_key_event()

Current key bindings:

q/Q/Esc - Quit
r/R - Run/Stop toggle
s/S - Stop
h/H - Help
Tab - Switch panes
Enter - Execute command

Ctrl-Q NOT currently handled - Need to add KeyCode::Char('q') with Ctrl modifier check

3. Configuration System Analysis

3.1 System Configuration

Location: src/system_config.rs

Key Structures:

Structure	Purpose	Location
`SystemConfig`	JSON system definition	Lines 58-67
`ComponentConfig`	Component configuration enum	Lines 70-75
`ConfigurableSystem`	Runtime system instance	Lines 362-428

Configuration Files:

configs/mcs4_basic.json - Basic MCS-4 system
configs/mcs4_max.json - Maximum configuration
configs/mcs4_io_demo.json - I/O demonstration

3.2 Existing Configuration Options

JSON Configuration Structure:

{
  "name": "IntelMcs4",
  "description": "Basic MCS-4 System",
  "version": "1.0",
  "metadata": {
    "cpu_speed": 750000,
    "rom_count": 2,
    "ram_count": 1
  },
  "components": { ... },
  "connections": { ... }
}

3.3 Where Display Configuration Fits

Option 1: Extend ConsoleConfig in src/gui/console.rs:35-58

pub struct ConsoleConfig {
    // Existing fields...
    pub show_rom: bool,           // NEW: ROM display toggle
    pub rom_address_range: String, // NEW: ROM address range to display
    pub display_format: String,    // NEW: hex/decimal/ascii
}

Option 2: Extend XML Config configs/console_config.xml

<interface>
    <!-- Existing options -->
    <show_rom>true</show_rom>
    <rom_bytes_per_row>16</rom_bytes_per_row>
    <display_format>hex</display_format>
</interface>

Option 3: Create New DisplayConfig structure for unified GUI/Console settings

4. Main Entry Point Analysis

4.1 Application Flow

Location: src/main.rs

flowchart TD
    A[main] --> B[Parse CLI Args]
    B --> C{Mode?}
    C -->|--console| D[Launch Console]
    C -->|--gui| E[Launch GUI]
    C -->|default| F[Traditional Mode]
    D --> G[run_console]
    E --> H[run_gui]
    F --> I[run_system_demo]

4.2 Mode Selection

Location: main()

// Interface mode selection and launch
if use_console {
    // Launch interactive console interface
    let console_config = ConsoleConfig::default();
    run_console(system_arc, console_config)
} else if use_gui {
    // Launch graphical user interface
    run_gui(Some(system_arc))
} else {
    // Traditional mode
    run_system_demo(system)
}

4.3 System Start/Stop

ConfigurableSystem Methods:

run() - Start system
stop() - Stop system
is_running() - Check running state

4.4 Keyboard Input Handling

Console: handle_key_event()

GUI: Uses egui event system - no explicit keyboard handler

Traditional Mode: No keyboard handling (Ctrl+C only)

Where Ctrl-Q Fits:

Mode	Location	Implementation
Console	`handle_key_event()`	Add Ctrl-Q detection
GUI	`GuiApp` update loop	Add keyboard shortcut
Traditional	`run_system_demo()`	Add terminal input thread

5. Component Data Access Analysis

5.1 Intel 4004 CPU

Location: src/components/cpu/intel_4004.rs

Register Access Methods:

Method	Returns	Location
`get_accumulator()`	`u8`	Line 1142
`get_carry()`	`bool`	Line 1154
`get_program_counter()`	`u16`	Line 1130
`get_register(index)`	`Option<u8>`	Line 1191
`get_stack_pointer()`	`u8`	Line 1160
`get_cycle_count()`	`u64`	Line 1166

5.2 Intel 4002 RAM

Location: src/components/memory/intel_4002.rs

Memory Access Methods:

Method	Returns	Location
`read_ram_direct(addr)`	`Option<u8>`	Line 818
`get_io_port(port)`	`Option<u8>`	Line 842
`get_ram_size()`	`usize`	Line 810

5.3 Intel 4001 ROM

Location: src/components/memory/intel_4001.rs

Expected Methods (need verification):

ROM data read/access
I/O port access

5.4 Component Access Pattern

From ConfigurableSystem:

// Access components HashMap
let components = system.get_components();

// Get CPU
if let Some(cpu_component) = components.get("CPU_4004") {
    if let Ok(cpu) = cpu_component.lock() {
        // Access CPU methods - but need downcast to Intel4004
    }
}

Challenge: Components are stored as Box<dyn Component> - need downcasting to access type-specific methods.

6. Fibonacci Example Analysis

6.1 Program Files

Location: programs/

File	Size	Purpose
`fibonacci.bin`	33 bytes	Basic Fibonacci (RAM only)
`fibonacci_output.bin`	55 bytes	Fibonacci with output ports

6.2 Expected Behavior

From programs/README.md:

Calculates first 8 Fibonacci numbers
Results stored in RAM locations 0-7
fibonacci_output.bin also outputs to ports for visibility

6.3 Where Results Appear

RAM Locations: 0x00-0x07 (first 8 Fibonacci numbers: 0, 1, 1, 2, 3, 5, 8, 13)

Output Ports: Port values visible during execution with fibonacci_output.bin

7. Implementation Recommendations

7.1 ROM/RAM/CPU Display - Console

File: src/gui/console.rs

Changes Required:

Add ROM display method (new ~50 lines after line 505):

fn draw_rom_contents(&self, f: &mut Frame, area: Rect) {
    // Access ROM components and display contents
}

Update RAM display draw_ram_contents():
- Add actual RAM data retrieval from Intel4002
- Use read_ram_direct() method
Update CPU display draw_system_info():
- Add actual register retrieval from Intel4004
- Use getter methods: get_accumulator(), get_program_counter(), etc.
Add component downcasting helper (new method):

fn get_cpu_state(&self) -> Option<CpuState> { ... }
fn get_ram_state(&self) -> Option<RamState> { ... }
fn get_rom_state(&self) -> Option<RomState> { ... }

7.2 ROM/RAM/CPU Display - GUI

File: src/gui/state.rs