performance-aware/README.org

8086 CPU Simulator

A complete 8086 processor emulator written in Odin, featuring instruction decoding, execution, and cycle-accurate simulation. Implements a comprehensive subset of the Intel 8086 instruction set with proper flag handling, memory management, and register operations.

Features

• Complete 8086 instruction decoding - Supports MOV, arithmetic, jumps, loops, stack operations, and more
• Cycle-accurate execution - Proper CPU state management with registers and flags
• Memory simulation - 1MB addressable memory space with effective address calculation
• Comprehensive testing - 21 assembly test programs with automated validation
• Reference validation - Compares execution results against reference CPU states

Architecture

The simulator is organized into several focused modules:

• sim8086.odin - Main entry point and program orchestration
• types.odin - Core data structures (CPU state, instructions, operands)
• instructions.odin - Complete 8086 instruction set definitions
• decoding.odin - Binary instruction decoding and parsing
• execution.odin - CPU execution engine with flag calculations
• printing.odin - Assembly output formatting
• testing.odin - Reference state parsing and validation

Building and Running

# Build the simulator
make

# Decode and print assembly
./sim8086 program.bin instructions

# Execute with register dump
./sim8086 program.bin registers

# Full execution with memory dump
./sim8086 program.bin all dump

Testing

Comprehensive test coverage included:

# Run all assembly tests
./test_asm.sh

# Run reference CPU validation tests
./test_ref_cpu.sh

Test files cover:

• Basic MOV operations and addressing modes
• Arithmetic and logical operations with proper flag setting
• Jump and loop instructions
• Stack operations (PUSH/POP)
• Complex programs with multiple instruction types

Technical Implementation

Instruction Decoding

• Bit-level parsing of 8086 machine code
• Support for all addressing modes (register, immediate, memory, direct)
• Proper handling of prefixes and multi-byte instructions

Execution Engine

• Register file with proper 8/16-bit access patterns
• CPU flags (Zero, Carry, Sign, Overflow, etc.) with accurate calculations
• Effective address computation for memory operations
• Instruction pointer management and control flow

Memory Model

• 1MB linear address space
• Little-endian byte ordering
• Memory-mapped I/O simulation

Supported Instructions

Data Movement: MOV, PUSH, POP, XCHG, LEA, LDS, LES Arithmetic: ADD, SUB, MUL, DIV, INC, DEC, CMP, NEG Logical: AND, OR, XOR, NOT, TEST Shifts/Rotates: SHL, SHR, SAR, ROL, ROR, RCL, RCR Control Flow: JMP, JE, JNE, JL, JG, LOOP, CALL, RET String Operations: MOVS, CMPS, SCAS, LODS, STOS System: INT, IRET, HLT, NOP

Built following the Performance Aware Programming course by Casey Muratori.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: Some test files are derived from the Performance Aware Programming course materials. Consider supporting the course if you find this project useful.