jan/rusty_emu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
rusty_emu/src/components/README.md

6.5 KiB
Raw Blame History

Rusty Emu - Cross-Platform System Emulator

Rust License Platform

🎯 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

Related Projects

🐛 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

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