Skip to content

Architecture

Jump to bottom
Przemyslaw Rachwlal edited this page May 4, 2026 · 1 revision

Architecture

Overview

The simulator follows a clean architecture with strict one-way dependency flow. Each layer depends only on layers below it.

Dependency Graph

CmosCpu.Core (no dependencies)
    ↓
CmosCpu.Bus ──────────────→ Core
CmosCpu.Memory ───────────→ Core, Bus
CmosCpu.Cpu ──────────────→ Core, Bus
CmosCpu.Devices ──────────→ Core, Bus
CmosCpu.Assembler ────────→ Core
    ↓
CmosCpu.Runtime ─────────→ Core, Bus, Memory, Cpu, Devices, Assembler
    ↓
CmosCpu.Computer ────────→ Core, Bus, Memory, Cpu, Devices, Runtime
    ↓
Symulator.Application ───→ Core, Cpu, Bus, Memory, Devices, Assembler, Runtime, Computer
    ↓
Symulator.Machines.* ────→ Core, Computer, Runtime, Devices, Application
    ↓
Symulator.Avalonia ──────→ Application, Machines.*, Computer, Core

Layer Descriptions

CmosCpu.Core

Core interfaces and value types with zero dependencies:

  • ICpuCore, IBus, IBusDevice, IMachine, IMachineProfile, IMachineBuilder
  • IMemoryMap, IClockedDevice, IResettable, IAssembler, ISimulator, IDebugger
  • CpuRegisters, Opcode, CpuFlags, MemoryRegion, InstructionInfo

CmosCpu.Bus

System bus that routes read/write operations to registered devices by address range.

CmosCpu.Memory

RAM and ROM implementations with load/store and memory map lookup.

CmosCpu.Cpu

CPU cores:

  • CpuCore: Educational 17-opcode ISA for learning CPU internals
  • Mos6502Cpu: Full MOS 6502 emulation (56 official opcodes, decimal mode, interrupts)
  • Z80Cpu: In-progress Z80 emulation (MVP stage)

CmosCpu.Devices

Memory-mapped I/O devices:

  • LedDevice — simple LED at memory address
  • TimerDevice — countdown timer
  • RtcDevice — DS3231 RTC emulation

CmosCpu.Assembler

SimpleAssembler — text-to-bytecode assembler with label support.

CmosCpu.Runtime

Machine assembly and DI wiring: Machine, MachineBuilder, adapters between CPU/bus and the core interfaces.

CmosCpu.Computer

High-level computer abstractions:

  • ComputerMachine, ComputerMemoryBus, ComputerRunController
  • Device emulations: Pia6821, Hd44780Lcd, I2C controller, UART/Serial
  • Apple1PiaTerminalDevice, Kim1Riot6530IoDevice

Symulator.Application

Application orchestration:

  • EmulatorController — session lifecycle management
  • IMachineCatalog — available machine discovery
  • IMachineModule — pluggable machine modules
  • SolutionDefinition — program manifest loader

Symulator.Machines.*

Machine-specific modules:

  • Apple-1: Terminal, PIA adapter, boot workflow, Woz Monitor + BASIC
  • KIM-1: Keypad, 7-segment LED display, RIOT/6530 I/O
  • Minimal Blink: Experimental dynamic hardware platform
  • Retro70: Simple educational 6502 computer

Symulator.Avalonia

Cross-platform desktop UI using Avalonia 11.2 with MVVM:

  • Machine selector, workspace hosting via DataTemplates
  • Emulator controls (run, pause, step, reset)
  • Machine-specific panels (terminal, keypad, LED, CPU state)

Machine Module Interface

IMachineModule
  ├── Id (string, e.g. "apple1", "kim1")
  ├── DisplayName
  ├── CreateSession() → IMachineSession
  └── PanelDescriptors → IReadOnlyList<IMachinePanelDescriptor>

IMachineSession
  ├── StartAsync(), StopAsync()
  ├── SendInputAsync(string)
  ├── OutputReceived event
  └── Snapshot → EmulatorStateSnapshot

Key Design Decisions

  • Memory-mapped I/O: All devices communicate through the system bus
  • Cycle accuracy: Devices tick in sync with CPU cycles
  • DI-first: Everything wired through Microsoft.Extensions.DependencyInjection
  • Nullable enabled: All projects use <Nullable>enable</Nullable>
  • No blocking waits: Async/await throughout
  • Avalonia threading: UI updates marshaled via Dispatcher.UIThread.Post

See Also

Clone this wiki locally