1. Virtual Machine 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
Forthcoming in 2003 by MIT Press,
The software suite was developed by students at the
Efi Arazi School of Computer Science at IDC
Chief Software Architect: Yaron Ukrainitz

2. Disclaimer This tutorial is both out of date and incomplete.
At the same time, it will help you get started with the VM Emulator program available in the book site.
There is no need to report errors found in this tutorial, since it is work in progress.

3. The book’s software suite
Translators:
Used to translate from high-level to low-level
Written by the students
(Executable solutions available).
Simulators:
used to build hardware platforms and execute programs;
supplied by us.
Simulators:
Hardware Simulator: used to build and simulate all the gates and chips specified in the book, from elementary logic gates to the CPU;
CPU Emulator: used to give an animated simulation of the Hack computer – the hardware platform built in the book;
VM Emulator: used to give an animated simulation of the Hack VM – a stack-based virtual machine implementation built after the JVM paradigm.

4. The book’s software suite:
Alternatively, the VM code generated by the compiler can be emulated by the VM Emulator (fastest).
The VM code can can be translated by JcVM (a VM Translator) into machine language programs that can be executed either on the Hack hardware (slow) or on the CPU Emulator (faster);
Programs written in the Jack language are compiled into VM code;
Benefits of VM emulation: platform independent, speeds up debugging, leads to better understanding of the virtual machine internals.

5. Presentation Objective
Learn how to use the VM Emulator for simulating the execution of virtual machine programs.

6. VM objects and their GUI
Virtual memory segments
Of the VM’s eight segments:
Six segments have GUI
The constant and pointer segments have no GUI
VM code (one or more functions). The index on the left is the command location within the function. It is not part of the code.

7. VM components Static variables of the current class
Local variables of the current function
Arguments of the current function
VM code (one or more functions). The index on the left is the command location within the function. It is not part of the code.
General purpose segments through which VM programs can manipulate selected locations in the heap.

8. Objects that are either implicit or external to the VM
I/O devices of the host platform: screen and keyboard
Working stack: topmost part of the stack, as seen by the current function
Global stack: Maintained by the VM implementation
RAM of of the host platform, stores the virtual registers, the stack, the heap, and memory-maps of I/O devices.
Call stack:
A conceptual control tool (not part of the VM). Lists all the currently executing functions, from Sys.init to the current function.

9. Loading and handling a program
Click one of the “open” buttons, and navigate to the program’s directory
Clear the code
Find a given command in the code
A VM program is a collection of VM files, stored in one directory

10. Testing using the default script
The emulator’s default script executes commands from the VM program in an infinite loop

11. Testing programs using test scripts
rom-load \,
output-file output,
output-list SP%D2.4.2
CurrentFunction%S1.15.1
Argument[0]%D3.6.3
RAM[256]%D2.6.2;
VMStep,
output;
repeat 3 { }
repeat 200 {
A test script is usually designed to test a specific program.
Can create an “output dump” of the test results.
Along with the script, a comparison file is sometimes supplied, to which the output is compared.
All relevant files (.prg, .tst, .cmp) should be in the same directory.
| SP | CurrentFunction |Argument[0] | RAM[256] |
| | Sys.init | | |
| | Math.fibonacci | | |
| | Sys.init | | |

12. Testing programs using test scripts (cont.)
Use the control buttons to run the script
To view the output results or the comparison file, select “output” or “compare” from the “view" box
Load the script
When the script ends, the comparison results are reported
Program execution stops automatically when a comparison failure occurs

13. Debugging tool: Breakpoints
this: The base address of the this segment.
this[i]: The contents of the this segment at i.
that: The base address of the that segment.
that[i]: The contents of the that segment at i.
temp[i]: The contents of the temp segment at i.
To update an existing breakpoint, double click it
Use the + and - buttons to add and remove breakpoints
To open the breakpoints panel, click the breakpoints button
When the variable reaches the specified value, a message is displayed.
A breakpoint consists of a variable name and a specified value
A powerful debugging tool

14. Visual options Select one of the animation options:
Program flow: animates only the program flow in the ROM.
Program & data flow: animates all program and data flow in the computer.
No animation: program and data flow are not animated.
When running long programs, choose No animation. The GUI will not be updated during simulation, increasing execution speed.
To control animation speed, use the speed slider.
Select one of the additional view options:
Script: shows the current script.
Output: shows the output file.
Compare: shows the comparison file.
None: Shows the simulated computer only.
Select the desired numeric format:
Decimal, Hexadecimal or Binary.

15. VM components
VM programs have full control over the computer’s I/O devices (in Hack: screen and keyboard)
The VM Emulator features precisely the same I/O devices available in the Hack computer platform.
Simulated screen: 256 rows of 512 black & white pixels. The pixels are continuously refreshed from respective bits in an 8K memory-map, located at RAM[16384] - RAM[24575].
Simulated keyboard: Must be activated (by clicking this button) to intercept the user’s keystrokes on the real keyboard. Updates a single-word memory map located in RAM[24576].

16. About tool making
In software ... a tool to solve a particular problem often becomes a general solution. And the tools themselves take on a life of their own, and sometimes the original project is forgotten. It would be as if a person set out to build a house, before the hammer was invented, and then decides that something like a hammer would be a useful tool – and so designed a hammer. The person then decides that perhaps nails, and maybe a saw, would be neat to have as well. So mired in tool-making, the person never gets around to building that particular house, but the tools can be used by others to build countless houses.“
From “GOTO,” by Steve Lohr, 2001