The instructions below setup your account so that it can
use the SPIM MIPS simulator, the PSE simulation viewer and the Emacs
The setup can be run from any ECE
Because of frequent changes to ECE Linux systems
it's possible that the setup routine won't work. Please report any
problems promptly for friendly, non-judgmental help so that you
can quickly get started on your assignment.
Locate a Linux workstation in the ECE workstation laboratory, Room
2241 Patrick F. Taylor Hall.
Their login screens will display Red Hat Enterprise
Linux or Scientific Linux.
Log into a Linux machine with your class account.
The accounts were (or will be) distributed by E-mail.
All passwords start with the characters 2@W,
followed by a random string of eight lower-case letters. When you
first log in a Gnome graphical desktop should appear.
Start a shell (command-line interpretor). One way to do
this is to right-click the desktop and select Open Terminal.
A window with Terminal in the title should appear with
a Unix prompt. If this looks scary
you might need to brush up
on Unix commands.
Yes, that's alot to type. However you can save
time by pressing the Tab key at certain times, specifically
when enough of a path component has been typed to disambiguate
the rest. For example, try pressing Tab after just typing /home/f.
It should finish the input with faculty. The setup routine
will modify your .bashrc and .emacs files. The
.bashrc file sets up your account each time you log in (more
precisely, each time you create a shell). The .emacs file contains
preferences for the Emacs text editor. The only change made to these
files is to include other files, so it's okay to edit them. It's also
safe to run setup multiple times, though that should not ordinarily be
This procedure shows the basic steps needed to work on a MIPS
programming homework assignment. These steps are written for a Homework
1, but can easily be adapted to other assignments by changing references
to the homework number, say from hw01.s to hw02.s.
Follow the instructions above for setting up the class account.
Copy the assignment files into your class account.
how to do so from a command shell:
[xyz.ece.lsu.edu]% cd ~Change to your home directory.
[xyz.ece.lsu.edu]% cp -r /home/faculty/koppel/pub/ee4720/hw/2017/hw01 .
Don't miss the dot at the end of the command.
This copies the hw01 directory into your class account.
You should know how to browse the files in the directory,
edit, copy, delete them, etc.
This may be a good time to practice your
(command-line interface) skills.
Change to the homework assignment directory.
[xyz.ece.lsu.edu]% cd ~/hw01Change to directory HOME/hw01.
Verify that files were copied, and look at what's there.
[xyz.ece.lsu.edu]% ls -laList directory, long format, show all files.
drwxr-xr-x 2 ee472000 gr4720 4096 Sep 15 15:29 .
drwxr-x--- 8 ee472000 ad4720 4096 Sep 15 15:29 ..
-rw-r--r-- 1 ee472000 gr4720 8425 Sep 15 15:29 hw01.s
Your directory listing may contain a different collection
of files, but there should be one of the form hw0X.s.
Load the homework assignment into an Emacs buffer. From the shell:
[xyz.ece.lsu.edu]% cd ~/hw01
[xyz.ece.lsu.edu]% emacs hw01.s &Start Emacs in background, have it load hw01.s.
There is no need to exit Emacs until you are done.
Verify that Emacs is working correctly.
If Emacs has been set up properly you should see
comments in red and the text LSU EE
4720 should appear in a black bold sans-serif font.
Verify that the MIPS simulator is working:
Press F9 to start the MIPS simulator using the file
in the current buffer as an input.
A window should pop up labeled xspim, with a primitive
graphical user interface.
Read the instructions in the file.
The comments in file hw01.s either describe the homework problem or
provide a link to the problems. Edit hw01.s to complete the
assignment. Please just modify one file, unless instructions in the
assignment code or the handout indicate that additional files should
Solve the problems.
An exact sequence of commands cannot be provided for this step.
The assignment will automatically be copied at the due date,
usually close to midnight or in the early morning on the day after the
due date. A trial copy may be performed before the due date and a
warning E-mail will be sent if the file could not be found.
These steps show how to run a MIPS program on SPIM.
After completing these steps look at the Basic Skills section
to learn techniques useful for debugging.
Follow the account setup instructions and log into your account.
Familiarize yourself with Emacs by following
the Using Emacs to Edit a File instructions.
Load a MIPS assembler file into an Emacs buffer, perhaps by
following the Homework Flow instructions above:
[xyz.ece.lsu.edu]% cd ~/hw01Change to directory HOME/hw01.
[xyz.ece.lsu.edu]% emacs hw01.sStart Emacs using hw01.s as first file to edit.
An Emacs window should open up with an assembler
file loaded. If setup was performed correctly then LSU EE 4720
should appear in a black bold font. If not, re-try the setup
or ask for help.
Start the simulator by pressing F9.
A window entitled xspim should pop up. The top pane should show
register values, the next pane should have buttons, the third should
show the program in binary and assembler forms, the fourth pane shows
the data area, and the bottom pane (which might extend past the bottom
of the screen) shows messages.
Check the bottommost pane for error messages. It may be necessary
to make other panes smaller to see the bottommost pane. If
there are any errors fix them, exit the simulator and restart.
Run the program by clicking the run button then clicking
ok on the
dialog box that pops up.
If the program generates output (and EE 4720 assignments do, at least
if they run long enough)
a window entitled SPIM Console should pop up. If you don't see it
try moving the simulator window. Use the arrow keys to scroll within
the SPIM Console window.
If you're satisfied with the output then you're done, otherwise
edit the MIPS program and try again. See the Basic Skills section
for some debugging techniques.
Students should have the following basic debugging skills before
attempting a homework assignment. More realistically, students should
remember that these basic debugging skills are conveniently described
here so that they can review them after encountering problems in an
initial attempt to solve the homework.
Do this by clicking step in the main SPIM window then clicking
step in the small dialog that pops up. Each press of step
will advance execution by one instruction, this can be seen by
the movement of highlighting in the Text Segments pane.
Determine Register and Memory Values
For those who might not have noticed,
the top of the main SPIM window shows register values. Memory values are
shown in the Data Segments pane. To find the address of the
data you are interested find a la pseudo-instruction that loads the
address of that data.
Set a Breakpoint
Single-stepping is a pain if you need to execute hundreds
of instructions before execution reaches the instruction you're
interested in. If this applies to you, find the address of the instruction by
scrolling the Text Segments pane until your instruction is visible;
the address is the first hexadecimal number. Then select breakpoints
and enter the address.
Many errors are due to the incorrect usage of an instruction.
Looking up an instruction should be quick and easy, so set a bookmark
on your favorite browser or otherwise provide one-click access
to the instruction
The following problems are frequently encountered when
SPIM Does Not Start After Pressing F9 in Emacs
Make sure the file has a name that ends .s. If so
Assembler should appear in the mode line near the bottom of the
Emacs window. If Assembler appears, check for a
menu. If not, double-check the account setup instructions. Make
sure your system has an X server. If so, Emacs will appear in its
own window, not in a terminal program (such as ssh or telnet).
If all the preceding is okay and SPIM still doesn't run Emacs
probably can't find the xspim program. You might be running
on the wrong system (should be ECE Sun or Linux systems) or else
something has changed. (If it's the year 2030 things might have
been moved without updating these instructions.)
Syntax and Other Assembly Errors
When you start SPIM look for errors on the bottommost pane.
That pane should start SPIM Version 6.3.1... If there are no
errors it should end See the file README for a full copyright notice.
Program Does not Seem to Run
In the run or step dialog the staring address should be about
If the starting address is zero then SPIM could not find the
__start symbol that should appear before the routine that is to run
first. If you are trying to run a homework solution shell make sure
you haven't deleted any code or that there are no errors that
are confusing SPIM before it reaches __start.
Stack Overflow Error
Most likely due to an infinite recursion error. A recursive
procedure needs to test some kind of no-more-recursion condition
before making a recursive call. If this condition is always false then
recursion will be infinite and stack space will be exhausted.
A zero or other invalid address is often due to common programming
errors, such as never setting a register to an address in the first
place. A misaligned address occurs when a lw or sw
instruction is executed
with an address that's not a multiple of 4, or for lh, etc., a
multiple of 2.
To debug a program find the point at which it stops doing
what was intended. To do this you need to know what the
program should be doing, so review the algorithm and work out a bit
by hand. You should also be able to single step, set SPIM breakpoints,
and examine register and memory values. Simple errors can be
caught by reviewing the code, but in more complex programs there
is no substitute for watching what happens when it runs.
The procedure below is for viewing a dataset file using PSE.
The procedure uses the sample dataset file perl.ds.
For an assignment substitute the appropriate file.
Log in to your account.
Use any valid ECE Sun or Linux account, a class account does not have
to be used.
Make sure that PSE (and other programs used for classes) is
in your execution path. One way is to follow the class account
setup instructions. Otherwise put the following in your .bashrc
file, or set the execution path and optionally PSE_DIR as shown:
if [ `uname` == 'Linux' ]; then
Start a shell. For example by right-clicking the desktop
and selecting "Open Terminal."
Enter the command:
A window titled "No Dataset - PSE" should pop up. If the account
was not set up properly the shell might give the error
pse: Command not found.. If so, setup the account
or type /home/faculty/koppel/pub/ee4720/lbin/pse (on Linux)
or /home/faculty/koppel/pub/ee4720/bin/pse (on Suns) instead of just pse.
The ampersand after pse runs it in the background so you can
use the shell for other commands, for example, running PSE
on a different dataset.
Select Open from the File menu. An Open File dialog should pop up.
If the dataset file to open (perl.ds, for example) is visible click on
it, otherwise either navigate to the directory containing the file,
type a path in the File text entry box, or call over a classmate and
ask "should it be doing this?"
If all goes well PSE should pop up a progress bar then show
a window full of dots (the overview window).
If the account was set up properly PSE should look for files
in the class dataset directory, /home/faculty/koppel/pub/ee4720/ds.
This default dataset directory is determined by environment
Initially PSE displays an overview of execution, with black dots
showing IPC (instructions per cycle) over a segment of program
execution. Other color dots may also be shown, click the "+" on the
left hand side to add more (or use the View | Overview Plot Series
The status line along the bottom shows time (in cycles), an
instruction number (based on a count of committed instructions), and a
tag (based on a count of decoded instructions).
Move the cursor over an interesting point and clock to view details.
The display should switch to a pipeline execution diagram (PED)
plot. Use the Overview button to return to the overview window.
To change the view between a ROB to a PED (pipeline execution diagram)
press the PED button.
Though they look very different, a PED plot is an upside down
and rearranged ROB plot, as can be seen by paying close attention
to the animation.
There is no way to close the current dataset or load a second one.
(It's on the to-do list.)
Run PSE again to view another dataset file. Note that by running
PSE in the background its easy to start multiple, simultaneous sessions.
For those who just can't right now, here are some useful key bindings:
Left and Right Arrow: Scroll through the ROB or PED plot.
Home and End: Go to the beginning or end or ROB or PED plot.
See the View menu for zoom command key bindings.
Clip mode prevents instructions from wrapping from bottom to
top in PED plots. When turned on it may make a bad choice about
which instructions to show. If you think that's happening
make sure the clip button is out.
If the Unlock button is visible that means the instructions
shown by the disassembly window won't follow the cursor. If that's
what you want, fine, otherwise press unlock.
Emacs, at its core, is a text editor, however surrounding that core
are many commands and modes to help with programming tasks of all
kinds and other activities from the practical, such as editing files
on remote computers (look for Remote Files in the documentation), to
the amusing, such as inserting keywords designed to attract the
attention of counterespionage agents (M-x spook). Emacs
has commands for practically anything.
These steps show how
to use Emacs to edit a file.
The first step shows how to start Emacs graphically, which is
what you'd want to do if you were not connecting remotely.
Connecting non-graphically is the better option if you were
connecting remotely (say from your PC at home).
To run Emacs graphically type emacs &
in a command shell or start using the Applications | Accessories |
Emacs Text Editor menu items.
A window should pop up, the frame will be labeled Emacs.
To run Emacs non-graphically type
emacs -nw in a command shell.
Emacs should start, there should be a character-mode
menu across the top.
Load a file by selecting Open File... from the Files menu.
If running non-graphically press F10 to access the menus.
Enter a file name. Note that text may appear in the bottom
of the main window in an area called the minibuffer,
or in a dialog box.
(Once loaded, the file name will appear in the mode line near the
bottom of the window.)
Enter text in the buffer to try out the editor.
Select Save Buffer from the Files menu to save.
When done with editing for the day
select Exit Emacs from Files to exit.
Many users prefer to leave Emacs open with multiple files
rather than exiting and re-starting Emacs for each file edited.