A Gentle Guide to Using the LC-3 Simulator
Throughout this document,
commands that you have to type or buttons you have to click will
1. Getting Java
The LC-3 Simulator is written in Java, which means Java must be
installed on the computer you plan to use. Java should already be
available on all public SEAS machines. If you plan to work on your
personal machine, you may need to install Java yourself. You can
download Java here.
The LC-3 simulator requires Java 1.4 or newer (which is available for
Windows, Linux, and Mac OS X).
2. Getting the Simulator
Next, you need to download the
simulator. It is distributed in a .jar file (short for Java ARchive)
which you can download here. In
Windows or on a Mac, you should be able to double-click the .jar file
to launch the simulator. You can also launch the simulator from the
command line (shell in Linux or command prompt in Windows) of your operating system (Linux/Unix) by using the
The Simulator version is 1.2.5 (r436). You should see the simulator
screen, much like the screenshot below.
If the above command jar command did not work, it is probably that java bin directory is not set in your kernel's (OS) search path.
For Linux machines make sure you shell is tcsh. Type:
/usr/java/jdk1.5.0/bin/java -jar PennSim.jar
The CETS computer labs should automatic have set the java environment variable but if the jar command does not work then, set the Java path in your .cshrc or .bashrc file to include the following in the set path section: set path = ($path /usr/java/jdk1.5.0/bin . ) .Make sure that there is a period before closing the brackets. Execute your .cshrc/.bashrc file using the source command. The source command will enable the the changes into your environment. E.g.
For Windows machines follow the link for setting up the search path. To launch the simulator, use the Command Prompt
via Start > Programs > Accessories. At the prompt, change directory (cd) to
location where LC3 jar file is saved. You can find the windows commands here.
Use any Java IDE you are familiar with and open the jar file.
If you have any problems starting the simulator, please email TA or Instructor. This will ensure the
3. Assembling and Loading Software
Now the simulator is running, but to get it to do anything
interesting, we need to load some software. The first piece of
software we should load is, naturally, an operating system. The LC-3
operating system is very basic: it handles simple I/O operations and
is responsible for starting other programs, such as the ones you will
write for homework assignments. Download the LC-3
OS here (right click to save).
So that you can understand what
the operating system does, we distribute it as an assembly language
file. But the LC-3 machine doesn't understand assembly directly; we
first have to 'assemble' the assembly code into machine language (a
.obj file containing binary data). The LC-3 simulator has a built-in
assembler, accessible (as is the case for most of its functionality)
via the Command Line text box (see screenshot above). To assemble the
operating system, type as
lc3os.asm at the command line and hit enter.
Make sure that the OS file is in the same directory as the .jar file;
command also understands relative and absolute paths if the OS is in
a different directory. Output from the assembly process is displayed
in the CommandLine Output Pane. After assembling the OS, you should
notice that 2 new files, lc3os.obj and lc3os.sym, have been created.
The .obj file is the machine language encoding of the assembly
language file, and the .sym file is a text file that holds symbol
information so the simulator can display your symbols. Recall that
symbols are really just a convenience for humans; the machine
language encoding knows only about offsets.
Now we can load the lc3os.obj
file into the simulator, either via the command load
lc3os.obj or by going to the File
menu and selecting Open
.obj file. Notice that the contents of the
memory change when the OS is loaded.
Now assemble and load the
solution file for Problem 0 into the simulator. The memory has
changed again, but you may not notice since the relevant memory
addresses (starting at x3000) aren't visible unless you've scrolled
the screen. User-level programs (i.e., non-OS code) start, by
convention, at x3000. If you type the command list
x3000 the memory view will jump to x3000 and you
can see the 1-instruction solution to this problem.
4. Running Code
To actually run code, you can
use the 4 control buttons at the top of the simulator, or type
commands into the command line interface (the command names are the
same as the buttons). Note that the PC register is set to x0200,
which is the entry point to the operating system by convention.
Recall that the solution code for Problem 0
increments the value in R2 and puts the result in R5. Set the value
in R2 to something you fancy, either by double-clicking it in the
Registers section, or via the command set
R2 (value). Now, actually run the code by
hitting the continue
button. The value magically gets incremented and moved to R5. Also observe that the PC now points to x0263, an apparently random
value somewhere in the operating system, and that the Status Display
tells us the machine is halted.
4a. Running Code...slowly
Clearly, some things are going
on here. But to determine what they are exactly, we need to slow the
execution down. You can hit the stop
button to pause the machine while it's executing, but this doesn't
give you very fine-grained control. The continue
command will start running instructions as fast as possible, but
often we want to go just one instruction at a time. This is what the
commands allow us to do. They both go one instruction at a time, but
command will "follow" function calls and traps, while next
just goes from line to line, "over" function calls and
traps and stopping only at the instruction immediately after them.
will "follow" branches. The LC-3
Manual has a more involved discussion, with an example, of the
difference between next
Let's try running the program
again, but just one instruction at a time. Notice that from the
halted state, the PC points to an instruction that will branch us
right back to the start of the operating system. So we can hit next
once and start the cycle over again. Note that registers are as we
left them. You can put a new value into R2 if you want, and the old
value in R5 will get overwritten. Sometimes, having old values lying
around everywhere can be problematic, and it's good to do a real
"reboot" via the reset
command. This clears all of memory and resets registers to
default values, so you have to reload the OS and your program.
You can keep next-ing
over the OS code; eventually you will hit the RTT instruction at
location x0205 that jumps to the start of our program at x3000. Now
you can see the 2 instructions that constitute our program. You can
see the ADD being performed, and then the machine gets halted again.
Continue running the increment-R2-into-R5 code until, if ever, you
get bored. Then move on to the next section.
4b. Running Code...for a little while
Going one instruction at a time is great, but
somewhat tedious. We need a happy medium between not knowing what's
going on at all, and having to go through every single instruction,
whether we care about it or not. Breakpoints are this happy medium.
A breakpoint is set at a
particular memory location, and tells the simulator to stop execution
upon reaching that point. Memory locations with breakpoints set on
them show up in the simulator with a red square in the "BP"
column. It is left as an exercise to the reader to determine what
"BP" stands for. You can set a breakpoint at a memory
location with the command break
set (memory location), or by checking the
checkbox in the "BP" column. You can get rid of a
previously-set breakpoint with the command break
clear (memory location), or by un-checking a
previously checked box. You can also set and clear breakpoints at
labels, instead of specifying a hex memory location.
When you tell the simulator to
it will only run until it hits a breakpoint (or the system halts or
has an error). When you are writing and testing your answer for
Problem 0, you can use the command break
set START to set a breakpoint at the beginning
of your code. Then, you can use continue
to skip all the OS code and get to the instructions you care about.
Then you can next
over your code to make sure it's doing what you want it to do.
5. Running Scripts
Now try running the
test script provided for Problem 0. You can do this with
the command script
(scriptfile). LC-3 script files are .lcs files,
but are really just plain text, and the file extension doesn't really
matter. If you open the script file with a text editor, you can see
that the script commands are the same as those you type at the
command line. For repetitive tasks, using a script file can save you
time, and perhaps the lifelong agony of Repetitive
Scripting is also a great way
of testing your code. You can write a few test cases and check your
code easily. Use the check
command to verify that a value is what you think it should be. A sample script
for problem 0 is provided in p0.lcs. For assignments you will be given some scripts but they will not cover all the important cases, so you should augment
the given scripts with some of your own.
6. General Help and Advice
This document doesn't cover all
of the simulator's functionality; for an extended discussion of usage
see the LC-3 Simulator Manual. For quick
help within the simulator itself, you can use the help
command to see a list of all of the LC-3's commands. Use help
(command) to get help on a specific command.
Many of the LC-3 commands have
shortcuts - b
is short for break,
and so forth. Use the help
command to see what shortcuts exist.
The LC-3 Command Line has a history feature - use the up and down
arrow keys to go backwards and forwards through the commands you've
If you resize the simulator
window to make it bigger, the Commandline Output Pane will grow. If
you have a small screen and the Commandline Output Pane still isn't
big enough, you can open an external, resizable Command Output Window
by selecting the Open
Command Output Window option from the File
menu. This lets you see a lot more output from the commands you run,
and is particularly useful for viewing the errors the assembler
Original Document by Milo Martin
Modified by Diana Palsetia