Programming and Debugging in LC-2 - Windows version

Where to find the LC-2 Simulator

• Working from home


You will need to download the simulator. Go to the "Useful Software and Documentation" section of the course homepage. There's a link to the simulator, click on it. The computer will as you whether to save or run the file. Save the file to an appropriate place on your hard disk. After download is complete, go to that place and double-click on the LC2.exe icon. This will open up the "Winzip Self Extractor" program which asks you where you want to put the simulator files. Again, select an appropriate directory and click on "Unzip". If you see a success message, then you can be sure that LC-2 simulator is installed in the directory you have just specified.

You need to have Winzip installed on your computer to be able to install the LC-2 simulator. If you don't have it go to http://www.winzip.com to download it.
 

• Working in the LRC


Go to one of the LRC Windows machines. Double click on the following icons. "My Computer -> LRCApps -> ee379k -> lc2"

How to write your programs

LC2Edit.exe

• Writing in machine language


If you are writing in machine language you have two options:
• Using the binary format for instructions
• Using the hexadecimal format for instructions

 
• How to write in binary format


If you are writing in binary format, your instructions should consist of 0's and 1's. For example an ADD instruction that adds R1 and R2 and stores the result in R3 would look like:

0001011001000010

You can also type the same instruction as:

0001 011 001 000 010

This makes the fields of the instruction more meaningful, and your program will be easier to debug.

First line of your program

The first line of your program must contain the starting address of where your program is to be loaded into memory. For example, if you want the simulator to load your program starting from memory address x3000, the first line of your program should contain

0011 0000 0000 0000

Adding comments to your program

You can add comments to your program by using the semi-colon , ";". Any text entered after a semi-colon will be ignored by the convert program which you will use to convert your program to a format that is readable by the LC-2 simulator. An example:

0101 001 010 000 011  ; and R2 and R3, store result in R1

A sample program in LC-2 machine language (in binary format) The following program OR's the contents of register 1 and register 2 and puts the result in register 3.

0011 0000 0000 0000   ; start at x3000
1001 100 001 111111   ; R4 <- not(R1)
1001 101 010 111111   ; R5 <- not(R2)
0101 110 100 000 101  ; R6 <- (R4) and (R5)
1001 011 110 111111   ; R3 <- not(R6) 
1111 0000 00100101    ; trap x25 (halt)

Type in this program into the LC2Edit window and skip the next section on hexadecimal format unless you want to learn about the hexadecimal format.
 
• How to write in hexadecimal format


If you are writing in hexadecimal format each instruction will consist of four hex digits. That is the only difference of the hex format from the binary formats. Again, you are supposed to put the starting address of where your program is to be loaded into memory as the first line of your program. You can comment your code the same way you did in binary format.

A sample program in LC-2 machine language (in hex format) This is the same sample program we used to illustrate the binary format.

3000   ; start at x3000
987f   ; R4 <- not(R1)
9abf   ; R5 <- not(R2)
5d05   ; R6 <- (R4) and (R5)
97bf   ; R3 <- not(R6) 
f025   ; trap x25 (halt)

Note that you cannot put x's in front of the instructions (x987f is not an acceptable format). Also note that you cannot mix the binary and hex formats, that is you cannot write some instructions in binary and some instructions in hex. Hex digits a, b, c, d, e, f can be uppercase or lowercase as you wish.


• Converting your program written in machine language


LC-2 simulator accepts programs in a certain binary format. So that you can run your programs on the LC-2 simulator you need to convert your program (which you wrote in plain text format) into the simulator's format. This can be done using the LC2Edit program that you have been using.
 
• Converting from binary format


If you have written your program in binary format, first save your program. Click on

File

on the menubar and then click on

Save As...

In the window that pops up type in

myprog.bin

as the name of your program and click the "OK" button. The ".bin" extension specifies that your program is written in binary format.

Now, to convert it into a format that can be understood by the LC-2 simulator click on

Translate

on the menubar and select the

Convert Base 2

option. In the lower part of the LC2Edit window you will see error messages if there are any. If not, a file named

myprog.obj

will be created in the same directory you are working in. This is the file you need to load into the simulator.
 
• Converting from hex format


If you have written your program in hex format, you need to save your program first. Click on

File

on the menubar and then click on

Save As...

In the window that pops up type in

myprog-hex.hex

as the name of your program and click the "OK" button. The ".bin" extension specifies that your program is written in binary format.

Now, to convert it into a format that can be understood by the LC-2 simulator click on

Translate

on the menubar and select

Convert Base 16

option. In the lower part of the LC2Edit window you will see error messages if there are any. If not, a file named

myprog-hex.obj

will be created in the same director you are working on. That is the file you need to load into the simulator.
 
• Writing in assembly language


In the LC2Edit program, type in your assembly program.

A sample program in LC-2 assembly language. This is the same sample program illustrated above in machine language.
 

.ORIG x3000    ; start at x3000
NOT R4, R1     ; R4 <- not(R1)
NOT R5, R2     ; R5 <- not(R2)
AND R6, R4, R5 ; R6 <- (R4) and (R5)
NOT R3, R6     ; R3 <- not(R6)
HALT           ; trap x25 (halt)
.END
 
• Converting your program written in assembly language


First save your program. Click on

File


on the menubar and then click on

Save As...


In the window that pops up type in

myprog.asm


as the name of your program and click on the "OK" button. The ".asm" extension specifies that your program is written in assembly format.
Now, to convert it into a format that can be understood by the LC-2 simulator, click on
 
Translate


on the menubar and select the
 
Assemble


option. In the lower part of the LC2Edit window you will see error messages if there are any. If not, a file named
 
myprog.obj


will be created in the same directory you are working in. This is the file you need to load into the simulator.

How to Run the LC-2 Simulator

Simulate.exe

• Loading your program into the simulator


By now you should have converted your program into a format readable by the LC-2 simulator. To load he program into the simulator click on the

File

menu on the menu bar of the "LC2 Simulator" window. The menu will drop down and you will see several options. Click on the

Load Program...

option. A file selection box will pop up. Find the file you want to load into the simulator (e.g. myprog.obj). Highlight it by clicking on it and then click on "Open". You will see that the memory of LC-2 will be loaded with 1's and 0's. These are the instructions in your program. For example, if you have loaded the program we demonstrated above and converted, the first few lines of the memory on the simulator will be

x3000 1001100001111111  x987f        ; not       R4, R1
x3001 1001101010111111  x9abf        ; not       R5, R2
x3002 0101110100000101  x5d05        ; and       R6, R4, R5
x3003 1001011110111111  x97bf        ; not       R3, R6
x3004 1111000000100101  xf025        ; trap      $25
x3005 0000000000000000  x0000        ; brnop     $3000
x3006 0000000000000000  x0000        ; brnop     $3000
x3007 0000000000000000  x0000        ; brnop     $3000

The numbers in brackets represent the hex address of the location and its contents. In this case memory location x3000 contains the not instruction we wrote previously. Instructions are given in three formats, binary, hex, and assembly to make it easier to debug.

Now we have successfully loaded our simple program into LC-2's memory. Let's try running and debugging it.
 

• Running your program


To test your program you might want to set the values of some registers and memory locations before you execute your program. You can do this by clicking on the

Simulate

on the menubar. Then click on

Set Value...

A window will pop up. In this window you can enter any memory location and any register and a value you want to be placed in that memory location or register. As our program OR's the values in registers 1 and 2, let's put some values into those registers before running our program. To do this type "R1" (without the quotes) into the box corresponding to Location. Let's set R1's value to 1. Type x0001 in the box corresponding to Value. Click "OK" after you fill in the appropriate values. In the top part of the simulator window you'll see that R1 contains x0001. This means that you've successfully set R1. To set R2, follow the same steps and put x0011 into R2.

To test this simple program you do not need to set any memory locations. But to test your programs you probably will. To do this again click on "Simulate" on the menu bar. Then click on "Set Value". In the box for "Location" put the memory address you want to set (for example x3200). In the "Value" box type the value you wish to be put in that location in memory (for example xFFAD). Click "OK" or press enter to set that memory location. Now in your screen you probably cannot see the contents of memory location x3200. In order to see whether you have set that location, you can scroll down the Memory part of the simulator window using the scroll bar on the right. You can do this by sliding the scroll bar down until you see the memory location you want to observe.

Running the Program

Now we have all the values ready to test if our program is working. What would you expect to be stored in R3 if you run this program in this setting? As this program is supposed to OR registers R1 and R2, you would expect that the value of R3 after the end of the execution of program would be x0011. (Verify that x0001 OR x0011 = x0011). To see whether this is the case click on

Execute

on the menubar. Then click on

Run

Some changes will happen in the Registers. Verify that final result stored in R3 is x0011.

Stepping Through Your Program

Now you have just learned how to run a program on LC-2. A more useful tool for debugging (finding the errors in the program) your program is stepping through the instructions in your program. This means that you run one instruction at a time and observe the changes each instruction makes in the LC-2. This way you can find problems in the individual instructions and you can exactly pinpoint the place where something goes wrong in the program. Let's give this a try. But first let's reinitialize the LC-2 and load our program again. To do that, click on

File

on the menu bar. Then click on

Reinitialize Machine

to zero out all the registers and memory locations. Now following the steps you learned, load the program into LC-2 again and set R1 to be x0001 and R2 to be x0011. To step through your program instruction by instruction click on "Run" on the menu bar and then click on

Execute

on the menubar and then click on

Step Over

The LC-2 Simulator will execute the currrent instruction and stop before executing the next one. Note that the blue arrow is now pointing to the next instruction of your program. That blue arrow follows the PC. Now you can observe the state of the machine. LC-2 has just executed the first instruction. The result of the first instruction is stored in the destination register designated by that instruction (R4). Verify that the value in R4 is the complement of the value in R1. This was exactly what the first instruction supposed to do. You can now step again and observe the effects of the second instruction. Notice the changes in registers R0 through R7 and also PC, IR, and Condition Codes. Are they what you would expect from the instruction? (they'd better be :) )

If you are already tired of stepping instruction by instruction you can click on "Run" in the "Execute" menu to execute rest of the instructions until the end of your program. If not you can step your program until you reach the end.

Making Life Easier: Using Breakpoints

You write a program and you are sure that some part is working and you do not want to step one by one all those instructions that you are sure are working. LC-2 simulator gives you the option to use breakpoints so that you don't have to step through all instructions in your program. The idea is, you set a breakpoint at some instruction in your program and when you run your program, the LC-2 simulator will execute all the instructions up to that breakpoint and stop at the breakpoint so that you can observe what has happened until then. You can set multiple breakpoints in your program. When you run the program, the LC-2 simulator will execute the instructions between two breakpoints and stop at each breakpoint encountered. Let's see how you can set a breakpoint in our program. First reinitialize the machine and load our program again into the LC-2 simulator. Set the value of R1 to x1100 and R2 to x0011. Now, to set a breakpoint click on "Simulate" on the menu bar. Then click on
 

Breakpoints...


A window asking you the address of the instruction you want to put the breakpoint at will pop up. Using that window, you can set and remove breakpoints and see the list of current breakpoints in the program. Let's set a breakpoint at the AND instruction. Type "PC" (without quotes) into the "Location" box. Then type x3002 in the value box. (This tells the simulator to stop the execution of the program if PC equals x3002. You can set a breakpoint for registers or memory locations, in which case the execution of the program will stop if a register or memory location is assigned a specific value). Click on "Add" button. You will see a red circle appearing next to the memory location x3002 in the Simulator window. This indicates that there's a breakpoint at that location. Now, when you run your program the execution will stop before the processing of that instruction. Let's see if this is the case. Click OK to close the breakpoints window. Click on "Execute" on menubar and then "Run" the program will pop up a window saying "PC = x3002". The execution of the program stops at that instruction. Now observe what's in registers R4 and R5 and verify that the first two NOT instructions are correctly executed by our Little Computer.

After stopping at a breakpoint you can continue execution by clicking "Execute" and then "Run". This will execute the program until the next breakpoint or until the end of your program. Or if you wish, you can step through your program utilizing what you have learned about stepping through your program in the previous section

Last Few Comments

For many of the commands you execute using the menubar in the simulator, there are shortcut keys and buttons you can use to execute them fast. For example, you can run your program just by hitting the F5 key. Explore the simulator to find out the fastest way of doing things.

This is a very fast-written document, so there might be minor (hopefully not major) errors in it. If you find a bug in this document, please contact any of the TAs. A section on assembly programming will be added later. Enjoy your ride through the Little Computer...