CmosCpu Simulator

Educational 8-bit CPU simulator inspired by CMOS/TTL-based computers. Built with .NET 10, C#, clean architecture, and modular design.

Features

• 8-bit CPU with 16-bit address bus
• Minimal instruction set (17 instructions)
• Memory-mapped I/O devices (LED, Timer, RTC)
• Interrupt handling (IRQ, NMI, RESET)
• Text assembler with label support
• Step and continuous execution modes with cycle-accurate device ticking
• DI-friendly architecture with NLog logging
• Universal machine abstraction (IMachine, IMachineProfile, ICpuCore)
• CpuStepResult with per-instruction cycle count
• IDebugger with breakpoint support (stop-on-breakpoint during Run)
• Avalonia UI frontend with modular machine support (Apple-1, KIM-1)
• 200+ unit and integration tests

Project Structure

CmosCpuSimulator/
├─ src/
│  ├─ CmosCpu.Core/              Core interfaces, types, and emulator contracts
│  ├─ CmosCpu.Bus/               System bus implementation (IBus)
│  ├─ CmosCpu.Memory/            RAM, ROM, MemoryMap
│  ├─ CmosCpu.Cpu/               CPU core with instruction set
│  ├─ CmosCpu.Devices/           I/O devices (LED, Timer, RTC)
│  ├─ CmosCpu.Assembler/         Text assembler
│  ├─ CmosCpu.Runtime/           DI container, Machine, MachineBuilder, profile, adapter
│  ├─ CmosCpu.Computer/          Universal computer machine abstraction
│  ├─ Symulator.Application/     Application layer: controller, catalog, machine contracts
│  ├─ Symulator.Machines.Apple1/ Apple-1 machine module (terminal, PIA, profiles)
│  ├─ Symulator.Machines.Kim1/   KIM-1 machine module (keypad, LED, RIOT)
│  └─ Symulator.Avalonia/        Avalonia UI frontend
├─ tests/                         Unit and integration tests (MSTest + Moq + FluentAssertions)
├─ docs/                          Documentation
├─ examples/                      Example programs
├─ profiles/                      Machine profiles
├─ roms/                          ROM binaries
└─ README.md

Prerequisites

• .NET 10 SDK (or .NET 8+)
• Linux, macOS, or Windows

Build

dotnet build

Run Tests

dotnet test

Run Avalonia Frontend

dotnet run --project src/Symulator.Avalonia

Emulator Contracts

Interface	Purpose
ICpuCore	CPU abstraction (steps, interrupts, identity)
IClockedDevice	Device that ticks with the system clock
IResettable	Object that can be reset
IMachine	Complete machine (CPU + bus + devices)
IMachineProfile	Named machine configuration profile
IMachineBuilder	Builder for assembling a machine
IMemoryMap	Memory region lookup
IDebugger	Breakpoint management
IEmulatorUiSettings	Runtime/UI settings (log toggles, limits)
CpuStepResult	Per-instruction result (PC, cycles)

Machine Module Contracts

Interface	Purpose
IMachineModule	Machine family provider (Apple-1, KIM-1)
IMachineSession	Active emulation session with lifecycle
IMachinePanelDescriptor	Machine-specific UI panel descriptor
IEmulatorController	Top-level controller for session management
IMachineCatalog	Registry of available machines

See docs/machine-modules.md for detailed module architecture.

Example: Blink LED

The examples/blink.asm program toggles an LED at address 0xC000:

.org 0x8000

start:
    LDA #0x01          ; ON
    STA 0xC000         ; write to LED
    CALL delay
    LDA #0x00          ; OFF
    STA 0xC000
    CALL delay
    JMP start          ; repeat

delay:
    LDA #0xFF
loop:
    SUB #0x01
    JNZ loop
    RET

Architecture

See docs/architecture.md for detailed architecture documentation.

Instruction Set

See docs/instruction-set.md for the complete instruction reference.

Quick Reference

Opcode	Mnemonic	Bytes	Description
0x00	NOP	1	No operation
0x01	LDA #v	2	Load A immediate
0x02	LDA a	3	Load A absolute
0x03	STA a	3	Store A absolute
0x04	ADD #v	2	Add to A
0x05	SUB #v	2	Subtract from A
0x06	JMP a	3	Jump
0x07	JZ a	3	Jump if Zero
0x08	JNZ a	3	Jump if not Zero
0x09	OUT p	2	Write A to I/O port
0x0A	IN p	2	Read from I/O port
0x0B	CLI	1	Clear interrupts
0x0C	SEI	1	Set interrupts
0x0D	PUSH_A	1	Push A to stack
0x0E	POP_A	1	Pop A from stack
0x0F	CALL a	3	Call subroutine
0x10	RET	1	Return from subroutine
0x11	HLT	1	Halt CPU

Memory Map

Range	Description
0x0000 - 0x7FFF	RAM
0x8000 - 0xBFFF	ROM
0xC000 - 0xC0FF	I/O devices
0xFF00 - 0xFFFF	System vectors

Platform Note

The solution targets net10.0. The UI is Avalonia (cross-platform desktop). Legacy frontends (Blazor Server, ConsoleApp, Terminal.Gui TUI) have been removed in favor of the modular Avalonia architecture.