4 Compatible ROM formats

In order to run the programs, it is required to have a ROM containing the instructions for the program. These instructions are executed by the virtual machine when the emulator starts.

This CHIP-8 distribution comes with a set of public domain ROMs that can be executed in order to test the features of the emulator. These ROMs are in the examples/ directory for the software distribution package, and once installed they are placed in /usr/local/share/doc/chip8/roms, although the exact location may change depending on where is the package installed in.

The user can also create new ROMs using software tools or manually writing machine code into a binary file or an hexadecimal file. These files have to be provided as parameters when starting the emulator, as explained in Running the emulator.

However, there are two ways of storing the program instructions inside CHIP-8 ROMs.

4.1 Binary ROM files

A binary ROM file is a file where every byte is a byte that must be placed in the RAM memory for the emulator when the game starts. In other words, the actual opcodes are encoded. Every 2 bytes in the ROM file can be translated to an actual instruction that the machine must run. (Or to some data such as an sprite).

This is the fastest way for starting ROMs because no transformation is needed. As the emulator starts, the contents of the file are loaded in RAM memory if they fit, and the game is started. However, they need special software, such as hexadecimal editors, in order to see the contents, because they are binary and cannot be opened with regular text editors.

As an example, let’s suppose that we have a binary ROM with the following contents, that we might have got using an hexadecimal file tool such as hexdump:

$ hexdump examples/PONG
0000 6a 02 6b 0c 6c 3f 6d 0c a2 ea da b6 dc d6 6e 00
0010 22 d4 66 03 68 02 60 60 f0 15 f0 07 30 00 12 1a

(more lines have been omitted for brevity)

When this ROM is loaded into memory, the first instruction that will be executed will be 6A02, as these are the first two bytes in the file. Next, the instruction 6B0C will be executed, and then 6C3F, and so.

Binary format is the most preferred way when working with dumps coming from external sources such as actual chips containing programs for old computers using the CHIP-8 format, because they represent the program as it was.

4.2 Hexadecimal ROM files

An hexadecimal ROM file has the hexadecimal characters that are required for running a ROM file, organized in a text file that can be edited by the user in order to build their own programs and games.

It is a file that makes use of a human readable character encoding such as US-ASCII, UTF-8 or Windows-1252 and that contains only characters in the ranges "0" to "9", "A" to "F" and "a" to "f. These ranges would equal to the US-ASCII codes 0x30-0x39, 0x41-0x46 and 0x61-0x66.

The contents for an hexadecimal ROM file can be inspected using regular text editors, as an example:

$ cat pong.hex
6A026B0C6C3F6D0CA2EADAB6DCD66E0022D46603
68026060F015F0073000121AC717770869FFA2F0
D671A2EADAB6DCD66001E0A17BFE6004E0A17B02
601F8B02DAB6600CE0A17DFE600DE0A17D02601F
8D02DCD6A2F0D67186848794603F8602611F8712
46021278463F1282471F69FF47006901D671122A

When an hexadecimal ROM file is given to the emulator, it must be processed. The hexadecimal ROM is converted to binary using the following method:

• It ignores any whitespace or line break.
• It reads the characters 2 by 2.
• For every pair of characters that should represent hexadecimal characters (meaning that they should match the regular expresion ([0-9A-Fa-f]{2}), the following operation is made: (L, R) -> (L << 4) | R, where L is the left hexadecimal character once converted to binary and R is the right hexadecimal character once converted to binary. This conversion is made by transforming every character to the 4-bit digit they represent (0x0 to 0xF).

Although it has not been implemented yet, the following operations are planned:

• Ignore also tabs, in order to ignore any kind of whitespace.
• Allow comments in hexadecimal ROM files to make it easier to people to know what code snippets should do.

4.3 Corrupt ROM files

This emulator has not been tested against fuzz testing, which means that it is not possible to know at this moment what should happen and how should the emulator behave when ROMs having corrupt instructions are execute.

Fuzz testing is made by giving a random input to a program. As an example, randomly generating about 100 to 200 bytes of instructions, either in binary or hexadecimal way, and loading the contents in order to check what happens.

Even though it has not been tested, the expected behaviour should be:

• Glitches on the screen.
• Weird behaviour of the program.
• Keyboard delays where they shouldn’t be.
• Sound, if available, playing through the speaker.

Anyway, it is not expected that a corrupt ROM could harm the host machine in anyway, becuase none of the operations execcuted by the program interact with the underlying operating system in a way that could have side effects. On the other side, all the operations that work with memory buffers make enough tests to minimize the risk of a buffer overflow error.

Despite all of that, this is something that hasn’t been further tested. As stated by the license terms of this sfotware, available in the COPYING file, the emulator is provided AS IS, with no extra warranties.