chip8stuff

Simple interpreter to execute CHIP-8 games. Capable of creating standalone executables with embedded ROM files, even after compile time.

Passes the Timendus/chip8-test-suite tests (except for the display wait quirk). The sound timer and playback is not implemented yet, since I have not yet tested any rom that makes use of it.

Rendering is done using the Pixels crate. All features are tested only on Linux and X11.

Usage

Pass the rom file via command line argument

./chip8stuff <ROM_FILE>

Use --paused to start the debugger in paused mode, allowing you to single-step right from the start.

./chip8stuff <ROM_FILE> --paused

Creating standlone executables with embedded ROM file

You can use the --embed command to create a copy of the executable that will include the given ROM file, so it can be executed directly without depending on a separate ROM file. The ROM will be appended to the ELF executable, followed by a trailer consisting of the magic value 0xC8 and the length of the ROM as u16 (big endian).

The new executable will be placed in the current working directory with the name chip8stuff_<ROM_FILE>_player

./chip8stuff --embed <ROM_FILE>
# run the new executable
./chip8stuff_<ROM_FILE>_player

See --verbose for detailed logging and --help for usage help.

Input

The original hex keypad

1	2	3	C
4	5	6	D
7	8	9	E
a	0	B	F

is mapped to the keyboard as following:

1	2	3	4
Q	W	E	R
A	S	D	F
Y	X	C	V

Debug features

• view register values

• view executed instructions

• pause execution/single step

• dump memory to a file, the exact file name will be printed on stdout at info level