Project 4: Machine Language & Annotation

Due 11:59pm Tuesday, April 28

Part 0: Get the Starter Materials

To complete this assignment, you will need to use git to access the starter materials that have been pushed to your repository by the course staff. First, run git status and see if it reports any changes. If you have any, you'll need to commit them before proceeding (git add . followed by git commit -m "Your message here"). Then, run:

• git pull (download any commits on the Gitlab server to your local repository)

After running that command, you have synchronized the local copy of your repo with the copy on the server. Very rarely, you may get a "merge conflict" where git can't automatically figure out how to combine the changes we pushed to the server. If that happens, feel free to email the staff list to resolve the issue.

Part I: Annotation

This week’s project requires you to read Chapter 4 of the textbook. As you are reading the chapter, complete the following:

1. Use at least three (3) of the strategies listed on the Annotating a Text handout. When you come to class on Thursday, please be prepared to share your annotations in small groups. You will be asked to explain your annotation choices as well as discuss which strategies helped you retain information the most.
2. Identify at least five (5) key points and complete the Annotation Worksheet in your repo (projects/4/annotation.docx). For each key point, include the following components:
   • A definition of what the key point or idea is in your own words.
   • An example that represents this idea and how it may show up in the real world
   • The annotation strategies that you utilized that will allow you to quickly refer back to the specific section of the text in which it discusses the key idea
   • The page number where the chapter references the key idea
   • Commentary that addresses how the key point is significant. Why should we care about this idea? How does this idea connect with other elements of the class or project?

After reading the chapter, include at the bottom of the Annotation Worksheet any lingering questions you still have. What aspects of the chapter are still confusing or unclear? More importantly, what steps will you need to take in order to address your questions?

In addition to completing the annotation worksheet for this course’s required chapter readings, identify a different course that you are currently enrolled in that includes readings. For your course’s readings, you will complete its own Annotation Worksheet and repeat the process that you did for Chapter 4 of CSE 390B. If the other classes that you are enrolled in do not have any readings (neither required or supplemental), please contact the CSE 390B staff (cse390b-staff@cs.uw.edu) to discuss an alternative option.

Edit the Annotation Worksheet "in-place" and submit by pushing to Gitlab.

Part II: Machine Language

Background

Every hardware platform is designed to execute commands in a certain machine language, expressed using agreed-upon binary codes. Writing programs directly in binary code is a possible, yet unnecessary. Instead, we can write such programs using a low-level symbolic language, called assembly, and have them translated into binary code by a program called assembler. In this project you will write some low-level assembly programs, and will be forever thankful for high-level languages like Java and Python. (Actually, assembly programming can be highly rewarding, allowing direct and complete control of the underlying machine.)

Overview

This project will be a brief departure from building chips — instead, you will act as a client of the computer and write code in a low-level machine language to execute. The purpose of this project is to familiarize yourself with the capabilities that the computer will provide to its programmer; later, when you build the computer hardware itself, you will draw on this project to understand why each feature exists.

You will write and test the following programs:

Program	Description	Guidelines / Tests
Mult.asm	Multiplication: in the Hack computer, the top 16 RAM words (RAM[0]...RAM[15]) are also referred to as R0...R15. With this terminology in mind, this program computes the value R0*R1 and stores the result in R2. The program assumes that R0>=0, R1>=0, and R0*R1<32768. Your program need not test these conditions, but rather assume that they hold.	Use a text editor to write your Mult.asm program using the Hack assembly language. Use the supplied Hack Assembler to translate your Mult.asm program, producing a Mult.hack file containing binary Hack instructions. Next, load the supplied Mult.tst script into the CPU Emulator. This script loads the Mult.hack program, and executes it. Run the script. If you get any errors, debug and edit your Mult.asm program. Then assemble the program, re-run the Mult.txt script, etc.
Fill.asm	I/O Handling: this program illustrates low-level handling of the screen and keyboard devices, as follows. The 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; the screen should remain fully black as long as the key is pressed. When no key is pressed, the program clears the screen, i.e. writes "white" in every pixel; the screen should remain fully clear as long as no key is pressed. Implementation note: your program may blacken and clear the screen's pixels in any spatial/visual order, as long as pressing a key continuously for long enough results in a fully blackened screen, and not pressing any key for long enough results in a fully cleared screen.	Write, test, and debug your Fill.asm program by following the same guidelines given above for the Mult program. The supplied Fill.tst script, which comes with no compare file, is designed to do two things: (i) load the Fill.hack program, and (ii) remind you to select 'no animation', and then test the program interactively by pressing and releasing some keyboard keys. The supplied FillAutomatic.tst script, along with the supplied compare file FillAutomatic.cmp, are designed to test the Fill program automatically, as described by the test script documentation. For completeness of testing, it is recommended to test the Fill program both interactively and automatically.

Contract

Write and test the two programs described above. When executed on the supplied CPU emulator, your programs should generate the results mandated by the specified tests.

Resources

To complete this assignment, you will need to read the specification of the Hack assembly language in Chapter 4.

In the tools directory of your repo, you will need to use 2 new tools. One is the Assembler tool, which converts Hack assembly language (.asm) to Hack binary code (.hack). You will also need the CPUEmulator tool, which loads .hack files and allows you to step through, examine the state of the emulated computer, and run test scripts. Note the CPUEmulator can theoretically be used to load and run a .asm file directly (implicitly assembling it), but the test scripts always load the underlying .hack file on disk which is produced by the Assembler. Therefore, we recommend you always use the Assembler to convert from .asm to .hack before emulating so as to avoid inconsistent results between the file you're seeing in the CPUEmulator and what the test script is evaluating on.

We recommend familiarizing yourself with the tools through experimentation, but if you'd prefer a more structured way to learn about their features you can check out the Assembler Tutorial (PPTX, PDF) and CPUEmulator Tutorial (PPTX, PDF) developed by the Nand2Tetris project.

Tips

The supplied Hack Assembler can be used in either command mode (from the command shell), or interactively. Both allow creating a persistent .hack file on disk for your .asm code. The latter mode of operation allows observing the translation process in a visual and step-wise fashion, as shown below:

The supplied CPU Emulator includes a ROM (also called Instruction Memory) representation, into which the binary code is loaded, and a RAM representation, which holds data. For ease of use, the emulator enables the user to view the loaded ROM-resident code in either binary mode, or in symbolic / assembly mode. In fact, the CPU emulator even allows loading symbolic code written in assembly directly into the ROM, in which case the emulator translates the loaded code 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 assembler generates a persistent binary file. This file can be executed either on the CPU emulator, as shown below, or directly on the hardware platform, as we'll do in the next project.

Part III: Assembly Language Reflection

Upon completing the Assembly Language assignment (Part II), take time to reflect on what that experience was like for you. In particular, remember that this specific assembly language/machine code was designed for use in an educational setting. We encourage you to think about the design decisions the authors made while designing this language, and especially focus on the tradeoff between the interface (the functionality available while programming in Hack assembly language) and the implementation (the chips that have to be designed for the Hack computer to support that interface).

Since we haven't talked about the implementation in depth yet, it's okay to guess. The point of this exercise is more about thinking critically to come up with a reasonable guess than it is about being correct!

1. Why was multiplication implemented in the software rather than in the hardware? What would be the pros and cons of implementing multiplication in the ALU and allowing the programmer to use it as an operation in assembly?
2. Why can't a single C-instruction load a value from memory and encode a jump to another instruction? What would be the pros and cons of allowing a single C-instruction to do both?
3. Choose one other aspect of the assembly language design beyond the two above that made it difficult to use in this assignment. Now, describe why the authors might have chosen to do it that way. Try to identify the pros and cons of making that decision.

Record your answers in the document called project_4_reflection.docx located in the projects/4 directory. Edit the document "in-place" — that is, make sure the completed version has the same name in the same location and commit/push the changes just like you did previously.

Submitting

To submit your project, make sure you commit and push your changes, then tag them as project-4 and push that tag as well:

• git add . (stage all your changes)
• git commit -m "Finish project 4" (bundle those changes as a commit; the message is up to you!)
• git push (push that commit to the Gitlab server)
• git tag project-4 (add the project-4 tag to that last commit)
• git push --tags (push the tag to the Gitlab server)

Then, verify that the tag and all your code is uploaded correctly by checking on gitlab.cs.washington.edu.