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

```mermaid
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:

```rust
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:

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

### 3. ExecutionController

Manages system lifecycle and coordinates component states:

```rust
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:

```json
{
  "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