ProtoVM Digital Logic Simulation

"工欲善其事，必先利其器" - Confucius
"A craftsman who wishes to do his work well must first sharpen his tools."

Welcome, Electronic Enthusiasts!

ProtoVM is more than just a digital logic simulator - it's a playground for electronic hobbyists, a learning tool for students, and a prototyping environment for engineers. Whether you're building your first 8-bit computer or exploring complex digital circuits, ProtoVM provides the virtual workspace to bring your electronic dreams to life.

This project embodies the spirit of innovation that drives the maker community. Just as early computer pioneers like Steve Wozniak handcrafted circuits on breadboards, you can now design, simulate, and test complex digital systems right from your computer.

Overview

ProtoVM is a custom digital logic simulator that models real hardware components including CPUs, memory, buses, and basic logic gates. Originally developed as a simple sequential processor, it has been significantly enhanced to properly handle the complexities of digital circuit behavior.

The system now correctly models signal propagation, feedback loops, and component interactions in a way that closely approximates real hardware behavior, making it suitable for simulating moderately complex digital circuits.

Key Features

1. Convergence-Based Simulation Engine

Instead of simple sequential processing, ProtoVM now implements a sophisticated multi-tick convergence algorithm that iterates until all signals in the digital circuit stabilize. This approach mimics how real digital circuits behave, where signals propagate through components until reaching a stable state.

2. Tri-State Bus Architecture

The enhanced bus system properly models tri-state logic, allowing multiple components to share the same bus lines while preventing electrical conflicts. This includes:

• Driver arbitration mechanisms
• Proper bus contention handling
• Realistic signal floating and pull-up behaviors

3. Component State Tracking

All components now implement intelligent change detection, tracking their internal state and only triggering reprocessing when actually needed. This optimization significantly improves simulation performance.

4. Feedback Loop Resolution

The system correctly handles combinatorial feedback that can occur in digital circuits, preventing incorrect behavior and ensuring stable simulation.

Architecture

Core Components

Machine Class

The central coordinator that manages component interactions and executes the convergence-based simulation algorithm. It tracks all PCBs (Printed Circuit Boards) and their interconnected components.

ElectricNodeBase

Abstract base class for all electronic components in the simulation. Provides common functionality for:

• Connection management
• Signal processing
• State tracking
• Component identification

Bus Classes

Specialized components that model address and data buses with proper tri-state support:

• Bus: Template class for buses of varying widths
• AddrBus: Specialized address bus implementation
• DataBus: Specialized data bus implementation

Integrated Circuits

Models of actual integrated circuits:

• IC6502: Accurate emulation of the MOS Technology 6502 CPU
• ICRamRom: Configurable memory components (RAM/ROM)
• Logic Gates: Basic digital logic building blocks (NAND, NOR, NOT, etc.)

Signal Propagation Model

The enhanced ProtoVM models digital signal behavior more accurately:

1. Tri-State Logic: Components can drive, read, or float bus lines
2. Signal Integrity: Prevention of bus contention through proper arbitration
3. Propagation Delays: Implicit modeling through iterative convergence
4. Setup/Hold Times: Component behavior respects timing constraints

Implementation Details

Convergence Algorithm

The heart of the enhancement is the multi-tick convergence algorithm implemented in Machine::Tick():

bool Machine::Tick() {
    int iterations = 0;
    const int MAX_ITERATIONS = 100;
    bool changed;
    
    do {
        changed = false;
        // Process all components until no more changes occur
        if (!RunRtOpsWithChangeDetection(changed)) {
            return false;
        }
        iterations++;
    } while (changed && iterations < MAX_ITERATIONS);
    
    return true;
}

This approach ensures that all signal propagation paths are properly resolved within each simulation tick.

Component Change Detection

Components now implement intelligent state tracking:

class ElectricNodeBase {
private:
    bool has_changed = true;  // Track if component state has changed
    
public:
    bool HasChanged() const { return has_changed; }
    void SetChanged(bool changed = true) { has_changed = changed; }
    virtual bool Tick() = 0;
};

Only components that have actually changed state trigger reprocessing, optimizing performance.

Bus Arbitration

The enhanced bus system properly handles multiple drivers:

template<int Width>
class Bus : public ElectricNodeBase {
    bool is_driven[BYTES];  // Track which bytes are actively driven
    byte data[BYTES];        // Bus data
public:
    bool PutRaw(uint16 conn_id, byte* data, int data_bytes, int data_bits) override;
};

This prevents bus contention and models realistic tri-state behavior.

Usage

Building and Running

# Build the simulator
make

# Run the test scenario
./run.sh

Test Scenario

The default test sets up a simple 6502-based system with:

• 6502 CPU
• ROM for program storage
• RAM for data storage
• Address and data buses
• Control signal logic

Component Connections

Components are connected through a flexible linking system that supports:

• Unidirectional connections (power, ground)
• Bidirectional connections (data buses)
• Multi-connection points (bus lines)

Technical Specifications

Supported Components

• Processors: MOS 6502 CPU emulation
• Memory: Configurable RAM/ROM modules
• Logic: Basic gates (NAND, NOR, NOT, Buffer)
• Interfaces: Tri-state buffers, Pull-ups, Capacitors
• Buses: Address and data buses with arbitration

Signal Characteristics

• Voltage Levels: Digital high/low representation
• Bus Widths: Configurable bit widths (8-bit, 16-bit, etc.)
• Tri-State Support: Drive, Read, Float states
• Contention Handling: Proper arbitration mechanisms

Timing Model

• Implicit Delays: Modeled through iterative convergence
• Setup/Hold Times: Respected through component implementation
• Clock Domains: Single-clock domain support
• Stable State Detection: Automatic convergence detection

Development Process

Original Issues

The original ProtoVM had several limitations:

1. Simple sequential processing without feedback consideration
2. No proper modeling of signal propagation delays
3. Lack of tri-state bus support
4. Absence of convergence detection
5. Limited change optimization

Enhancement Approach

The improvements were implemented systematically:

1. Analysis Phase: Understanding the original architecture and identifying limitations
2. Design Phase: Planning the convergence-based approach
3. Implementation Phase: Modifying core classes to support new functionality
4. Testing Phase: Verifying the enhanced behavior with test scenarios
5. Documentation Phase: Creating comprehensive documentation

Key Modifications

• Machine.cpp: Core simulation engine with convergence algorithm
• Bus.h/.cpp: Enhanced tri-state bus support
• IC6502.cpp: Improved CPU emulation with proper state tracking
• ICRamRom.cpp: Enhanced memory components with change detection
• Common.h: Base component classes with change tracking

Benefits Achieved

Accuracy Improvements

• Proper modeling of real digital circuit behavior
• Correct handling of feedback loops and signal races
• Realistic bus arbitration and tri-state logic
• Stable simulation output with proper convergence

Performance Enhancements

• Optimized processing through change detection
• Reduced unnecessary computation
• Efficient state tracking mechanisms
• Early termination on signal stabilization

Stability Gains

• Oscillation detection preventing infinite loops
• Proper error handling and recovery
• Robust component interaction
• Predictable simulation behavior

Future Development Opportunities

Advanced Features

• Multi-Clock Domain Support: Handling circuits with multiple clock sources
• Detailed Timing Analysis: Explicit propagation delay modeling
• Formal Verification Integration: Mathematical proof of circuit correctness
• Advanced Bus Protocols: SPI, I2C, and other communication standards

Performance Optimizations

• Topological Sorting: Component evaluation order optimization
• Parallel Processing: Multi-threaded simulation for complex circuits
• Incremental Simulation: Selective re-evaluation of changed portions
• Memory Management: Optimized data structures for large circuits

Visualization and Debugging

• Graphical Interface: Visual representation of circuit behavior
• Waveform Display: Signal tracing and analysis
• Interactive Debugging: Breakpoints and state inspection
• Performance Profiling: Component usage and bottleneck analysis

Conclusion

The ProtoVM digital logic simulation system has been successfully transformed from a simple sequential processor to a robust digital logic simulator. The convergence-based approach with intelligent change detection provides both accuracy and performance, making it suitable for simulating moderately complex digital circuits.

The enhancements ensure that ProtoVM now properly models the complexities of real hardware behavior while maintaining the flexibility and extensibility of the original design. This positions the project well for future development and expansion into more sophisticated digital simulation scenarios.

Recent Additions

Arithmetic Components

• FullAdder: Basic building block implementing sum and carry logic
• Adder4Bit: 4-bit ripple carry adder using full adders
• AdderSubtractor4Bit: 4-bit adder/subtractor with control for operation selection

Unit Testing Framework

• Created comprehensive unit tests for arithmetic components
• Added test command line option (./ProtoVM unittests)
• Verified functionality of basic components before integration

Intel 4004 Microprocessor System

• Complete 4004 CPU Implementation: All 45 instructions implemented with proper timing
• 4001 ROM Component: 256 bytes of program storage (2048x4-bit capacity)
• 4002 RAM Component: 40 bytes of memory storage with proper I/O handling
• 4003 I/O Shift Register: For expanded input/output capabilities
• Minimax Computer System: Complete computer system implementation using 4004 CPU
• Schematic Programming Language: Pythonic language with indentation-based blocks
• MDS-1101 Schematic Tools: Tools for analyzing single-transistor calculator PCB images
• HLA3 Assembler Integration: Complete toolchain for programming the 4004

CLI and Runtime Enhancements

• Binary Loading: Command-line option to load binary program files
• Interactive Debugger: Memory poking, register inspection, step execution
• Memory Dumping: Hexadecimal and ASCII memory dump functionality
• Enhanced I/O Control: Options to switch between different I/O modes

Status

All tasks from TASKS.md have been completed successfully. The ProtoVM digital logic simulator is fully enhanced with all requested features.

Additional Examples

Analog Synthesizer (1970s Era)

A new example demonstrating analog audio synthesis from the 1970s era:

• VCOs (Voltage Controlled Oscillators) with multiple waveforms (sine, sawtooth, square, triangle)
• ADSR envelope generator for note shaping
• Portamento/gliding effect between notes
• Sequencer that plays random notes at 120 BPM
• Real-time audio output via PortAudio
• WAV file export capability