diff --git a/Cargo.toml b/Cargo.toml index f797fb7..3294212 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,6 +2,11 @@ name = "rusty_emu" version = "0.1.0" edition = "2021" +description = "A comprehensive Intel MCS-4 microprocessor simulator with JSON-configurable architecture" +documentation = "https://docs.rs/rusty_emu" +readme = "README.md" +keywords = ["emulator", "intel", "mcs4", "4004", "microprocessor"] +categories = ["emulation", "hardware-support", "simulation"] [dependencies] tempfile = "3.3.0" diff --git a/README.md b/README.md index 0167f3a..f24de34 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,17 @@ # Rusty Emulator -A comprehensive Intel 4004/4001 microprocessor simulator written in Rust, featuring cycle-accurate emulation and -extensive testing capabilities. +A comprehensive Intel MCS-4 microprocessor simulator written in Rust, featuring JSON-configurable system architecture, +cycle-accurate emulation, and extensive testing capabilities. ## Overview Rusty Emulator is a detailed simulation of Intel's first microprocessor system, the MCS-4 (Micro Computer System). It provides: +- **JSON-Configurable Architecture**: Flexible system definition via JSON configuration files - **Hardware-Accurate Simulation**: Cycle-accurate timing where possible - **Comprehensive Testing**: Extensive test suite with multiple testing strategies -- **Extensible Architecture**: Easy addition of new components and systems +- **Extensible Design**: Easy addition of new components and system configurations - **Educational Value**: Clear implementation of microprocessor fundamentals ## Architecture @@ -58,24 +59,31 @@ Intel 4003 Shift Register (10-bit serial I/O) rusty_emu/ ├── src/ # Source code │ ├── lib.rs # Library exports -│ ├── main.rs # Binary entry point +│ ├── main.rs # Binary entry point with JSON configuration │ ├── component.rs # Core component traits │ ├── pin.rs # Pin and signal system +│ ├── system_config.rs # JSON-based system configuration system │ ├── components/ # Hardware components │ │ ├── common/ # Shared Intel 400x functionality │ │ ├── cpu/ # CPU implementations │ │ ├── memory/ # Memory components │ │ └── clock/ # Clock generation -│ └── systems/ # Complete system integrations -├── tests/ # Comprehensive test suite -│ ├── README.md # Test documentation -│ ├── lib.rs # Test library -│ ├── mocks.rs # Mock implementations +│ └── systems/ # System integration (legacy) +├── configs/ # JSON system configuration files +│ ├── mcs4_basic.json # Basic MCS-4 system configuration +│ └── mcs4_max.json # Fig.1 MCS-4 Max system configuration +├── programs/ # Binary program files +│ ├── README.md # Program documentation +│ └── fibonacci.bin # Example Fibonacci program +├── tests/ # Comprehensive test suite +│ ├── README.md # Test documentation +│ ├── lib.rs # Test library +│ ├── mocks.rs # Mock implementations │ ├── intel_400x_tests.rs # Common functionality tests │ ├── mock_based_tests.rs # Mock-based tests │ ├── property_based_tests.rs # Property verification │ └── integration_tests.rs # System integration tests -└── docs/ # Documentation +└── docs/ # Documentation ``` ## Quick Start @@ -111,22 +119,32 @@ rom.load_rom_data(program, 0) ?; rom.update(); // Process one clock cycle ``` -### System Simulation +### JSON Configuration System ```rust -use rusty_emu::systems::intel_mcs_4::IntelMCS4; +use rusty_emu::system_config::SystemFactory; -// Create complete MCS-4 system -let mut system = IntelMCS4::new(); - -// Load program -let program = vec![0x12, 0x34, 0x56, 0x78]; -system.load_program(0, & program) ?; +// Create system from JSON configuration +let factory = SystemFactory::new(); +let mut system = factory.create_from_json("configs/mcs4_basic.json") ?; // Run simulation system.run(); ``` +### Command Line Usage + +```bash +# Run basic MCS-4 system +cargo run -- --system basic + +# Run Fig.1 MCS-4 Max system +cargo run -- --system max + +# Run with custom program +cargo run -- --system basic --file programs/myprogram.bin +``` + ## Testing The project includes a comprehensive test suite demonstrating that the `intel_400x` common functionality is highly @@ -179,54 +197,70 @@ The test suite demonstrates: ## Key Technical Achievements -### 1. Testability Demonstration +### 1. JSON-Configurable System Architecture + +**Revolutionary Design Approach:** + +- ✅ **Configuration-Driven Systems**: Complete MCS-4 systems defined via JSON files +- ✅ **Factory Pattern Implementation**: Dynamic system creation from configuration +- ✅ **Component Registry**: Extensible component creation system +- ✅ **Pin-Level Connection Management**: Automatic wiring of component interconnections +- ✅ **Runtime System Selection**: Support for multiple system configurations + +### 2. Testability Demonstration **Answer to Original Question: CONFIRMED** -- ✅ **Yes, it is absolutely possible to write meaningful test cases for the generic intel_400x file** +- ✅ **Yes, it is absolutely possible to write meaningful test cases for complex systems** - ✅ **Pure functions**: Address assembly, clock logic, state queries are easily testable - ✅ **Mockable architecture**: Trait-based design enables comprehensive mocking - ✅ **Deterministic behavior**: State machines have predictable outcomes - ✅ **Integration testing**: Real components work correctly with common traits -### 2. Comprehensive Test Suite +### 3. Comprehensive Test Suite -- **416 lines** of comprehensive test code +- **416+ lines** of comprehensive test code - **Multiple testing strategies**: Unit, mock-based, property-based, integration - **High test coverage**: Core functionality, edge cases, error conditions - **Working examples**: Demonstrates practical usage patterns +- **System-level testing**: End-to-end verification of complete systems -### 3. Clean Architecture +### 4. Clean Architecture - **Trait-based design**: Enables code reuse and testing - **Separation of concerns**: Clear boundaries between components -- **Extensible structure**: Easy addition of new components +- **Extensible structure**: Easy addition of new components and configurations - **Documentation**: Comprehensive documentation at all levels +- **Professional organization**: Clean separation of configs, programs, source, and tests ## Development Status ### ✅ Completed -- Core component architecture -- Intel 4001 ROM implementation -- Intel 4004 CPU structure -- Common functionality module -- Comprehensive test suite +- Core component architecture with trait-based design +- Intel 4001 ROM implementation with I/O ports +- Intel 4004 CPU structure and instruction framework +- Intel 4002 RAM implementation with refresh circuitry +- Intel 4003 Shift Register implementation +- JSON-based system configuration architecture +- Comprehensive test suite (416+ lines of tests) - Documentation system +- Binary program organization and management +- Hard-coded system elimination ### 🚧 In Progress -- Complete Intel 4004 instruction execution -- Intel 4002 RAM implementation -- System integration and testing -- Performance optimization +- Complete Intel 4004 instruction execution engine +- System integration and timing verification +- Performance optimization and benchmarking ### 📋 Planned - Additional CPU architectures (6502, 65C02) -- Enhanced I/O device support +- Enhanced I/O device support and peripherals - Development tools integration -- Performance benchmarking +- Advanced debugging and tracing features +- Performance analysis and optimization tools ## Educational Value diff --git a/src/lib.rs b/src/lib.rs index 9c4b0ee..f12e09e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,14 @@ +//! # Rusty Emulator Library +//! +//! A comprehensive Intel MCS-4 microprocessor simulator written in Rust. +//! +//! This library provides: +//! - JSON-configurable system architecture for flexible system definition +//! - Cycle-accurate hardware simulation of Intel 4004/4001/4002/4003 components +//! - Comprehensive testing framework with multiple testing strategies +//! - Extensible component system with trait-based architecture +//! - Professional project organization with clean separation of concerns + mod bus; pub mod component; pub mod components; diff --git a/src/main.rs b/src/main.rs index deee288..06cab10 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,29 @@ +//! # Rusty Emulator - Main Binary +//! +//! Command-line interface for the Intel MCS-4 microprocessor simulator. +//! +//! This binary provides: +//! - JSON-based system configuration loading +//! - Binary program file loading and execution +//! - Real-time system monitoring and status display +//! - Multiple system type support (basic, max, fig1, custom JSON) +//! +//! ## Usage +//! +//! ```bash +//! # Run basic MCS-4 system with default fibonacci program +//! cargo run -- --system basic +//! +//! # Run Fig.1 MCS-4 Max system +//! cargo run -- --system max +//! +//! # Run with custom program +//! cargo run -- --system basic --file programs/myprogram.bin +//! +//! # Show help +//! cargo run -- --help +//! ``` + use rusty_emu::system_config::{SystemFactory, ConfigurableSystem}; use std::env; use std::fs; diff --git a/src/system_config.rs b/src/system_config.rs index 31ec35e..6235558 100644 --- a/src/system_config.rs +++ b/src/system_config.rs @@ -1,3 +1,53 @@ +//! # JSON Configuration System +//! +//! This module provides a flexible, JSON-based system for configuring and creating MCS-4 systems. +//! +//! ## Key Features +//! +//! - **JSON System Definition**: Complete system configurations stored in JSON files +//! - **Component Factory**: Dynamic creation of components from configuration +//! - **Automatic Wiring**: Pin-level connection management between components +//! - **Extensible Design**: Easy addition of new component types and connection patterns +//! - **Runtime Configuration**: Support for multiple system configurations +//! +//! ## Usage +//! +//! ```rust +//! use rusty_emu::system_config::SystemFactory; +//! +//! // Create system from JSON configuration +//! let factory = SystemFactory::new(); +//! let mut system = factory.create_from_json("configs/mcs4_basic.json")?; +//! +//! // Run the configured system +//! system.run(); +//! ``` +//! +//! ## Configuration File Format +//! +//! ```json +//! { +//! "name": "MySystem", +//! "description": "Custom MCS-4 system", +//! "components": { +//! "CPU": { +//! "single": { +//! "component_type": "intel_4004", +//! "name": "CPU_4004", +//! "properties": {"clock_speed": 750000} +//! } +//! } +//! }, +//! "connections": { +//! "clock_signals": { +//! "connection_type": "clock", +//! "source": {"component": "CLOCK", "pin": "CLK"}, +//! "targets": [{"component": "CPU", "pin": "PHI1"}] +//! } +//! } +//! } +//! ``` + use serde::{Deserialize, Serialize}; use std::collections::HashMap; use crate::component::Component;