1. Slide 1/39Hardware Simulator TutorialTutorial Index 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, www.idc.ac.il/csdwww.idc.ac.il/csd This software was developed by students at the Efi Arazi School of Computer Science at IDC Chief Software Architect: Yaron Ukrainitz Hardware Simulator Tutorial

2. Slide 2/39Hardware Simulator TutorialTutorial Index The Elements of Computing Systems (TECS) The TECS book is based on a constructive approach to learning computer science. The book evolves around the construction of a complete computer platform, done in the framework of a 1- or 2-semesters course. In the first part of TECS, the students build all the logic gates and chips-set of a simple yet powerful computer, called Hack. This is done using HDL (Hardware Description Language) and a hardware simulator, supplied with the book. In the second part of TECS, the students build the computers software hierarchy, consisting of an assembler, a virtual machine, a Java-like language called Jack, a compiler for it, and a simple operating system, written in Jack. TECS is completely self-contained, requiring only programming as a pre-requisite.

3. Slide 3/39Hardware Simulator TutorialTutorial Index 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 built after the JVM paradigm. Simulators: used to build hardware platforms and execute programs; supplied by us. Translators: Used to translate from high- level to low- level Written by the students (Executable solutions available). The books software suite:

4. Slide 4/39Hardware Simulator TutorialTutorial Index The books software suite: This tutorial describes the Hardware simulator.

5. Slide 5/39Hardware Simulator TutorialTutorial Index Hardware Simulation Tutorial Purpose: learn how to use the simulator with which all the chips specified in the book can be built Required knowledge: Chapter 1 of the book Recommended: Appendix A + Appendix B of the book. Contents: I. Getting startedGetting started II. Test scriptsTest scripts III. Built-in chipsBuilt-in chips IV. Clocked chipsClocked chips V. Debugging toolsDebugging tools

6. Slide 6/39Hardware Simulator TutorialTutorial Index Hardware Simulation Tutorial Part I: Getting Started

7. Slide 7/39Hardware Simulator TutorialTutorial Index Loading a chip 1. To load a new chip description, click the Load Chip button. 2. Navigate to a directory and select an.hdl file.

8. Slide 8/39Hardware Simulator TutorialTutorial Index Loading a chip Names and current values of the chips input pins May be changed by the user. Read-only view of the loaded.hdl file Defines the chip logic To edit it, use an external text editor. Names and current values of the chips output pins Calculated by the simulator; read-only. Names and current values of the chips internal pins (Used in the chip logic to connect the chips parts) Calculated by the simulator; read-only.

9. Slide 9/39Hardware Simulator TutorialTutorial Index Chip interface // Exclusive-or gate. CHIP Xor { IN a,b; OUT out; // implementation missing } // Exclusive-or gate. CHIP Xor { IN a,b; OUT out; // implementation missing } Chip interface: Name of the chip Names of all the input and output pins Description of the intended chip operation Supplied by the chip architect; Similar to an API, or a contract.

10. Slide 10/39Hardware Simulator TutorialTutorial Index Chip implementation // Exclusive-or gate. CHIP Xor { IN a,b; OUT out; PARTS: Not(in=a,out=Nota); Not(in=b,out=Notb); And(a=a,b=Notb,out=w1); And(a=Nota,b=b,out=w2); Or(a=w1,b=w2,out=out); } // Exclusive-or gate. CHIP Xor { IN a,b; OUT out; PARTS: Not(in=a,out=Nota); Not(in=b,out=Notb); And(a=a,b=Notb,out=w1); And(a=Nota,b=b,out=w2); Or(a=w1,b=w2,out=out); } Can be implemented by an HDL programmer in several ways This particular implementation is based on the Boolean expression Xor(a,b) = Or(And(a,Not(b)), And(b,Not(a))) The internal parts (Not, And, Or) are connected using internal pins, created and named by the HDL programmer (e.g. Nota, Notb, w1, w2 ).

11. Slide 11/39Hardware Simulator TutorialTutorial Index Exploring the chip structure 1. Click the PARTS keyword 2. A table pops up, showing all the chips internal parts (lower- level chips) and whether they are primitive/composite and clocked/unlocked.

12. Slide 12/39Hardware Simulator TutorialTutorial Index 1. Click one of the chip PARTS 2. Another table pops up, showing the input/output pins of the selected part, along with their current values; A convenient debugging tool. Exploring the chip structure

13. Slide 13/39Hardware Simulator TutorialTutorial Index Manual chip testing 1. User: changes the values of some input pins 2. Simulator: responds with 2 cues: The output and internal pins will be darkened, to indicate that the displayed values are no longer valid The Eval button will be enabled.

14. Slide 14/39Hardware Simulator TutorialTutorial Index Manual chip testing 1. User: changes the values of some input pins 2. Simulator: responds with 2 cues: The output and internal pins are darkened, to indicate that the displayed values are no longer valid The Eval button is enabled. Re- calc 3. User: Clicked the Eval button 4. Simulator: re-calculates the values of the output and internal pins according to the chip logic, applied to the current input values

15. Slide 15/39Hardware Simulator TutorialTutorial Index Hardware Simulation Tutorial Part II: Test Scripts

16. Slide 16/39Hardware Simulator TutorialTutorial Index Test scripts load Xor.hdl, output-file Xor.out, compare-to Xor.cmp, output-list a%B3.1.3 b%B3.1.3 out%B3.1.3; set a 0, set b 0, eval, output; set a 0, set b 1, eval, output; load Xor.hdl, output-file Xor.out, compare-to Xor.cmp, output-list a%B3.1.3 b%B3.1.3 out%B3.1.3; set a 0, set b 0, eval, output; set a 0, set b 1, eval, output; Good for pro-active, automated and replicable chip testing Supplied with each chip definition Using script commands, can effect anything that can be done interactively Written in a simple language described in Appendix B of the book A test script can create an output file that records the results of the chip test If a compare file is supplied, the simulator will compare the generated outputs to the desired outputs, line by line. | a | b | out | | 0 | 0 | 0 | | 0 | 1 | 1 | | 1 | 0 | 1 | | 1 | 1 | 0 | | a | b | out | | 0 | 0 | 0 | | 0 | 1 | 1 | | 1 | 0 | 1 | | 1 | 1 | 0 |

17. Slide 17/39Hardware Simulator TutorialTutorial Index Loading a script To load a script file, click the Load Script button It is not necessarily required to load a chip first, since the script may contain a load chip command.

18. Slide 18/39Hardware Simulator TutorialTutorial Index Script controls Executes the next simulation step Executes step after step repeatedly Pauses the simulation Resets the script Controls the script execution speed Logical simulation steps, each ending with a semicolon.

19. Slide 19/39Hardware Simulator TutorialTutorial Index Running a script Typical scripts init code: 1.Loads Xor.hdl 2.Initializes Xor.out 3.Instructs to compare to Xor.cmp 4.Declares an output line format Script exec- ution flow

20. Slide 20/39Hardware Simulator TutorialTutorial Index Script exec- utionends Running a script

21. Slide 21/39Hardware Simulator TutorialTutorial Index Output and Compare files To view the generated output file or the compare file, choose Output or Compare from the View button. When the script execution ends, the simulator reports the comparison results between the output file and the compare file.

22. Slide 22/39Hardware Simulator TutorialTutorial Index Conclusion: the chip logic (Xor.hdl) is apparently well-defined. Output and Compare files Observation: This output file looks like the Xor truth table

23. Slide 23/39Hardware Simulator TutorialTutorial Index Hardware Simulation Tutorial Part III: Built-in Chips

24. Slide 24/39Hardware Simulator TutorialTutorial Index Built-In chips General A built-in chip has an HDL interface and a Java implementation (e.g. Xor.class) The name of the Java class is specified following the builtin keyword Built-In versions of all the chips discussed in the book are supplied with the HW simulator. // Xor gate (builtin) CHIP Xor { IN a,b; OUT out; BUILTIN Xor; } // Xor gate (builtin) CHIP Xor { IN a,b; OUT out; BUILTIN Xor; } Objectives Built-in chips are used to: Implement primitive chips (Nand, DFF) Implement chips that have peripheral side effects (like I/O hardware drivers) Implement chips that feature a GUI (for debugging) Replace chips that the user didnt implement for one reason or another Improve simulation speed and save memory (when used as parts in complex chips) Test a chip before it is built in HDL Facilitate behavioral simulation of the entire hardware architecture.

25. Slide 25/39Hardware Simulator TutorialTutorial Index Loading a built-in chip 2. Built-in chip. Can be tested or used as a part in other chips just like any other chip, without having to write it first. 1. Built-in versions of all the chips mentioned in the book are stored in the BuiltIn directory.

26. Slide 26/39Hardware Simulator TutorialTutorial Index 2. If the loaded chip, or one or more of its parts, have GUI side-effects, the simulator displays the GUIs here. Built-in chips with GUI effects GUI of built-in Screen chip GUI of built-in RAM16K chip GUI of built-in Keyboard chip 1. A chip whose parts include built- in chips was loaded into the simulator

27. Slide 27/39Hardware Simulator TutorialTutorial Index Using built-in chips as internal parts // demo GUI-empowered chips CHIP GUIDemo { IN in[16],load,address[15]; OUT out[16]; PARTS: RAM16K(in=in,load=load,address=address[0..13],out=null); Screen(in=in,load=load,address=address[0..12],out=null); Keyboard(out=null); } // demo GUI-empowered chips CHIP GUIDemo { IN in[16],load,address[15]; OUT out[16]; PARTS: RAM16K(in=in,load=load,address=address[0..13],out=null); Screen(in=in,load=load,address=address[0..12],out=null); Keyboard(out=null); } RAM16K, Screen, Keyboard: built-in chips with GUI side-effects Effect: When the simulator evaluates this chip, it displays the GUI side- effects of the built-in chip parts This particular chip: The only purpose of this chip is to force the simulator to show the GUI of these built-in chips. Other than that, the chip logic is meaningless: it simultaneously feeds the data input (in) into the RAM16K and the Screen chips, and it does nothing with the keyboard.

28. Slide 28/39Hardware Simulator TutorialTutorial Index 4. The logic of these chips is described in Chapter 5 in the book (Computer Architecture). 3. 16 black pixels are drawn in row=156 col=320 3. The –1 constant is seen in the RAM16K chips GUI 1. User enters: In = –1 (=16 1s in binary) address=5012 Load = 1 2. Similar to theEval button. More about this soon Built-in chips with GUI effects

29. Slide 29/39Hardware Simulator TutorialTutorial Index Hardware Simulation Tutorial Part IV: Clocked Chips (Sequential Logic)

30. Slide 30/39Hardware Simulator TutorialTutorial Index Clocked chips The implementation of clocked chips is based on sequential logic The operation of clocked chips depends on the state of the computers internal clock: Clock cycle = Tick phase (down), followed by a Tock-phase (up) During a Tick-Tock, the internal state of the clocked chip changes, but its output dont change yet At the beginning of the next Tick, the outputs of the clocked chip commit to the new values In real computers, the clock is implemented by an oscillator In simulators, the clock cycles can be simulated either manually by the user, or automatically by a test script.

31. Slide 31/39Hardware Simulator TutorialTutorial Index The D-Flip-Flop chip (DFF) // D-Flip Flop. CHIP DFF { IN in; OUT out; BUILTIN DFF; CLOCKED in,out; } // D-Flip Flop. CHIP DFF { IN in; OUT out; BUILTIN DFF; CLOCKED in,out; } The DFF chip: A primitive, built-in gate All the clocked chips are based on low-level DFFs DFF Functionality: While the clock does a tick-tock, the DFF sets its internal state to the value of its input pin Exactly when the next tick-tock starts, the DFF sets its output pin to the value of its internal state. Clocked input pin: changes in its value will effect the chip outputs only in next clock cycle Clocked output pin: can change its value only at the next clock cycle The simulator knows that the loaded chip is clock-dependent when: One or more of its pins is declared clocked, or: One or more of its parts (or sub-parts) is a clocked chip

32. Slide 32/39Hardware Simulator TutorialTutorial Index Running the clock manually First click (Tick): the chips internal state changes to reflect the new inputs Second click (Tock): the chips output will commit to the new state (this screen shot was taken after a a tick and a tock). Built-in, clocked chip (RAM8) GUI of the built- in RAM8 chip

33. Slide 33/39Hardware Simulator TutorialTutorial Index Running the clock automatically 2. single-action tick-tock 2. Tick-tocks repeatedly and infinitely. Useful when simulating clock-regulated chips, like the program counter (PC) or the CPU. 2. Controls the script speed, and thus the simulated clock speed. 1. Default script: always loaded when the simulator starts running.

34. Slide 34/39Hardware Simulator TutorialTutorial Index Hardware Simulation Tutorial Part V: Debugging tools

35. Slide 35/39Hardware Simulator TutorialTutorial Index Directory structure (.hdl,.tst,.out,.cmp) // Xor.tst: typical test script load Xor.hdl, output-file Xor.out, compare-to Xor.cmp, set a 0, set b 0, eval, output; // Etc. // Xor.tst: typical test script load Xor.hdl, output-file Xor.out, compare-to Xor.cmp, set a 0, set b 0, eval, output; // Etc. All the HDL files, test scripts, and comparison files related to the same chip must be placed in the same directory When a chip or a script file is loaded, the simulator assumes that all the other files relevant to that chip or script are in the same directory as that of the loaded file. CHIP Xor { IN a, b; OUT out; PARTS: Not(in=a,out=Nota); Not(in=b,out=Notb); And(a=a,b=Notb,out=aNotb); And(a=Nota,b=b,out=bNota); Or(a=aNotb,b=bNota,out=out); } CHIP Xor { IN a, b; OUT out; PARTS: Not(in=a,out=Nota); Not(in=b,out=Notb); And(a=a,b=Notb,out=aNotb); And(a=Nota,b=b,out=bNota); Or(a=aNotb,b=bNota,out=out); } When an HDL file is loaded, the simulator looks for the HDL files of its internal parts in the same directory as that of the loaded file If the.hdl file of an internal part is not found, the simulator invokes its built- In version instead (only if the part is one of the chips specified in the book).

36. Slide 36/39Hardware Simulator TutorialTutorial Index System variables The simulator recognizes and maintains the values of 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 their HDL names, e.g. a, b, out, Nota, Notb, etc. in the case of the Xor implementation presented earlier in this tutorial GUI elements: the values stored in the contents of built-in chips with GUI can be accessed via variables with proper names. For example, the value of register 3 of the RAM8 chip can be accessed via RAM8[3]. These variables can be used in scripts and breakpoints, for debugging.

37. Slide 37/39Hardware Simulator TutorialTutorial Index Breakpoints The breakpoints logic: Breakpoint = variable name and value When the specified variable in some breakpoint reaches its specified value, the script pauses and a message is displayed A powerful debugging tool. To update an existing breakpoint, double-click it to add and remove breakpoints, use the +/- buttons

38. Slide 38/39Hardware Simulator TutorialTutorial Index Test scripts of complex chips load Computer.hdl rom-load max.hack, output-file ComputerMax.out, compare-to ComputerMax.cmp, output-list RAM[0]%D2.6.2 RAM[1]%D2.6.2 RAM[2]%D2.6.2, breakpoint PC 10; set RAM[0] 15, set RAM[1] 32; repeat 14 { tick, tock; } output; set PC 0, set RAM[0] 47, set RAM[1] 22; while PC<13 { tick, tock; } output; Clear-breakpoints; load Computer.hdl rom-load max.hack, output-file ComputerMax.out, compare-to ComputerMax.cmp, output-list RAM[0]%D2.6.2 RAM[1]%D2.6.2 RAM[2]%D2.6.2, breakpoint PC 10; set RAM[0] 15, set RAM[1] 32; repeat 14 { tick, tock; } output; set PC 0, set RAM[0] 47, set RAM[1] 22; while PC<13 { tick, tock; } output; Clear-breakpoints; Users may write their own test scripts, according to specific debugging needs Scripts that test the CPU chip or the computer chip usually start by loading a machine-language program into the ROM chip The rest of the script typically uses various features like: Output tables Loops Breakpoints Variables manipulation Tick, Tock Etc. All these features are described in Appendix B of the book.

39. Slide 39/39Hardware Simulator TutorialTutorial Index Visual options Script: displays the current script Output: displays the output file Compare: displays the comparison file Screen: displays the GUI effects of built-in chips, if any. Program flow: animates the flow of the current ROM-resident program Program & data flow: animates the flow of the current program and the data flow throughout the GUI elements displayed on the screen No animation (default) : program and data flow are not animated. Tip: When running programs, any animation effects slow down the simulation considerably. Format of displayed pin values: Decimal (default) Hexadecimal Binary

40. Slide 40/39Hardware Simulator TutorialTutorial Index Postscript: 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).