feat: migrate to parking_lot mutex and add system control architecture

plans/system_control_architecture.md

@@ -0,0 +1,218 @@
+# 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