jamespolley / Hack-VM-Translator

Virtual Machine translator for symbolic Hack assembly code. Written in Python.

Hack-VM-Translator

Virtual Machine translator for symbolic Hack assembly code. Project from weeks 1 and 2 of the course, Build a Modern Computer from First Principles: From Nand to Tetris Part II.

Description

Hack-VM-Translator converts VM code into symbolic Hack assembly code, which is designed for the Hack computer. Translation of virtual machine code into assembly code is part of a two-tier compilation process (notably used by Java). Virtual machine code is an intermediary step on the journey from high-level language code to machine code that is ultimately run by a computer.

This project is separated into the following components:

• VMTranslator - Main class. Handles input, reads the VM file, writes to the assembly file, and drives the VM translation process.
• Parser - Handles traversal and parsing of each line into its lexical components.
• CodeWriter - Generates symbolic Hack assembly code from parsed VM commands.

Usage

Hack-VM-Translator translates a single .vm file, or all .vm files within a directory, into one .asm file.

Examples:

$ python VMTranslator.py fileName.vm

$ python VMTranslator.py fileDirectoryName

VM Language

Commands

• Arithmetic/Logical
  • add
  • sub
  • and
  • or
  • neg
  • not
  • lt
  • eq
  • gt
• Memory Access
  • push segment i
  • pop segment i
• Branching
  • label label
  • goto label
  • if-goto label
• Function
  • function functionName nVars
  • call functionName nArgs
  • return

Segments

• local
• argument
• this
• that
• constant*
• pointer
• temp
• static

*Note: constant is technically not a segment. In push and pop commands, constant is used as a segment to maintain the command syntax structure and simplify the translation process.

Special Symbols

Symbol	Usage
SP	Predefined symbol that points to the memory address within the host RAM just after the address containing the topmost stack value.
LCL, ARG, THIS, THAT	Predefined symbols that point to the base addresses within the host RAM of the virtual segments local, argument, this, and that of the currently running VM function.
R13-R15	Predefined symbols that can be used for any purpose.
Xxx.i symbols	Each static variable i in the file Xxx.vm is translated into the assembly variable Xxx.j, where j is incremented each time a new static variable is encountered in the file Xxx.vm. These variables are later allocated to RAM by the Hack assembler.
functionName$label	Let foo be a function within a VM file Xxx.vm. Each label bar command command within foo should generate and insert into the assembly code stream a symbol Xxx.foo$bar. When translating goto bar and if-goto bar commands (within foo) into assembly, the full label specification Xxx.foo$bar must be used instead of bar.
functionName	Each function foo command within a VM file Xxx.vm should generate and insert into the assembly code stream a symbol Xxx.foo that labels the entry point to the function's code. This symbol is later translated by the Hack assembler into the physical memory address where the function's code begins.
functionName$ret.i	Let foo be a function within a VM file Xxx.vm. Within foo, each function call command should generate and insert into the assembly code stream a symbol Xxx.foo$ret.i, where i is a running integer (one such symbol should be generated for each call command within foo). This symbol serves as the return address to the calling function. This symbol is later translated by the Hack assembler into the physical memory address of the command immediately after the function call command.