Project 15 (ecs04)

Feb 17, 2010

Objective

Get a taste of low-level programming in machine language and get acquainted with the Hack computer platform. In the process of working on this project, you will also become familiar with the assembly process, and you will appreciate visually how the translated binary code executes on the target hardware.

Resources

In this project you will use two tools supplied with the book: an assembler, designed to translate Hack assembly programs into binary code, and a CPU Emulator, designed to run binary programs on a simulated Hack platform.

About the Tools

The supplied assembler: The book's software suite includes a Hack assembler that can be used in either command mode or GUI mode. The latter mode of operation allows observing the translation process in a visual and step-wise fashion.

The machine language programs produced by the assembler can be tested in two different ways. First, one can run the .hack program in the CPU Emulator. Alternatively, one can run the same program directly on the hardware, by loading it into the computer’s instruction memory using the hardware simulator. Since we will complete building the hardware platform only in the next chapter, the former option makes more sense at this stage.

The supplied CPU Emulator: This program simulates the Hack computer platform. It allows loading a Hack program into the simulated ROM, and visually observing its execution on the simulated hardware.

For ease of use, the CPU Emulator enables loading binary .hack files as well as symbolic .asm files. In the latter case, the emulator translates the assembly program into binary code on the fly. This utility seems to render the supplied assembler unnecessary, but this is not the case. First, the supplied assembler shows the translation process visually, for instructive purposes. Second, the binary files generated by the assembler can be executed directly on the hardware platform. To do so, load the Computer chip (built in Project 5) into the hardware simulator, and then load the .hack file generated by the assembler into the computer’s ROM chip.

Note that you can also load a test script into the CPUEmulator that tests your .asm code, but the .tst scripts provided attempt to load a .hack file. Simply edit the .tst files to get the CPUEmulator to load your .asm file, automatically translate it into machine code, and run your test.

Requirements

Write and test the two programs described below. When executed on the CPU Emulator, your programs should generate the results mandated by the test scripts supplied in the project directory.

Program Function Comments

Mult.asm

Multiplication: The inputs of this program are the current values stored in R0 and R1 (i.e. the two top RAM locations). The program computes the product R0*R1 and stores the result in R2.

We assume (in this program) that R0 >= 0, R1 >= 0, and  R0*R1 < 32768. Your program need not test these conditions, but rather assume that they hold.  The supplied Mult.tst and Mult.cmp scripts will test your program on several representative data values.

Fill.asm

I/O handling: This program runs an infinite loop that listens to the keyboard input. When a key is pressed (any key), the program blackens the screen, i.e. writes "black" in every pixel. When no key is pressed, the screen should be cleared.

You may choose to blacken and clear the screen in any visual order, as long as pressing a key continuously for long enough will result in a fully blackened screen and not pressing any key for long enough will result in a cleared screen. This program has a test script (Fill.tst) but no compare file – it should be checked visually by inspecting the simulated screen.

Recommended Steps

First, read ECS chapter 4. You may find these additional slides helpful.

Within your src directory, create a subdir named project04. Extract the contents of project04.zip into it.

Add, commit and push the new files.

cd src/project04
git add *
git commit -m "Adding project04 files. Phhhttthlllbt!"
git push
  1. Use a (programmer-quality) text editor to write the first program in assembly, and save it as project04/mult/Mult.asm.
  2. Use the supplied assembler (in either batch or interactive mode) to translate your program. If you get syntax errors, edit your Mult.asm program. If there are no syntax errors, the assembler will produce a file called project04/mult/Mult.hack, containing binary machine instructions.
  3. Use the supplied CPU Emulator to test the resulting Mult.hack code. This can be done either interactively, or batch-style using the supplied Mult.tst script. If you get run-time errors, go to step 1.
  4. Repeat stages 2-4 for the second program (Fill.asm), which is in the project04/fill directory.

Alternative workflow (recommended):

  1. Edit Mult.tst, changing the file load directive from Mult.hack to Mult.asm. (Commit your change!)
  2. Use a (programmer-quality) text editor to write the first program in assembly, and save it as project04/mult/Mult.asm.
  3. Use the supplied CPU Emulator and Mult.tst to test the resulting (.hack) machine code, which it will automatically generate from your Mult.asm code. If you get run-time errors, go to step 2.
  4. Repeat stages 1-3 for the second program (Fill.asm), which is in the project04/fill directory.

Debugging Tip: The Hack language is case sensitive. A common error occurs when one writes, say, “@foo” and “@Foo” in different parts of the program, thinking that both commands refer to the same variable. In fact, the assembler treats these symbols as two completely different identifiers.

Grading Criteria (400 pts)

I must be able to pull your repo at 5PM on Monday, February 22 and I should see your project04 files.

Your repository must show a history of work. You should be committing every time you complete a chip. A repository log showing one commit with a message like "project04 done" is not acceptable.

This is due by 5PM on Monday, February 22.