CHIP8IDE

Introduction

CHIP8IDE is an interactive development environment used to write programs for the CHIP-8 virtual machine.

CHIP-8 is a virtual machine architecture that was designed for a microcomputer kit released in 1977. Later in this article there is a history of that kit, the COSMAC VIP. It comprised a CPU chip, 4K of memory, a 16-button keypad, and an interface to drive a standard-def TV screen to display an array of white pixels on black.

The purpose of the CHIP-8 VM was to let hobbyists write game programs for their tiny kit computer in a simplified language, without having to learn all the details of the hardware. In the years since, many people have written emulators for the CHIP-8 so programs written for it could run on later hardware. This package contains an emulator for executing CHIP-8 code, and offers tools for entry, editing, assembly, disassembly, and debugging CHIP-8 programs.

The CHIP-8 machine is programmed using an assembly language. That means you program the hardware by writing individual machine instructions to manipulate binary values in the machine's registers and memory. To create output you write instructions that draw pixels on the screen. To get input you write instructions that read the state of the keypad buttons. You control the flow of execution by writing conditional jump instructions.

Although the CHIP-8 virtual machine has many fewer parts and instructions than a modern CPU, the experience of writing code for it is very similar to writing assembly code for a real CPU like the Intel Core i7, ARMv8, or RISC-V. Learning to write and debug CHIP-8 code is excellent preparation for writing assembly code for a real machine.

You can download self-contained executables of CHIP8IDE for Ubuntu, MacOS and Windows 7 at bit.ly/chip8ide.

There is a folder named extras included with CHIP8IDE. It contains binary and source programs, and these useful documents:

• An_Easy_Programming_System.pdf was a magazine article by the designer of CHIP-8. It clearly explains how the designer meant CHIP-8 to be used.

• COSMAC_VIP_Manual.pdf is part of the original manual that you would have received with your new microcomputer kit. It tells how to use CHIP-8 and gives a sense of what it was like to be a computer hobbyist forty years ago.

• assembler_reference.pdf is the documentation for the CHIP-8 assembly language. You will want to keep it handy whenever you are writing code.

Those documents provide a complete introduction to the CHIP-8 "machine" and how it is meant to be used. The rest of this document is about CHIP8IDE:

• User interface tells about the windows the app opens.

• Using the editor tells how to write, open, edit, assemble and save programs.

• Executing a program tells about viewing memory and registers and how to run and single-step programs.

• Display and keypad tells about using the emulated screen and keypad.

• History has more on the interesting history of CHIP-8 and SCHIP.

• Design summarizes the code modules of CHIP8IDE for readers.

• Sources acknowledges the many CHIP-8 internet sources that were plundered to make this app.

<a name="UI"></a>User interface

When you start it, CHIP8IDE opens three independent windows, the Edit window, the Memory window, and the Display window.

The Edit window contains a plain-text editor that you use to write or edit a CHIP-8 program. It supports all the usual editing keystrokes and operations. The Edit window also does syntax-checking and highlights any error statements. You can use the Edit window to set breakpoints so the machine stops when it reaches a certain statement. While you are single-stepping through a program, the Edit window highlights the source line that matches the next instruction to execute.

The Memory window displays the CHIP-8 machine memory and registers. It has the RUN/STOP button to start and stop execution, and a STEP button to execute a single instruction. When the machine is stopped you can see exactly what is in its memory and its registers. You can double-click on a memory byte or register and enter a new value in hexadecimal, and so alter the program or its execution.

The Display window contains the emulated screen output of the program as an array of square pixels. It has 32x64 pixels in CHIP-8 mode, or 64x128 pixels in SCHIP mode. (The program sets the mode when it executes.)

The Display window also presents the emulated 16-key keypad. When a program is running, it takes input from the keypad. The keys can be clicked with the mouse, or you can map keyboard keystrokes to the 16 keypad keys.

You can change the sizes and positions of the three windows. On a smaller screen you may want to overlap the Edit window and the Display window, because you rarely use them at the same time. The program remembers the window sizes and positions and restores them when it starts again.

<a name='ED'></a>Using the editor

You use the Editor to open programs, edit them, and load them into the emulated machine for execution.

Opening a source file

Start CHIP8IDE and select the File>Open command. Navigate to the extras folder that is distributed with the program. Navigate inside it to the source folder and open the file draw_the_key.asm. Now you are looking at a short CHIP-8 program in its source form. It consists of assembler language statements, comments, and white-space.

In the docs folder find the assembler_reference.pdf file and open it in another window. Read the text under the heading Statements. You can see examples of statements now in the Edit window.

Editing

In the Edit window, experiment with the normal edit keys for your system. You will find that you can edit this text with the same keys, like cut, copy and paste, and the same mouse actions, that you would use with NotePad on Windows, TextEdit on MacOS, or gedit on Linux.

You can also select text and drag it, and you can drag text from other apps and drop it on this window. That means if you have a favorite editor, you can use it when writing a longer program. Then just select the program text and paste it, or drag it, into the Edit window.

There is a Find/Replace dialog that comes up when you key control-f (command-f on Mac). After you find something with the dialog you can use these keys:

• Find next: control-g (command-g)
• Find previous: shift-control-g (shift-command-g)
• Replace: control-= (command-=)
• Replace and find again: control-t (command-t)

Assembling and errors

If you have changed the file while you were experimenting, get a fresh copy by opening draw_the_key.asm. (Do not save if CHIP8IDE asks if you want to save the modified file!)

Click the CHECK button below the Edit window. This button tells CHIP8IDE to assemble the statements (convert them into their binary executable form).

Now that you have assembled the program, CHIP8IDE can show you its binary form in the Edit window. Using the mouse or the arrow keys, move to different lines of the program in the Edit window. The address of each instruction and its binary form are displayed in hexadecimal below the window.

Let's make an error. On the first instruction, LD I, QUERY, change the opcode LD to LX which is not a recognized opcode. Hit the down-arrow to move to the next line. When the cursor leaves that line, the line turns red. The red color tells you that statement has some kind of error.

Move the cursor back onto the line. Below the window is the error message "Statement does not make sense". That is the general error statement used when some part of a statement can't be recognized. In this case, the assembler does not recognize LX as any sort of opcode or expression.

Change LX back to LD and move away from that line; it is no longer red. Go back and insert a plus sign after QUERY so it reads QUERY+. Move away again; the line is red. Move back; the error message is "Invalid expression near 7". Put the cursor at the left margin and hit the right-arrow 7 times to see where the invalid expression begins.

Without fixing the error, click the CHECK button. You get an error dialog telling you there is a "format" error, that is, an error in the format of some statement. Fix the error by removing that plus sign, and click CHECK again. Now the assembly completes without any messages.

Some errors cannot be recognized while you are entering or editing statements. They are only found at assembly time. Near the bottom of the program, change the label QUERY: to read QUERYX: (or anything that is not QUERY:). Move the cursor away from that line: it is not red, so there is nothing wrong with the form of that statement or any other.

Click the CHECK button and a message box tells you there is one "expression error" to correct. Click OK, and note that the LD I, QUERY statement is now red. What could be wrong with it? Click in that line and you see the error message "Symbol 'QUERY' is undefined". This statement refers to a name QUERY that ought to be defined on some other line. But it isn't! This is an error that should be easy to fix. Fix it and click CHECK again to verify that the program is good.

When you are writing a large program and CHECK reports errors, you can use the key control-e (command-e). This makes the Editor skip directly to the next line that has an error.

The Edit window has one more useful key, but it is explained in the next section.

Opening a binary file

You have been working with a source file, a text file with assembly language statements and (hopefully) comments. However, most CHIP-8 programs on the internet are binary files that contain only CHIP-8 instructions in their assembled form as binary bytes. CHIP8IDE can open these, too.

Select File>Open. (You have modified the draw_the_key.asm file, so you are asked if you want to save it. Say no!)

Navigate into