rusty_emu/plans/system_control_architecture.md

System Control Architecture Design

Overview

This document outlines the architecture for implementing enhanced system start/stop/pause controls for the Intel MCS-4 emulator. The design provides centralized system management with fine-grained control over execution state and clock parameters.

System Architecture

graph TB
    subgraph "System Controller Layer"
        SC[SystemController Trait]
        EC[ExecutionController]
        SS[SystemState Enum]
    end
    
    subgraph "System Layer"
        CS[ConfigurableSystem]
        SF[SystemFactory]
    end
    
    subgraph "Component Layer"
        CPU[Intel4004]
        CLK1[GenericClock]
        CLK2[TwoPhaseClock]
        ROM[Intel4001]
        RAM[Intel4002]
    end
    
    subgraph "Interface Layer"
        GUI[GUI Control Panel]
        CON[Console Commands]
        KB[Keyboard Shortcuts]
    end
    
    SC --> EC
    EC --> CS
    CS --> CPU
    CS --> CLK1
    CS --> CLK2
    CS --> ROM
    CS --> RAM
    
    GUI --> SC
    CON --> SC
    KB --> SC

Core Components

1. SystemController Trait

Defines the interface for system-wide control operations:

pub trait SystemController {
    fn start(&mut self) -> Result<(), String>;
    fn stop(&mut self) -> Result<(), String>;
    fn pause(&mut self) -> Result<(), String>;
    fn resume(&mut self) -> Result<(), String>;
    fn is_running(&self) -> bool;
    fn is_paused(&self) -> bool;
    fn set_clock_frequency(&mut self, frequency: f64) -> Result<(), String>;
    fn set_clock_enabled(&mut self, enabled: bool) -> Result<(), String>;
    fn get_system_state(&self) -> SystemState;
    fn get_clock_frequency(&self) -> f64;
    fn get_clock_enabled(&self) -> bool;
}

2. SystemState Enum

Tracks the overall system execution state:

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum SystemState {
    Stopped,
    Running,
    Paused,
    Error(String),
}

3. ExecutionController

Manages system lifecycle and coordinates component states:

pub struct ExecutionController {
    system_state: SystemState,
    clock_frequency: f64,
    clock_enabled: bool,
    components: HashMap<String, Arc<Mutex<Box<dyn Component>>>>,
}

Component Enhancements

Clock Components

GenericClock & TwoPhaseClock Enhancements:

• Add paused boolean field
• Implement pause() and resume() methods
• Add dynamic frequency adjustment with set_frequency(f64)
• Add enable() and disable() methods for power control
• Update update() methods to respect pause state

CPU Component

Intel4004 Enhancements:

• Add paused boolean field
• Implement pause() to halt instruction execution
• Implement resume() to continue instruction execution
• Update update() to check pause state before executing instructions
• Maintain clock edge detection during pause for seamless resume

Memory Components

Intel4001 & Intel4002 Enhancements:

• Add paused boolean field
• Implement pause() and resume() methods
• Update update() to respect pause state
• Ensure memory operations complete current cycle before pausing

Interface Updates

Console Commands

New console commands:

• pause / p - Pause system execution
• resume - Resume system execution
• clock <freq> - Set clock frequency (e.g., clock 500000)
• clock on / clock off - Enable/disable clock
• speed + / speed - - Increase/decrease clock frequency by 50%

GUI Controls

New GUI control panel:

• System state indicator (Stopped/Running/Paused)
• Start/Stop/Pause/Resume buttons
• Clock frequency slider (100Hz - 10MHz range)
• Clock enable/disable toggle
• Real-time frequency display
• Keyboard shortcuts (Space=pause/resume, +/- for frequency)

Configuration Schema

Extended JSON configuration with clock control:

{
  "clock_control": {
    "initial_frequency": 750000,
    "min_frequency": 1000,
    "max_frequency": 10000000,
    "frequency_step": 50000,
    "auto_start": true
  }
}

Implementation Strategy

Phase 1: Core Infrastructure

1. Implement SystemController trait
2. Create SystemState enum
3. Build ExecutionController
4. Update ConfigurableSystem

Phase 2: Component Updates

1. Update clock components with pause/resume
2. Update CPU with execution control
3. Update memory components
4. Add dynamic frequency adjustment

Phase 3: Interface Integration

1. Update console with new commands
2. Enhance GUI with control panel
3. Add keyboard shortcuts
4. Update configuration handling

Phase 4: Testing & Documentation

1. Create comprehensive test suite
2. Update all documentation
3. Verify backwards compatibility

Key Design Decisions

Pause Behavior

• Complete system freeze including clock signals
• Components maintain state for seamless resume
• Clock edges are tracked but not propagated during pause

Frequency Adjustment

• Dynamic adjustment during runtime
• Smooth transitions without glitches
• Validation against component limits

State Management

• Centralized state tracking
• Thread-safe state updates
• Consistent state across all components

Benefits

1. Enhanced Control: Fine-grained system management
2. Dynamic Adjustment: Runtime frequency changes
3. Better Debugging: Pause/resume for analysis
4. User Experience: Intuitive controls in both interfaces
5. Extensibility: Clean architecture for future enhancements

Compatibility

• Maintains existing Component trait
• Backwards compatible with current configurations
• No breaking changes to existing APIs
• Optional features with sensible defaults