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 computers 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 books 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 Books 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 books
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
(High level Prog.jack
language)
VM programs are normally
Jack written by compilers
Compiler
For example, the Jack
Supplied Built in
by us Prog.vm projects
compiler (chapters 10-11)
7 and 8 generates VM programs
VM Altrenative VM VM The VM program can be
Emulator Implementations Translator translated further into
machine language, and
then executed on a host
Prog.asm computer
Alternatively, the same VM
Assembler
program can be emulated
as-is on a VM emulator.
(Binary code) Prog.hack
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 lets 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 VMs anatomy
The emulators GUI is rather crowded, but each
Working
GUIstack:
element has an important debugging role.
Topmost part of the
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
Lets 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 dont 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.
Wont 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 VMs 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 BasicTest.cmp, commands
compare-to BasicTest.cmp,
(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[402]%D1.6.1 RAM[3006]%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
simulation set
set argument
argument 400,
400, commands
step set
set this
this 3000,
3000,
set that 3010;
set that 3010;
Repeated repeat
repeat 25
25 {{
simulation vmstep,
vmstep, Typical execution loop
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
Execution
Script Controls 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 programs 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
programs 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 sp%D2.4.2
output-list 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
set
various debugging-oriented
set RAM[256]
RAM[256] 15,
15,
set sp 257;
set sp 257;
commands:
repeat
repeat 33 {{
Write variable values (output)
}}
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
Its like building something
where you dont 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
