SPIM MIPS Simulator SPIM A MIPS32 Simulator James Larus larus@microsoft.com Formerly: Professor, Computer Sciences Department, University of Wisconsin-Madison Currently: Senior Researcher, Microsoft Research spim is a self-contained simulator that will run MIPS32 assembly language programs. It reads and immediately executes assembly language code for this processor. spim 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 some complex floating point comparisons and rounding modes and details of the memory system page tables.) The MIPS architecture has several variants that differ in minor ways (in particular, the MIPS64), which means that spim will not run programs compiled for recent SGI processors. MIPS compilers also generate a number of assembler directives that spim cannot process. These directives 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 long obsolete (though, has never been surpassed for its simplicity and elegance), so SPIM now supports the more modern MIPS32 architecture, which contains a large number of rarely 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 that handles exceptions will need to be updated. Examples of the 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 visual windowing interface. On Unix, the spim program provides the terminal interface and the xspim program provides the X window interface. On PCs, the spim program provides the console interface and PCSpim provides the Windows interface. Downloading SPIM Platform Program Form File Unix or Linux system spim xspim Source code http://www.cs.wisc.edu/~larus/SPIM/spim.tar.Z or http://www.cs.wisc.edu/~larus/SPIM/spim.tar.gz Microsoft Windows (Windows 95, 98, NT, 2000, XP) spim PCSpim Executable http://www.cs.wisc.edu/~larus/SPIM/pcspim.zip Source code http://www.cs.wisc.edu/~larus/SPIM/pcspim_src.zip To run spim or xspim on a Unix or Linux system, copy either the compressed tar file (http://www.cs.wisc.edu/~larus/SPIM/spim.tar.Z) or the gzip'ed tar file (http://www.cs.wisc.edu/~larus/SPIM/spim.tar.gz). Both files contains source code and must be compiled on a particular system. To run PCspim on a PC under Microsoft Windows, download the file http://www.cs.wisc.edu/~larus/SPIM/pcspim.zip, unzip it, and run setup.exe. Source for the PC version (both PCspim and spim) is available separately in the file http://www.cs.wisc.edu/~larus/SPIM/pcspim_src.zip. There is no specific Macintosh version of spim. However, the Unix version of xspim can be compiled and run on Mac OS X. Installation Windows Download the file http://www.cs.wisc.edu/~larus/SPIM/pcspim.zip and save it on your machine. Unzip the file. Run the setup.exe program. Unix, Linux, or Mac OS X 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. Download either the file http://www.cs.wisc.edu/~larus/SPIM/spim.tar.Z or http://www.cs.wisc.edu/~larus/SPIM/spim.tar.gz. 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 Move the file spim.tar to the directory in which you want to build spim and untar it: % tar xf spim.tar To compile spim, you must first configure it for your system by running the Configure script: % Configure Note: Configure compiles a program with the C compiler named cc. If you want it to use another compiler, set the environment variable CC to its name before running the script, e.g.: % setenv CC gcc % Configure Next, you must set the directories in which spim will be installed by editing a makefile (the file that tells how to build spim). In general, if you are installing spim and want the windowing version (xspim), you will edit the file Imakefile. If you don't want xspim or are running on a system without X-windows installed, you can use the file Makefile.std. Finally, if you are running under Microsoft Windows using Cygwin, edit the file Makefile.cygwin. 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 the makefile need not be changed. Then, if you are using Imakefile type: % xmkmf % make If you want an X-window version of spim, also type: % make xspim If you do not have X-windows or the program xmkmf, edit either Makefile.std or Makefile.cygwin and type: % make -f Makefile.std test 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, xspim, and the manual pages in the directories that you set (above). To test that spim is correctly built, type % make test and examine the output of the test. (Note: the exception handler must be installed before running the test.) Resources Morgan Kaufmann has generously provided an on-line version of Appendix A from Hennessy & Patterson, Computer Organization and Design: The Hardware/Software Interface (as a Adobe PDF file). This is a complete and more up-to-date version of documentation included with spim. 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 recent and through.. There is some documentation for the Windows interface to spim: Adobe PDF file. The best book for MIPS programmers 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): MIPS32� Architecture for Programmers Volume I: Introduction to the MIPS32� Architecture v2.00 (1249 KB) MIPS32� Architecture for Programmers Volume II: The MIPS32� Instruction Set v2.00 (3258 KB) MIPS32� Architecture for Programmers Volume III: The MIPS32� Privileged Resource Architecture v2.00 (1507 KB) 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 MIPS R2000 and R3000 programmers 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 easily be used as a cross compiler. A retargeted port of gcc is available on the MPS Resource Page. I have not used this compiler. Changes in Latest Version The current version of spim is 7.0 (March 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 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.
