Skip to content

Commit ca4604c

Browse files
mattmikolaymattmikolay
committed
Add manual in Markdown format
1 parent 98b27bc commit ca4604c

File tree

1 file changed

+196
-0
lines changed

1 file changed

+196
-0
lines changed

‎MANUAL.md

+196
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# chasm Manual
2+
Version 1.0
3+
4+
Originally released December 2010
5+
6+
Converted to Markdown November 2016
7+
8+
## Introduction
9+
CHIP-8 is an interpreted programming language initially developed by Joseph
10+
Weisbecker for the COSMAC VIP computer in 1977. Created to simplify the
11+
programming of video games, CHIP-8 was popular and portable for the computers of
12+
its generation. As a result, a variety of games have been developed in the
13+
CHIP-8 language.
14+
15+
CHIP-8 allows graphical output to a sixty-four by thirty-two monochrome pixel
16+
display. One sound timer triggers the playing of a monotone frequency, and one
17+
delay timer can be used for scheduling. A sixteen-key hexadecimal keypad is used
18+
for input. Sixteen eight-bit data registers can be used to store data, and the
19+
sixteen-bit address register can be used to store a memory address.
20+
21+
The portability of the CHIP-8 language is due to the fact that it is an
22+
interpreted hexadecimal language. All CHIP-8 instructions are hexadecimal
23+
numbers and can be easily stored and read in memory. However, programming in
24+
CHIP-8 has often been perceived as a difficult task due to this hexadecimal
25+
format, as the purpose of each instruction in a program is not immediately
26+
evident. Because of this, the need for a CHIP-8 pseudo-assembler arises.
27+
28+
The CHIP-8 language is an interpreted programming language, as its instructions
29+
are read by an interpreting program, which then executes corresponding code on
30+
the host computer. chasm presents the CHIP-8 language to a programmer using a
31+
system of easy-to-read and remember mnemonics, which are then translated into
32+
the traditional interpreted CHIP-8 opcodes. Because the chasm mnemonics are
33+
translated into an interpreted language rather than a machine language, chasm is
34+
known as a pseudo-assembler instead of a regular assembler.
35+
36+
Although this difference may be important, it over-complicates the matters that
37+
this manual concerns. Therefore, the mnemonic language used by chasm will be
38+
identified as assembly language from this point on, and the interpreted
39+
programming language that chasm outputs will be identified as machine language
40+
or machine code.
41+
42+
## Features
43+
chasm is a pseudo-assembler for the CHIP-8 programming language. It was designed
44+
to accept a text file containing 'assembly language' mnemonics as input, and
45+
output the resulting CHIP-8 'machine code' to a separate file.
46+
47+
Version 1.0 of chasm supports all thirty-five original CHIP-8 commands defined
48+
by Joseph Weisbecker for the COSMAC VIP computer.
49+
50+
chasm also supports an additional command called the `.START` command, used to
51+
specify the memory address at which the resulting CHIP-8 program should be
52+
loaded on the host machine. This designated value is used by chasm to determine
53+
the values of label addresses during the label linking process. Although the
54+
`.START` command is completely optional, it should be the first command found in
55+
the input file when present.
56+
57+
chasm supports two other commands, the `DB` and `DW` commands, which accept an
58+
8-bit value and a 16-bit value respectively as arguments. These commands insert
59+
the given argument into the generated output code at the corresponding address,
60+
and can be used to insert graphics data into CHIP-8 assembly source code.
61+
62+
## Supported instructions
63+
* Code in { } brackets designate optional parameters for an instruction.
64+
* Vx and Vy are register names, kk is a byte, nnn is an address, n is a
65+
nibble.
66+
67+
| Opcode | Mnemonic |
68+
| :----: | :----------------------- |
69+
| 00E0 | CLS |
70+
| 00EE | RET |
71+
| 0nnn | SYS (addr) |
72+
| 1nnn | JP (addr) |
73+
| 2nnn | CALL (addr) |
74+
| 3xkk | SE (Vx), (byte) |
75+
| 4xkk | SNE (Vx), (byte) |
76+
| 5xy0 | SE (Vx), (Vy) |
77+
| 6xkk | LD (Vx), (byte) |
78+
| 7xkk | ADD (Vx), (byte) |
79+
| 8xy0 | LD (Vx), (Vy) |
80+
| 8xy1 | OR (Vx), (Vy) |
81+
| 8xy2 | AND (Vx), (Vy) |
82+
| 8xy3 | XOR (Vx), (Vy) |
83+
| 8xy4 | ADD (Vx), (Vy) |
84+
| 8xy5 | SUB (Vx), (Vy) |
85+
| 8xy6 | SHR (Vx) {, (Vy)} |
86+
| 8xy7 | SUBN (Vx), (Vy) |
87+
| 8xyE | SHL (Vx) {, (Vy)} |
88+
| 9xy0 | SNE (Vx), (Vy) |
89+
| Annn | LD I, (addr) |
90+
| Bnnn | JP V0, (addr) |
91+
| Cxkk | RND (Vx), (byte) |
92+
| Dxyn | DRW (Vx), (Vy), (nibble) |
93+
| Ex9E | SKP (Vx) |
94+
| ExA1 | SKNP (Vx) |
95+
| Fx07 | LD (Vx), DT |
96+
| Fx0A | LD (Vx), K |
97+
| Fx15 | LD DT, (Vx) |
98+
| Fx18 | LD ST, (Vx) |
99+
| Fx1E | ADD I, (Vx) |
100+
| Fx29 | LD F, (Vx) |
101+
| Fx33 | LD B, (Vx) |
102+
| Fx55 | LD [I], (Vx) |
103+
| Fx65 | LD (Vx), [I] |
104+
| N/A | .START (addr) |
105+
| N/A | DB (byte) |
106+
| N/A | DW (word) |
107+
108+
## Example output
109+
The following table contains a side-by-side comparison of two files: input.asm,
110+
a text file containing assembly language mnemonics, and output.c8, a data file
111+
containing corresponding CHIP-8 machine language opcodes. Each line (or lines)
112+
of input.asm has its corresponding CHIP-8 opcode printed directly adjacent under
113+
the output.c8 column. input.asm is printed as if viewed in a standard ASCII text
114+
editor, and output.c8 is printed as if viewed in a hexadecimal editor with a
115+
byte-span value of 2. It should be noted that CHIP-8 commands are stored using
116+
big-endian mode, with the most-significant byte first and the least-significant
117+
byte last.
118+
119+
----- input.asm ----- --- output.c8 ---
120+
START: CLS 00E0
121+
RND V0, #FF C0FF
122+
LD I, #224 A224
123+
LD B, V0 F033
124+
LD V2, [I] F265
125+
LD F, V0 F029
126+
LD V0, #00 6000
127+
LD V3, #00 6300
128+
DRW V0, V3, 5 D035
129+
LD F, V1 F129
130+
LD V0, #05 6005
131+
DRW V0, V3, 5 D035
132+
LD F, V2 F229
133+
LD V0, 10 600A
134+
DRW V0, V3, 5 D035
135+
LD V0, K F00A
136+
JP START 1200
137+
138+
DB #FF FFEA
139+
DB #EA
140+
141+
DW #21AC 21AC
142+
143+
## Proper usage
144+
chasm accepts two files: an input file and an output file. The lines stored in
145+
the input file are read and converted into corresponding CHIP-8 code, which is
146+
then stored in the output file. If an error occurs while opening either the
147+
input or output file, an error message is displayed to the user.
148+
149+
The proper syntax for chasm is:
150+
151+
chasm [input filename] [output filename]
152+
153+
If this syntax is not followed, an error message, along with the guidelines for
154+
the proper syntax, are displayed to the user.
155+
156+
## Design description
157+
### Initialization
158+
Upon startup, chasm checks to make sure the correct amount of command line
159+
arguments were entered and processes them accordingly. chasm is called with the
160+
following syntax:
161+
162+
chasm [input filename] [output filename]
163+
164+
chasm attempts to open the file passed by the user as input.
165+
166+
### Input processing
167+
chasm processes the assembly language commands found in the input file by
168+
looping through the file and processing each individual line, separating it into
169+
sections called "arguments." An argument is any part of an assembly command. The
170+
following diagram provides an example:
171+
172+
| Argument 0 | Argument 1 | | Argument 2 |
173+
|:----------:|:----------:|:-:|:----------:|
174+
| LD | F | , | V0 |
175+
176+
While separating each line into arguments, chasm checks if a label has been
177+
included. If one is found, a label is created, and the corresponding argument is
178+
removed from the argument array. This allows processing of the line to continue
179+
regardless of the created label.
180+
181+
After the line has been separated into arguments and any present labels have
182+
been removed, chasm begins processing the arguments and generating the resulting
183+
machine code. If an error is found in the syntax of the arguments, or the
184+
assembler undergoes an error, relevant information is printed to the screen.
185+
186+
### Label linking
187+
After the entire input file has been processed, any references to labels made by
188+
assembly language commands will have been stored in a label reference array.
189+
chasm loops through this array, checking to make sure that each label referenced
190+
actually exists, and linking the identified labels with their corresponding
191+
memory addresses.
192+
193+
### File output
194+
chasm has now finished generating machine code corresponding to the assembly
195+
instructions found in the input file. This machine code is sent to the
196+
designated output file for storage, and the program reaches completion.

0 commit comments

Comments
 (0)