chip8

chip8 is a CHIP-8 interpreter written
in Rust with Rust-SDL2.

Features

• Supports both of the original and modified semantics
  of the CHIP-8 instructions.
• Enables users to determine how many CHIP-8 instructions will be executed per
  second.
• Reduces CHIP-8’s inherent flicker by emulating the screen ghosting
  effect.
• Demonstrates how to use sdl2::update() (or
  SDL_UpdateTexture) for efficient rendering.
• Demonstrates how to use SDL’s built-in audio subsystem without relying on the
  SDL_mixer extension library.

Requirements

Rust

This program targets the latest stable version of Rust 1.70.0 or later.

Simple DirectMedia Layer (SDL)

This program uses the Rust-SDL2 crate, which requires the SDL library to be
installed. Rust-SDL2’s README.md provides full details on how to install the
SDL library on Linux, macOS, and Windows.

Installation

$ git clone https://github.com/dkim/chip8.git
$ cd chip8
$ cargo update  # optional
$ cargo build --release

Usage

$ cargo run --release -- --help
chip8 1.0.0
chip8 is a CHIP-8 interpreter written in Rust with Rust-SDL2.
USAGE:
    chip8 [FLAGS] [OPTIONS] <rom-file>
FLAGS:
    -h, --help                    Prints help information
        --no-load-store-quirks    Increases I by X + 1 for FX55/FX65, emulating the original CHIP-8
        --no-shift-quirks         Shifts VY (not VX) for 8XY6/8XYE, emulating the original CHIP-8
    -V, --version                 Prints version information
OPTIONS:
        --cpu-speed <cpu-speed>    Sets how many CHIP-8 instructions will be executed per second
                                   [default: 700]
        --waveform <waveform>      Sets the waveform of the beep [default: triangle]  [possible
                                   values: sawtooth, sine, square, triangle]
ARGS:
    <rom-file>    Sets a ROM file to run
$ cargo run --release -- 'resources/RS-C8003 - Astro Dodge (2008)/Astro Dodge (2008) [Revival Studios].ch8'

Keyboard

Each key on the CHIP-8 hex keyboard can be typed on a QWERTY layout keyboard, as follows:

Compatibility Notes

8xy6 and 8xyE

The following table shows the inconsistent definitions of the semantics of the
8xy6 and 8xyE instructions in four authoritative and/or popular documents:

The 8xy6 and 8xyE instructions were not documented in the official manual, “RCA
COSMAC VIP CDP18S711 Instruction Manual,” while the similar 8xy1, 8xy2, 8xy4,
and 8xy5 instructions were documented as follows:

From the source code of the original CHIP-8 interpreter, people figured out
that the 8xy1, 8xy2, 8xy4, and 8xy5 instructions were implemented by executing
the corresponding machine code F1 (or), F2 (and), F4 (add), and F5 (subtract),
respectively, and that, therefore, the 8xy6 and 8xyE instructions would result
in the execution of the machine code F6 (shift right) and FE (shift left). That
is, the 8xy6 and 8xyE instructions had the following semantics in the original
CHIP-8 interpreter:

Peter K. Morrison published the above semantics of the 8xy6 and 8xyE
instructions (in addition to two other undocumented instructions) in the VIPER
newsletter, vol. 1, no. 2.

However, CHIP-48, a pioneer implementation of CHIP-8 for the HP-48 calculator,
gave the 8xy6 and 8xyE instructions slightly different meanings. They shifted
Vx, instead of Vy, by one bit and stored the results in Vx:

SCHIP, a popular extension of CHIP-8 by Erik Bryntse, was written based on the
publicly available CHIP-48 source code and followed CHIP-48’s definitions of
8xy6 and 8xyE. SCHIP got so popular that many subsequent interpreters and
applications employed the variant semantics of 8xy6 and 8xyE (consciously or
unconsciously) although they claimed to be CHIP-8-compatible.

“Cowgod’s Chip-8 Technical Reference v1.0” suggests the modified semantics of
8xy6 and 8xyE while “Mastering CHIP-8” suggests the original one.

This program supports both semantics of 8xy6 and 8xyE to be able to run all
CHIP-8 programs. The modified semantics is used by default and the original
semantics can also be used with the --no-shift-quirks command-line option.

NOTE: There are some documents (e.g. Chip-8 on the COSMAC VIP and the
previous version of the CHIP-8 page on Wikipedia) saying that 8xy6 and 8xyE
should store the result of shifting Vy in both Vx and Vy:

I believe that they just made mistakes. For instance, “Chip-8 on the COSMAC
VIP“ says in its table that Vy as well as Vx should be updated, but the
flowchart on the same page says that the result of the operation should be
saved in only Vx. It seems that some people made mistakes and that others just
copied them.

Fx55 and Fx65

The official manual and two popular documents disagree about what effect the
Fx55 and Fx65 instructions have on the I register (in addition to the main
load/store functionality):

The official manual, “RCA COSMAC VIP CDP18S711 Instruction Manual,” stated
explicitly that the exeuction of Fx55 and Fx65 would increase the I register by
x + 1.

According to HP48-Superchip, the I register was increased by x (not x + 1) in
CHIP-48, a pioneer implementation of CHIP-8 for the HP-48 calculator. The
behavior was inherited by SCHIP 1.0, a popular extension of CHIP-8.

The SCHIP 1.1 specification did not explicitly mention in the description of
Fx55 and Fx65 whether the I register should change, but appears to have implied
that the I register should not be altered. The implementation provided with the
specification retained the value of the I register.

Like the SCHIP 1.1 specification, “Cowgod’s Chip-8 Technical Reference v1.0”
does not mention the effects of Fx55 and Fx65 on the I register. On the other
hand, “Mastering CHIP-8” suggests the I register should be increased by x + 1.

This program supports the two variants of Fx55 and Fx65. By default, it retains
the original value of the I register. If the --no-load-store-quirks
command-line option is given, Fx55 and Fx65 increase the I register by x + 1.
I could not find any application on the Internet that requires the I register
to be be increased by x.

See Also

• Thomas Daley, ROM compatibility.

License

Licensed under either of

• Apache License, Version 2.0
  (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license
  (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.