Chip8Assembler
A Super Chip 8 assembler
Install / Use
/learn @craigthomas/Chip8AssemblerREADME
(Super) Chip 8 Assembler
Table of Contents
What is it?
This project is an XO Chip, Super Chip, and Chip 8 assembler written in Python 3.6. The assembler will take valid XO Chip, Super Chip, and Chip 8 assembly statements, and generate a binary file containing the correct machine instructions.
Requirements
In order to run the assembler, you will need to use Python 3.6 or greater. If you wish to clone the repository for development, you will need Git.
Installation
To install the source files, download the latest release from the releases section of the repository and unzip the contents in a directory of your choice. Or, clone the repository in the directory of your choice with:
git clone https://github.com/craigthomas/Chip8Assembler.git
Next, you will need to install the required packages for the file:
pip install -r requirements.txt
Usage
To run the assembler:
python assembler.py input_file --output output_file
This will assemble the instructions found in file input_file and will generate
the associated Chip 8 machine instructions in binary format in output_file.
Input Format
The input file needs to follow the format below:
LABEL MNEMONIC OPERANDS COMMENT
Where:
LABELis a 15 character label for the statementMNEMONICis a Chip 8 operation mnemonic from the Mnemonic Table belowOPERANDSare registers, values or labels, as described in the Operands sectionCOMMENTis a 30 character comment describing the statement (may have a#preceding it)
An example file:
# A comment line that contains nothing
clear CLR
start LOAD r1,$0 Clear contents of register 1
ADD r1,$1 Add 1 to the register
SKE r1,$A Check to see if we are at 10
JUMP start Jump back to the start
end JUMP end Loop forever
data FCB $1A One byte piece of data
data1 FDB $FBEE Two byte piece of data
Print Symbol Table
To print the symbol table that is generated during assembly, use the --symbols
switch:
python assembler.py test.asm --symbols
Which will have the following output:
-- Symbol Table --
0x0200 clear
0x0202 start
0x020A end
0x020C data
0x020E data1
Print Assembled Statements
To print out the assembled version of the program, use the --print switch:
python assembler.py test.asm --print
Which will have the following output:
-- Assembled Statements --
0x0200 0000 # A comment line that contains nothing
0x0200 00E0 clear CLR #
0x0202 6100 start LOAD r1,$0 # Clear contents of register 1
0x0204 7101 ADD r1,$1 # Add 1 to the register
0x0206 310A SKE r1,$A # Check to see if we are at 10
0x0208 1202 JUMP start # Jump back to the start
0x020A 120A end JUMP end # Loop forever
0x020C 001A data FCB $1A # One byte piece of data
0x020E FBEE data1 FDB $FBEE # Two byte piece of data
With this output, the first column is the offset in hex where the statement starts, the second column contains the full machine-code operand, the third column is the user-supplied label for the statement, the forth column is the mnemonic, the fifth column is the register values of other numeric or label data the operation will work on, and the fifth column is the comment string.
Mnemonic Table
The assembler supports mnemonics for both the Chip 8 and Super Chip 8 language specifications, as well as pseudo operations.
Chip 8 Mnemonics
| Mnemonic | Opcode | Operands | Description |
| -------- | ------ |:--------:|----------------------------------------------------------------------------|
| SYS | 0nnn | 1 | System call (ignored) |
| CLR | 00E0 | 0 | Clear the screen |
| RTS | 00EE | 0 | Return from subroutine |
| JUMP | 1nnn | 1 | Jump to address nnn |
| CALL | 2nnn | 1 | Call routine at address nnn |
| SKE | 3snn | 2 | Skip next instruction if register s equals nn |
| SKNE | 4snn | 2 | Do not skip next instruction if register s equals nn |
| SKRE | 5st0 | 2 | Skip if register s equals register t |
| LOAD | 6snn | 2 | Load register s with value nn |
| ADD | 7snn | 2 | Add value nn to register s |
| MOVE | 8st0 | 2 | Move value from register s to register t |
| OR | 8st1 | 2 | Perform logical OR on register s and t and store in t |
| AND | 8st2 | 2 | Perform logical AND on register s and t and store in t |
| XOR | 8st3 | 2 | Perform logical XOR on register s and t and store in t |
| ADDR | 8st4 | 2 | Add s to t and store in s - register F set on carry |
| SUB | 8st5 | 2 | Subtract s from t and store in s - register F set on !borrow |
| SHR | 8st6 | 2 | Shift bits in s 1 bit right, store in t - bit 0 shifts to register F |
| SHL | 8stE | 2 | Shift bits in s 1 bit left, store in t - bit 7 shifts to register F |
| SKRNE | 9st0 | 2 | Skip next instruction if register s not equal register t |
| LOADI | Annn | 1 | Load index with value nnn |
| JUMPI | Bnnn | 1 | Jump to address nnn + index |
| RAND | Ctnn | 2 | Generate random number between 0 and nn and store in t |
| DRAW | Dstn | 3 | Draw n byte sprite at x location reg s, y location reg t |
| SKPR | Es9E | 1 | Skip next instruction if the key in reg s is pressed |
| SKUP | EsA1 | 1 | Skip next instruction if the key in reg s is not pressed |
| MOVED | Ft07 | 1 | Move delay timer value into register t |
| KEYD | Ft0A | 1 | Wait for keypress and store in register t |
| LOADD | Fs15 | 1 | Load delay timer with value in register s |
| LOADS | Fs18 | 1 | Load sound timer with value in register s |
| ADDI | Fs1E | 1 | Add value in register s to index |
| LDSPR | Fs29 | 1 | Load index with sprite from register s |
| BCD | Fs33 | 1 | Store the binary coded decimal value of register s at index |
| STOR | Fs55 | 1 | Store the values of register s registers at index |
| READ | Fs65 | 1 | Read back the stored values at index into registers |
Super Chip 8 Mnemonics
| Mnemonic | Opcode | Operands | Description |
|----------| ------ |:--------:|----------------------------------------------|
| SCRD | 00Cn | 1 | Scroll down n lines |
| SCRR | 00FB | 0 | Scroll right 4 pixels |
| SCRL | 00FC | 0 | Scroll left 4 pixels |
| EXIT | 00FD | 0 | Exit interpreter |
| EXTD | 00FE | 0 | Disable extended mode |
| EXTE | 00FF | 0 | Enable extended mode |
|
