Added everything

README.md

@@ -1,4 +1,53 @@
-fpg8
-====
+# FPG-8
+FPG-8 is an implementation of Chip-8/S-Chip language for FPGAs using Verilog.
 
-Chip-8/S-Chip implementation in Verilog
+It was developed as a project for the [ECE-574] course at [Worcester Polytechnic Institute].
+
+It definitelly is not the fastest or more optimized implementation, but it works pretty well.
+
+It was written for the [Nexys 3] board, but should work well on other boards.
+
+All the interaction with the system is done through the USB serial port and the game output is shown on a VGA display. Sound is generated using the [Digilent DA1 Module] connected to pins 1-6 of the PmodA port of the Nexys 3.
+
+### Binaries
+If you don't care about all the nerdy stuff in the following sections, you can simply download the [binaries]. The binary distribution contains the Java application compiled in a JAR file and a bit file to program your board using, for example, [Adept].
+
+### Verilog and C code
+The complete Verilog code is available under the **verilog** folder. It was developed using the ISE tools from Xilinx. It uses some cores from the IP Core Generator, specially the [Microblaze] microcontroller that handles the serial communication.
+
+The Microblaze is programmed in C and the source is available under the **c** folder. [Here]'s an excelent tutorial about how to merge the C code into the bit file before programming the FPGA.
+
+### Java code
+It's impossible to play games typing commands to a serial port, so I wrote a Java application that uses the serial port to load the games, capture user input and also control the debugger. The complete code is under the **java** folder. It uses Maven to handle dependencies, except for the [SteelCheckbox], that is not available on the Maven Repository.
+
+The application searches for games under the **games** folder on the application's directory. Games are stored in a ZIP file containing a `rom.ch8` file that is the Chip-8 ROM, a `logo.png` file that contains a 80x80 picture that is shown on the menu on the left, a `screenshot.png` file that contains a 510x253 picture that is shown on the center when the came is selected and a `description.json` file that contains some information about the game in [JSON] format. The `slowdown` should not be greater than 65535, because it's a 16-bit number. The `mapping` parameter maps the Chip-8 keyboard to your keyboard. Any letter is valid and also the special values `arrow-up`, `arrow-down`, `arrow-left`, `arrow-right`, `ctrl`, `alt`, `shift`, `enter` and `space`.
+
+After days of Verilog development, I really wanted to play some games, so this application was written very fastly. It can't handle board disconnections, permission errors or any other thing your evil mind can think of.
+
+### ASM code
+I included the source for a simple application I wrote to test some opcodes of my implementation. It's available under the **asm** folder. It can be assembled by the [Mochi8 Assembler].
+
+There is also a program that writes "Thank You!" on the screen, that I used in the end of the project presentation.
+
+### Docs
+Under the **docs** folder there are the slides I used for the presentation of this project.
+
+In a few days I'll upload the report that describes the implementation and can also be used as a complete documentation for the Chip-8/S-Chip language.
+
+### Miscelaneous
+Under the **misc** folder you can find a OpenOffice Calc spreadsheet that I created to help me drawing the font for the "Thank You" program.
+
+### Acknowledgements
+I'd like to thank **Professor R. James Duckworth** for the great VHDL/Verilog course and the opportunity to develop this project and **Boyang Li** for being a great TA.
+
+[binaries]: https://github.com/guimeira/fpg8/releases
+[Adept]: http://www.digilentinc.com/Products/Detail.cfm?NavPath=2,66,69&Prod=ADEPT&CFID=6114451&CFTOKEN=b4315c79c33731b4-0CDF65D2-5056-0201-0284F3BE6330CA60
+[ECE-574]: http://ece.wpi.edu/~rjduck/ece574.htm
+[Worcester Polytechnic Institute]: http://www.wpi.edu
+[Nexys 3]: http://www.digilentinc.com/Products/Detail.cfm?NavPath=2,400,897&Prod=NEXYS3
+[Digilent DA1 Module]: http://www.digilentinc.com/Products/Detail.cfm?Prod=PMOD-DA1
+[Microblaze]: http://www.xilinx.com/tools/microblaze.htm
+[Here]: http://ece.wpi.edu/~rjduck/Microblaze%20MCS%20Tutorial%20v5.pdf
+[SteelCheckbox]: http://harmoniccode.blogspot.com/2010/11/friday-fun-component-iii.html
+[JSON]: http://json.org/
+[Mochi8 Assembler]: http://mochi8.weebly.com/

asm/testfixture.asm

@@ -0,0 +1,116 @@
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;This program is written in the Chip-8 assembly language and is used to test    ;
+;the Verilog implementation through a test fixture.                             ;
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+;==Test the clear screen function==
+CLS
+
+;==Test the function calls, jumps and returns==
+CALL TEST_CALL
+JP TEST_JMP
+JMP_RETURN: JP CONTINUE_TEST
+
+TEST_CALL: RET
+
+TEST_JMP: JP JMP_RETURN
+
+CONTINUE_TEST:
+;==Test skip functions==
+LD V1,10
+SE V1,10
+LD V2,5 ;should be skipped
+SE V1,20
+LD V2,50 ;should be executed
+SNE V2,0
+LD V3,4 ;should be skipped
+SNE V2,50
+LD V3,65 ;should be executed
+LD V8,0
+LD V9,0
+SE V8,V9
+LD V8,29 ;should be skipped
+SE V8,V1
+LD V8,10 ;should be executed
+SNE V8,V1
+LD V8,23 ;should be skipped
+SNE V8,V1
+LD V8,90 ;should be executed
+
+;==Test arithmetic==
+LD V1,0
+ADD V1,209
+LD V2,53
+OR V1,V2
+AND V1,V2
+XOR V1,V2
+LD V1,50
+LD V2,60
+ADD V1,V2 ;add without carry
+LD V1,200
+LD V2,100
+ADD V1,V2 ;add with carry
+LD V1,100
+LD V2,40
+SUB V1,V2 ;sub without borrow
+LD V1,40
+LD V2,100
+SUB V2,V1 ;sub with borrow
+LD V1,100
+LD V2,40
+SUBN V1,V2 ;subn with borrow
+LD V1,40
+LD V2,100
+SUBN V1,V2 ;subn without borrow
+LD V1,2
+SHR V1
+SHR V1
+SHL V1
+SHL V1
+
+;==Test data transfer between regs==
+LD V1,100
+LD V0,20
+LD V1,V0
+LD I,123
+ADD I,V1
+LD V1,5
+LD F,V1
+
+;==Test data transfer to memory and BCD function==
+LD V1,200
+LD I,200
+ADD I,V1
+LD V1,124
+LD B,V1
+LD V2,[I] ;read BCD results to V0,V1,V2
+LD [I],VF ;store all registers
+LD V0,0
+LD V1,0
+LD V2,0
+LD V3,0
+LD V4,0
+LD V5,0
+LD V6,0
+LD V7,0
+LD V8,0
+LD V9,0
+LD VA,0
+LD VB,0
+LD VC,0
+LD VD,0
+LD VE,0
+LD VF,0
+LD VF,[I] ;restore all registers from memory
+
+;==Invoke screen scrolling functions==
+SCD 3
+SCR
+SCL
+
+;==Change screen mode==
+HIGH
+LOW
+
+;==Exit==
+EXT

asm/thankyou.asm

@@ -0,0 +1,207 @@
+;This little program writes "thank you" on the screen.
+
+HIGH
+LD V0,24
+LD V1,16
+LD I,LETTER_T
+DRW V0,V1,0
+ADD V0,16
+
+LD I,LETTER_H
+DRW V0,V1,0
+ADD V0,16
+
+LD I,LETTER_A
+DRW V0,V1,0
+ADD V0,16
+
+LD I,LETTER_N
+DRW V0,V1,0
+ADD V0,16
+
+LD I,LETTER_K
+DRW V0,V1,0
+ADD V0,16
+
+ADD V1,20
+LD V0,32
+
+LD I,LETTER_Y
+DRW V0,V1,0
+ADD V0,16
+
+LD I,LETTER_O
+DRW V0,V1,0
+ADD V0,16
+
+LD I,LETTER_U
+DRW V0,V1,0
+ADD V0,16
+
+LD I,EXCLAMATION_POINT
+DRW V0,V1,0
+ADD V0,16
+
+LOOP: JP LOOP
+
+LETTER_T:
+DB $01111111, $11111110
+DB $01111111, $11111110
+DB $01100011, $11000110
+DB $01000011, $11000010
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00001111, $11110000
+
+LETTER_H:
+DB $01111100, $00111110
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111111, $11111100
+DB $00111111, $11111100
+DB $00111111, $11111100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $01111100, $00111110
+
+LETTER_A:
+DB $00000011, $11000000
+DB $00000111, $11100000
+DB $00001110, $01110000
+DB $00011100, $00111000
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111111, $11111100
+DB $00111111, $11111100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $01111100, $00111110
+
+LETTER_N:
+DB $01111000, $00111110
+DB $00111000, $00011100
+DB $00111100, $00011100
+DB $00111110, $00011100
+DB $00111110, $00011100
+DB $00111011, $00011100
+DB $00111011, $00011100
+DB $00111001, $10011100
+DB $00111001, $10011100
+DB $00111000, $11011100
+DB $00111000, $11011100
+DB $00111000, $01111100
+DB $00111000, $01111100
+DB $00111000, $00111100
+DB $00111000, $00111100
+DB $01111100, $00011110
+
+LETTER_K:
+DB $01111100, $00011110
+DB $00111000, $00001100
+DB $00111000, $00011100
+DB $00111000, $00111000
+DB $00111000, $01110000
+DB $00111000, $11100000
+DB $00111011, $11000000
+DB $00111111, $10000000
+DB $00111111, $00000000
+DB $00111111, $10000000
+DB $00111011, $11000000
+DB $00111000, $11100000
+DB $00111000, $01110000
+DB $00111000, $00111000
+DB $00111000, $00011000
+DB $01111100, $00111100
+
+LETTER_Y:
+DB $01111100, $00111110
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00011100, $00111000
+DB $00001110, $01110000
+DB $00000111, $11100000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000111, $11100000
+
+LETTER_O:
+DB $00000011, $11000000
+DB $00001111, $11110000
+DB $00111111, $11111100
+DB $01111000, $00011110
+DB $01110000, $00001110
+DB $01110000, $00001110
+DB $01110000, $00001110
+DB $01110000, $00001110
+DB $01110000, $00001110
+DB $01110000, $00001110
+DB $01110000, $00001110
+DB $01110000, $00001110
+DB $01111000, $00011110
+DB $00111111, $11111100
+DB $00001111, $11110000
+DB $00000011, $11000000
+
+LETTER_U:
+DB $01111100, $00111110
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00111000, $00011100
+DB $00011100, $00111000
+DB $00001111, $11110000
+DB $00000111, $11100000
+
+EXCLAMATION_POINT:
+DB $00000011, $11000000
+DB $00000111, $11100000
+DB $00001111, $11110000
+DB $00011111, $11111000
+DB $00001111, $11110000
+DB $00001111, $11110000
+DB $00000111, $11100000
+DB $00000111, $11100000
+DB $00000011, $11000000
+DB $00000011, $11000000
+DB $00000001, $10000000
+DB $00000001, $10000000
+DB $00000000, $00000000
+DB $00000001, $10000000
+DB $00000011, $11000000
+DB $00000001, $10000000