SPIM

A MIPS32 Simulator

spim is a self-contained simulator that will run MIPS32 assembly language programs. It reads and executes assembly language programs written for this processor. spim also provides a simple debugger and minimal set of operating system services. spim does not execute binary (compiled) programs.

spim implements almost the entire MIPS32 assembler-extended instruction set. (It omits most floating point comparisons and rounding modes and the memory system page tables.) The MIPS architecture has several variants that differ in various ways (e.g., the MIPS64 architecture supports 64-bit integers and addresses), which means that spim will not run programs compiled for all types of MIPS processors. MIPS compilers also generate a number of assembler directives that spim cannot process. These directives usually can be safely deleted.

Earlier versions of spim (before 7.0) implemented the MIPS-I instruction set used on the MIPS R2000/R3000 computers. This architecture is obsolete (though, has never been surpassed for its simplicity and elegance). spim now supports the more modern MIPS32 architecture, which is the MIPS-I instruction set augmented with a large number of occasionally useful instructions. MIPS code from earlier versions of SPIM should run without changes, except code that handles exceptions and interrupts. This part of the architecture changed over time (and was poorly implemented in earlier versions of spim). Code of this sort need to be updated. Examples of the new code are in exceptions.s and Tests/tt.io.s.

spim comes with complete source code and documentation. It also include a torture test to verify a port to a new machine.

spim implements both a simple, terminal-style interface and a window interface. On Unix, Linux, and Mac OS X the spim program provides a simple terminal interface and the xspim program provides the windowing interface. On Microsoft Windows, the spim program provides a console interface and PCSpim provides a Windows interface.

Downloading SPIM

• To run spim or xspim on a Unix, Linux, or Mac OS X system, copy either the compressed tar file (http://itsys.hansung.ac.kr/lec/cstruct/new/spim/SPIM/spim.tar.Z) or the gzip'ed tar file (http://itsys.hansung.ac.kr/lec/cstruct/new/spim/SPIM/spim.tar.gz).  Both files contains source code and must be compiled for your system.

• Ben Liblit of the Cooperative Bug Isolation Project (http://www.cs.wisc.edu/cbi/) produced a compiled version of spim for Fedora. It contains the project's low-overhead monitoring code, which can help find bugs in spim. If you are running Linux, this package can: save you the time and trouble of compiling and installing spim, help find bugs, and aid an interesting research project.

• To run PCspim under Microsoft Windows, download the file http://itsys.hansung.ac.kr/lec/cstruct/new/spim/SPIM/pcspim.zip, unzip it, and click on setup.exe.

• Source for the Microsoft Windows version (both PCspim and spim) is available separately in the file http://itsys.hansung.ac.kr/lec/cstruct/new/spim/SPIM/pcspim_src.zip.

• There is no native Macintosh version of spim. However, the xspim will compiles and runs on Mac OS X.

Installation

Microsoft Windows

1. Download the file http://itsys.hansung.ac.kr/lec/cstruct/new/spim/SPIM/pcspim.zip and save it on your machine.

2. Unzip the file.

3. Click on the setup.exe program.

Unix, Linux, or Mac OS X

(Note: the directions changed slightly for version 7.2, to reflect a new directory structure. Please read carefully.)

Installation is a bit more complex for a Unix or Linux system, as you need to compile the program for your particular computer and operating system.

1. Download either the file http://itsys.hansung.ac.kr/lec/cstruct/new/spim/SPIM/spim.tar.Z or http://itsys.hansung.ac.kr/lec/cstruct/new/spim/SPIM/spim.tar.gz.

2. Decompress the file, using either the program uncompress for the first file or gzip for the second file:
   
       % uncompress spim.tar.Z
   
   or
   
       % gzip -d spim.tar.gz
    

3. Move the file spim.tar to the directory in which you want to build spim and untar it:
   
       % tar xf spim.tar
   
   It will create a directory named spim-7.2 (or the most recent version number).
    

4. The simple terminal interface is contained in the spim-7.2/spim directory and the X-windows interfaces is in the spim-7.2/xspim directory. The other directories are described in the README file.
    

5. Next, you must set the directories in which spim will be installed by editing the Makefile (the file that contains instructions on building spim). In general, if you are installing spim and want the windowing version (xspim), edit the file xspim/Imakefile. If you don't want xspim or are running on a system without X-windows installed, you use the file spim/Makefile.
   
   Set these pathnames to the appropriate locations for your system:

       EXCEPTION_DIR -- The full pathname of the directory in which to install the spim exception handler (exceptions.s).

       BIN_DIR -- The full pathname of the directory in which spim and xspim should be installed.

       MAN_DIR -- The full pathname of the directory in which the manual pages for spim and xspim should be installed.
   
   In general, the remaining parameters in a Makefile need not be changed.
    

6. Then, if you are using Imakefile file, change to the spim-7.2/xspim directory and type:
   
       % xmkmf
       % make
   If you do not have a copy of xmkmf, you can use the Makefile in the xspim directory, but beware that it may not work on your system because the paths to the X windows libraries could be different.
    

7. If you do not have X-windows, change to the spim-7.2/spim directory, edit Makefile, and type:
   
       % make
      

8. To run spim or xspim, the exception handler must be installed in the directory specified by the variable EXCEPTION_DIR in the Makefile. If the file exception.s is not installed, spim and xspim fail before they start running. You can either install this file by hand or by typing
   
       % make install
   
   which also installs spim or xspim, and the manual pages in the directories that you set (above).
    

9. To test that spim is correctly built, change to the spim-7.2/spim directory and type:
   
       % make test
   
   and examine the output of the test. (Note: the exception handler must be installed before running the test.)

Resources

• Elsevier (aka Morgan Kaufmann) has generously provided the spim documentation (Appendix A) from the third edition of Hennessy & Patterson, Computer Organization and Design: The Hardware/Software Interface. This documentation is far more complete and up-to-date than the documentation included in the spim distribution. The COD documentation includes:

  •  Appendix A: Assemblers, Linkers, and the SPIM Simulator (PDF). An overview and reference manual for spim and the MIPS32 instruction set.

  • Getting Started with spim (PDF). Overview of the console version of spim (both Unix and Windows).

  • Getting Started with xspim (PDF). Overview of the X-windows version of spim.

  • Getting Starting with PCSpim (PDF). Overview of the Microsoft Windows version of spim.

  • SPIM Command-Line Options (PDF). Overview of the command line options of spim (all versions).

• The documentation included with spim is also online (as a postscript or Adobe PDF file). This document is for the original spim (pre-version 7.0), which simulated the MIPS-I architecture rather than MIPS32, and so differs in many minor aspects from the current version of spim. Appendix A of Hennessy & Patterson, Computer Organization and Design: The Hardware/Software Interface (above), is more up-to-date and correct..

• The best book I have seen on MIPS programming is: Dominic Sweetman, See MIPS Run, Morgan Kaufmann, San Francisco, CA, 1999, ISBN 1-55860-410-3.

• MIPS, Inc. has excellent free documentation on the MIPS32 architecture on their website (registration required) http://www.mips.com/products/resource_library/product_materials/MIPS_Architecture.php:

  • MIPS32® Architecture for Programmers Volume I: Introduction to the MIPS32® Architecture (.pdf)

  • MIPS32® Architecture for Programmers Volume II: The MIPS32® Instruction Set (.pdf)

  • MIPS32® Architecture for Programmers Volume III: The MIPS32® Privileged Resource Architecture (.pdf)

• An old reference manual for the MIPS architecture (including processors subsequent to the R2000/R3000) is: Gerry Kane and Joe Heinrich, MIPS RISC Architecture, Prentice Hall, Englewood Cliffs, N.J. 07632 ISBN 0-13-1059254.

• Another good book for the MIPS R2000 and R3000 is: Erin Farquhar and Philip Bunce, The MIPS Programmer's Handbook, Morgan Kaufmann, San Francisco, CA, 1994, ISBN 1-55860-297-6.

• The GNU C compiler can generate code for the MIPS R3000 and can be used as a cross compiler. A retargeted port of gcc is available on the MPS Resource Page. I have not used this compiler.

• Downcast Systems offers a very nice text editor for MIPS assembly code called MIPSter. It has syntax highlight, MIPS-specific help, good integration with SPIM, and a number of other features to make it easier to write assembly code. MIPSter is an inexpensive commercial product, and it offers a limited time trial version.

• Andrea Grandi ported SPIM to the Nokia 770/800 Internet Tablet so you never need to be without the ability to run MIPS programs. The port of SPIM is available at: http://www.ptlug.org/wiki/SPIM_N770.

Changes in Latest Version

The current version of spim is 7.3 (August 2006), which is a minor release that cleans up a number of bugs in 7.2:

• Fix for flex 2.5.33 (internal change broke spim's scanner).

• Exception handler can be a semicolon-separated list of files that will be loaded in order. On Unix, SPIM_EXCEPTION_HANDLER environment variable is consulted before command line arguments.

• Memory corruption caused spim to crash when label was defined twice in succession.

• PCSpim updates register and memory display after a parse error while reading a file.

• Eliminated unnecessary null char between strings in list of strings produced by .asciiz.

• Makefiles (in spim/ and xspim/) now contain clearly defined paths for installing executables, exception handler, and man pages. The man pages are no longer installed by the "make install" command.

• Change psfig to epsfig in spim.tex (does anyone still use this obsolete documentation?).

The previous version of spim is 7.2.1 (August 2005), which is a minor release that cleans up a number of bugs in 7.1:

• Fixed multiple problems in memory mapped IO in xspim and spim. (Note: to make programming uniform across all three platforms, memory mapped IO now follows"Unix" handling of carriage return (CR) and new line (NL) characters . On input, a CR is translated to a NL, and on output, a CR is printed after a NL. This was previously true for PCSpim and xspim, but not spim.)

• Fixed bug in indexed address computation in LW and SW instructions.

• Eliminated non-POSIX flags IUCLC and IXANY to facilitate port to Mac OS X.

• Use termios(3) library calls instead of IOCTLs to fix bug introduced in port from termio to termios struct.

• Test default case for jalr, without default $rd (=31).

• Trap handler in test extracted wrong bits from ExcCode field of Cause register.

• Pervasive restructuring of files to put 3 UIs (spim, xspim, PCSpim) in separate directories and cleanup organization and Makefiles.

• Use correct help file in install process.

• Added work-around for bug in flex 2.5.31 that left yytext_ptr undefined.

• Epilogue code restored $at register, then used a pseduo instructions that smashed it.

• Cleared filename when reinitializing PCSpim, which broke next reload command.

The previous version of spim is 7.1 (January 2005), which is a minor release that cleans up a number of bugs in 7.0:

• Minor cleanup.

• Switched Windows installer to Microsoft .msi installer, from InstallShield.

• exceptions.s used wrong mask for exception cause field.

• Clearing the transmitter or receiver interrupt enable bits also clear interrupt pending bits in Cause register.

• Code to poll for a console input character in X windows blocked and prevented any output until input occured.

• Type of "mul" instruction was wrong, which lead to it being printed without destination register.

• Print underlying instruction, not breakpoint.

• Unparing error that unparsed beq as beql.

• Eliminated dependence on obsolete termio.h in favor of POSIX termios.h since Mac OS X doesn't have termio.h any more.

• Fix null pointer problem if no entries in registry.

• Turn off EXL bit after break instruction, since break is handled by spim, not MIPS, code and the bit was never cleared.

• Set default path for exceptions.s to C:\Program Files\PCSpim, the default installation directory.

• Test for SQRT.S used double constant, which failed on SPARC (but not x86).

The previous version of spim is 7.0 (August 2004), which is a major release that contains a significant number of changes from version 6.5:

• Upgraded simulator to MIPS32, Version 1 architecture (except details of FPU and memory).

• Exceptions and interrupts reimplemented, to make them closer to the actual hardware.

• Memory mapped IO console reimplemented to make it work properly.

• Implemented timer in CPU.

• Renamed "trap" to "exception" to correspond to MIPS terminology.

• Introduced short forms of command line arguments and dropped need for "-file" argument.

• Major internal cleanup and reorganization of code to eliminate unused code and simplify implementation.

• PCSpim prompts about reinitialization when file reloaded.

• PCSpim lets user set font.

• Word align all segment boundaries and ensure sbrk returns word-aligned addresses.

• Added new syscall (EXIT2_SYSCALL) that returns value from SPIM.

• Improved implementation of delayed load instructions.

• Refactored the test cases, so that endian-independent code is in tt.core.s

• Many small bug fixes.

Outstanding bugs in 7.0:

• The trap handler (exceptions.s) fails when the trapping instruction is in the delay slot of a branch or jump. The trap handler returns by simplemindedly adding 4 to the EPC (which is the branch's address in this case), so it does not return to the instruction executed after the trapping instruction.

• Handling of newlines and carriage returns is inconsistent between platforms. When a program prints a newline, PCSpim also prints a carriage return, spim and xspim don't. Or, is this consistent with the underlying platform?

The previous version of spim is 6.5 (January 2003), which contains the following changes from version 6.4:

• If started program is started with only one argument, assume it is a file name.

• Added Alt-F4 shortcut to PCSpim.

• Fixed trap.handler to return to instruction at EPC on interrupt.

• Fixed (real!) hardware exception on integer overflow in division.

• -trap_file did not properly parse argument in xspim.

• Fixed printing of error on last line without a carriage return.

• Print proper registers when printing hex FP numbers.

• Properly zero newly allocated memory.

• Added nops (addu $0, $0, 0) to trap handler, so that it works properly in bare mode!

• PCSPIM.HLP file was corrupted.

The previous version of spim is 6.4 (January 2002), which contains the following changes from version 6.3:

• PCSpim no longer shifts the focus of the register and data segments when values change.

• Fixed bug in the expansion of USH pseudo-op.

• Add system calls for open, close, read, and write.

• Fixed the Configure file to work with Mac OSX.

• Made the REM pseudo-op require 3 arguments.

• Fixed PCSpim dumping code to dump contents of console window.

• Treat LUI's immediate value as unsigned, as it is not sign extended.

• More error checking for malformed programs.

• Make symbol "main" as global.

• Avoid clearing last few bytes of data segments when they expand.

• Check that high-order 4 bits in jump instruction's PC match bits in target PC.

The previous version of spim is 6.3 (January 2001), which contains the following changes from version 6.2:

• PCSpim interface simplified to 4 fixed panes, similar to xspim, which permit cut and paste.

• PCSpim console stays on the screen after assembly program  terminates.

• Comments in assembly source displayed in text segment.

• NOP is standardized to sll $0 $0 0 (= 0x00000000)

• Fixed several bugs and missed optimization in computing immediate values in lw/sw instruction sequences.

• High 2 bits in negative branch offsets were incorrect.

• Display floating point registers with up to 18 digits of precision.

• New spim command (print_all_regs) prints all registers.

• Minor changes to compile spim under cygwin for Windows.

• Validate the range of immediate values in MIPS (but not pseudo) instructions.

• Fixed display of stack with non-word aligned $sp.

• New flags:

  • -delayed-branches  Simulate MIPS delayed control transfers for branches, jumps, and calls

  • -delayed-loads Simulate MIPS non-interlocked loads.

Copyright

spim is copyrighted by James R. Larus and distributed under the following conditions:

• You may make copies of spim for your own use and modify those copies.
• All copies of spim must retain my name and copyright notice.
• You may not sell spim or distribute spim in conjunction with a commercial product or service without the expressed written consent of James Larus.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

 The DOS and Windows ports were done by David A. Carley and are copyrighted by Morgan Kaufmann Publishers.

SPIMSAL Note

spimsal is an old version of spim that ran on PCs running Windows 3.1 and Macintoshes. spimsal implements an extended version of the MIPS instruction set and is based on an old version of spim. It also does NOT run under Windows 95 or Windows NT.