VM Emulator Tutorial

This program is part of the software suite

that accompanies the book

The Elements of Computing Systems

by Noam Nisan and Shimon Schocken
MIT Press
www.nand2tetris.org
This software was developed by students at the
Efi Arazi School of Computer Science at IDC
Chief Software Architects: Yaron Ukrainitz and Yannai Gonczarowski

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 1/34

Background

The Elements of Computing Systems evolves around

the construction of a complete computer system,
done in the framework of a 1- or 2-semester course.
In the first part of the book/course, we build the
hardware platform of a simple yet powerful
computer, called Hack. In the second part, we build
the computer’s software hierarchy, consisting of an
assembler, a virtual machine, a simple Java-like
language called Jack, a compiler for it, and a mini
operating system, written in Jack.
The book/course is completely self-contained,
requiring only programming as a pre-requisite.
The book’s web site includes some 200 test
programs, test scripts, and all the software
tools necessary for doing all the projects.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 2/34

The Book’s Software Suite
(All the supplied tools are dual-platform: Xxx.bat starts
Xxx in Windows, and Xxx.sh starts it in Unix)

Simulators
(HardwareSimulator, CPUEmulator, VMEmulator):
 Used to build hardware platforms and
execute programs;
 Supplied by us.

Translators (Assembler, JackCompiler):

 Used to translate from high-level to low-level;
 Developed by the students, using the book’s
specs; Executable solutions supplied by us.
This tutorial is
about the
Other
VM emulator  Bin: simulators and translators software;

 builtIn: executable versions of all the logic

gates and chips mentioned in the book;
 OS: executable version of the Jack OS;

 TextComparer: a text comparison utility.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 3/34

VM Emulator Tutorial

I. Getting Started

II. Using Scripts

III. Debugging

Relevant reading (from The Elements of Computing Systems):

 Chapter 7: Virtual Machine I: Stack Arithmetic

 Chapter 8: Virtual Machine II: Program Control

 Appendix B: Test Scripting Language, Section 4.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 4/34

VM Emulator Tutorial

Part I:
Getting Started

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 5/34

The Typical Origin of VM Programs

 VM programs are normally

written by compilers

 For example, the Jack

Supplied Built in
by us projects
compiler (chapters 10-11)
7 and 8 generates VM programs

 The VM program can be

translated further into
machine language, and
then executed on a host
computer

 Alternatively, the same VM

program can be emulated
as-is on a VM emulator.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 6/34

Example: Pong game (user view)

Ball moves and

bounces off the
Number of walls “randomly”
successful
hits
User move the bat
left and right,
trying to hit the
ball

Now let’s go behind the scene ...

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 7/34

VM Emulator at a Glance

VM program
(In this
example: Screen:
Pong code (In this example:
+ OS code) Pong game action)

Virtual
memory
The VM emulator serves three purposes:
segments Keyboard
 Running programs enabler
 Debugging programs
 Visualizing the VM’s anatomy
The emulator’s GUI is rather crowded, but
Working stack:
each
Topmost
GUIpart of thehas an important debugging role.
element
global stack, as seen
by the VM program Not Part of the VM!
(displayed in the VM emulator
for reference purposes)
Call stack:
Hierarchy of all the
Global stack: Host RAM:
functions that are
Function frames Stores the global
currently running
+ working stack stack, heap, etc.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 8/34

Loading a VM Program

 Let’s start with a trivial VM program that

manipulates only the stack (i.e. does not
involve the memory segments Static,
Local, Argument, etc.);
 VM programs that don’t manipulate
memory segments can be loaded via the
“load file” button.

Navigate to a
directory and
select a .vm file

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 9/34

Running a Program

Script controls
Default test script
Always loaded, unless
another script is loaded
by the user.
VM code is loaded: (read-only)
The index on the left is the
location of the VM command
within the VM code (a GUI
effect, not part of the code).

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 10/34

Running a Program

Impact of first
13 “vmsteps”

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 11/34

Loading a Multi-File Program

 Most VM programs, like Pong, consist of more than one .vm

file. For example, the Jack compiler generates one .vm file
for each .jack class file, and then there are all the .vm fies
comprising the operating system. All these files must reside
in the same directory.
 Therefore, when loading a multi-file VM program into the VM
emulator, one must load the entire directory.

Won’t work!
Why? Because Pong is a
multi-file program, and ALL
these files must be loaded.
Solution: navigate back to the
directory level, and load it.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 12/34

Loading a Multi-File Program

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 13/34

VM Emulator Tutorial

Part II:
Virtual Memory
Segments

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 14/34

Virtual Memory Segments

A technical point to keep in mind:

 Most VM programs include pop and
push commands that operate on
Static, Local, Argument, etc.;
 In order for such programs to operate
properly, VM implementations must
initialize the memory segments’ bases,
e.g. anchor them in selected addresses in
the host RAM;
 Case 1: the loaded code includes function
calling commands. In this case, the VM
Memory segments: implementation takes care of the required
 The VM emulator segment initializations in run-time, since
displays the states this task is part of the VM function call-
of 6 of the 8 VM’s and-return protocol;
memory segments;  Case 2: the loaded code includes no
 The Constant and function calling commands. In this case,
Pointer segments the common practice is to load the code
are not displayed. through a test script that handles the
necessary initialization externally.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 15/34

VM Emulator Tutorial

Part II:
Using Scripts

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 16/34

 Typical VM Script
load
load BasicTest.vm,
BasicTest.vm,
output-file
output-file BasicTest.out,
BasicTest.out, Typical “script setup”
Simulation step compare-to
compare-to BasicTest.cmp,
BasicTest.cmp, commands
(a series of script output-list
commands output-list RAM[256]%D1.6.1
RAM[256]%D1.6.1
RAM[300]%D1.6.1
RAM[300]%D1.6.1 RAM[401]%D1.6.1
RAM[401]%D1.6.1
ending with a
semicolon) RAM[402]%D1.6.1 RAM[3006]%D1.6.1
RAM[402]%D1.6.1 RAM[3006]%D1.6.1
RAM[3012]%D1.6.1
RAM[3012]%D1.6.1
RAM[3015]%D1.6.1
RAM[3015]%D1.6.1 RAM[11]%D1.6.1;
RAM[11]%D1.6.1;

set
set sp
sp 256,
256, Typical memory
Next set
set local
local 300,
300, segments initialization
set commands
simulation set argument
argument 400,
400,
step set
set this
this 3000,
3000,
set
set that
that 3010;
3010;

Repeated repeat
repeat 25
25 {{
simulation vmstep, Typical execution loop
vmstep,
step output;
output;
}}

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 17/34

Loading a Script

Navigate to a
directory and select
a .tst file.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 18/34

Script Controls Execution
speed
control

Script = a series of
simulation steps, each
ending with a semicolon;
Reset
the script

Pause the
simulation

Execute step
after step
repeatedly
Execute the next
simulation step

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 19/34

Running the Script

Loads a VM program
into the emulator

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 20/34

Running the Script

VM code
is loaded

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 21/34

Running the Script
(click a few times)

The memory segments

were initialized (their
base addresses were
anchored to the RAM
locations specified by
the script).

A loop that
executes the
loaded VM
program

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 22/34

Running the Script

Impact after
first 10
commands
are executed

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 23/34

VM Emulator Tutorial

Part III:
Debugging

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 24/34

View Options

View options:
 Script: displays the loaded script;
 Output: displays the generated output file;
 Compare: displays the given comparison file;
 Screen: displays the simulated screen.

When the script terminates, the

comparison of the script output
and the compare file is reported.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 25/34

Animation Options

Speed control
(of both execution
and animation)

Animation control:
source
 Program flow (default): highlights the next
transit
VM command to be executed;
 Program & data flow: highlights the next
VM command and animates data flow;
destn.  No animation: disables all animation
Usage tip: To execute any non-trivial program
quickly, select no animation.
data flow animation related to
the last VM command (in this
example: push argument 0)

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 26/34

Breakpoints: a Powerful Debugging Tool
The VM emulator keeps track of the following variables:
 segment[i]: Where segment is either local, argument, this, that, or temp

 local, argument, this, that: Base addresses of these segments in the host RAM

 RAM[i]: Value of this memory location in the host RAM

 sp: Stack pointer

 currentFunction: Full name (inc. fileName) of the currently executing VM function

 line: Line number of the currently executing VM command

Breakpoints:
 A breakpoint is a pair <variable, value> where variable is one of the labels listed above
(e.g. local[5], argument, line, etc.) and value is a valid value

 Breakpoints can be declared either interactively, or via script commands

 For each declared breakpoint, when the variable reaches the value, the emulator
pauses the program’s execution with a proper message.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 27/34

Setting Breakpoints

2. Previously-
declared
breakpoints

By convention, function 4. Select the variable

headers are colored violet on whose value you
1. Open the
wish to break
breakpoint
panel
Here the violet coloring is
overridden by the yellow
“next command” highlight.

5. Enter the value

at which the break
A simple VM program: should occur
Sys.init calls
Main.main, that calls
Main.add (header not
seen because of the 3. Add, delete,
scroll), that does some or update
simple stack arithmetic. breakpoints

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 28/34

Setting Breakpoints

Breakpoints logic:
When local[1] will
become 8, or when sp
will reach 271, or when
the command in line 13
will be reached, or when
execution will reach the
Main.add function, the
emulator will pause the
program’s execution.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 29/34

Breakpoints in Action

Execution reached the

Main.add function, an
event that triggers a
display of the breakpoint
and execution pause.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 30/34

Breakpoints in Action

Following some push

and pop commands,
the stack pointer (sp)
became 271, an event
that triggers a display
of the breakpoint and
execution pause.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 31/34

Breakpoints in Action

Following some more execution,

A powerful
the second local variable
(local[1]) became 8, an event
debugging tool!
that triggers a display of the
breakpoint and execution pause.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 32/34

Breakpoints in Scripts
load
load myProg.vm,
myProg.vm,
 For systematic and replicable
output-file
output-file myProg.out,
myProg.out, debugging, use scripts
output-list
output-list sp%D2.4.2
sp%D2.4.2
CurrentFunction%S1.15.1
CurrentFunction%S1.15.1
 The first script commands usually
Argument[0]%D3.6.3
Argument[0]%D3.6.3 load the .vm program and set up
RAM[256]%D2.6.2;
RAM[256]%D2.6.2; for the simulation
breakpoint
breakpoint currentFunction
currentFunction Sys.init,
Sys.init,  The rest of the script may use
various debugging-oriented
set
set RAM[256]
RAM[256] 15,
15,
set sp 257; commands:
set sp 257;

repeat
• Write variable values (output)
repeat 33 {{
vmStep,
vmStep, • Repeated execution (while)
}}
output;
output; • Set/clear Breakpoints
while
while sp
sp << 260
260 {{
• Etc. (see Appendix B.)
vmstep;
vmstep;
}}
output;
output;

clear-breakpoints;
clear-breakpoints;

//
// Etc.
Etc.

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 33/34

End-note on Creating Virtual Worlds

“It’s like building something

where you don’t have to order
the cement. You can create a
world of your own, your own
environment, and never leave
this room.”

(Ken Thompson,
1983 Turing Award lecture)

VM Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 34/34