Cadmium

A CHIP-8 emulation environment written in C++ with a raylib backend.

<!-- TOC -->

• Cadmium
  • Introduction
  • Online Version
  • Features
    • Supported CHIP-8 variants
    • Multi Architecture Debugging
    • Quirks
    • Keyboard Shortcuts
  • Command-line
  • Versioning
  • Compiling from Source
    • Linux / macOS
    • Windows
    • Build for Web
  • Used Resources
    • Information
    • Other Emulators used for Verification
    • Libraries
  • Special Credits
  • FAQ
    • Why the name Cadmium?
    • Why the pixel look?
    • Which font is that?

<!-- TOC -->

Introduction

CHIP-8 is maybe the first breed of what is today called a "fantasy console". The first opcode interpreter was written by Joseph Weisbecker for the "COSMAC" CDP1802 cpu that he developed at RCA and was used in machines like e.g. the COSMAC VIP and the Telmac 1800.

CHIP-8 is today seen as the "Hello world" of emulators, so the first suggestion if someone wants to get into emulator coding is to write a CHIP-8 the get the feeling for it. I already had done some work on emulators and wrote my own implementation of a Commodore 64 emulator in C++, so one could say that I had no reason to actually make a CHIP-8 one, but on a longer weekend off, I stumbled across the topic, I knew the system from my trusty old HP-48GX, during my study times in the 1990s, so I felt it would be fun to try to cobble an implementation together in a few hours. It worked quite well, and as I was using raylib for some tools and took part in a raylib game jam, I saw this as a good fit.

I had so much fun with this project that I added emulation of the original COSMAC VIP and the DREAM6800 to the project, to allow using those to run the historical CHIP-8 interpreters from the past and also to allow execution of hybrid CHIP-8 programs that contain a mix of CHIP-8 and assembly subroutines using the rarely supported 0nnn opcode. So this project explores the corners of historic CHIP-8 as well and sometimes goes a bit beyond it.

Online Version

Emscripten builds are available here for testing:

• https://games.gulrak.net/cadmium - This is the most current release version
• https://games.gulrak.net/cadmium-wip/?p=xochip - this is the current work in progress

Simply drag rom files (.ch8, .hc8, .ch10, .c8h, .c8e, .c8x, .sc8, .mc8, .xo8) or Octo sources (.8o), or Octo cartridges (.gif), or even COSMAC VIP programs (.bin or .ram) onto the window to load them.

Features

The emulation behavior used in Cadmium is based on opcode information documented in the opcode table, various VIPER magazine issues, the CHIP-8 extensions and compatibility pages and tests on various emulators and the HP-48SX/HP-48GX calculator implementations as well as analyzing the historic interpreters' code and running them on COSMAC VIP and DREAM6800 (but both emulated, as I sadly don't have access to real hardware of those yet).

Supported CHIP-8 variants

The emulation is based on different emulation cores and, depending on the core, on a set of "quirks" named options that go along with the core. To lessen the burden to remember the combinations, Cadmium uses "Behavior Presets" to combine a core, some settings and set of quirks to easily switch between CHIP-8 variants. The naming conventions adapted are based on the list put together by Tobias V. Langhoff at https://chip-8.github.io/extensions/ and for the classic COSMAC VIP based variants it is mainly based on the VIPER magazine where those interpreter variants where published.

The Supported presets are:

• CHIP-8
• CHIP-8-STRICT (cycle exact HLE VIP CHIP-8)
• CHIP-8E
• CHIP-8X
• CHIP-10
• CHIP-48
• SUPER-CHIP 1.0
• SUPER-CHIP 1.1
• SUPER-CHIP COMP
• MODERN-SUPER-CHIP
• MegaChip 8 (with Mega8 wrapping/scrolling support if wrapping is enabled)
• XO-CHIP
• VIP-CHIP-8 (CHIP-8 on an emulated COSMAC VIP)
• VIP-CHIP-8 TPD (same, but with 64x64 display)
• VIP-HI-RES-CHIP-8 (same, but with 64x128 display)
• VIP-CHIP-8E (same, with CHIP-8E interpreter)
• VIP-CHIP-8X (same, with CHIP-8X and VP-590/VP-595 add-on boards)
• VIP-CHIP-8X TPD (same hardware as VIP-CHIP-8X but 64x64)
• VIP-HI-RES-CHIP-8X (same hardware as VIP-CHIP-8X but 64x128)
• CHIP-8-DREAM (CHIP-8 on an emulated DREAM6800)

Whith CHIP-8-STRICT Cadmium might be the first high-level emulator that has a core that can execute CHIP-8 with the behavior and timing of the initial VIP CHIP-8 interpreter without actually emulating the actual COSMAC VIP. While this core, like other HLE emulators, can not execute machine subroutines, it emulates the exact timing behavior of every instruction and the overall frame timing to reach cycle exact accuracy compared to the real machine. The main difference to the VIP-CHIP-8 preset is, that this one needs quite less host CPU resources, but as said, can't run hybrid programs.

The SUPER-CHIP COMP or SCHIPC is a more generic variant that is similar to Chromatophores SCHPC/GCHPC variants of SCHIP1.1 to allow more modern games (often developed on Octo) that target SuperCHIP to run without tweeking some quirks that, while correct for the original SCHIP1.1, are not common in modern programs.

The MODERN-SUPER-CHIP is more or less Octo's interpretation of SUSER-CHIP and what Timendus test suite v4.1 checks for as modern SCHIP.

The VIP-CHIP-8 variant presets activate a core that is emulating a COSMAC VIP driven by a CDP1802 CPU with 4k RAM, to execute original CHIP-8 interpreter variants to allow more accurate emulation of classic CHIP-8 and even allow hybrid roms (.hc8) that contain CDP1802 parts to execute on Cadmium. The currently available behaviors are classic CHIP-8, CHIP-8 Two Page Display (TPD), HI-RES-CHIP-8 (four page display, FPD), and CHIP-8X with the VP-590 Color Board and the VP-595 Simple Sound Board attached, as well as a TDP and a HI-RES version of 8X using that hardware.

The CHIP-8-DREAM preset activates a core that is emulating a DREAM6800 driven by an M6800 CPU with 4k RAM, to execute the original CHIP-8 CHIPOS kernel and run an accurate emulation of DREAM6800 CHIP-8. This core also allows hybrid roms that use machine code parts.

There now also is the possibility to select a COSMAC VIP without any CHIP-8 interpreter. Cadmium then falls back into a raw 1802 COSMAC VIP emulation that allows to load and run games and programs made for the VIP that don't use CHIP-8.

Multi Architecture Debugging

Cadmium allows for those presets, that emulate actual hardware, to debug seamlessly on the CHIP-8 opcode level or the backend CPU assembly level:

Breakpoints and single stepping works in both views, the selected instruction tab defines the logical entity the debug buttons work on, the register view shows the registers of that entity. Breakpoints of the hidden entity still work and the tab switches to the entity that hit the breakpoint.

Note: Be aware, that in COSMAC VIP 1802 mode, while breakpoints and single stepping works fine, there is no step-over/step-out support as there is no defined way of the 1802 CPU to enter subroutines and return, and no stack in the sense most other CPUs have it. The M6800 debugging of the DREAM6800 side has those features enabled, as have all CHIP-8 modes, even the VIP one.

Quirks

Emulation uses a number of configurable "quirks" or options, to allow a wide range of roms to work with it. Contrary to some other sources, Cadmium sees the initial original VIP behavior as the reference, so disabling all following options gives a basic VIP CHIP-8:

• 8xy6/8xyE just shift Vx
• 8xy1/8xy2/8xy3 don't reset VF
• Fx55/Fx65 increment I only by x
• Fx55/Fx65 don't increment I
• Bxnn/jump0 uses Vx
• wrap sprite pixels
• Dxyn doesn't wait for vsync
• Lores Dxy0 draws with 0(classic CHIP-8)/8/16 pixel width
• Dxyn uses SCHIP1.1 collision logic
• SCHIP lores drawing
• Half-pixel lores scroll
• Mode change clears screen
• 128x64 hires support
• only 128x64 mode
• multicolor support
• Cyclic stack
• Extended display wait
• XO-CHIP sound engine

Keyboard Shortcuts

| Function | Windows/Linux | macOS | |:--------------|:--------------------------------:|:--------------------------------:| | New | <kbd>Ctrl</kbd> + <kbd>O</kbd> | <kbd>Cmd</kbd> + <kbd>O</kbd> | | Open File | <kbd>Ctrl</kbd> + <kbd>O</kbd> | <kbd>Cmd</kbd> + <kbd>O</kbd> | | Save File | <kbd>Ctrl</kbd> + <kbd>S</kbd> | <kbd>Cmd</kbd> + <kbd>S</kbd> | | Key Map | <kbd>Ctrl</kbd> + <kbd>K</kbd> | <kbd>Cmd</kbd> + <kbd>K</kbd> | | Quit | <kbd>Ctrl</kbd> + <kbd>Q</kbd> | <kbd>Cmd</kbd> + <kbd>Q</kbd> |