Laboratory assignment · 24 September

Lab 7: VM Translator, Part I

Build the first part of a VM-to-Hack translator in Python, covering stack arithmetic, logical operations, and memory-access commands.

Back to course home

Objective and contract

Translate VM code into Hack assembly

The generated assembly must satisfy the standard VM mapping on the Hack platform.

Contract

Xxx.vm becomes Xxx.asm

When the generated assembly runs on the CPU emulator, it must produce the results required by the supplied test scripts and compare files.

Program
Write VMTranslator.py in Python.
Input
One valid .vm file containing commands covered by this project.
Output
A Hack assembly-language file with the same base name and the extension .asm.
Example
python VMTranslator.py BasicTest.vm must generate BasicTest.asm.
Open VM Emulator Open Web IDE

Implementation plan

Build and test in two stages

Complete each stage before depending on it in the next one.

Stage I

Stack arithmetic and logic

Implement push constant x and all nine arithmetic/logical commands:

  • add, sub, and neg
  • eq, gt, and lt
  • and, or, and not
Stage II

Memory access

Implement the complete push segment i and pop segment i commands for all eight VM segments:

  • constant
  • local, argument, this, and that
  • pointer and temp
  • static

Recommended Stage II order

  1. Reuse the already implemented constant segment.
  2. Implement local, argument, this, and that.
  3. Implement pointer and temp, including changes to the bases of this and that.
  4. Implement static.

Test programs

Five focused tests

Each program targets the commands introduced at a particular implementation stage.

Stage I

SimpleAdd

Pushes two constants and adds them. Use it as the first test of stack manipulation and add.

Stage I

StackTest

Executes a sequence that exercises all arithmetic and logical commands.

Stage II

BasicTest

Tests push and pop with the principal virtual memory segments.

Stage II

PointerTest

Tests pointer, this, and that, including modification of the segment bases.

Stage II

StaticTest

Tests translation and use of the static segment.

For each program Xxx, use Xxx.vm as input. The supplied XxxVME.tst demonstrates its intended VM behavior; Xxx.tst and Xxx.cmp test your translated assembly on the CPU emulator.

Workflow

Obtain, translate, and test each program

Use the VM emulator to understand the source program and the CPU emulator to verify your translation.

Implementation steps

  1. Open the Nand2Tetris VM Emulator and choose Load Files.
  2. Open projects/07. It contains the five test-program folders listed above.
  3. Enter a folder—for example, BasicTest—select BasicTest.vm, and copy or download it to your computer.
  4. Run your translator: 
    python VMTranslator.py BasicTest.vm
    It must produce BasicTest.asm.
  5. Repeat for the remaining programs at the appropriate implementation stage.

Testing and debugging each program

  1. Run Xxx.vm in the VM emulator with XxxVME.tst to understand its intended behavior.
  2. Translate Xxx.vm with your current translator to produce Xxx.asm.
  3. Inspect the assembly output for visible syntax, label, or control-flow errors.
  4. Load the generated assembly in the CPU emulator and run the supplied Xxx.tst test script.
  5. Compare the result with Xxx.cmp. If it fails, correct the translator and generate the assembly again.

Follow the prescribed order. Later tests depend on features exercised by earlier tests. Implementing later stages first can make failures difficult to diagnose.

Important for this lab

Initialization is supplied by the tests

Bootstrap code and segment initialization belong to the next VM-translator project.

A complete VM implementation normally begins with startup code that initializes the stack pointer and establishes the virtual segments' base addresses. You do not have to generate that startup code in this lab. The supplied Project 7 test scripts manually perform the initialization required by these five programs.