SPIM A MIPS32 Simulator

spim has moved to SourceForge.org. New versions of spim are at that site. This site only contains old versions of the simulator.

Why move? SourceForge offers a number of services, such as a source code repository and collaborative tools, that make it easier to share code with other developers. Now that spim has an open source license, the time has come to move off a 20-year old web site and join the 21st century.

spim is a self-contained simulator that runs MIPS32 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 MIPS processors. MIPS compilers also generate a number of assembler directives that spim cannot process. These directives usually can be safely ignored.

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, never 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). This type of code will need to be updated. Examples of new exception handling are in the files: 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 terminal and a window interface. On Microsoft Windows, Linux, and Mac OS X, the spim program provides the simple terminal interface and the QtSpim program provides the windowing interface.

Happy Birthday SPIM!

spim turned 20 years old January 2010. I wrote the original version of spim as the target machine for my first compiler class at University of Wisconsin, Madison in the spring semester 1990. spim is likely older than most of the students currently using it!

As a birthday present, the 8.0 version of spim has a simpler, less restrictive license, namely the standard BSD license.

QtSpim

The newest version of spim is called QtSpim, and unlike all of the other version, it runs on Microsoft Windows, Mac OS X, and Linux—the same source code and the same user interface on all three platforms! QtSpim is the version of spim that currently being actively maintaned. The other versions are still available, but please stop using them and move to QtSpim. It has a modern user interface, extensive help, and is consistent across all three platforms. QtSpim makes my life far easier, and will likely improve yours and your students' experience as well.

A compiled, immediately installable version of QtSpim is available for Microsoft Windows, Mac OS X, and Linux can be downloaded from: https://sourceforge.net/projects/spimsimulator/files/. Full source code is also available (to compile QtSpim, you need Nokia's Qt framework, a very nice cross-platform UI framework that can be downloaded from here).

Further Information

• 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 http://www.mips.com/products/product-materials/processor/mips-architecture/:

  • 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 9.0 (January 2011), which is a major release that introduces QtSpim and fixes some bugs in all versions:

• Add Debian package and Linux desktop metadata.

• Moved SVN repository to SourceForge.

• Fit and finish bugs in PCSpim and error parsing quoted command line arguments.

• QtSpim!!!

• Single stepping hung at breakpoint.

• Did not display first 4K of the stack.

• Ported PCSpim to VisualStudio 2010.

• Fixed type errors so code compiles under Linux and on x64 systems.

• Moved version information into CPU/version.h and eliminated old, ad-hoc Configure file for spim and xpsim.

The current version of spim is 8.0 (January 2010), which is a minor release that cleans up bugs in 7.5 and moves to a BSD license:

• Changed install path from /usr to /usr/local and removed -D option to install command (which doesn't exists on Mac OS X).

• Change license to a BSD license, update copyright notices, and eliminated references to my old email address.

• Simplify alignment of data on stack to ensure enough room is left for environment and args at top of stack.

• Initialize stack with arguments when running program from run dialog.

• read_input filled buffer with last character of file not terminated by newline.

• Links to MIPS documentation were broken.

• Did not return value from exit syscall.

The current version of spim is 7.5 (August 2009), which is a minor release that cleans up bugs in 7.4:

• Correct problem with installer script that did not install appropriate versions of msvcrt and mfc dlls for Visual Studio 9.0.

• Fix install scripts to put exceptions.s at /usr/lib/spim on Linux.

• Fixed major memory leak caused by overwritten instructions not being freed.

• Force redisplay of data segment in situations when register values (such as $sp) have changed.

• Properly initialize PC at first invocation of step operation on PCSPim.

• Fixed bug in Xxpim that caused the step commend to reinitialize the stack.

The current version of spim is 7.4 (January 2009), which is a minor release that cleans up bugs in 7.3:

1/14/09: Released new version of pcspim.zip to correct problem with installer script that did not install appropriate versions of msvcrt and mfc dlls.
1/21/09: Released new version of spim.tar.Z and spim.tar.gz to correct problem with install command for spim program (but not xspim).

• Fixed install directories for Linux systems.

• Retained command line arguments in second and subsequent runs.

• Bug in overflow from low-order word in MADD, MSUB.

• Bug in decoding SPECIAL2 instructions (e.g. madd).

The previous 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 Larus and distributed under a BSD license.

Copyright (c) 1990-2010, James R. Larus. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of the James R. Larus nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 The DOS and Windows ports were done by David A. Carley and are copyrighted y 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.