"Guide to Using the Unix version of the LC-3 Simulator
by Kathy Buchheit The University of Texas at Austin
© copyright, Kathy Buchheit January 2001, October 2003
Guide to Using the Unix version of the LC-3 Simulator
The LC-3 is a piece of hardware, so you might be wondering why we need a simulator. The reason is that the LC-3 doesn’t actually exist (though it might one day). Right now it’s just a plan – an ISA and a microarchitecture which would implement that ISA. The simulator lets us watch what would happen in the registers and memory of a “real” LC-3 during the execution of a program.
How this guide is arranged
For those of you who like to dive in and try things out right away, the first section walks you through entering your first program, in machine language, into a text editor (we’ll use emacs as an example). You’ll also find information about writing assembly language programs, but you’ll probably skip that part until you’ve learned the LC-3 assembly language. The second section gives you a quick introduction to the simulator’s interface, and the third shows you how to use the simulator to watch the effects of the program you just wrote. The fourth section takes you through a couple of examples of debugging in the simulator. The last section is meant as reference material for the simulator. In other words, Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Creating a program for the simulator The simulator: what you see on the screen Running a program in the simulator Debugging programs in the simulator LC-3 Simulator reference, Unix version page 2 7 11 16 20
1
Chapter 1
Creating a program for the simulator
This example is also in the textbook, Introduction to Computing Systems: From Bits and Gates to C and Beyond! You’ll find it in Chapter 6, beginning on page 166. The main difference here is that we’re going to examine the program with the error of line x3003 corrected. We’ll get to a debugging example once we’ve seen the “right way” to do things.
The Problem Statement
Our goal is to take the ten numbers which are stored in memory locations x3100 through x3109, and add them together, leaving the result in register 1.
Using emacs
If you know how to use Unix already, and you have a favorite text editor, go ahead and open it, and use it to write and save your program. If you don’t have a preferred text editor, try using emacs. At this point, you should be logged in to a Unix machine, and have a console window open. (I’m assuming basic Unix familiarity, so ask another user in your lab if you don’t know how to log in and open a console.) At the console prompt, type
emacs addnums.bin &
If you want to name your program something different from “addnums.bin,” you could replace that name with the one you like better. The last three letters, “bin,” specify that you’re going to type your program in binary. If you want to type it in hex instead (I’ll explain that momentarily), you could say “addnums.hex.” The “&” at the end of the line tells Unix that you want to open the emacs text-editing program in a separate window.
Entering your program in machine language
You have the option to type your program into emacs in one of three ways: binary, hex, or the LC-3 assembly language. Here’s what our little program looks like in binary: 0011000000000000 0101001001100000 0101100100100000 0001100100101010 1110010011111100 0110011010000000 0001010010100001 0001001001000011 0001100100111111 0000001111111011 2
1111000000100101 When you type this into emacs, you’ll probably be looking at a chart which tells you the format of each instruction, such as the one inside the back cover of the textbook. So it may be easier for you to read your own code if you leave spaces between the different sections of each instruction. Also, you may put a semicolon followed by a comment after any line of code, which will make it simpler for you to remember what you were trying to do. In that case your binary would look like this: 0011 0000 0000 0000 0101 001 001 1 00000 0101 100 100 1 00000 0001 100 100 1 01010 1110 010 011111100 0110 011 010 000000 0001 010 010 1 00001 0001 001 001 0 00 011 0001 100 100 1 11111 0000 001 111111011 1111 0000 00100101 ;start the program at location x3000 ;clear R1, to be used for the running sum ;clear R4, to be used as a counter ;load R4 with #10, the number of times to add ;load the starting address of the data ;load the next number to be added ;increment the pointer ;add the next number to the running sum ;decrement the counter ;do it again if the counter is not yet zero ;halt
Either way is fine. The program which converts your program to machine language ignores spaces anyway. The second way will just be easier for you to read. Your program could also look like this, if you choose to type it in hex (notice that comments after a semicolon are still an option). In this case, you would have named your program “addnums.hex.” 3000 5260 5920 192A E4FC 6680 14A1 1243 193F 03FB F025 ;start the program at location x3000 ;clear R1, to be used for the running sum ;clear R4, to be used as a counter ;load R4 with #10, the number of times to add ;load the starting address of the data ;load the next number to be added ;increment the pointer ;add the next number to the running sum ;decrement the counter ;do it again if the counter is not yet zero ;halt
If you entered your program in binary, with spaces and comments, your emacs window will look something like this:
Saving your program
At the top of the emacs window, you’ll see the word Files. Click on that now. Then click on Save Buffer. This will save your program under the name you gave when you
3
started emacs a little while ago. If you want to save your program under a different name for some reason, click on Files and then Save Buffer As…. At the bottom of the emacs window, you’ll see “Write file: ~/” and then a rectangular cursor. Type your new file name and press Enter.
Creating the .obj file for your program *
Before the simulator can run your program, you need to convert the program to a language that the LC-3 simulator can understand. The simulator doesn’t understand the ASCII representations of hex or binary that you just typed into emacs. It only understands true binary, so you need to convert your program to actual binary, and save it in a file called addnums.obj. If you saved your program in binary and called it “addnums.bin,” go to the Unix prompt and type
lc3convert –b2 addnums.bin
If you saved your program in hex as “addnums.hex,” type this at the Unix prompt:
lc3convert –b16 addnums.hex
When you type the appropriate line and press Enter, a new file will be created in the same directory where you saved your original addnums program. It will automatically have the same name, except that its file extension (the part of its name which comes after the “.”) will be .obj. If you typed your program in 1s and 0s, or in hex, only one new file will appear: addnums.obj.
4
If you don’t know the LC-3 assembly language yet, now you’re ready to skip ahead to Chapter 2, and learn about the simulator. Once you do learn the assembly language, a little bit later in the semester (or quarter), you can finish Chapter 1 and learn about the details of entering your program in a much more readable way.
Entering your program in the LC-3 assembly language
So you’re partway through the semester, and you’ve been introduced to assembly language. Now entering your program is going to be quite a bit easier. This is what the program to add ten numbers could look like, making use of pseudo-ops, labels, and comments. .ORIG AND AND ADD LEA LOOP LDR ADD ADD ADD BRp HALT .END x3000 R1,R1,x0 R4,R4,x0 R4,R4,xA R2,x0FC R3,R2,x0 R2,R2,x1 R1,R1,R3 R4,R4,x-1 LOOP ;clear R1, to be used for the running sum ;clear R4, to be used as a counter ;load R4 with #10, the number of times to add ;load the starting address of the data ;load the next number to be added ;increment the pointer ;add the next number to the running sum ;decrement the counter ;do it again if the counter is not yet zero
You still need to change your program to a .obj file, which is now called “assembling” your program. To do this, save your program as “addnums.asm.” Then at the command prompt, type
lc3as addnums.asm
and notice that this time you didn’t need to specify “addnums.obj” because your assembled file will automatically get the extension “.obj.” Since you used the fancier assembly language approach, you’ve been rewarded with not just one, but a couple of files: addnums.obj, as you expected addnums.sym, the symbol table created on the assembler’s first pass Let’s take a look at the addnums.sym file. addnums.sym Here’s what this file looks like if you open it in a text editor: // Symbol table // Scope level 0: // Symbol Name // ----------------
Page Address -----------5
//
LOOP
3004
You only had one label in your program: LOOP. So that’s the only entry in the symbol table. 3004 is the address, or memory location, of the label LOOP. In other words, when the assembler was looking at each line one by one during the first pass, it got to the line LOOP LDR R3,R2,x0 ;load the next number to be added
and saw the label “LOOP,” and noticed that the Location Counter held the value x3004 right then, and put that single entry into the symbol table. So on the second pass, whenever the assembler saw that label referred to, as in the statement BRp LOOP
it replaced LOOP with the value that will yield x3004 when added to the PC, namely x1FB. If you’d had more labels in your program, they would have been listed under Symbol Name, and their locations would have been listed under Page Address.
6
Chapter 2
The simulator: what you see on the screen
To start the simulator, type this at the prompt:
lc3sim-tk &
When you launch the Unix version of the LC-3 Simulator, you see this:
7
Chapter 5 of this guide is a more complete reference to all the parts of this interface. If you want all the details, look there. If you want just enough details to be able to continue the step-by-step example, keep reading.
The registers
Below the heading CPU, notice the list of registers.
The General Purpose Registers, R0 through R7, are the eight registers that LC-3 instructions use as sources of data and destinations of results. The numbers following the “=” are the contents of those registers, first in hex and then (in parentheses) in decimal. If, during the execution of a program, R2 contained the decimal value 129, you would see this:
The Special Registers section shows the names and contents of five important registers in the LC-3 control unit. Those registers are the PC, the IR, and the N, Z, and P condition code registers.
The PC, or program counter, points to the next instruction to be run. When you load your program, it will contain the address of your first instruction. The default value is x3000. The IR, or instruction register, contains the value of the current instruction. The CC, or condition codes, are set by certain instructions (ADD, AND, OR, LEA, LD, LDI, and LDR). They consist of three registers: N, Z, and P. Remember that only one of the three can have the value 1 at any time. The simulator shows us the values of the three registers all lumped together. The above situation, NZP = 001, means that N=0, Z=0, and P=1.
The memory
Below the registers, you see a long, dense list of numbers which begins like this:
8
Use the scrollbar at the right (with the middle mouse button) to scroll up and down through the memory of the LC-3. Remember that the LC-3 has an address space of 216, or 65536 memory locations in all. That’s a very long list to scroll through. You’re likely to get lost. If you do, go to the Memory Address box and manually enter a memory location and press enter. You will then be taken directly to that memory location. In the From field, type the memory location you want to start with, such as 3000. In the To field, type the memory location to display through, such as 3020. Then click Print, and those x20 locations will appear in the Memory part of the simulator. The first column in the long list of memory locations tells you the address of the location. The second column tells you the contents of a location, in hex. The columns after the first two are the assembly language interpretation of the contents of a location. If a location contains an instruction, this assembly interpretation will be useful. If a location contains data, just ignore these columns entirely.
The Console Window
A second window also appears when you run the simulator. It is rather inconspicuous, and has the vague title “LC-3 Console.” This window will give you messages such as “Halting the processor.” If you use input and output routines in your program, you’ll see your output and do your input in this window.
9
10
Chapter 3
Running a program in the simulator
Now you’re ready to run your program in the simulator. Open the simulator by typing
lc3sim-tk &
at the prompt. To load your program, click Browse and then locate your program on disk. This is what you’ll see when your program is loaded:
11
Notice that the first line of your program, no matter what format you originally used, is gone. That line specified where the program should be loaded in memory: x3000. Since nothing has happened yet (you haven’t started running or stepping through your program), the PC is pointing to the first line of your program (x3000).
Loading the data (ten numbers) into memory
There are several ways to get the ten numbers that you’re planning to add into the memory of the LC-3 simulator. You want them to begin at location x3100. First way: Manually enter each data value in the memory location by left-clicking on the memory location and then entering a value in the Value field. Do this for all ten locations. This method is rather tedious! Do not dispair, there’s another way to accomplish the same thing. Second way: go back to emacs, and enter the data as code in hex. First start emacs at the command prompt:
12
emacs data.hex &
and then enter this in your file: 3100 3107 2819 0110 0310 0110 1110 11B1 0019 0007 0004 ;data starts at memory location x3100 ;the ten numbers we want to add begin here
Save this code as data.hex by clicking on Files and choosing Save Buffer. As usual, the first line is the address where we want the data to begin. The other lines are the actual data we want to load into memory. To convert your program to an .obj file, type this at the prompt:
convert –b16 data.hex
Now, a file called data.obj will exist wherever you saved your .hex file. Now go back to the simulator, choose to load a program… once again, and select data.obj. Note that you can load multiple .obj files so they exist concurrently in the LC-3 simulator’s memory. The memory locations starting with x3100 will look like this:
Now your data is in place, and you’re ready to run your program.
13
Running your program
Enter memory address x3000 in Memory Address so that you may see your program. Be sure that PC contains x3000 as well so that the LC3 will know where to begin executing your program. Now, we’ll set a breakpoint. This will cause the LC-3 to stop when the PC reaches this address. Setting and unsetting breakpoints is very simple in the LC-3. All you have to do is double click on the memory location where you would like the breakpoint set. Double click on location x3009. That sets a breakpoint on line x3009. If you don’t follow this suggestion, you’ll never see your result in R1, because we’ll do the trap routine for HALT, which changes R1 before it halts the simulator. (I’ll explain breakpoints in more detail in the next chapter.) After you set your breakpoint, the line will look like this:
That B at the beginning of the line shows that you’ve set a breakpoint on that line. So we’ll stop when we get to line x3009, before we execute the instruction there. Now for the big moment: click on Continue. If you’ve already added up the ten numbers you put into the data section of your program, you know that x8135 is the answer to expect. That’s what you should see in R1 when the program stops at the breakpoint.
Stepping through your program
So now that you’ve seen your program run, you know it works. But that doesn’t give you a good sense for what’s actually going on in the LC-3 during the execution of each instruction. It’s much more interesting to step through the program line by line, and see what happens. You’ll need to do this quite a bit to debug less perfect code, so let’s try it. First, you need to reset the very important program counter to the first location of your program. So set the PC back to x3000. (Enter x3000 in the PC window) Click on Next. This will execute exactly one LC-3 instruction. A couple of interesting things just happened: • R1 got cleared. (If you “cleaned up” by clearing R1 before you started, this won’t be an exciting event.) • The IR has the value x5260. Look at the hex value of location x3000. That is also x5260. The IR holds the value of the “current” instruction. Since we finished the first instruction, and have not yet run the second, the first instruction is still the current one. Click Next for a second time. Again, notice the new values for the PC and IR. The second instruction clears R4.
14
Click Next a third time. The PC and IR update once again, and now R4 holds the value x0a, which is decimal 10, the number of times we need to repeat our loop to add ten numbers. This is because the instruction which just executed added x000a to x0000, and put the result in R4. Continue to step through your program, watching the results of each instruction, and making sure they are what you expect them to be. At any point, if you “get the idea” and want your program to finish executing in a hurry, click on Continue, and that will cause your program to execute until it reaches the breakpoint you set on the Halt line. So now you know how it feels to write a program perfectly the very first time, and see it run successfully. Savor this moment, because usually it’s not so easy to attain. But maybe programming wouldn’t be as fun if you always got it right immediately. So let’s pretend we didn’t. The next chapter will walk you through debugging some programs in the simulator.
15
Chapter 4
Debugging programs in the simulator
Now that you’ve experienced the ideal situation of seeing a program work perfectly the first time, you’re ready for a more realistic challenge – realizing that a program has a problem, and trying to track down that problem and fix it.
Example:
Debugging the program to multiply without a multiply instruction
This example is taken from the textbook, and is discussed on pages 129 and 130. The program is supposed to multiply two positive numbers, and leave the result in R2.
Typing in the program
First you’ll need to enter the program in LC3Edit. It should look like this: 0011 0010 0000 0000 0101 010 010 1 00000 0001 010 010 0 00 100 0001 101 101 1 11111 0000 011 111111101 1111 0000 00100101 ;the address where the program begins: x3200 ;clear R2 ;add R4 to R2, put result in R2 ;subtract 1 from R5, put result in R5 ;branch to location x3201 if the result is zero or positive ;halt
As you can tell by studying this program, the contents of R4 and R5 will be “multiplied” by adding the value in R4 to itself some number of times, specified by the contents of R5. For instance, if R4 contains the value 7, and R5 contains the value 6, we want to add 0+7 the first time through, then 7+7 the second time through, then 14+7 the third time through, then …, then 35+7 the sixth time through, ending up with the value 42 in R2 when the program finishes.
Converting the program to .obj format
Once you’ve typed your p..."
|
You need to upgrade your Flash Player , or try to enable javascript in order see this document properly.
|
|
Comments
