A complete LC-3 virtual machine implementation in Rust.

• Full implementation of all 15 LC-3 opcodes
• Dual-mode trap handling (native Rust fallback + OS vector dispatch)
• Memory-mapped I/O: KBSR, KBDR, DSR, DDR, MCR
• Cross-platform terminal support (Unix + Windows)
• Bundled LC-3 OS image for full hardware fidelity
• MCR-based halt mechanism (matches real hardware)
• PSR (Processor Status Register) with NZP condition codes
• Feature-gated instruction tracing for debugging
• Typed instruction decoding with unit tests
• Result-based error handling (no panics in core logic)

# Run a program with OS support (default)
cargo run -- program.obj

# Run without OS (traps handled natively)
cargo run -- --no-os program.obj

# Run with instruction tracing (requires --features trace)
cargo run --features trace -- --trace program.obj

# Load multiple images
cargo run -- os_extensions.obj program.obj

src/
├── main.rs          # CLI, signals, terminal lifecycle
├── vm.rs            # VM struct, fetch-decode-execute loop
├── memory.rs        # 64K memory + MMIO registers
├── cpu.rs           # Opcode execution handlers
├── instructions.rs  # Typed instruction decoding structs
├── trap.rs          # Trap dispatch (native + OS vector)
├── terminal.rs      # Platform-abstracted terminal I/O
└── error.rs         # Error types

cargo build --release

cargo test

• LC-3 ISA Specification (PDF)
• Write your Own Virtual Machine (Tutorial)
• lc3sim-c by Ryan Pendleton

In development — see PLAN.md for implementation roadmap.