#+OPTIONS: toc:nil

* 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

#+BEGIN_SRC bash
# 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
#+END_SRC

** Testing

Comprehensive test coverage included:

#+BEGIN_SRC bash
# Run all assembly tests
./test_asm.sh

# Run reference CPU validation tests
./test_ref_cpu.sh
#+END_SRC

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 [[https://www.computerenhance.com/p/table-of-contents][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.