This project has intermediate milestones that are relevant to your grade.
Develop an assembler that translates programs written in Hack assembly language into the binary code understood by the Hack hardware platform. The assembler must implement the Translation Specification described in Chapter 6, Section 2.
The only tool needed for completing this project is the programming language in which you will implement your assembler. You may also find the following two tools useful: the Assembler and CPU Emulator supplied with the book. These tools allow you to experiment with a working assembler before you set out to build one yourself. In addition, the supplied assembler provides a visual line-by-line translation GUI, and allows online code comparisons with the outputs that your assembler will generate. For more information about these capabilities, refer to this Assembler Tutorial.
When loaded into your assembler, a Prog.asm file containing a valid Hack assembly language program should be translated into the correct Hack binary code and stored in a Prog.hack file. The output produced by your assembler must be identical to the output produced by the assembler supplied with the book.
Build the assembler in two stages. First write a symbol-less assembler, i.e. an assembler that can only translate programs that contain no symbols. Then extend your assembler with symbol handling capabilities. The test programs that are supplied for this project come in two such versions (without and with symbols), to help you test your assembler incrementally.
Each test program except the first one comes in two versions: ProgL.asm is symbols-less, and Prog.asm is with symbols.
| Program | Description | Symbol-less version |
|
Adds the constants 2 and 3 and puts the result in R0. |
||
|
Computes max(R0,R1) and puts the result in R2. |
||
|
Draws a rectangle at the top left corner of the screen. The rectangle is 16 pixels wide and R0 pixels high. |
||
|
A single-player ping-pong game. A ball bounces constantly off the screen's “walls.” The player attempts to hit the ball with a bat by pressing the left and right arrow keys. For every successful hit, the player gains one point and the bat shrinks a little to make the game harder. If the player misses the ball, the game is over. To quit the game, press ESC. |
The Pong program was written in the Jack programming language (Chapter 9) and translated into the supplied assembly program by the Jack compiler (Chapters 10-11). Although the original Jack program is only about 300 lines of code, the executable Pong application is about 20,000 lines of binary code, most of which being the Jack operating system (Chapter 12). Running this interactive program in the CPU emulator is a slow affair, so don't expect a high-powered Pong game. This slowness is actually a virtue, since it enables your eye to track the graphical behavior of the program. In future projects in the book this game will run much faster.
The supplied assembler: The practice of using the supplied assembler (which is guaranteed to produce correct binary code) to test another assembler (which is not necessarily correct) is illustrated in the following screen shot and explanation.
First, read ECS chapter 6. Then, you should also quickly read these additional slides and this Assembler Tutorial.
Next, choose a language with which you will build your assembler. I recommend a scripting language such as Ruby, Python or Perl. You may use any language you want. Java? Fine. C#? Fine. C/C++? Ok. Lua? Fine. Haskell? Fine. Clojure? Ok. Scheme? Fine. Erlang? Well, ok. Perl? Sure. Bash script with sed, awk, etc? Ok. Important: choosing a language because "that's what's installed on my computer" is a terrible reason; read ECS chapter 6 and choose with intent. Ultimately, you are responsible for installing, learning about, and being productive with the language that you choose.
Within your src directory, create a subdir named project06. Extract the contents of project06.zip into it.
Add, commit and push the new files.
Write and test your assembler program in the two stages described above. You should use the assembler supplied with the book to compare the output of your assembler to the correct output. This testing procedure is described next. For more information about the supplied assembler, refer to the Assembler Tutorial.
Let Prog.asm be some program written in Hack assembly. Suppose that we translate this program using the supplied assembler, producing a binary file called Prog.hack. Next, we use your assembler to translate the same program into another file, say Prog.mine.hack. Now, if your assembler is working correctly, it follows that Prog.hack = Prog.mine.hack. Thus, one way to test a newly written assembler is to load Prog.asm into the supplied assembler program, load Prog.mine.hack as a compare file, and then translate and compare the two binary files (see Figure 6.3). If the comparison fails, the your assembler that produced Prog.mine.hack must be buggy; otherwise it may be OK.
Stick to the milestones below; the first few milestones are not time-intensive.
Use regular expressions when analyzing assembly instructions.
| Due Date | Points | Description | Grading Criteria |
|---|---|---|---|
| March 2 @ 6:00AM (do it Monday!) |
100 | Choose a language | I must receive an email telling me what language you intend to use. |
| March 3 @ 6:00AM (do it Tuesday!) |
100 | File I/O | You must commit & push an early version of your simple 'driver' program. At this stage it should just open the .asm file for reading and open a .hack file, ready for writing. |
| March 4 @ 6:00AM (do it Wednesday!) |
100 | Stub out the API | You must commit & push all files relevant to your program. These files should define the classes, class methods, functions, etc necessary for your assembler to function. The API is specified in ECS chapter 6. Your code should be well-commented per the book's API description (code without comments will receive a 0). You do not have to implement the API, just define it. |
| March 5 @ 5:00PM | 200 | Symbol-less Assembler | You must commit & push the first version of your assembler. It should pass a manual comparison of Add.hack, MaxL.hack, and RectL.hack, PongL.hack. |
| March 8 @ 5:00PM | 200 | Full Assembler | You must commit & push the final version of your assembler. It should pass a manual comparison of Max.hack, Rect.hack, and Pong.hack. |
| n/a | extra credit | Share snippets | Share your gists containing regular expressions, code snippets (eg, opening & writing to files), helpful libraries, etc by posting links to your gists on the forum. |
Your repository must show a history of work. You should be committing every time you complete a milestone (per the ones above or your own intermediate milestones). A repository log showing one commit with a message like "project done" is not acceptable.