rusty_emu/src/README.md

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:

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

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

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