Hardware Simulator 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.idc.ac.il/tecs
This software was developed by students at the
Efi Arazi School of Computer Science at IDC
Chief Software Architect: Yaron Ukrainitz

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 1/49

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.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 2/49

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;
This tutorial is
about the ƒ Supplied by us.
hardware
simulator. 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.
Other
ƒ 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.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 3/49

The Hack computer
The hardware simulator described in this
tutorial can be used to build and test many
different hardware platforms. In this book, we
focus on one particular computer, called Hack.
Hack -- a 16-bit computer equipped with a
screen and a keyboard -- resembles hand-held
computers like game machines, PDA’s, and
cellular telephones.
The first 5 chapters of the book specify the
elementary gates, combinational chips,
sequential chips, and hardware architecture of
the Hack computer.
All these modules can be built and tested using
the hardware simulator described in this
tutorial.
That is how hardware engineers build chips
for real: first, the hardware s designed,
tested, and optimized on a software
simulator. Only then, the resulting
gate logic is committed to silicon.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 4/49

Hardware Simulation Tutorial

I. Getting started

II. Test scripts

III. Built-in chips

IV. Clocked chips

V. GUI-empowered chips

VI. Debugging tools

VII. The Hack Platform

Relevant reading (from “The Elements of Computing Systems”):

ƒ Chapter 1: Boolean Logic
ƒ Appendix A: Hardware Description Language
ƒ Appendix B: Test Scripting Language

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 5/49

Hardware Simulation Tutorial

Part I:
Getting Started

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 6/49

Chip Definition (.hdl file)

/**
/** Exclusive-or
Exclusive-or gate.
gate. out
out == aa xor
xor bb */
*/
chip CHIP
CHIP Xor
Xor {{
interface IN
IN a,
a, b;
b;
OUT
OUT out;
out;

//
// Implementation
Implementation missing.
missing.
}}

ƒ Chip interface:
‰ Name of the chip
‰ Names of its input and output pins
‰ Documentation of the intended chip operation
ƒ Typically supplied by the chip architect; similar to an API, or a contract.
HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 7/49
Chip Definition (.hdl file)

/**
/** Exclusive-or
Exclusive-or gate.
gate. out
out == aa xor
xor bb */
*/
chip CHIP
CHIP Xor
Xor {{
interface IN
IN a,
a, b;
b;
OUT
OUT out;
out;

PARTS:
PARTS:
Not(in=a,
Not(in=a, out=nota);
out=nota);
chip
Not(in=b,
Not(in=b, out=notb);
out=notb);
implementation
And(a=a,
And(a=a, b=notb,
b=notb, out=w1);
out=w1);
And(a=nota, b=b,
And(a=nota, b=b, out=w2);
out=w2);
Or(a=w1, b=w2,
Or(a=w1, b=w2, out=out);
out=out);
}}

ƒ Any given chip can be implemented in several different ways. This particular
implementation is based on: Xor(a,b) = Or(And(a,Not(b)), And(b,Not(a)))
ƒ Not, And, Or: Internal parts (previously built chips), invoked by the HDL
programmer
ƒ nota, notb, w1, w2: internal pins, created and named by the HDL programmer;
used to connect internal parts.
HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 8/49
Loading a Chip

Navigate to a
directory and select
an .hdl file.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 9/49

Loading a Chip

ƒ Names and current

values of the chip’s
output pins;
ƒ Calculated by the
simulator; read-
ƒ Names and current values only.
of the chip’s input pins;
ƒ To change their values,
enter the new values ƒ Names and current values of
here. the chip’s internal pins
(used to connect the chip’s
parts, forming the chip’s logic);
ƒ Calculated by the simulator;
read-only.

ƒ Read-only view of the loaded .hdl file;

ƒ Defines the chip logic;
ƒ To edit it, use an external text editor.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 10/49

Exploring the Chip Logic

2. A table pops up, showing the chip’s internal

1. Click the parts (lower-level chips) and whether they are:
PARTS ƒ Primitive (“given”) or composite (user-defined)
keyword ƒ Clocked (sequential) or unclocked (combinational)

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 11/49

Exploring the Chip Logic

2. A table pops up, showing the

input/output pins of the selected
1. Click any one of part (actually, its API), and their
the chip PARTS current values;
A convenient debugging tool.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 12/49

Interactive Chip Testing

1. User: changes the values of some

input pins
2. Simulator: responds by:
ƒ Darkening the output and internal
pins, to indicate that the displayed
values are no longer valid
ƒ Enabling the eval
Re-
(calculator-shaped) button.
calc

3. User: Clicked the eval button

4. Simulator: re-calculates the values
of the chip’s internal and output
pins (i.e. applies the chip logic to
the new input values)
5. To continue interactive testing,
enter new values into the input
pins and click the eval button.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 13/49

Hardware Simulation Tutorial

Part II:
Test Scripts

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 14/49

Test Scripts
load
load Xor.hdl,
Xor.hdl, Test scripts:
output-file
output-file Xor.out,
Xor.out,
compare-to
compare-to Xor.cmp,
Xor.cmp, ƒ Are used for specifying, automating and
output-list Init
output-list a%B3.1.3
a%B3.1.3 replicating chip testing
b%B3.1.3
b%B3.1.3
out%B3.1.3;
out%B3.1.3; ƒ Are supplied for every chip mentioned in
set
set aa 0,
0, the book (so you don’t have to write them)
set
set bb 0,
0,
eval,
eval,
ƒ Can effect, batch-style, any operation that
Simulation step
output;
output; can be done interactively

set
set aa 0,
0, Generated ƒ Are written in a simple language described
set
set bb 1,
1,
output file in Appendix B of the book
eval, (Xor.out)
eval,
output; ƒ Can
Simulation
createstep
an output file that records the
output;
Etc.
Etc.
results of the chip test

|| aa || bb || out
out ||
|| 00 || 00 || 00 || ƒ If the script specifies a compare file, the
|| 00 || 11 || 11 || simulator will compare the .out file to
|| 11 || 00 || 11 || the .cmp file, line by line.
|| 11 || 11 || 00 ||

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 15/49

Loading a Script

To load a new script (.tst

file), click this button;

Interactive loading of the chip

itself (.hdl file) may not be
necessary, since the test
script typically contains a
“load chip” command.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 16/49

Script Controls

Controls
the script
execution
speed Script =
series of
simulation
steps, each
Resets
ending with
the script
a semicolon.
Pauses the
script execution

Multi-step execution,
until a pause

Executes the next

simulation step

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 17/49

Running a Script

Script
exec-
Typical “init” code:
ution
1. Loads a chip definition (.hdl) file
flow
2. Initializes an output (.out) file
3. Specifies a compare (.cmp) file
4. Declares an output line format.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 18/49

Running a Script

Comparison of the output lines to

the lines of the .cmp file are
reported.

Script
exec-
ution
ends

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 19/49

Viewing Output and Compare Files

Observation:
This output file
looks like a Xor
truth table

Conclusion: the chip logic

(Xor.hdl) is apparently
correct (but not necessarily
efficient).

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 20/49

Hardware Simulation Tutorial

Part III:
Built-in Chips

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 21/49

Built-In Chips
General
ƒ A built-in chip has an HDL interface and a Java //
// Mux16
Mux16 gate
gate (example)
(example)
implementation (e.g. here: Mux16.class) CHIP
CHIP Mux16
Mux16 {{
IN
IN a[16],b[16],sel;
a[16],b[16],sel;
ƒ The name of the Java class is specified following
the BUILTIN keyword OUT
OUT out[16];
out[16];
BUILTIN
BUILTIN Mux16;
Mux16;
ƒ Built-In implementations of all the chips that
}}
appear in he book are supplied in the
tools/buitIn directory.

Built-in chips are used to:

ƒ Implement primitive gates (in the computer built in this book: Nand and DFF)
ƒ Implement chips that have peripheral side effects (like I/O devices)
ƒ Implement chips that feature a GUI (for debugging)
ƒ Provide the functionality of chips that the user did not implement for some reason
ƒ Improve simulation speed and save memory (when used as parts in complex chips)
ƒ Facilitate behavioral simulation of a chip before actually building it in HDL
ƒ Built-in chips can be used either explicitly, or implicitly.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 22/49

Explicit Use of Built-in Chips

The chip is loaded from the

tools/buitIn directory (includes
executable versions of all the chips
mentioned in the book).

Standard interface.

Built-in implementation.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 23/49

Implicit Use of Built-in Chips
/**
/** Exclusive-or
Exclusive-or gate.
gate. out
out == aa xor
xor bb */
*/
CHIP
CHIP Xor
Xor {{
IN
IN a,
a, b;
b;
OUT
OUT out;
out;
PARTS:
PARTS:
Not(in=a,out=Nota);
Not(in=a,out=Nota);
Not(in=b,out=Notb);
Not(in=b,out=Notb);
And(a=a,b=Notb,out=aNotb);
And(a=a,b=Notb,out=aNotb);
And(a=Nota,b=b,out=bNota);
And(a=Nota,b=b,out=bNota);
Or(a=aNotb,b=bNota,out=out);
Or(a=aNotb,b=bNota,out=out);
}}

ƒ When any HDL file is loaded, the simulator parses its definition. For each internal
chip Xxx(...) mentioned in the PARTS section, the simulator looks for an Xxx.hdl
file in the same directory (e.g. Not.hdl, And.hdl, and Or.hdl in this example).
ƒ If Xxx.hdl is found in the current directory (e.g. if it was also written by the user), the
simulator uses its HDL logic in the evaluation of the overall chip.
ƒ If Xxx.hdl is not found in the current directory, the simulator attempts to invoke the
file tools/builtIn/Xxx.hdl instead.
ƒ And since tools/builtIn includes executable versions of all the chips mentioned in
the book, it is possible to build and test any of these chips before first building their
lower-level parts.
HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 24/49
Hardware Simulation Tutorial

Part IV:
Clocked Chips
(Sequential Logic)

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 25/49

Clocked (Sequential) Chips

ƒ The implementation of clocked chips is based on sequential logic

ƒ The operation of clocked chips is regulated by a master clock signal:

ƒ In our jargon, a clock cycle = tick-phase (low), followed by a tock-phase (high)

ƒ During a tick-tock, the internal states of all the clocked chips are allowed to change,
but their outputs are “latched”

ƒ At the beginning of the next tick, the outputs of all the clocked chips in the
architecture commit to the new values

ƒ In a real computer, the clock is implemented by an oscillator; in simulators, clock

cycles can be simulated either manually by the user, or repeatedly by a test script.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 26/49

The D-Flip-Flop (DFF) Gate

/** Clocked chips

/** Data
Data Flip-flop:
Flip-flop:
** out(t)=in(t-1)
out(t)=in(t-1) ƒ Clocked chips include registers,
** where
where tt is
is the
the time
time unit.
unit. RAM devices, counters, and
*/
*/
CHIP
the CPU
CHIP DFF
DFF {{
IN
IN in;
in; ƒ The simulator knows that the
OUT
OUT out;
out; loaded chip is clocked when
one or more of its pins is
BUILTIN
BUILTIN DFF;
DFF; declared “clocked”, or one or
CLOCKED
CLOCKED in,
in, out;
out;
}} more of its parts (or sub-parts,
recursively) is a clocked chip
ƒ In the hardware platform built in
the book, all the clocked chips
DFF: are based, directly or indirectly,
ƒ A primitive memory gate that can on (many instances of) built-in
“remember” a state over clock cycles DFF gates.
ƒ Can serve as the basic building block of
all the clocked chips in a computer.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 27/49

Simulating Clocked Chips

Clocked (sequential) chips are clock-regulated.

Therefore, the standard way to test a clocked chip
is to set its input pins to some values (as with
combinational chips), simulate the progression of
the clock, and watch how the chip logic responds
to the ticks and the tocks.
For example, consider the simulation of an 8-word
random-access memory chip (RAM8).
Since this built-in chip also
happens to be GUI- empowered,
the simulator displays its GUI

A built-in, (More about GUI-empowered

clocked chips, soon)
chip
(RAM8) is
loaded

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 28/49

Simulating Clocked Chips

3. User: clicks
the clock icon
again (tock)

1. User: enters
some input
values and
4. Simulator: 2. Simulator:
clicks the clock
commits the changes the
icon once (tick)
chip’s output pin internal state of
to the value of the chip, but note
the chip’s that the chip’s
A built-in, internal state. output pin is not
clocked yet effected.
chip
(RAM8) is
loaded

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 29/49

Simulating Clocked Chips Using a Test Script

Controls the script

speed, and thus the
simulated clock speed,
and thus the overall
Default script: always loaded when
chip execution speed
the simulator starts running;
Single-action
tick-tock The logic of the default script simply
runs the clock repeatedly;
Tick-tocks Hence, executing the default script
repeatedly and has the effect of causing the clock
infinitely to go through an infinite train of tics
and tocks.
This, in turn, causes all the clocked
chip parts of the loaded chip to react
to clock cycles, repeatedly.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 30/49

Hardware Simulation Tutorial

Part V:
GUI-Empowered
chips

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 31/49

Built-in Chips with GUI Effects

2. If the loaded chip or For each GUI-empowered built-in chip that appears
some of its parts have in the definition of the loaded chip, the simulator
GUI side-effects, the does its best to putGUI of the
the chip GUIbuilt-in
in this area.
simulator displays the Screen.hdl chip
The actual GUI’s behaviors are then effected by the
GUI’s here. Java classes that implement the built-in chips.

1. A chip whose
parts include GUI of the built-in
built-in chips Keyboard.hdl chip
was loaded into
the simulator
GUI of the built-in
(ignore the chip RAM16K.hdl chip
logic for now)

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 32/49

The Logic of the GUIDemo Chip
RAM16K,
Screen, &
//
// Demo
Demo of
of built-in
built-in chips
chips with
with GUI
GUI effects
effects Keyboard
CHIP are built-in
CHIP GUIDemo
GUIDemo {{
chips with GUI
IN
IN in[16],load,address[15];
in[16],load,address[15]; side-effects
OUT
OUT out[16];
out[16];
PARTS:
PARTS:
RAM16K(in=in,load=load,address=address[0..13],out=null);
RAM16K(in=in,load=load,address=address[0..13],out=null);
Screen(in=in,load=load,address=address[0..12],out=null);
Screen(in=in,load=load,address=address[0..12],out=null);
Keyboard(out=null);
Keyboard(out=null);
}}

ƒ Effect: When the simulator evaluates this chip, it displays the GUI side-
effects of its built-in chip parts
ƒ Chip logic: The only purpose of this demo chip is to force the simulator to
show the GUI of some built-in chips. Other than that, the chip logic is
meaningless: it simultaneously feeds the 16-bit data input (in) into the
RAM16K and the Screen chips, and it does nothing with the keyboard.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 33/49

GUIDemo Chip in Action

3. 16 black
2. User: pixels are
runs the drawn
clock beginning in
row = 156
col = 320

1. User enters:
ƒ in = –1
Explanation: According to the specification of
(=16 1’s in binary)
the computer architecture3. The chipinlogic
described the
ƒ address = 5012 routesscreen
book, the pixels of the physical the inarevalue
ƒ load = 1 continuously refreshed fromsimultaneously
an 8K RAM- into
the Screen
resident memory map implemented bychip
the and
Screen.hdl chip. The exact the RAM16K
mappingchip
between this memory chip and the actual
pixels is specified in Chapter 5. The refresh
process is carried out by the simulator.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 34/49

Hardware Simulation Tutorial

Part VI:
Debugging tools

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 35/49

System Variables

The simulator recognizes and maintains the following variables:

ƒ Time: the number of time-units (clock-cycles) that elapsed since the script
started running is stored in the variable time

ƒ Pins: the values of all the input, output, and internal pins of the simulated chip
are accessible as variables, using the names of the pins in the HDL code

ƒ GUI elements: the values stored in the states of GUI-empowered built-in chips
can be accessed via variables. For example, the value of register 3 of the
RAM8 chip can be accessed via RAM8[3].

All these variables can be used in scripts and breakpoints, for debugging.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 36/49

Breakpoints

2. Previously-
1. Open the declared
breakpoints breakpoints
panel

3. To update an existing
breakpoint, double-click it

The breakpoints logic:

ƒ Breakpoint = (variable, value)
ƒ When the specified variable in some
breakpoint reaches its specified value,
3. Add, delete, the script pauses and a message is
or update displayed
breakpoints ƒ A powerful debugging tool.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 37/49

Scripts for Testing the Topmost Computer chip
load
load Computer.hdl
Computer.hdl ƒ Scripts that test the CPU chip or the
ROM32K
ROM32K load
load Max.hack,
Max.hack, Computer chip described in the book usually
output-file ComputerMax.out,
output-file ComputerMax.out,
compare-to start by loading a machine-language program
compare-to ComputerMax.cmp,
ComputerMax.cmp,
output-list (.asm or .hack file) into the ROM32K chip
output-list time%S1.4.1
time%S1.4.1
reset%B2.1.2
reset%B2.1.2 ƒ The rest of the script typically uses various
ARegister[]%D1.7.1
ARegister[]%D1.7.1
DRegister[]%D1.7.1
features like:
DRegister[]%D1.7.1
PC[]%D0.4.0
PC[]%D0.4.0 • Output files
RAM16K[0]%D1.7.1
RAM16K[0]%D1.7.1
RAM16K[1]%D1.7.1
RAM16K[1]%D1.7.1
• Loops
RAM16K[2]%D1.7.1;
RAM16K[2]%D1.7.1; • Breakpoints
breakpoint
breakpoint PC PC 10;
10;
//
// First run: compute max(3,5)
First run: compute max(3,5) • Variables manipulation
set RAM16K[0]
set RAM16K[0] 3, 3,
set • tick, tock
set RAM16K[1]
RAM16K[1] 5, 5,
output;
output; • Etc.
repeat
repeat 14
14 {{
tick,
tick, tock,
tock, output;
output;
• All these features are described in Appendix
}} B of the book (Test Scripting Language).
//
// Reset
Reset the
the PC
PC (preparing
(preparing for
for
// second run)
// second run)
set
set reset
reset 1,
1,
tick,
tick, tock, output;
tock, output;
// Etc.
// Etc.
clear-breakpoints;
clear-breakpoints;

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 38/49

Visual Options

ƒ Program flow: animates the

flow of the currently loaded
Format of displayed ƒ Script: displays the
pin values: current test script
program
ƒ Decimal (default) ƒ Output: displays the
ƒ Program & data flow: animates
the flow of the current program ƒ Hexadecimal generated output file
and the data flow throughout the ƒ Binary ƒ Compare: displays
GUI elements displayed on the the supplied
screen comparison file
ƒ No animation (default): ƒ Screen: displays the
program and data flow are not GUI effects of built-in
animated. chips, if any.
ƒ Tip: When running programs on
the CPU or Computer chip, any
animation effects slow down the
simulation considerably.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 39/49

Hardware Simulation Tutorial

Part VII:

The Hack
Hardware Platform

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 40/49

Hack: a General-Purpose 16-bit Computer
Sample applications running on the Hack computer:

Hang
Maze
Man

Grades
Pong
Stats

These programs (and many more) were written in the Jack programming language,
running in the Jack OS environment over the Hack hardware platform. The hardware
platform is built in chapters 1-5, and the software hierarchy in chapters 6-12.
HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 41/49
The Hack Chip-Set and Hardware Platform
Elementary logic gates Combinational chips Sequential chips Computer Architecture
(Project 1): (Project 2): (Project 3): (Project 5):
ƒ Nand (primitive) ƒ HalfAdder ƒ DFF (primitive) ƒ Memory
ƒ Not ƒ FullAdder ƒ Bit ƒ CPU
ƒ And
ƒ Add16 ƒ Register ƒ Computer
ƒ Or
ƒ Inc16 ƒ RAM8
ƒ Xor
ƒ ALU ƒ RAM64
ƒ Mux
ƒ RAM512
ƒ Dmux
ƒ RAM4K
ƒ Not16
ƒ And16 ƒ RAM16K
ƒ Or16 ƒ PC
ƒ Mux16
ƒ Or8Way Most of these chips are generic, meaning that they can be
used in the construction of many different computers.
ƒ Mux4Way16
ƒ Mux8Way16 The Hack chip-set and hardware platform can be built using
the hardware simulator, starting with primitive Nand.hdl and
ƒ DMux4Way
DFF.hdl gates and culminating in the Computer.hdl chip.
ƒ DMux8Way
This construction is described in chapters 1,2,3,5 of the book,
and carried out in the respective projects.

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 42/49

Aside: H.D. Thoreau about chips, bugs, and close observation:

I was surprised to find that the chips were covered

with such combatants, that it was not a duellum, but a
bellum, a war between two races of ants, the red always
pitted against the black, and frequently two red ones to
one black. The legions of these Myrmidons covered all
the hills and vales in my wood-yard, and the ground was
already strewn with the dead and dying, both red and
black.
It was the only battle which I have ever witnessed, the only battlefield I
ever trod while the battle was raging; internecine war; the red
republicans on the one hand, and the black imperialists on the other. On
every side they were engaged in deadly combat, yet without any noise
that I could hear, and human soldiers never fought so resolutely.... The
more you think of it, the less the difference. And certainly there is not
the fight recorded in Concord history, at least, if in the history of
America, that will bear a moment’s comparison with this, whether for the
numbers engaged in it, or for the patriotism and heroism displayed.
From “Brute Neighbors,” Walden (1854).

HW Simulator Tutorial www.idc.ac.il/tecs Tutorial Index Slide 43/49

 CPU 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.idc.ac.il/tecs
This software was developed by students at the
Efi Arazi School of Computer Science at IDC
Chief Software Architect: Yaron Ukrainitz

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 1/40

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.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 2/40

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
This tutorial is execute programs;
about the
CPU emulator. ƒ 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.
Other
ƒ 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.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 3/40

Tutorial Objective

Learn how to use the

CPU Emulator
for simulating the
execution of machine
language programs on
the Hack computer

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 4/40

The Hack computer

This CPU emulator simulates the

operations of the Hack computer,
built in chapters 1-5 of the book.
Hack -- a 16-bit computer equipped
with a screen and a keyboard --
resembles hand-held computers
like game machines, PDA’s, and
cellular telephones.
Before such devices are actually
built in hardware, they are planned
and simulated in software.
The CPU emulator is one of
the software tools used for
this purpose.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 5/40

CPU Emulator Tutorial

I. Basic Platform

II. I/O devices

III. Interactive simulation

IV. Script-based simulation

V. Debugging

Relevant reading (from “The Elements of Computing Systems”):

ƒ Chapter 4: Machine Language

ƒ Chapter 5: Computer Architecture

ƒ Appendix B: Test Scripting Language

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 6/40

CPU Emulator Tutorial

Part I:
Basic Platform

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 7/40

The Hack Computer Platform (simulated)

Travel Advice:
This tutorial includes some examples
of programs written in the Hack
machine language (chapter 4).
There is no need however to
understand either the language or the
programs in order to learn how to use
the CPU emulator.
Rather, it is only important to grasp the
general logic of these programs,
as explained (when relevant)
in the tutorial.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 8/40

The Hack Computer Platform

screen

data
memory
keyboard
instruction enabler
memory

registers ALU

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 9/40

Instruction memory

The loaded code can be viewed

either in binary, or in symbolic
notation (present view)

Instruction memory
(32K): Holds a machine
language program

Next instruction
is highlighted

Program counter (PC) (16-bit):

Selects the next instruction.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 10/40

Data memory (RAM)

Data memory (32K RAM), used for:

ƒ General-purpose data storage
(variables, arrays, objects, etc.)
ƒ Screen memory map
ƒ Keyboard memory map

Address (A) register, used to:

ƒ Select the current RAM location
OR
ƒ Set the Program Counter (PC) for
jumps (relevant only if the current
instruction includes a jump directive).

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 11/40

Registers

Registers (all 16-bit):

ƒ D: Data register
ƒ A: Address register
ƒ M: Stands for the memory register
whose address is the current
value of the Address register

M (=RAM[A])

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 12/40

Arithmetic/Logic Unit

Arithmetic logic unit (ALU)

ƒ The ALU can compute various arithmetic
and logical functions (let’s call them f) on
subsets of the three registers {M,A,D}
ƒ All ALU instructions are of the form
{M,A,D} = f ({M,A,D})
(e.g. M=M-1, MD=D+A , A=0, etc.)
Current ƒ The ALU operation (LHS destination,
instruction function, RHS operands) is specified by
M (=RAM[A]) the current instruction.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 13/40

CPU Emulator Tutorial

Part II:
I/O Devices

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 14/40

I/O devices: screen and keyboard

Simulated screen: 256 columns by

512 rows, black & white memory-
mapped device. The pixels are
continuously refreshed from respective
bits in an 8K memory-map, located at
RAM[16384] - RAM[24575].

Simulated keyboard:
One click on this button causes the
CPU emulator to intercept all the
keys subsequently pressed on the
real computer’s keyboard; another
click disengages the real keyboard
from the emulator.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 15/40

Screen action demo

Perspective: That’s how computer

programs put images (text, pictures,
video) on the screen: they write bits into
some display-oriented memory device.
This is rather hard to do in machine
language programming, but quite easy 3. Built-in Refresh action:
in high-level languages that write to the The emulator draws the
screen indirectly, using OS routines like corresponding pixels on the
printString or drawCircle, as we screen. In this case, 16 black
will see in chapters 9 and 12. pixels, one for each binary 1.
Since all high level programs and OS
routines are eventually translated into
machine language, they all end up
doing something like this example.

1. Select a word in the RAM region

that serves as the screen memory
map, e.g. address 16384 (the first
word in the screen memory map).
2. Enter a value, say –1
(1111111111111111 in binary)

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 16/40

Keyboard action demo

1. Click the keyboard enabler

2. Press some key on the
real keyboard, say “S”

3. Watch here:

Keyboard memory
map
(a single 16-bit
memory location)

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 17/40

Keyboard action demo

Perspective: That’s how computer

programs read from the keyboard: they
peek some keyboard-oriented memory
device, one character at a time.
This is rather tedious in machine Visual echo
language programming, but quite easy in (convenient AsGUI
long a key
high-level languages that handle the effect, not is pressed,
part of the
keyboard indirectly, using OS routines hardware platform)
like readLine or readInt, as we will see
in Chapters 9 and 12.
Since all high level programs and OS
routines are eventually translated into
machine language, they all end up doing
something like this example.

The emulator displays

Keyboard memory Its character code in the
map keyboard memory map
(a single 16-bit
memory location)

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 18/40

CPU Emulator Tutorial

Part III:
Interactive
Simulation

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 19/40

Loading a program

Navigate to a
directory and select
a .hack or .asm file.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 20/40

Loading a program

Can switch
from binary to
symbolic
representation

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 21/40

Running a program

4. Watch
here
2. Click the 1. Enter a
“run” button. number, 3. To speed up
say 50. execution,
use the speed
control slider

Program’s description: Draws a rectangle at the

top left corner of the screen. The rectangle’s width
is 16 pixels, and its length is determined by the
current contents of RAM[0].
Note: There is no need to understand the program’s
code in order to understand what’s going on.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 22/40

 Hack programming at a glance (optional)
Next instruction is M=-1.
Since presently A=17536, the next ALU
instruction will effect RAM[17536] =
1111111111111111. The 17536 address,
which falls in the screen memory map,
corresponds to the row just below the Program action:
rectangle’s current bottom. In the next screen Since RAM[0] happens to be 50,
refresh, a new row of 16 black pixels will be the program draws a 16X50
drawn there. rectangle. In this example the
user paused execution when
there are 14 more rows to draw.

Program’s description: Draws a rectangle at the

top left corner of the screen. The rectangle’s width
is 16 pixels, and its length is determined by the
current contents of RAM[0].
Note: There is no need to understand the program’s
code in order to understand what’s going on.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 23/40

Animation options

Controls execution
(and animation)
speed.

Animation control:
ƒ Program flow (default): highlights the
current instruction in the instruction memory
and the currently selected RAM location
ƒ Program & data flow: animates all
program and data flow in the computer
ƒ No animation: disables all animation
Usage tip: To execute any non-trivial program
The simulator can quickly, select no animation.
animate both program
flow and data flow

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 24/40

CPU Emulator Tutorial

Part IV:
Script-Based
Simulation

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 25/40

Interactive VS Script-Based Simulation
A program can be executed and debugged:
ƒ Interactively, by ad-hoc playing with the emulator’s GUI
(as we have done so far in this tutorial)
ƒ Batch-ly, by running a pre-planned set of tests, specified in a script.

Script-based simulation enables planning and using tests that are:

ƒ Pro-active
ƒ Documented
ƒ Replicable
ƒ Complete (as much as possible)

Test scripts:
ƒ Are written in a Test Description Language (described in Appendix B)
ƒ Can cause the emulator to do anything that can be done interactively,
and quite a few things that cannot be done interactively.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 26/40

The basic setting

test script
tested program

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 27/40

Example: Max.asm
Note: For now, it is not necessary to understand either the Hack
machine language or the Max program. It is only important to
grasp the program’s logic. But if you’re interested, we give a Hack language at a glance:
language overview on the right.
ƒ (label) // defines a label
//
// Computes
Computes M[2]=max(M[0],M[1])
M[2]=max(M[0],M[1]) wherewhere MM stands
stands for
for RAM
RAM
@0
@0 ƒ @xxx // sets the A register
D=M
D=M //
// DD == M[0]
M[0] // to xxx’s value
@1
@1
D=D-M
D=D-M //
// DD == DD -- M[1]
M[1] ƒ The other commands are self-
@FIRST_IS_GREATER
@FIRST_IS_GREATER explanatory; Jump directives
D;JGT
D;JGT //
// If
If D>0
D>0 goto
goto FIRST_IS_GREATER
FIRST_IS_GREATER like JGT and JMP mean “Jump
@1
@1 to the address currently stored
D=M
D=M //
// DD == M[1]
M[1] in the A register”
@SECOND_IS_GREATER
@SECOND_IS_GREATER
0;JMP
0;JMP //
// Goto
Goto SECOND_IS_GREATER
SECOND_IS_GREATER ƒ Before any command involving
(FIRST_IS_GREATER)
(FIRST_IS_GREATER) a RAM location (M), the A
@0
@0 register must be set to the
D=M
D=M //
// D=first
D=first number
number desired RAM address
(SECOND_IS_GREATER)
(SECOND_IS_GREATER) (@address)
@2
@2
M=D
M=D //
// M[2]=D
M[2]=D (greater
(greater number)
number) ƒ Before any command involving
(INFINITE_LOOP)
(INFINITE_LOOP) a jump, the A register must be
@INFINITE_LOOP
@INFINITE_LOOP // // Infinite
Infinite looploop (our
(our standard
standard set to the desired ROM
0;JMP // way to terminate programs).
0;JMP // way to terminate programs). address (@label).
CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 28/40
Sample test script: Max.tst
// The scripting language
// Load
Load the
the program
program and
and set
set up:
up:
load
load Max.asm,
Max.asm, has commands for:
output-file
output-file Max.out,
compare-to
Max.out,
Max.cmp, ƒ Loading programs
compare-to Max.cmp,
output-list
output-list RAM[0]%D2.6.2
RAM[0]%D2.6.2 ƒ Setting up output and compare files
RAM[1]%D2.6.2
RAM[1]%D2.6.2
RAM[2]%D2.6.2;
RAM[2]%D2.6.2;
ƒ Writing values into RAM locations

//
ƒ Writing values into registers
// Test
Test 1:
1: max(15,32)
max(15,32)
set RAM[0] 15,
set RAM[0] 15, ƒ Executing the next command (“ticktack”)
set
set RAM[1]
RAM[1] 32;
repeat 14 {
32; ƒ Looping (“repeat”)
repeat 14 {
ticktock;
ticktock; ƒ And more (see Appendix B).
}}
output;
output; // // to
to the
the Max.out
Max.out file
file Notes:

// ƒ As it turns out, the Max program requires 14

// Test
Test 2:
2: max(47,22)
max(47,22)
set
set PC
PC 0,
0, //
// Reset
Reset prog.
prog. counter
counter
cycles to complete its execution
set RAM[0] 47,
set RAM[0] 47,
set
ƒ All relevant files (.asm,.tst,.cmp) must
set RAM[1]
RAM[1] 22;
22;
repeat 14
repeat 14 { { be present in the same directory.
ticktock;
ticktock;
}} Output
output;
output;
|| RAM[0]
RAM[0] || RAM[1]
RAM[1] || RAM[2]
RAM[2] ||
// || 15
15 || 32
32 || 32
32 ||
// test
test 3:
3: max(12,12)
max(12,12)
// Etc. || 47
47 || 22
22 || 47
47 ||
// Etc.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 29/40

Using test scripts Speed
control

Load a
script

Script = a series of
simulation steps, each
ending with a semicolon;
Reset
Important point: Whenever an assembly
the script
program (.asm file) is loaded into the
emulator, the program is assembled on the
Pause
fly into the
machine language code, and this is
simulation
the code that actually gets loaded. In the
process, all comments and white space are
Execute step after from the code, and all symbols
removed
step repeatedly
resolve to the numbers that they stand for.

Execute the next

simulation step

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 30/40

The default script (and a deeper understanding of the CPU emulator logic)

If you load a program file without first

loading a script file, the emulator
loads a default script (always). The
Note that these run/stop buttons don’t
default script consists of a loop that
control the program. They control the
runs the computer clock infinitely.
script, which controls the computer’s
clock, which causes the computer
hardware to fetch and execute the
program’s instructions, one instruction
per clock cycle.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 31/40

CPU Emulator Tutorial

Part V:
Debugging

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 32/40

Breakpoints: a powerful debugging tool

The CPU emulator continuously keeps track of:

ƒ A: value of the A register
ƒ D: value of the D register
ƒ PC: value of the Program Counter
ƒ RAM[i]: value of any RAM location
ƒ time: number of elapsed machine cycles

Breakpoints:
ƒ A breakpoint is a pair <variable, value> where variable is one of
{A, D, PC, RAM[i], time} and i is between 0 and 32K.
ƒ 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.

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 33/40

Breakpoints declaration

2. Previously-
declared
breakpoints

1. Open the
breakpoints
panel

3. Add, delete,
or update
breakpoints

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 34/40

Breakpoints declaration

1. Select the system

variable on which you
want to break

2. Enter the value

at which the break
should occur

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 35/40

Breakpoints usage

1. New
breakpoint
2. Run the
program

3. When the A register will be 2, or

RAM[20] will be 5, or 12 time units
(cycles) will elapse, or RAM[21] will
be 200, the emulator will pause the
program’s execution with an
appropriate message.

A powerful debugging tool!

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 36/40

Postscript: Maurice Wilkes (computer pioneer) discovers debugging:

As soon as we started programming, we found to our

surprise that it wasn't as easy to get programs right
as we had thought. Debugging had to be discovered. I
can remember the exact instant when I realized that
a large part of my life from then on was going to be
spent in finding mistakes in my own programs.

(Maurice Wilkes, 1949).

CPU Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 37/40

 Assembler 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.idc.ac.il/tecs
This software was developed by students at the
Efi Arazi School of Computer Science at IDC
Chief Software Architect: Yaron Ukrainitz

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 1/22

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.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 2/22

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):
This tutorial is ƒ Used to build hardware platforms and
about the execute programs;
assembler
ƒ Supplied by us.

Translators (Assembler, JackCompiler):

ƒ Used to translate from high-level to low-level;
ƒ Developed by the students, using the book’s
specs;
The machine code Executable
generated by solutions supplied by us.
the assembler can be tested
either in theOther
hardware simulator
or in the CPU 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.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 3/22

Assembler Tutorial

I. Assembly program example

II. Command-level Assembler

III. Interactive Assembler

Relevant reading: Chapter 4: Machine and Assembly Language

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 4/22

Assembler Tutorial

Part I:
Assembly
Programming
at a Glance

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 5/22

Example
Sum.asm Sum.hack
//
// Computes
Computes sum=1+...+100.
sum=1+...+100. 0000000000010000
0000000000010000
@i
@i //
// i=1
i=1 1110111111001000
1110111111001000
M=1
M=1 0000000000010001
0000000000010001
@sum
@sum //// sum=0
sum=0 1110101010001000
1110101010001000
M=0
M=0 0000000000010000
0000000000010000
(LOOP)
(LOOP) 1111110000010000
1111110000010000
@i
@i //
// if
if (i-100)=0
(i-100)=0 goto
goto END
END 0000000001100100
0000000001100100
D=M
D=M 1110010011010000
1110010011010000
@100
@100 0000000000010010
0000000000010010
D=D-A
D=D-A Assembler 1110001100000001
1110001100000001
@END
@END 0000000000010000
0000000000010000
D;JGT
D;JGT 1111110000010000
1111110000010000
@i
@i //
// sum+=i
sum+=i 0000000000010001
0000000000010001
D=M
D=M 1111000010001000
1111000010001000
@sum
@sum 0000000000010000
0000000000010000
M=D+M
M=D+M 1111110111001000
1111110111001000
@i
@i //
// i++
i++ 0000000000000100
0000000000000100
M=M+1
M=M+1 1110101010000111
1110101010000111
@LOOP
@LOOP //// goto
goto LOOP
LOOP
0;JMP
0;JMP
(END)
(END) //
// infinite
infinite loop
loop
@END
@END
0;JMP
0;JMP

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 6/22

Example
Sum.asm
//
// Computes
Computes sum=1+...+100.
sum=1+...+100. The assembly program:
@i //
// i=1
@i
M=1
i=1 ƒ Stored in a text file named Prog.asm
M=1
@sum
@sum //// sum=0
sum=0 ƒ Written and edited in a text editor
M=0
M=0
(LOOP)
(LOOP)
@i
@i //
// if
if (i-100)=0
(i-100)=0 goto
goto END
END
D=M
D=M
@100
The assembly process:
@100
D=D-A
D=D-A ƒ Translates Prog.asm into Prog.hack
@END
@END
D;JGT ƒ Eliminates comments and white space
D;JGT
@i
@i //
// sum+=i
sum+=i ƒ Allocates variables (e.g. i and sum) to
D=M
D=M
@sum
memory
@sum
M=D+M
M=D+M ƒ Translates each assembly command
@i
@i //
// i++
i++ into a single 16-bit instruction written in
M=M+1
M=M+1 the Hack machine language
@LOOP
@LOOP //// goto
goto LOOP
LOOP
0;JMP
0;JMP ƒ Treats label declarations like (LOOP)
(END)
(END) //
// infinite
infinite loop
loop and (END) as pseudo commands that
@END
@END generate no code.
0;JMP
0;JMP

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 7/22

Assembler Tutorial

Part II:
Learn how to invoke the
supplied assembler from
the OS shell level.
(the assembler that you have
to write in project 6 should
have the same GUI and
behavior)

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 8/22

The command-level assembler

Display the
assembly source
code (contents of
the .asm text file)

We illustrate how to use the assembler

in the Windows command level (DOS);
The Unix way is similar.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 9/22

Inspecting the source file

Source
code is
shown

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 10/22

Invoking the Assembler

Invoke the Name of the file to be

assembler translated (argument of
program the assembler program).

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 11/22

Invoking the Assembler

Display the generated

machine code Two ways to test the generated
machine code:
1. Invoke the hardware simulator,
load the Computer.hdl chip, then
load the code (.hack file) into the
internal ROM chip;
2. Load and run the code in the
CPU emulator (much quicker).

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 12/22

Hardware Simulation Tutorial

Part III:

Learn how to use

the interactive
Assembler

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 13/22

Loading an assembly program

Navigate to a
directory and select
an .asm file.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 14/22

Loading an assembly program

ƒ Read-only view of the

assembly source code
ƒ To edit it, use an external
text editor.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 15/22

Translating a program

Immediate
translation
(no animation)

Start from the

beginning

Pause the
translation

Translate the
entire program

Translate
line-by-line

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 16/22

Inspecting the translation

2. The
1. Click an corresponding
assembly translated code
command is highlighted

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 17/22

Saving the translated code

Saves the
translated code
in a .hack file
ƒ The “save” operation is
enabled only if the
translation was error-free;
ƒ Otherwise, the translation
stops with an error
message.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 18/22

Using Compare Files

1. Load a
compare file

2. Select a compare
(.hack) file

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 19/22

Using Compare Files

2. Translate the
program (any
translation mode
can be used)

1. Compare file is
shown

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 20/22

Using Compare Files

The translation of
the highlighted line
does not match the
corresponding line
in the compare file.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 21/22

End-note: R. Feynman on why symbols don’t matter compared to their meaning

On weekends, my father would take me for walks in

the woods and he’d tell me about interesting things
that were going on. “See that bird?” he says. “It’s
a Spencer Warbler.” (I knew he didn’t know the real
name.) “Well, in Italian, it’s Chutto Lapittida. In
Portuguese, it’s a Bom da Peida. In Chinese, it’s a
Chung-long-tah, and in Japanese, it’s Katano Tekeda.
You can know the name of that bird in all the
languages of the world, but when you’re finished,
you’ll know absolutely nothing whatever about the
bird. You’ll only know something about people in
different places, and what they call the bird. So
let’s look at the bird and see what it is doing – that’s
what counts.” This is how I learned very early the
difference between knowing the name of something
and knowing something.

Richard P. Feynman, The Making of a Scientist, 1988.

Assembler Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 22/22

 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.idc.ac.il/tecs
This software was developed by students at the
Efi Arazi School of Computer Science at IDC
Chief Software Architect: Yaron Ukrainitz

VM Emulator Tutorial, www.idc.ac.il/tecs 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.idc.ac.il/tecs 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.idc.ac.il/tecs 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.idc.ac.il/tecs Tutorial Index Slide 4/34

VM Emulator Tutorial

Part I:
Getting Started

VM Emulator Tutorial, www.idc.ac.il/tecs 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.idc.ac.il/tecs 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.idc.ac.il/tecs 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 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.idc.ac.il/tecs Tutorial Index Slide 8/34

Running a Program

Navigate to a Script controls

directory and Default test script
select a .vm file 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.idc.ac.il/tecs Tutorial Index Slide 9/34

Running a Program

Impact of first
13 “vmsteps”

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 10/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.idc.ac.il/tecs Tutorial Index Slide 11/34

Loading a Multi-File Program

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 12/34

VM Emulator Tutorial

Part II:
Virtual Memory
Segments

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 13/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.idc.ac.il/tecs Tutorial Index Slide 14/34

VM Emulator Tutorial

Part II:
Using Scripts

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 15/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[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.idc.ac.il/tecs Tutorial Index Slide 16/34

Loading a Script

Navigate to a
directory and select
a .tst file.

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 17/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.idc.ac.il/tecs Tutorial Index Slide 18/34

Running the Script

The memory segments

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

A loop that
Impact after
executes the
first 10
loaded VM
commands
program
are executed

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 19/34

VM Emulator Tutorial

Part III:
Debugging

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 20/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.idc.ac.il/tecs Tutorial Index Slide 21/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.idc.ac.il/tecs Tutorial Index Slide 22/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.idc.ac.il/tecs Tutorial Index Slide 23/34

Breakpoints in Action
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.

Following some push

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

VM Emulator Tutorial, www.idc.ac.il/tecs Tutorial Index Slide 24/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.idc.ac.il/tecs Tutorial Index Slide 25/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.idc.ac.il/tecs Tutorial Index Slide 26/34