jan/rusty_emu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Added debug output

Browse source 
Added GUI
This commit is contained in:
Jan-Peter von Hunnius 2025-10-03 11:44:55 +02:00
parent 3d4de8b268
commit e17d6ad177
18 changed files with 3137 additions and 162 deletions
Download patch file Download diff file Expand all files Collapse all files

258
README.md
View file

@ -52,6 +52,8 @@ Intel 4003 Shift Register (10-bit serial I/O)
- **12-Bit Address Space**: 4096 possible memory locations
- **Memory-Mapped I/O**: Peripherals accessed as memory locations
- **Thread-Safe Design**: All components are Send + Sync
- **Graphical User Interface**: Modern desktop application with real-time monitoring
- **Interactive Console**: Terminal-based interface with live system monitoring
## Project Structure
@ -63,6 +65,11 @@ rusty_emu/
│ ├── component.rs # Core component traits
│ ├── pin.rs # Pin and signal system
│ ├── system_config.rs # JSON-based system configuration system
│ ├── console.rs # Interactive console interface
│ ├── gui.rs # Graphical user interface module
│ │ ├── components.rs # GUI component implementations
│ │ ├── state.rs # GUI state management
│ │ └── mod.rs # GUI module exports
│ ├── components/ # Hardware components
│ │ ├── common/ # Shared Intel 400x functionality
│ │ ├── cpu/ # CPU implementations
@ -102,6 +109,37 @@ cargo build --release
cargo test
```
### Dependencies
#### Core Dependencies
- **Rust**: Latest stable version (rustup.rs)
- **Standard Library**: Threading, collections, I/O
#### GUI Dependencies
The graphical user interface requires additional dependencies:
- **egui**: Immediate mode GUI framework (`cargo add egui`)
- **eframe**: egui application framework (`cargo add eframe`)
- **System Display**: 1200x800 minimum resolution recommended
#### Optional Dependencies
- **rfd** (recommended): Native file dialogs for ROM loading
- **serde_json**: Enhanced JSON configuration support
### Installation
```bash
# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Clone and build
git clone <repository-url>
cd rusty_emu
cargo build --release
# For GUI support (optional)
cargo add egui eframe rfd
```
### Basic Usage
```rust
@ -147,8 +185,218 @@ cargo run -- --system max
# Run with custom program
cargo run -- --system basic --file programs/myprogram.bin
# Launch graphical user interface
cargo run -- --gui --system basic
# Launch interactive console interface
cargo run -- --console --system basic
```
## Graphical User Interface (GUI)
The emulator features a modern desktop application built with egui, providing an intuitive interface for real-time system monitoring and control.
### GUI Features
- **Real-time System Monitoring**: Live display of CPU registers, RAM contents, and system status
- **Interactive Controls**: Start, stop, reset, and configure emulator execution
- **Visual Status Display**: Clock status, cycle counts, and component health indicators
- **Memory Viewer**: Interactive RAM and ROM content display with hex/decimal views
- **Register Viewer**: CPU register state with index register selection
- **File Management**: Load ROM files and manage system configurations
- **Responsive Design**: Clean, modern interface with real-time updates
### GUI Interface Components
```
┌─────────────────────────────────────────────────────────────┐
│ Intel MCS-4 Emulator [─] [□] [×] │
├─────────────────────────────────────────────────────────────┤
│ System Control │ Memory Viewer │ Register Viewer │ Status │
├────────────────┼────────────────┼─────────────────┼─────────┤
│ ■ Start System │ [Bank: 0] │ [Index: 0] │ ● Run │
│ ■ Stop System │ [00 01 02 03] │ Accumulator: 00 │ Cycles: │
│ ■ Reset System │ [04 05 06 07] │ Carry: 0 │ 12345 │
│ ■ Load ROM │ [08 09 0A 0B] │ PC: 0000 │ │
│ ■ Close │ [0C 0D 0E 0F] │ R0: 00 │ CPU RAM │
│ │ │ Stack: 00 │ ROM CLK │
└────────────────┴────────────────┴─────────────────┴─────────┘
```
### GUI Usage
```bash
# Launch GUI with basic system
cargo run -- --gui --system basic
# Launch GUI with custom configuration
cargo run -- --gui --system custom_config.json
# Launch GUI with specific program
cargo run -- --gui --system basic --file programs/myprogram.bin
```
### GUI Requirements
The GUI requires the following dependencies:
- **egui**: Immediate mode GUI framework
- **eframe**: egui application framework
- **System Display**: 1200x800 minimum resolution recommended
### GUI Integration
The GUI is fully integrated with the existing emulator architecture:
#### Thread Safety
- **Non-blocking Operation**: GUI runs in main thread, emulation in separate thread
- **Lock-free Updates**: State copying prevents blocking between GUI and emulation
- **Arc<Mutex<>> Pattern**: Thread-safe system access using Rust's ownership system
#### State Management
- **Centralized State**: All GUI state managed in `GuiState` structure
- **Real-time Sync**: Automatic state updates from emulator system
- **Error Isolation**: GUI errors don't affect emulator execution
#### Component Integration
- **Component Monitoring**: Live status of CPU, RAM, ROM, and clock components
- **Memory Access**: Direct RAM content display with bank selection
- **Register Access**: Real-time CPU register state visualization
### GUI Troubleshooting
#### Common Issues
**GUI fails to start**
```bash
# Install required dependencies
cargo add egui eframe
# Check system requirements
# - Display resolution: 1200x800 minimum
# - Graphics drivers: Updated drivers recommended
```
**GUI appears but no system connection**
```bash
# Verify system creation
cargo run -- --gui --system basic
# Check console output for error messages
# Look for: "DEBUG: System created successfully"
```
**Performance issues or slow updates**
```bash
# GUI is optimized for 60 FPS updates
# If slow, check:
# - System resources (CPU, memory)
# - Graphics drivers
# - Display resolution settings
```
#### Debug Mode
Enable debug output to troubleshoot issues:
```bash
# Run with debug output
cargo run -- --gui --system basic
# Look for DEBUG messages in console:
# - "DEBUG: System created successfully"
# - "DEBUG: Starting system for GUI mode"
# - "DEBUG: GUI interface..."
```
#### Dependencies
Ensure all GUI dependencies are properly installed:
```bash
# Core GUI dependencies
cargo add egui # GUI framework
cargo add eframe # Desktop application framework
# Optional enhancements
cargo add rfd # Native file dialogs (recommended)
cargo add serde_json # Enhanced JSON support
```
## Interactive Console Interface
The console interface provides a terminal-based UI with real-time system monitoring:
### Console Features
- **Live System Monitoring**: Real-time display of CPU state and memory contents
- **Interactive Commands**: Start, stop, reset, and inspect system state
- **Formatted Output**: Clean tabular display of registers and memory
- **Non-blocking Operation**: Efficient monitoring without interfering with emulation
### Console Usage
```bash
# Launch console interface
cargo run -- --console --system basic
# Console interface will display:
# ┌─────────────────────────────────────────────────────────┐
# │ SYSTEM MONITOR │
# │ CPU Registers | Clock | Bus | RAM | Output Ports │
# └─────────────────────────────────────────────────────────┘
```
### Console Integration
The console interface integrates seamlessly with the emulator:
#### Real-time Monitoring
- **Non-blocking Operation**: Console runs alongside emulation without interference
- **Formatted Display**: Clean tabular output for easy reading
- **Live Updates**: Real-time system state during execution
- **Efficient Output**: Optimized update intervals to avoid spam
#### Thread Architecture
- **Separate Threads**: Emulation and console run in independent threads
- **Shared State**: Thread-safe access to system state via Arc<Mutex<>>
- **Graceful Shutdown**: Proper cleanup when console is terminated
### Console Troubleshooting
#### Common Issues
**Console output is garbled or too fast**
```bash
# Console is optimized for readability
# If issues occur, check:
# - Terminal window size (wider is better)
# - Font settings and encoding
# - Console buffer settings
```
**Console shows "DEBUG" messages**
```bash
# Debug messages are normal during development
# They provide insight into system operation:
# - "DEBUG: System created successfully"
# - "DEBUG: Starting system for console mode"
# - "DEBUG: Enhanced monitoring active"
```
**Console doesn't respond to input**
```bash
# Console interface is read-only by design
# It focuses on monitoring rather than interaction
# For interactive controls, use the GUI interface:
# cargo run -- --gui --system basic
```
#### Performance Optimization
The console interface is optimized for performance:
- **Update Intervals**: 100ms for system state, 5s for detailed output
- **Minimal Overhead**: Negligible impact on emulation performance
- **Memory Efficient**: No GUI overhead, lower resource usage
## Testing
The project includes a comprehensive test suite demonstrating that the `intel_400x` common functionality is highly
@ -195,6 +443,13 @@ The test suite demonstrates:
- [`src/components/common/README.md`](src/components/common/README.md) - Intel 400x common functionality
- [`src/systems/README.md`](src/systems/README.md) - System integration documentation
### User Interface Documentation
- [`src/gui.rs`](src/gui.rs) - Graphical user interface module documentation
- [`src/gui/components.rs`](src/gui/components.rs) - GUI component implementations
- [`src/gui/state.rs`](src/gui/state.rs) - GUI state management documentation
- [`src/console.rs`](src/console.rs) - Interactive console interface
### Test Documentation
- [`tests/README.md`](tests/README.md) - Comprehensive test documentation
@ -251,6 +506,9 @@ The test suite demonstrates:
- Documentation system
- Binary program organization and management
- Hard-coded system elimination
- Graphical User Interface (GUI) with real-time monitoring
- Interactive Console Interface with live system display
- Thread-safe GUI state management and component integration
### 🚧 In Progress