Repository files navigation

An Octo compatible XO Chip, Super Chip, and Chip 8 emulator.

1. What is it?
2. License
3. Compiling
   1. Big-endian Architectures
   2. Unit Tests
4. Running
   1. Running a ROM
   2. Screen Scaling
   3. Instructions Per Second
   4. Quirks Modes
      1. Shift Quirks
      2. Index Quirks
      3. Jump Quirks
      4. Clip Quirks
      5. Logic Quirks
5. Keys
   1. Regular Keys
   2. Debug Keys
6. ROM Compatibility
7. Troubleshooting
8. Further Documentation

This project is a Super Chip 8 emulator written in C. There are two other versionsof the emulator written in different languages:

• Chip8Python
• Chip8Java

The original goal of these projects was to learn how to code a simple emulator.

In addition to supporting Chip 8 ROMs, the emulator also supports the Super Chip8 instruction set. Note that no additional configuration is needed to run a SuperChip 8 ROM - simply run the ROM the same way you would run a normal Chip 8 ROM.

This project makes use of an MIT style license. Please see the file called LICENSEfor more information.

Simply copy the source files to a directory of your choice. In addition tothe source, you will need the following required software packages:

• GNU C Compiler 4.6.3 or later
• GNU Make 3.81 or later
• SDL 2.0.20 or later
• CUnit 2.1-3 or later

Note that other C compilers make work as well. To compile the project, open acommand prompt, switch to the source directory, and type:

make

Assuming that the required packages are installed and available on your searchpath, the project should compile without errors. The standard build variablesare available if you wish to customize the build further. For example, to usean ARM based C compiler, simply override theCC variable during the build:

CC=arm-c-compiler-bin make

Regardless of the compiler, a successful build should result in a single binaryin the source directory called:

yac8e

The binary stands for "Yet Another Chip 8 Emulator".

If you plan to run the Chip 8 emulator on a big-endian architecture, you willneed to compile with the following flag:

make CFLAGS=-DWORDS_BIGENDIAN

To run the unit test suite, use the make target oftest:

make test

The command-line interface requires a single argument, which is the fullpath to a Chip 8 ROM:

yac8e /path/to/rom/filename

This will start the emulator with the specified ROM. The emulator alsotakes optional parameters.

The-s or--scale switch will scale the size of the window (the original size at1x scale is 64 x 32):

yac8e /path/to/rom/filename -s 10

The command above will scale the window so that it is 10 times the normalsize.

The-t or--ticks switch will limit the number of instructions per secondthat the emulator is allowed to run. By default, the value is set to 1,000.Minimum values are 100. Use this switch to adjust the running time of ROMsthat execute too quickly. For simplicity, each instruction is assumed totake the same amount of time.

Over time, various extensions to the Chip8 mnemonics were developed, whichresulted in an interesting fragmentation of the Chip8 language specification.As discussed in Octo'sMastering SuperChipdocumentation, one version of the SuperChip instruction set subtly changedthe meaning of a few instructions from their original Chip8 definitions.This change went mostly unnoticed for many implementations of the Chip8language. Problems arose when people started writing programs using theupdated language model - programs written for "pure" Chip8 ceased tofunction correctly on emulators making use of the altered specification.

To address this issue,Octo implementsa number ofquirks modes so that all Chip8 software can run correctly,regardless of which specification was used when developing the Chip8 program.This same approach is used here, such that there are severalquirks flagsthat can be passed to the emulator at startup to force it to run withadjustments to the language specification.

Additional quirks and their impacts on the running Chip8 interpreter areexamined in great depth at Chromatophore'sHP48-Superchiprepository. Many thanks for this detailed explanation of various quirksfound in the wild!

The--shift_quirks flag will change the way that register shift operations work.In the original language specification two registers were required: thedestination registerx, and the source registery. The source registeryvalue was shifted one bit left or right, and stored inx. For example,shift left was defined as:

Vx = Vy << 1

However, with the updated language specification, the source and destinationregister are assumed to always be the same, thus they register is ignored andinstead the value is sourced fromx as such:

Vx = Vx << 1

The--index_quirks flag controls whether post-increments are made to the index registerfollowing various register based operations. For load (Fn65) and store (Fn55) registeroperations, the original specification for the Chip8 language results in the indexregister being post-incremented by the number of registers stored. With the SuperChip8 specification, this behavior is not always adhered to. Setting--index_quirkswill prevent the post-increment of the index register from occurring after either of theseinstructions.

The--jump_quirks controls how jumps to various addresses are made with the jump (Bnnn)instruction. In the original Chip8 language specification, the jump is made by taking thecontents of register 0, and adding it to the encoded numeric value, such as:

PC = V0 + nnn

With the Super Chip8 specification, the highest 4 bits of the instruction encode theregister to use (Bxnn) such. The behavior of--jump_quirks becomes:

PC = Vx + nn

The--clip_quirks controls whether sprites are allowed to wrap around the display.By default, sprits will wrap around the borders of the screen. If turned on, thensprites will not be allowed to wrap.

The--logic_quirks controls whether the F register is cleared after logic operationssuch as AND, OR, and XOR. By default, F is left undefined following these operations.With the flag turned on, F will always be cleared.

The filekeyboard.c contains the key mapping between the PC keyboard keysand the Chip 8 emulator keys. Updating the second column of thekeyboard_defarray will effectively change the key mapping.

There are two sets of keys that the emulator uses: debug keys and regularkeys.

The original Chip 8 had a keypad with the numbered keys 0 - 9 and A - F (16keys in total). The original key configuration was as follows:

The Chip8 emulator maps them to the following keyboard keys by default:

In addition to the key mappings specified in the configuration file, there are additionalkeys that impact the execution of the emulator.

Here are the list of public domain ROMs and their current status with the emulator, alongwith links to public domain repositories where applicable.

• Runningmake fails with errors regardingSDL functions.

You will need to ensure that you have SDL 2.20 or later installed on yourcomputer. Additionally, you will need to make sure that thesdl2-configbinary is available on your search path. The makefile uses it exclusively toensure that the correctLDFLAGS andCFLAGS are set. If you do not have thebinary, you can try providing the correct flags and paths to the SDL libraryon the command line. For example:

CFLAGS=-I/usr/include/SDL2 make

The above command would force the make to use/usr/include/SDL2 as a sourceof header files during the compile. Additionally, library flags need to beset as well, such as:

LDFLAGS=-lSDL2 -lSDL2_mixer make

Comments in the source code are written to conform to Doxygen conventions.A Doxygen configuration file, along with an associated make target have beensupplied. Simply type:

make doc

This will create a directory calleddoc withhtml andlatex directories.Underhtml, open theindex.html file in a web browser for more information.