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.
- Type emacs & in a command shell
or start using the "Applications | Accessories | Emacs Text Editor"
menu item.
A window should pop up, the frame will be labeled Emacs.
- Load a file by selecting "Open File..." from the Files menu.
- 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.
The tutorial is an introduction for first-time users.
Info provides detailed documentation for Emacs and other programs.
- Start Emacs
- Select "Browse Manuals" from "Help" menu.
- Following instructions, select the Emacs manual.
SPIM is a simple MIPS simulator. It reads
MIPS assembly language programs and under user control it executes
them.
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.
- Obtain or write a MIPS assembly language program with SPIM
directives. If this is for an EE 3755 assignment locate and
copy the file to your account.
- Load the program into an Emacs buffer.
If everything is set up correctly comments should be in
red, instructions should be blue, registers should be in gold, etc.
- Start the simulator by pressing F9 or by choosing the SPIM | Run XSPIM
menu item.
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 (by dragging the black squares) 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 3755 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 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 skills before
attempting a homework assignment. More realistically, students
should make sure that they have these skills after encountering problems
in an initial attempt to solve the homework.
- Single-Step Execution
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.
- Find Documentation
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
documentation
'The following problems are frequently encountered when
using SPIM.
- 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 "SPIM" pull-down
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 an ECE Linux system) 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
0x00400000. 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.
- Address Errors
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" is executed
with an address that's not a multiple of 4, or for "lh", etc., a
multiple of 2.
The following are common errors in
MIPS programs.
- Unintended Instruction in Delay Slot
In the first code fragment above the add $a0, $t0, $s1
is executed even though the jump is taken.
- Program Does Not Work Properly, For Some Reason
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 setting up and running the software
for the first time on a sample Verilog description, "ripple.v".
Alternate instructions can be found in lesson 7 of the ModelSim
tutorial. (See the references page.)
- Log in to your account.
Use any valid ECE Sun account, a class account does not have to be used.
- Create a new directory and make it current.
- Copy the Verilog file to the directory.
- Create a "library" named work.
In the Unix tradition, this command generates no output
if it works.
The library is where the HDL (Verilog and VHDL) compilers
put the compiled designs.
This step is usually done just once per directory.
- Start the ModelSim GUI (Graphical User Interface)
You will be greeted by a rhinoceros-emblazoned dialog box.
Select Proceed to Modelsim. The dialog box should disappear, leaving a window
with the title "ModelSim EE/Plus".
There are buttons to create and open projects. Projects won't
be used in these instructions though they can be used to
complete assignments.
- Compile the Verilog description in one of the following ways:
- Enter
in the Unix shell or in the ModelSim window (at what will
initially be a "ModelSim>" prompt).
- With Emacs set up as described elsewhere, load the Verilog file
ripple.v into a buffer and press [f9] or select "Compile" from
the "Verilog" pull-down menu in Emacs.
- Select "Compile" from the "Design" pull down menu from
the ModelSim window. A "Compile HDL Source Files" dialog
box should pop up. Select file "ripple.v" and click "Edit
Source". A "source_edit" window should pop up. Next
click "Compile" in the "Compile HDL Source Files" dialog.
- Click the compile button (the leftmost botton one)
on the ModelSim window toolbar.
In all cases the compiler will generate output that looks something like:
Model Technology ModelSim SE vlog 5.5c Compiler 2001.07 Jun 22 2001
-- Compiling module ripple_4
-- Compiling module bfa_implicit
-- Compiling module demoadd
Top level modules:
demoadd
If there are compile errors then you can jump to offending
source lines by double clicking the corresponding error message in the
ModelSim window or single-clicking with the center mouse
button in the Emacs *compilation* window.
By default the source window is read only. Select "read only"
from the Edit menu to toggle out of read only mode.
- Load a design into the simulator by selecting "Load New Design"
from the ModelSim "Design" menu. A "Load Design" dialog should
pop up. Select "demoadd", the testbench for the design, then
click "Load". The dialog box should disappear and the
ModelSim window should show an impressive legal notice followed
by:
# Loading work.demoadd
# Loading work.ripple_4
# Loading work.bfa_implicit
# do startup.do
VSIM 5>
- Learn how to move windows to the front of the display.
On a Sun workstation this can be done using the "Front"
button on the left-hand key cluster.
- Bring up simulator information windows
by clicking the "V" button on the toolbar or
by typing
in the ModelSim window.
Windows can be opened individually using the ModelSim "View"
menu.
- In the "structure" window make sure "demoadd" is
highlighted.
Drag the blue dot next to "sum" in the "signals" window to the
"wave" window.
Repeat the process for "a" and "b".
This must be done before running the simulation (otherwise
you can't view those signals).
These signals are in the testbench module, demoadd. To
see the ripple adder signals select "ripple_4" in the
structure window. The ripple adder signals should appear
in the signals window, where they can be dragged into
the wave window.
- Run the simulation by pressing the "Run All" icon (a little text
page with a double down arrow) or by selecting "Run -All"
from the "Run" ModelSim menu.
The ModelSim window should show "# Finished", in addition
to other changes.
- View the waveforms by pressing the "Zoom All" icon (the rightmost
magnifying glass) on the wave window toolbar or by using
the "Zoom" menu. The waveforms should fill the waveform display
area.
To change the signal values to hexadecimal or some other radix,
double click the signal name in the "wave" window.
- To exit, select "Quit" from the ModelSim "File" menu.
This will get rid of all the windows.
If there are unsaved changes in the source window you'll
be prompted to save but you won't be warned to save
formating information you might have specified in the "wave"
window and elsewhere.
- Read the Editing and Re-Simulating procedure. There are
some non-obvious things you need to know.
- See Chapter 10 of the ModelSim EE/SE User's Manual
for more information.
The procedure below is to be used after you
set up a directory and have initially compiled a
Verilog description, perhaps using the procedure
above. The steps for starting the ModelSim software
are slightly different after a description is compiled.
- Make the directory containing the Verilog description
current.
- Start the GUI specifying the top-level module (usually the
testbench) you want to simulate:
If you rather not type the name of the top-level module
start the simulator without arguments:
You will be greeted by the rhinoceros. Click "Done", a "Load Design"
dialog should pop up. Select the top level module then click "Load".
- Open the "structure", "signals", "wave", and other windows by
clicking the "V" button or by issuing "view" commands in the ModelSim
window. Drag the signals you want to see into the "wave" window and
make any other changes.
- Run time simulation by typing "Run" into the ModelSim window,
clicking one of the run toolbar icons, or selecting one
of the "Run" pull-down menu entries. The status bar at the bottom
of the ModelSim window should show simulation time and the wave,
signal, and perhaps other windows should be updated with simulated
signal values.
- You are not satisfied. (Pretend, if necessary.) Edit the Verilog
code using the source window or your favorite text editor.
- Re-compile by pressing [f9] in Emacs or by selecting "Compile" from
the "Design" pull-down menu in the ModelSim window, by pressing the
toolbar, or by entering vlog ripple.v in the ModelSim window. If
necessary, fix bugs and recompile.
Beware, if you select
"Compile" while a compile dialog box is already open an error dialog
(with the title "Error in Tcl Script") will pop up. If this happens
click "OK" in the error dialog and find the already-opened compile
dialog.
- If you want to simulate the same top-level module skip this step.
Suppose "bar" is the name of the new top-level module you want to simulate.
Enter vsim bar
in the ModelSim window or select "Load New Design..." from the
"Design" pull-down menu.
- Click the restart toolbar botton (to the right of the clipboard)
or select "Restart..." from the "Run" menu in the ModelSim window.
Click "Restart" on the dialog that should have popped up.
- Run the simulation again.