How laurentprudhon/zxspectrumsimulator works
Project Type and Purpose
• This is a desktop emulator suite (“monorepo”) for accurately simulating the Z80 CPU and ZX Spectrum computer at the electronic (wire-and-clock) level.
• Components include a code-generation tool (Instruction table generator), the core Z80 simulation library, the ZX Spectrum-specific emulator layers (ROM, ULA, tape, BASIC, peripherals), a WPF‐based UI, an assembly code editor, and a large test harness.
File-Structure Analysis
• Top-level solution “ZxSpectrumSimulator.sln” contains multiple projects:
• Z80Simulator.GenerateTables: pre-build tool that ingests CSV instruction data & documentation to emit opcode tables.
• Z80Simulator: core simulation engine (Assembly, CPU, Instructions, System—Bus, Memory, IOPins).
• Z80Simulator.Test: rich NUnit/xUnit test suite covering ALU, CPU controls, machine cycles, microinstructions, system integration, ZEXALL.
• ZXSpectrum: ZX Spectrum emulator layers (ROM loader, ULA, BASIC interpreter, tape file formats, devices).
• ZXSpectrum.Test: tests for tape files, ULA video, basic programs, performance.
• ZXSpectrumUI: WPF front-end, platform adapters (keyboard, joystick, screen, speaker), NAudio for sound, game-loader assets.
• ZXCodeEditor: standalone WPF editor for incremental assembly, syntax highlighting, linking to the emulator back-end.
README Insights
• Emphasis on “electronic level”: clock, bus, pins.
• Goal: full reconstruction to deeply understand hardware and ROM.
• Loads real tape captures, plays original games.
a. Main Components (layered top-down):
1. Instruction Table Generator (Z80Simulator.GenerateTables) – design-time component.
2. Core Z80 Engine (Z80Simulator):
– CPU Model (Registers, ALU, Decoder, Microinstructions)
– System Model (Bus, Memory, IOPins, Clock)
– Assembly/Disassembly modules.
3. ZX Spectrum Emulator (ZXSpectrum):
– ROM Loader
– ULA (video timing, screen buffer)
– TapeFile Reader/Recorder
– BASIC Interpreter
– Peripheral abstractions (Joystick, Keyboard, Speaker)
4. UI Layer:
– WPF App (ZXSpectrumUI): MainWindow, Game Loader, Controls
– Platform Adapters: map emulator pins/signals into UI widgets
– ZXCodeEditor: Asm code editing, incremental assembler UI.
5. Test Harness:
– Z80Simulator.Test & ZXSpectrum.Test: drive inputs, capture logs, validate against reference data.
b. Interactions:
• UI calls into ZXSpectrum API to load ROM/tape, start/stop clock.
• ZXSpectrum wraps Z80Simulator: at each tick, drives CPU→System→Memory→Devices.
• ULA emits video frames back to ScreenAdapter; SpeakerAdapter plays audio via NAudio.
• ZXCodeEditor optionally outputs assembly into Z80Simulator.GenerateTables / Z80Simulator.Assembler.
• Test projects instantiate either Z80Simulator or ZXSpectrum.System to run scenarios, compare CSV logs.
c. Architectural Patterns
• Layered architecture: tool → core engine → specialization → presentation.
• Modular design: each instruction group in separate partial classes (e.g., Z80CPU_Instructions_*.cs).
• Dependency injection (System interfaces) for memory/devices.
• The test harness uses a simulation‐only “TestSystem” with mock devices.
d. Key Technologies
• C#/.NET, partial classes for instruction sets, CSV-based table generation.
• WPF for UI + AvalonEdit for code editing + NAudio for audio output.
• xUnit/NUnit for tests, CSV log comparison.