EasyCPU

🌐 Live demo: delfuria.github.io/EasyCPU — run EasyCPU directly in your browser, no installation required.

A comprehensive, cross-platform IDE for teaching Assembly language programming and X86 processor architecture fundamentals.

EasyCPU is an educational tool designed to make learning assembly language and CPU architecture accessible and intuitive. It provides a simplified but functional virtual CPU that implements a subset of X86 instructions, allowing students to write, execute, and debug assembly programs with immediate visual feedback on CPU state.

🎯 Key Features

Core Capabilities

Interactive Assembly Editor – Write assembly code with syntax support for EasyCPU's instruction set
Step-by-Step Debugging – Execute programs one instruction at a time to understand control flow and side effects; after each step the register, memory, symbol and stack values that changed are highlighted
Real-Time CPU State Visualization – Monitor registers, memory, stack, and flags as code executes
Integrated Compiler – Parse and compile assembly code with detailed syntax error reporting; runtime errors (division by zero, stack overflow, invalid IP…) are reported with the offending line
Multiple Data Format Viewers – Display memory, stack, and register values in decimal, hexadecimal, or ASCII
Infinite Loop Detection – Safely interrupt runaway programs with configurable thresholds
Code & Data Separation – Organize assembly into code and data sections; the data section supports MASM-style DB/DW variables, EQU constants, strings, DUP and ORG
Console I/O – DOS-style int 21h services for keyboard input and text output
x86-Faithful Byte Memory – Optional per-program mode (Esegui → Memoria a byte (x86), saved in the .asj file): 512 bytes, little-endian words, 2-byte stack steps, and x86 rules (byte ptr/word ptr required for ambiguous operands, no memory-to-memory operations)

Educational Features

Live Register & Flag Tracking – Watch how each instruction modifies CPU state
Memory Inspection – View memory and stack contents, plus a Symbols list with the address, type and current value of each data name
Run-to-Instruction – Execute all instructions up to a selected line for faster iteration
Breakpoints – Mark lines with F9 or a click in the editor margin; execution pauses there so the CPU state can be inspected
Execution State Indicators – Visual feedback on whether program is running, paused, or stopped
Error Highlighting – Clicking compilation errors jumps directly to problematic code
Print (Ctrl+P / ⌘P) – Prints the data section, with the memory address of each declaration, and the code with line numbers and syntax colors, through the browser's print dialog (which can also save as PDF)
Contextual Help (F1) – Opens the Assembly Reference in the browser at the instruction under the cursor (offline on desktop, online on iOS/Android)

📚 What is EasyCPU?

EasyCPU is:

✅ An educational tool for learning assembly fundamentals
✅ A simplified X86 simulator with a reduced, easy-to-understand instruction set
✅ An interactive debugger for real-time program state inspection
✅ A didactic environment designed for classroom and self-study use

EasyCPU is not:

❌ A production assembler – it does not generate native machine code for any real platform
❌ A full X86 emulator – it implements a simplified subset of instructions and addressing modes
❌ Compatible with standard Intel syntax or POSIX assembly conventions
❌ Intended for real-world assembly development

🔧 What You Can Do With EasyCPU

Write Assembly Programs

Create programs using EasyCPU's instruction set. Programs can:

Perform arithmetic and logical operations
Manipulate memory and stack
Use conditional and unconditional jumps
Call subroutines
Work with registers and flags

Debug Step-by-Step

Execute one instruction at a time to:

Trace control flow
Inspect register values after each operation
Watch memory and stack changes
Understand how different addressing modes work
Verify algorithm correctness

Learn CPU Fundamentals

Develop practical understanding of:

Register-based computation
Memory and addressing
Stack frame management
Flag-based conditional logic
Procedure calls and returns
Infinite loop detection

📖 Assembly Instruction Set

EasyCPU implements an 8086-style instruction set (16-bit and 8-bit registers, CF/ZF/SF/OF/DF flags with x86 bit layout, base+index addressing such as [bx+si+2]):

Arithmetic: ADD, ADC, SUB, SBB, MUL, IMUL, DIV, IDIV, INC, DEC, NEG, CBW, CWD
Logic: AND, OR, XOR, NOT, TEST
Shift/Rotate: SHL, SHR, SAR, ROL, ROR, RCL, RCR
Data Transfer: MOV, XCHG, LEA
String: MOVSB/MOVSW (MOVS), LODSB/LODSW, STOSB/STOSW, CMPSB/CMPSW, SCASB/SCASW with REP, REPE/REPZ, REPNE/REPNZ prefixes
Comparison: CMP
Conditional Jumps (signed): JE/JZ, JNE/JNZ, JL, JLE, JG, JGE, JO, JNO, JS, JNS (plus x86 synonyms JNGE, JNG, JNLE, JNL)
Conditional Jumps (unsigned): JA, JAE, JB, JBE, JC, JNC (plus synonyms JNBE, JNB, JNAE, JNA)
Loops: LOOP, LOOPE/LOOPZ, LOOPNE/LOOPNZ, JCXZ
Unconditional Control: JMP (direct, or indirect through a register or memory: jmp bx, jmp [tab+bx])
Procedure Calls: CALL (direct or indirect: call [proc+si]), RET, RET n
Stack: PUSH, POP, PUSHF, POPF
Flags: CLC, STC, CMC, CLD, STD
Interrupts: INT (DOS-style int 21h console services)
Miscellaneous: NOP, STOP

MUL/DIV operate on unsigned values, IMUL/IDIV on signed values.

int 21h provides DOS-style services selected via AH: 01h read a character with echo (into AL), 02h write the character in DL, 07h read a character without echo, 09h write the $-terminated string at DX, 0Ah read a line into the buffer at DX, 4Ch terminate the program. Output and keyboard input are shown/captured in the dedicated Console panel.

By default memory is made of 256 16-bit cells (word model). The optional x86-faithful mode switches the program to a 512-byte memory with little-endian words, a 64-byte stack (SP starts at 512 and moves by 2), and x86 compile-time rules; see the Modalità x86 fedele chapter of the Assembly Reference.

The data section supports MASM-style symbolic declarations: DB/DW variables, EQU constants, strings, DUP, ORG and offset; code labels can be used as values (offset label in code, tab DW case0, case1 in data) to build jump tables. byte ptr and word ptr set the size of a memory operand (example programs in Docs/samples).

For complete instruction documentation, register definitions, addressing modes, and flag behavior, see the Easy CPU Assembly Reference.

🎓 IDE Overview

The EasyCPU IDE is organized into four main areas:

Code & Data Editor

Side-by-side editors for assembly code and data section initialization. Supports syntax highlighting and automatic indentation.

Register Viewer

Displays all CPU registers (AX, BX, CX, DX, SI, DI, BP, SP, IP) in the selected format, with the high and low bytes of AX–DX (AX = 0141 [AH=01 AL=41]). The flags are listed as C, Z, S, O, D (carry, zero, sign, overflow, direction).

Memory Inspector

Shows the data memory and the stack. Toggle between decimal, hexadecimal, and character formats (the choice is remembered); view the stack in one or two columns. In byte-memory mode the panel is titled Memoria (byte) and shows 16 bytes per row, while the stack shows one word per row. Below the memory, the Symbols section lists the names defined in the data section and the code labels with their instruction number.

Console Panel

Displays output and captures keyboard input for int 21h calls. Auto-activates on int 21h and shows a blinking cursor while waiting for a keypress.

Execution Controls

Toolbar buttons and menu commands for:

Run (F5) – Execute until program end, a breakpoint (F9) or infinite loop detection
Step (F11; F10 steps over a call) – Execute one instruction (for rep-prefixed string instructions, one repetition per step)
Run to Instruction (Ctrl+F5) – Execute until selected line
Stop (F8) – Halt execution
New/Open/Save – File management, with the 10 most recent programs (in the browser, under the Recenti entry of the side menu)

Breakpoints

A breakpoint pauses the program when execution reaches its line, leaving registers, memory and stack available for inspection; from there you can continue with Run or go on step by step.

Set/remove – Press F9 (or Esegui → Imposta/Rimuovi breakpoint) on the line under the cursor, or click the margin to the left of the line numbers; the line is marked with a red dot
Where they apply – Run (F5), Run to Instruction (Ctrl+F5), and Step Over/Step Out (F10/Shift+F11) when a breakpoint is inside the subroutine being skipped
Executable lines only – Breakpoints on empty lines, comments or lines holding only a label are ignored
rep string instructions – Execution pauses when the instruction is reached, not at every repetition
Saved per program – Kept between sessions: in a .bkpt file next to the program on the desktop, in localStorage in the browser

Compilation & Error Reporting

Automatic compilation before execution. Syntax errors are listed with line numbers and descriptions; click an error to navigate directly to it in the editor. Errors detected while the program runs are shown in the same panel as Esecuzione errors, with the line of the instruction that caused them.

Settings Persistence

Options, panel layout, recent programs and breakpoints are kept between sessions: in files on the desktop, in the browser's localStorage in the web version (clear the site data to reset them).

For detailed step-by-step tutorials and screenshots, see the EasyCPU IDE Tutorial. (Note: Tutorial focuses on Windows UI; layouts differ slightly on other platforms.)

📝 Documentation

Complete documentation is available in the Docs/ folder:

Easy CPU Assembly Reference – Complete instruction set documentation with syntax, examples, and flag behavior
EasyCPU IDE Tutorial – Step-by-step guide to using the IDE, debugging, and managing programs
Toolbar Icons Reference – Visual guide to IDE toolbar buttons

Ready-to-run example programs (.asj) are available in Docs/samples/, organized by topic (data transfer, arithmetic and flags, logic and shifts, stack and subroutines, data section, int 21h console, complete programs, jumps and loops, string instructions, errors, indirect jumps, byte memory, step-by-step debugging, F1 help); each one starts with a comment describing what it shows and the expected result. The original examples in the legacy .as format are in Docs/Subroutines/.

Design documents for the x86 extensions (roadmap, open proposals and their designs) are in Proposte/.

🚀 Project Structure

EasyCPU/
├── EasyCpu.Assembler/          # Assembly parser and compiler
│   ├── Parsing/                # Lexer, parser, AST
│   ├── Processore/             # Virtual CPU and instruction execution
│   └── Memoria/                # Memory and register management
├── EasyCpu.Backend/            # Shared backend logic
├── EasyCpu.Common/             # Common types and utilities
├── EasyCPU/                    # Shared Avalonia UI (views/viewmodels)
├── EasyCPU.Desktop/            # Desktop platform (Windows/macOS/Linux)
├── EasyCPU.Browser/            # Browser platform (WASM)
├── EasyCPU.iOS/                # iOS platform
├── EasyCPU.Android/            # Android platform
├── EasyCpu.Assembler.Tests/    # Unit tests for assembler
├── EasyCpu.DocGen/             # Generates Docs/html/reference.html (F1 help) from the Assembly Reference
├── Docs/                       # Documentation
│   ├── Easy CPU Assembly Reference.md
│   ├── EasyCPU IDE Tutorial.md
│   ├── html/reference.html     # Generated F1 help page (EasyCpu.DocGen)
│   ├── samples/                # Example programs (.asj) by topic
│   └── Subroutines/            # Original examples (.as)
└── Proposte/                   # x86 extension roadmap and design documents

🛠️ Requirements

.NET SDK 10 or later
AvaloniaUI 12.0+ (included via NuGet)
Platform-specific requirements:
- Desktop: Windows 10+, macOS 10.13+, or Linux (GTK 3.0+)
- Browser: Modern web browser with WebAssembly support
- iOS: iOS 12.0+ with Xcode
- Android: Android 5.0+ (API level 21+) with Android SDK

Install Required Workloads

To build for specific platforms, install the necessary .NET workloads:

# Desktop support (Windows/macOS/Linux)
dotnet workload install desktop

# Browser/WebAssembly support
dotnet workload install wasm-tools

# iOS support
dotnet workload install ios

# Android support
dotnet workload install android

# Install all at once
dotnet workload install desktop wasm-tools ios android

After installing workloads, restore NuGet dependencies:

dotnet restore

🖥️ Supported Platforms

EasyCPU is implemented for multiple platforms with a shared core:

Platform	Status	Features
Desktop (Windows/macOS/Linux)	✅ Implemented	Full IDE with all features
Browser (WebAssembly)	✅ Implemented	Complete IDE running in browser via WASM; options, layout, recent programs and breakpoints are kept in the browser's `localStorage` (clear the site data to reset them)
iOS	✅ Implemented	Touch-optimized interface for iPad/iPhone
Android	✅ Implemented	Native Android app interface

All platforms share the same assembly compiler and virtual CPU core, ensuring consistent behavior across devices.

🏗️ Architecture

EasyCPU is built on a modular architecture with clear separation of concerns:

Core Components

EasyCpu.Assembler – Assembly language parser and compiler, and the virtual CPU that executes the compiled program (registers, flags, memory, stack)
EasyCpu.Backend – File formats (.asj, legacy .as) and settings storage (files on the desktop, localStorage in the browser)
EasyCpu.Common – Shared data structures and utilities used across projects
EasyCPU. (UI Projects)* – Platform-specific front-ends (Desktop, Browser, iOS, Android)

Technology Stack

Framework: .NET SDK 10
UI Framework: AvaloniaUI – Cross-platform, XAML-based UI for Desktop, Browser, iOS, and Android
Language: C#
Browser Target: WebAssembly (Emscripten compilation)

🔨 Build

Build for Desktop (Windows/macOS/Linux)

# Restore dependencies
dotnet restore EasyCPU.Desktop

# Build
dotnet build EasyCPU.Desktop -c Release

# Or directly run
dotnet run --project EasyCPU.Desktop -c Release

Build for Browser (WebAssembly)

# Restore dependencies
dotnet restore EasyCPU.Browser

# Publish for WebAssembly (creates wwwroot output)
dotnet publish EasyCPU.Browser -c Release

# The output will be in EasyCPU.Browser/bin/Release/net10.0/publish/wwwroot

Build for iOS

# Restore dependencies
dotnet restore EasyCPU.iOS

# Build
dotnet build EasyCPU.iOS -c Release -f net10.0-ios

# Or create an IPA for deployment
dotnet publish EasyCPU.iOS -c Release -f net10.0-ios

Build for Android

# Restore dependencies
dotnet restore EasyCPU.Android

# Build
dotnet build EasyCPU.Android -c Release -f net10.0-android

# Or create an APK for deployment
dotnet publish EasyCPU.Android -c Release -f net10.0-android

Clean Build

To perform a clean rebuild across all projects:

# Clean all build artifacts
dotnet clean

# Restore workloads and dependencies
dotnet workload restore
dotnet restore

# Rebuild all projects
dotnet build -c Release

👥 Credits

EasyCPU was developed by Paolo Meozzi and Stefano Del Furia.

Special thanks to JetBrains for supporting this project with open-source licenses for their IDEs.

Special thanks to Avalonia for providing the cross-platform UI framework that powers EasyCPU across Desktop, Browser, iOS, and Android.

📄 License

See repository for license details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
Docs		Docs
Proposte		Proposte
VS Solution		VS Solution
images		images
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
ICONE-TOOLBAR.md		ICONE-TOOLBAR.md
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation