# Source Code Architecture

This directory contains the core implementation of the Rusty Emulator, an Intel 4004/4001 microprocessor simulator
written in Rust.

## Architecture Overview

```
src/
├── lib.rs                 # Library root and main exports
├── main.rs               # Binary entry point (GUI, console, CLI)
├── component.rs          # Core component trait definitions
├── connection.rs         # Component interconnection
├── pin.rs               # Pin and signal abstractions
├── types.rs             # Common type definitions (U12 address type)
├── system_config.rs     # JSON-based system configuration
├── gui/                 # Graphical user interface
│   ├── mod.rs          # GUI module exports
│   ├── components.rs   # GUI component implementations
│   └── state.rs        # GUI state management
└── components/          # Hardware component implementations
    ├── mod.rs          # Component module exports
    ├── common/         # Shared Intel 400x functionality
    │   ├── mod.rs     # Common exports
    │   └── intel_400x.rs  # Intel 400x unified state machine and traits
    ├── cpu/           # CPU implementations
    │   ├── mod.rs    # CPU module exports
    │   ├── intel_4004.rs  # Intel 4004 CPU (complete instruction set)
    │   ├── mos_6502.rs    # MOS 6502 CPU (placeholder)
    │   └── wdc_65c02.rs   # WDC 65C02 CPU (placeholder)
    ├── memory/        # Memory component implementations
    │   ├── mod.rs    # Memory module exports
    │   ├── intel_4001.rs  # Intel 4001 ROM with I/O ports
    │   ├── intel_4002.rs  # Intel 4002 RAM with output ports
    │   └── intel_4003.rs  # Intel 4003 shift register
    └── clock/         # Clock generation components
        ├── mod.rs    # Clock module exports
        ├── generic_clock.rs   # Generic clock generator
        └── two_phase_clock.rs # Two-phase clock for Intel 400x
```

## Core Abstractions

### Component System

The emulator is built around a component-based architecture where each hardware element implements the `Component`
trait:

```rust
pub trait Component: Send + Sync {
    fn name(&self) -> String;
    fn pins(&self) -> HashMap<String, Arc<Mutex<Pin>>>;
    fn get_pin(&self, name: &str) -> Result<Arc<Mutex<Pin>>, String>;
    fn update(&mut self);
    fn run(&mut self);
    fn stop(&mut self);
    fn is_running(&self) -> bool;
}
```

### Pin System

All components communicate through pins that can be in one of three states:

- `High` (logic 1)
- `Low` (logic 0)
- `HighZ` (high impedance/tri-state)

### Clocking

The system uses a two-phase clock architecture (Φ1, Φ2) that matches the Intel 4004's requirements.

## Component Categories

### CPU Components (`src/components/cpu/`)

- **Intel4004**: Complete Intel 4004 CPU implementation
- **MOS6502**: MOS Technology 6502 CPU (placeholder)
- **WDC65C02**: Western Design Center 65C02 CPU (placeholder)

### Memory Components (`src/components/memory/`)

- **Intel4001**: 256-byte ROM with 4-bit I/O ports
- **Intel4002**: 320-bit RAM with 4-bit output ports
- **Intel4003**: 10-bit shift register

### Common Functionality (`src/components/common/`)

- **Intel400x**: Shared traits and utilities for all Intel 400x series chips
    - Clock handling and edge detection
    - Data bus operations
    - Address handling and latching
    - Control pin management
    - Reset handling
    - Timing state machines

### Clock Components (`src/components/clock/`)

- **GenericClock**: Configurable clock generator

## System Configuration (`src/system_config.rs`)

### JSON-Based System Configuration

Complete system configuration via JSON files featuring:

- Intel 4004 CPU with configurable clock speed
- Intel 4001 ROM units with programmable contents
- Intel 4002 RAM units with bank selection
- Intel 4003 shift registers for I/O expansion
- System clock and timing configuration
- Automatic component interconnection via pin wiring

## Key Features

### Hardware-Accurate Simulation

- Cycle-accurate timing where possible
- Two-phase clock operation
- Proper pin drive and tri-state handling
- Bus contention detection and avoidance

### Extensible Architecture

- Trait-based component system
- Easy addition of new CPU types
- Pluggable memory implementations
- Configurable system topologies

### Testing Support

- Comprehensive test suite
- Mock components for isolated testing
- Property-based testing for verification
- Integration tests for system validation

## Usage Examples

### Basic Component Usage

```rust
use rusty_emu::components::memory::intel_4001::Intel4001;

// Create a ROM component
let mut rom = Intel4001::new("ROM1".to_string());

// Load program data
let program = vec![0x12, 0x34, 0x56, 0x78];
rom.load_rom_data(program, 0) ?;

// Use in simulation
rom.update(); // Process one clock cycle
```

### System Integration

```rust
use rusty_emu::system_config::SystemFactory;

// Create system from JSON configuration
let factory = SystemFactory::new();
let system = factory.create_from_json("configs/mcs4_basic.json") ?;

// Get system information
let info = system.get_system_info();
println!("Created system: {} with {} components", info.name, info.component_count);

// Run simulation (in a real application)
// system.run();
```

## Development Guidelines

### Adding New Components

1. Implement the `Component` trait
2. Add appropriate pin configuration
3. Implement timing-accurate behavior
4. Add comprehensive unit tests
5. Update module exports

### Testing Requirements

- Unit tests for individual components
- Integration tests for component interactions
- Property-based tests for behavioral verification
- Mock-based tests for external dependencies

### Code Organization

- Keep components focused on single responsibilities
- Use traits for shared behavior
- Maintain clear separation between hardware abstraction and implementation
- Document hardware deviations and limitations

## Performance Considerations

- Components are designed to be thread-safe
- Pin operations use lock-free algorithms where possible
- Memory access patterns optimized for simulation performance
- Clock cycles processed efficiently

## Hardware Accuracy Notes

- Intel 4004 timing is approximated due to Rust's timing limitations
- Pin signal propagation is simplified for simulation purposes
- Some hardware-specific behaviors may be abstracted for testability
- Bus contention handling prioritizes safety over perfect accuracy