Project 5: Annotation, Machine Language, & Computer Memory

Due Date: Friday, February 2, 2024 at 11:59pm

Introduction

In this project, you will engage in the metacognitive skill of annotating a text, specifically the Project 5 specification, identifying specific annotation strategies and applying them to annotating the specification. Then, you will reflect on the annotation experience. You will also practice the metacogntive skill of time management by filling out the assignment timeline for Project 5.

The technical part of this project consists of writing Hack Assembly code that calculates the maximum of two numbers stored in memory. Additionally, you will implement the memory module for the Hack computer, which will be used in the next project of building a computer.

Instructions

Navigate to the Project 5 assignment on Canvas. Download the document template titled Project 5.docx. Open the document, read the instructions on the first page, and estimate the amount of time you think it will take you to complete this project. Then, complete parts I, II, III, and IV of the project.

Part I: Annotation (10 points)

This part of the project requires you to read and annotate the Project 5 specification. We recommend that you get the annotations done as early as possible. Complete the following steps for Part I:

1. Fill out the assignment timeline. After you have finished annotating the specification, make a detailed plan of when you will work on each part of the project. It's up to you to decide how you will divide up the assignment and much you want to do in a single day. Be ready to reflect on this timeline with your TA at your next 1:1 meeting!



2. Annotate the specification. You may either print out or digitally mark up the Project 5 specification as you read it. Identify at least five key annotation strategies that you used while annotating the specification. Evaluate the effectiveness of each strategy in helping you understand approach the assignment. Here are a few examples of strategies you could leverage:

   • Digitally annotating the specification
   • Handwriting your annotations
   • Color coding
   • Creating a checklist for yourself of tasks to do
   • Estimating time or dividing the specification into more manageable milestones
   • Using arrows or bullet points
   • Drawing diagrams
   • Placing important info in boxes/bubbles
   • Summarizing ideas in your own words
   • Jotting down notes about implementation ideas
   • Writing down questions you have



3. Submit a copy of your annotated specification. If you handwrote your annotations, insert a picture of your notes within the reflection document. If you made annotations digitally, either insert a link within the document that allows us to access your annotations.


4. Complete the annotation strategies table and reflection questions. Reflect and evaluate the annotation strategies that you used in engaging with the Project 5 specification. Be sure to reflect on each of the strategies that you used and address the reflection questions.

In your upcoming 1:1 TA meeting, be prepared to share your annotations. You will be asked to explain your annotation choices as well as discuss which strategies helped you approach the Project 5 specification most effectively.

Part II: Machine Language (10 points)

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 possible, but also unnecessary, tedious, and highly error-prone. 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 an assembler. In this project, you will write a simple low-level assembly program and then become forever grateful for high-level languages like Java and Python. (But, assembly programming can be highly rewarding and useful in certain situations, allowing direct and complete control of the underlying machine.)

Pulling Project 5 Starter Code

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 (Downloads commits on the GitLab server to your local repository)

After running this command, you have synchronized the local copy of your repository with the copy on the server.

Overview

This section 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 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 program (starter code and tests can be found in the projects/p5/ directory):

Program	Description	Guidelines / Tests
Max.asm	In the Hack computer, the top sixteen RAM words (RAM[0]...RAM[15]) are also referred to as R0...R15. With this terminology in mind, this program determines the max of the values (comparing them as unsigned integers) stored in R0 and R1, stores the max value in R2, and stores the address of the max value in R3. If the two values in R0 and R1 are equal, then R0 should be considered the max. The program assumes that 0 ≤ R0 < 32768 and 0 ≤ R1 < 32768. Your program need not test these conditions, but rather assume that they hold.	Use a text editor to write your Max.asm program using the Hack assembly language. Use the supplied Hack Assembler to translate your Max.asm program, producing a Max.hack file containing binary Hack instructions. Next, load the supplied Max.tst script into the CPU Emulator. This script loads the Max.hack program, and executes it. Run the script. If you get any errors, debug and edit your Max.asm program. Then assemble the program, rerun the Max.tst script, etc.

Contract

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

Resources

To complete this part of the assignment, you will likely find the specification of the Hack assembly language in Chapter 4 useful.

In the tools directory of your repo, you will need to use two new tools. One is the Assembler tool, which converts Hack assembly language (.asm) to Hack binary code (.hack). You will also need the CPU Emulator tool, which loads .hack files and allows you to step through, examine the state of the emulated computer, and run test scripts. Note the CPU Emulator 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 CPU Emulator 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 (pdf, pptx) and the CPU Emulator Tutorial (pdf, pptx) developed by the Nand2Tetris project.

Part II 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: Computer Memory (10 points)

Background

In previous projects, we've built the computer's basic processing and storage devices (ALU and RAM, respectively). In this project and in Project 6, we will put everything together, yielding the complete Hack Hardware Platform. The result will be a general-purpose computer that can run programs written in the Hack machine language.

Overview

Like Projects 2, 3, and 4, this project will involve building a set of HDL chips. This time, you will build the highest-level chips in the whole system, culminating with the "Computer" chip itself. As usual, you should construct these chips using the chips listed in previous projects (with a few exceptions that will be noted; see the "Tips" section for more details). In Project 5, you will build only one of these chips, the Memory chip, which encompasses the entire RAM address space (note that even though this is part of Project 6, Memory.hdl and its tests are stored in the directory projects/p6/ so that they can be used in your future Project 6 implementations as well). Later, in Project 6, you will build the CPU and then tie everything together to build the final computer.

Chip Name	Description	Testing
Memory.hdl	Entire RAM address space. Estimated Difficulty: Medium.	Test your chip using the provided Memory.tst test script (which tests against Memory.cmp).

Contract

Your implementation of Memory.hdl should pass the provided tests.

Resources

See Chapter 5 for details about the computer's implementation (particularly the section on the Memory design for this project). Per usual, use the HDL Reference or HDL Survival Guide to look up details of the language. You may also find the Hack Chip Set reference useful to remember chip interfaces.

Part III Tips

The Memory chip includes three chip-parts: RAM16K, Screen, and Keyboard. The Screen and the Keyboard are available as built-in chips, and thus there is no need to implement them. Although the RAM16K chip was built in Project 4, we recommend using its built-in version, as it provides a debugging-friendly GUI (i.e., don't copy in your solution from Project 4).

Additionally, even though the Memory interface may be intimidating at first, the implementation strategies and techniques are similar to those you've used in previous projects.

Submitting Parts II & III

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

• git add . (Stage all your changes)
• git commit -m "Finish project 5" (Bundle those changes as a commit)
• git push (Push this commit to the GitLab server)
• git tag project-5 (Add the project-5 tag to that last commit)
• git push --tags (Push the tag to the GitLab server)

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

Part IV: Project 5 Reflection (5 points)

In the document Project 5.docx, record how long the project took you in reality and write a short written reflection about your experience completing this project.

Submitting Your Work

Make sure you have submitted your completed .hdl files on GitLab by following the instructions in the heading above titled "Submitting Parts II & III." Then, save your changes from the Project 5.docx document as a PDF and submit the document to the assignment titled "Project 5: Annotation, Machine Language, & Computer Memory" on Gradescope. Project 5 will be considered completed once you have followed these steps.