rusty_emu/src/components

Rusty Emu - Cross-Platform System Emulator

🎯 Project Overview

Rusty Emu is a modular, cross-platform system emulator written in Rust, designed to emulate various historical computing systems and embedded devices with a focus on accuracy and performance.

Currently Supported Systems

System	Status	Description
Intel MCS-4	✅ Implemented	Historical 4-bit microprocessor family
Commodore VIC-20	🔄 Planned	Classic 8-bit home computer
Yamaha TG100	🔄 Planned	AWM tone generator module

---

🏗️ Architecture

Core Components

rusty_emu/
├── src/
│   ├── core/              # Emulator core infrastructure
│   │   ├── cpu/           # CPU emulation base
│   │   ├── memory/        # Memory management
│   │   └── peripherals/   # I/O device handling
│   ├── systems/           # System-specific implementations
│   │   ├── intel_mcs4/    # Intel MCS-4 emulation
│   │   ├── vic20/         # VIC-20 emulation (planned)
│   │   └── yamaha_tg100/  # Yamaha TG100 emulation (planned)
│   └── ui/                # User interface components

---

Key Features

• Modular Design: Easily extensible for new systems
• Cross-Platform: Runs on Windows, macOS, and Linux
• Cycle-Accurate: Precise timing emulation
• Debugging Support: Built-in debugging capabilities
• Hardware Rendering: Efficient graphics emulation

---

🚀 Getting Started

Prerequisites

• Rust 1.70+ toolchain
• Cargo package manager
• System dependencies for graphics/audio

Installation

# Clone the repository
git clone https://github.com/jhunnius/rusty_emu.git
cd rusty_emu

# Build in release mode
cargo build --release

# Run with specific system
cargo run --release -- --system intel_mcs4 --rom path/to/rom.bin

Quick Examples

# Emulate Intel MCS-4 system
./rusty_emu --system intel_mcs4 --rom examples/mcs4/demo.rom

# Enable debug mode
./rusty_emu --system intel_mcs4 --rom demo.rom --debug

# Load with specific configuration
./rusty_emu --system intel_mcs4 --rom demo.rom --config mcs4_config.toml

---

📋 System Specifications

Intel MCS-4 Implementation

Supported Components:
✅ Intel 4004 CPU (4-bit processor)
✅ 4001 ROM (2560-bit ROM with I/O)
✅ 4002 RAM (320-bit RAM with output port)
✅ 4003 Shift Register (10-bit I/O expander)

Memory Architecture:

• Instruction ROM: 4KB
• Data RAM: 1280 bits
• I/O Ports: Multiple 4-bit ports

---

VIC-20 Emulation (Planned)

Target Specifications:

• CPU: MOS 6502 @ 1.108 MHz
• Memory: 5KB RAM (expandable to 32KB)
• Graphics: VIC-I chip, 176×184 resolution
• Sound: 3 voices + noise
• I/O: Tape, Serial, User Port

---

Yamaha TG100 Emulation (Planned)

Target Features:

• Tone Generation: AWM (Advanced Wave Memory)
• Polyphony: 16–32 voices
• Effects: Reverb, Chorus
• MIDI Implementation

---

🛠️ Development

Adding New Systems

Create System Module

// systems/my_system/mod.rs
pub struct MySystem {
    cpu: MyCpu,
    memory: MemoryMap,
    peripherals: Vec<Box<dyn Peripheral>>,
}

impl System for MySystem {
    fn step(&mut self) -> EmulatorResult<()> {
        // System emulation logic
    }
}

Implement CPU Core

// systems/my_system/cpu.rs
impl Cpu for MyCpu {
    fn execute_instruction(&mut self) -> EmulatorResult<()> {
        // Instruction execution
    }
}

Register System

// src/lib.rs
pub mod systems {
    pub mod my_system;
}

---

Building from Source

# Debug build with logging
RUST_LOG=debug cargo build

# Run tests
cargo test

# Benchmark performance
cargo bench

# Check code quality
cargo clippy
cargo fmt

---

🧪 Testing

# Run all tests
cargo test

# System-specific tests
cargo test --test intel_mcs4

# Integration tests
cargo test --test integration

# Performance benchmarks
cargo bench

---

📊 Performance

Current performance targets:

• Intel MCS-4: 740 kHz emulation speed (real-time)
• VIC-20: 1.108 MHz emulation speed (real-time)
• Yamaha TG100: Audio processing at 44.1 kHz

---

🔧 Configuration

Example Configuration (TOML)

[system.intel_mcs4]
clock_speed = 740000  # 740 kHz
memory_size = 4096    # 4KB ROM

[display]
width = 800
height = 600
scale = 2
fullscreen = false

[audio]
sample_rate = 44100
buffer_size = 1024

[debug]
breakpoints = [0x1234, 0x5678]
log_level = "info"

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Follow Rust conventions and cargo fmt
• Use meaningful variable names
• Include documentation comments
• Write tests for new functionality

---

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgments

• Intel MCS-4: Reference documentation from Intel archives
• VIC-20: VICE emulator team for reference implementation
• Yamaha TG100: Yamaha technical documentation
• Rust Community: Excellent emulation resources and crates

---

📚 Resources

Documentation

• Intel MCS-4 Manuals
• VIC-20 Programmer's Reference
• Yamaha TG100 Service Manual

Related Projects

• VICE: Versatile Commodore Emulator
• MAME: Multiple Arcade Machine Emulator
• Yuzu: Nintendo Switch Emulator

---

🐛 Issue Reporting

If you find a bug, please open an issue with:

• System and ROM information
• Steps to reproduce
• Expected vs. actual behavior
• Log output (if available)

---

📞 Support

• Discussions: GitHub Discussions
• Issues: GitHub Issues

Rusty Emu — Preserving computing history through accurate emulation. 🕹️