CPU Emulator Tutorial

This program is part of the software suite

that accompanies

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 Architect: Yaron Ukrainitz

CPU Emulator Tutorial, www.nand2tetris.org 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.nand2tetris.org 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
 Supplied by us.
CPU emulator.

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.nand2tetris.org 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.nand2tetris.org 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.nand2tetris.org 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.nand2tetris.org Tutorial Index Slide 6/40

CPU Emulator Tutorial

Part I:
Basic Platform

CPU Emulator Tutorial, www.nand2tetris.org 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.nand2tetris.org Tutorial Index Slide 8/40

The Hack Computer Platform

screen

data
memory
keyboard
instruction enabler
memory

registers ALU

CPU Emulator Tutorial, www.nand2tetris.org 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.nand2tetris.org 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.nand2tetris.org 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.nand2tetris.org 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.nand2tetris.org Tutorial Index Slide 13/40

CPU Emulator Tutorial

Part II:
I/O Devices

CPU Emulator Tutorial, www.nand2tetris.org 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.nand2tetris.org 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.nand2tetris.org 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.nand2tetris.org 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
high-level languages that handle the effect, not key
partisof
keyboard indirectly, using OS routines the hardwarepressed,
like readLine or readInt, as we will platform)
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 Its character code in the
memory map keyboard memory map
(a single 16-bit
memory location)

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 18/40

CPU Emulator Tutorial

Part III:
Interactive
Simulation

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 19/40

Loading a program

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

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 20/40

Loading a program

Can switch
from binary to
symbolic
representation

CPU Emulator Tutorial, www.nand2tetris.org 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.nand2tetris.org Tutorial Index Slide 22/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.nand2tetris.org Tutorial Index Slide 23/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.nand2tetris.org Tutorial Index Slide 24/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.nand2tetris.org Tutorial Index Slide 25/40

CPU Emulator Tutorial

Part IV:
Script-Based
Simulation

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 26/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.nand2tetris.org Tutorial Index Slide 27/40

The basic setting

test script
tested program

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 28/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
0;JMP //
// way
way toto terminate
terminate programs).
programs). address (@label).
CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 29/40
Sample test script: Max.tst
// The scripting language
// Load
Load the
the program
program and
and set
set up:
up:
load Max.asm,
load 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;  Writing values into RAM locations
RAM[2]%D2.6.2;
 Writing values into registers
//
// Test
Test 1:
1: max(15,32)
max(15,32)
set RAM[0]
set RAM[0] 15,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; // // toto 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 cycles to complete its execution
set PC 0, // Reset
PC 0, // Reset prog.
prog. counter
counter
set RAM[0] 47, 
set RAM[0] 47,
set
All relevant files (.asm,.tst,.cmp) must
set RAM[1]
RAM[1] 22;22; be present in the same directory.
repeat 14
repeat 14 { {
ticktock;
ticktock;
}} Output
output;
output; || RAM[0] || RAM[1]
RAM[1] || RAM[2]
|RAM[0]
|
RAM[2]
//
// test
test 3:
3: max(12,12)
max(12,12) || 15
15 || 32
32 || 32
32
||
// Etc.
// Etc. || 47
47 || 22
22 || 47
47 ||
CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 30/40
Using test scripts

Load a
script

Interactive loading of the tested

program itself (.asm or .hack file)
is typically not necessary, since
test scripts typically begin with a
“load program” command.

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 31/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
removed from the code, and all symbols
after step resolve to the numbers that they stand for.
repeatedly
Execute the next
simulation step

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 32/40

Using test scripts

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

When the script terminates, the

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

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 33/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.nand2tetris.org Tutorial Index Slide 34/40

CPU Emulator Tutorial

Part V:
Debugging

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 35/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.nand2tetris.org Tutorial Index Slide 36/40

Breakpoints declaration

2. Previously-
declared
breakpoints

1. Open the
breakpoints
panel

3. Add, delete,
or update
breakpoints

CPU Emulator Tutorial, www.nand2tetris.org Tutorial Index Slide 37/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.nand2tetris.org Tutorial Index Slide 38/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.nand2tetris.org Tutorial Index Slide 39/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.nand2tetris.org Tutorial Index Slide 40/40