A from-scratch implementation of a CHIP-8 toolchain, including an interpreter, assembler, and disassembler.

CHIP-8 is a simple interpreted programming language from the 1970s, used on early 8-bit microcomputers. It's a popular starting point for emulator development due to its small instruction set and simple architecture. See the technical reference if you want to read more about it.

This project was born out of a desire to:

• Deeply understand how emulators, virtual machines & interpreters work
• Provide a comfortable toolchain for writing new CHIP-8 programs and analyze old ones
• Practice writing clean Rust code

Components:

• Interpreter:
  • Full support for the original CHIP-8 instruction set, as defined here (no "quirks"!)
  • Graphical output using SDL2
• Assembler:
  • Clear & consistent syntax (as defined by Cowgod)
  • User-friendly error messages
  • Supports all instructions & useful directives
• Disassembler:
  • Translates compiled bytecode into human-readable assembly
  • Makes reverse engineering & ROM analysis easier

• Support for CHIP-8 variants ("quirks"): Super-Chip, XO-CHIP, etc.
• A GUI IDE for writing and running CHIP-8 code (like Octo or Cadmium)
• A compiled high-level language like c8c

• Rust (latest stable version recommended)
• SDL2 development libraries

1. Install Rust: https://www.rust-lang.org/
2. Install SDL2 development libraries:
   • Debian/Ubuntu: sudo apt install libsdl2-dev
   • macOS: brew install sdl2
   • Windows: Use vcpkg or download SDL2 manually.

3. git clone https://www.github.com/kitrofimov/chip8vm
   cd chip8vm
   cargo build --release

4. Find the binaries in target/release!

While interpreting, the CHIP-8 keypad is mapped to the keyboard as follows:

CHIP-8:  1 2 3 C       Keyboard:  1 2 3 4
         4 5 6 D                  Q W E R
         7 8 9 E                  A S D F
         A 0 B F                  Z X C V

interpreter <rom.ch8>
assembler <input.asm> <output.ch8>
disassembler <input.ch8> <output.asm>

• Timendus for his wonderful ROM test suite
• gulrak for the opcode table
• mittmikolay and tobiasvl for their technical references
• Cowgod for assembler syntax reference