VM Language and Implementation Summary

[cadet1620]

[This is a new document. Corrections, additions, etc. are encouraged!]

Memory Access Commands
push segment index	Pushes a memory location's value or a constant, onto the stack.
pop segment index	Pops a value off the stack and stores it in a memory location.
Arithmetic/Logical Commands
Arithmetic operations and comparisons are 2's complement.
Logical operations are bitwise.
add	Pop y, pop x, push x + y.
sub	Pop y, pop x, push x - y.
and	Pop y, pop x, push AND(x, y).
or	Pop y, pop x, push OR(x, y).
lt	Pop y, pop x, push -1 if x < y, else 0.
eq	Pop y, pop x, push -1 if x = y, else 0.
gt	Pop y, pop x, push -1 if x > y, else 0.
neg	Pop x, push −x.
not	Pop x, push NOT(x).
"Pop, pop, push" is the logical effect of the commands. Your translator does not need write actual push and pop commands.
Program Flow commands
Must be within a function, and label may be duplicated between multiple functions.
The ASM symbol should be functionName$label. ('$' is a legal ASM symbol character that is assumed will not be in functionName or label.)
label symbol	Defines a target for goto and <i<if-goto</i> commands.
goto symbol	Unconditional jump to symbol.
if-goto symbol	Pop x. If x ≠ 0, jump to symbol.
symbol is a string of letters, digits, underscore (_), dot (.), and colon (:) that does not begin with a digit.
Function commands
function functionName nLocals	Begin a new function that uses nLocals local variables.
call functionName nArgs	Call functionName. nArgs arguments have been pushed on the stack.
return	Return to the calling function. The current top-of-stack value is the return value.
functionName is a string of letters, digits, underscore (_), dot (.), and colon (:) that does not begin with a digit.

---

Memory segments
Pointer-based addressing
argument	0 ≤ index < nArgs	*(ARG + index)	Arguments for the current function.
local	0 ≤ index < nLocals	*(LCL + index)	Local variables for the current function.
this	index ≥ 0	*(THIS + index)	Data fields in class objects.
that	index ≥ 0	*(THAT + index)	Array indexing.
Absolute addressing
pointer	index = 0 or 1	THIS (0) or THAT (1)	The base pointers for the this and that segments.
temp	0 ≤ index ≤ 7	R5 - R12	Project global temporary variables.
static	index ≥ 0	filename.index	File global variables.
constant	index ≥ 0	@index	A read only constant, value = index.

---

Implementation of function related commands

call f n (calling a function f after n arguments have been pushed onto the stack)	push return-address // (Using the label declared below) push LCL // Save LCL of calling function push ARG // Save ARG of calling function push THIS // Save THIS of calling function push THAT // Save THAT of calling function ARG = SP-n-5 // Reposition ARG (n = number of args.) LCL = SP // Reposition LCL goto f // Transfer control (return-address) // Declare a label for the return-address
function f k (declaring a function f that has k local variables)	(f) // Declare label for the function entry repeat k times: // k = number of local variables PUSH 0 // Initialize all of them to 0
return (from a function)	FRAME = LCL // FRAME is a temporary variable RET = * (FRAME-5) // Put the return-address in a temp. var. *ARG = pop() // Reposition the return value for the caller SP = ARG+1 // Restore SP of the caller THAT = *(FRAME-1) // Restore THAT of the caller THIS = *(FRAME-2) // Restore THIS of the caller ARG = *(FRAME-3) // Restore ARG of the caller LCL = *(FRAME-4) // Restore LCL of the caller goto RET // Goto return-address (in the caller's code)

---

Bootstrap code

SP=256          // Initialize the stack pointer to 0x0100
call Sys.init   // Start executing (the translated code of) Sys.init

Note that this is a VM "call Sys.init 0" command, not a jump.

---

Command line

VMTranslator foo/bar/file.vm
  Translate foo/bar/file.vm to foo/bar/file.asm, do not write bootstrap code.

VMTranslator foo/bar/directory
  Translate all *.vm files in foo/bar/directory to foo/bar/directory/directory.asm, write bootstrap code.