MARS - Mips Assembly and Runtime Simulator

Version 3.2.1

18 January 2007

Introduction

MARS, the Mips Assembly and Runtime Simulator, will assemble and simulate the execution of MIPS assembly language programs. It can be used either from a command line or through its integrated development environment (IDE). MARS is written in Java and requires at least version 1.4 of the J2SE Java Runtime Environment (JRE) to work. It is distributed as an executable JAR file. The MARS home page is http://courses.missouristate.edu/KenVollmar/MARS/. This document is available for printing there.

As of version 3.2, MARS assembles and simulates 155 basic instructions of the MIPS-32 instruction set, 319 pseudo-instructions or instruction variations and 17 syscall functions mainly for console and file I/O. These are listed in a separate help tab. It supports seven different memory addressing modes for load and store instructions: label, immed, label+immed, ($reg), label($reg), immed($reg), and label+immed($reg), where immed is an integer up to 32 bits. A setting is available to disallow use of pseudo-instructions and extended instruction formats and memory addressing modes.

Our guiding reference in implementing the instruction set has been Computer Organization and Design, Third Edition by Patterson and Hennessy, Elsevier - Morgan Kaufmann, 2005. It summarizes the MIPS-32 instruction set and pseudo-instructions in Figures 3.24 and 3.25 on pages 226-227, with details provided in the text and in Appendix A. MARS version 3.2 implements all the instructions in Appendix A and those figures except the delay branches from the left column of Figure 3.25. It also implements all the system services (syscalls) and assembler directives documented in Appendix A.

The MARS IDE provides program editing and assembling but its real strength is its support for interactive debugging. The programmer can easily set and remove execution breakpoints or step through execution forward or backward (undo) while viewing and directly editing register and memory contents.

Using MARS from a command line.

MARS can be run from a command interpreter to assemble and execute a MIPS program in a batch fashion. The format for running MARS from a command line is:

java -jar mars.jar [options] program.asm [more.asm]

Valid options (not case sensitive, separated by spaces) are:

aassemble only, do not simulate
bbrief - do not display register/memory address along with contents
ddisplay MARS debugging statements (of interest mainly to MARS developer)
decdisplay memory or register contents in decimal.
hexdisplay memory or register contents in hexadecimal (default)
hdisplay this help. Use this option by itself and with no filename.
nppseudo-instructions or extended instruction formats are not permitted.
pproject option - will assemble the specified file and all other assembly files (*.asm; *.s) in its directory.
nwhere n is an integer maximum count of execution steps to simulate. If 0, negative or not specified, there is no maximum.
$regwhere reg is number or name (e.g. 5, t3, f10) of register whose content to display at end of run. Even-numbered float register displays both float and double. Option may be repeated.
m-nmemory address range from m to n whose contents to display at end of run. m and n may be decimal or hexadecimal (starts with 0x), m <= n,both must be on word boundary. Option may be repeated.

Example: java -jar mars.jar h
Displays command options and explanations.

Example: java -jar mars.jar $s0 $s1 0x10010000-0x10010010 fibonacci.asm
Assemble and run fibonacci.asm. At the end of the run, display the contents of registers $s0 and $s1, and the contents of memory locations 0x10010000 through 0x10010010. The contents are displayed in hexadecimal format.

Example: java -jar mars.jar a fibonacci.asm
Assemble fibonacci.asm. Does not attempt to run the program, and the assembled code is not saved.

Example: java -jar mars.jar 100000 infinite.asm
Assemble and run infinite.asm for a maximum of 100,000 execution steps.

Example: java -jar mars.jar p major.asm
Assemble major.asm and all other files in the same directory, link the assembled code, and run starting with the first instruction in major.asm.

Example: java -jar mars.jar major.asm minor.asm sub.asm
Assemble and link major.asm, minor.asm and sub.asm. If successful, execution will begin with the first instruction in major.asm.

The ability to run MARS from the command line is useful if you want to develop scripts (macros) to exercise a given MIPS program under multiple scenarios or if you want to run a number of different MIPS programs such as for grading purposes.

Using MARS through its IDE

The IDE is invoked when MARS is run with no command arguments, e.g. java -jar mars.jar. It may also be launched from a graphical interface by double-clicking the mars.jar icon that represents this executable JAR file. The IDE provides basic editing, assembling and execution capabilities. Hopefully it is intuitive to use. Here are comments on some features.

The assembler and simulator are invoked from the IDE when you select the Assemble, Go, or Step operations from the Run menu or their corresponding toolbar icons or keyboard shortcuts. MARS messages are displayed on the MARS Messages tab of the message area at the bottom of the screen. Runtime output is displayed on the Run I/O tab. Runtime input is entered through a pop-up dialog box then echoed to the Run I/O tab.

MARS provides many features for interactive debugging through its execute pane. Features include:

Cool Capability: Plug-in Tools

Beginning with Version 2.0, MARS is capable of running externally-developed software that interacts with an executing MIPS program and MIPS system resources. The requirements for such a program are:
  1. It implements the mars.tools.MarsTool interface.
  2. It is part of the mars.tools package.
  3. It compiles cleanly into a ".class" file, stored in the mars/tools directory.
MARS will detect all qualifying tools upon startup and include them in its Tools menu. When a tool's menu item is selected, an instance of it will be created using its no-argument constructor and its action() method will be invoked. If no qualifying tools are found at MARS startup, the Tools menu will not appear.

To use such a tool, load and assemble a MIPS program of interest then select the desired tool from the Tools menu. The tool's window will open and depending on how it is written it will either need to be "connected" to the MIPS program by clicking a button or will already be connected. Run the MIPS program as you normally would, to initiate tool interaction with the executing program.

Beginning with Version 3.2, the abstract class mars.tools.AbstractMarsToolAndApplication is included in the MARS distribution to provide a substantial framework for implementing your own MARS Tool. A subclass that extends it by implementing at least its two abstract methods can be run not only from the Tools menu but also as a free-standing application that uses the MARS assembler and simulator in the background.

Several Tools developed by subclassing AbstractMarsToolAndApplication are included with MARS: an Introduction to Tools, a Data Cache Simulator, a Memory Reference Visualizer, and a Floating Point tool. The last one is quite useful even when not connected to a MIPS program because it displays binary, hexadecimal and decimal representations for a 32 bit floating point value; when any of them is modified the other two are updated as well.

If you wish to develop your own MARS Tool, you will first need to extract the MARS distribution from its JAR file if you have not already done so. As of Version 3.2, all MARS tools must be stored in the mars/tools directory.

An API for this feature is forthcoming. Please check the MARS homepage.

Cool Capability: Extending the syscall set or reassigning syscall numbers

Beginning with Version 3.1, system calls (syscall instruction) are implemented using a technique similar to that for tools. This permits anyone to add a new syscall by defining a new class that meets these requirements:
  1. It implements the mars.mips.instructions.syscalls.Syscall interface, or extends the mars.mips.instructions.syscalls.AbstractSyscall class (which provides default implementations of everything except the simulate() method).
  2. It is part of the mars.mips.instructions.syscalls package.
  3. It compiles cleanly into a ".class" file, stored in the mars/mips/instructions/syscalls directory.
MARS will detect all qualifying syscall classes upon startup and the runtime simulator will invoke them when the syscall instruction is simulated and register $v0 contains the corresponding integer service number.

Syscalls and syscall number assignments in MARs match those of SPIM. However if you wish to change syscall number assignments, you may do so by editing the Syscall.properties file included in the release (this requires extracting it from the JAR file).

An API for this feature is forthcoming. Please check the MARS homepage.

Cool Capability: Extending the instruction set

You can add customized pseudo-instructions to the MIPS instruction set by editing the PseudoOps.txt file included in the MARS distribution. Instruction specification formats are explained in the file itself. The specification of a pseudo-instruction is one line long. It consists of an example of the instruction, constructed using available instruction specification symbols, followed by a tab-separated list of the basic MIPS instructions it will expand to. Each is an instruction template constructed using instruction specification symbols combined with special template specification symbols. The latter permit substitution at program assembly time of operands from the user's program into the expanded pseudo-instruction.

PseudoOps.txt is read and processed at MARS startup, and error messages will be produced if a specification is not correctly formatted. Note that if you wish to edit it you first have to extract it from the JAR file.

Some MARS Assembler and Simulator Limitations

Limitations of MARS as of Version 3.2 include: Versions 3.0 and later assemble and simulate nearly all the MIPS32 instructions documented in the textbook Computer Organization and Design, Third Edition by Patterson and Hennessy, Elsevier - Morgan Kaufmann, 2005. All basic and pseudo instructions, directives, and system services described in Appendix A are implemented.

Some MARS IDE Limitations

The text editor is not "MIPS aware" and is similar to using Notepad. It does however display the current cursor position in line-column format and allows you to display line numbers. It also has unlimited Undo/Redo capability. If you want to use an outside text editor, MIPSter is a fine shareware MIPS text editor that can be used outside MARS. See http://www.downcastsystems.com/mipster/. If you do this, we suggest you select the MARS setting to assemble files automatically upon opening.

You can only work on one file at a time. Selecting New or Open closes the existing file. It is however possible to assemble and link a multi-file project by placing all source files in the same directory and selecting the "Assemble operation applies to all files in current directory." setting in the Settings menu. The MARS command mode additionally allows you to list specific files to be assembled and linked.

Configuration changes other than those in the Settings menu (e.g., moving or resizing windows) are not saved so will not be restored the next time MARS is run.

The IDE will work only with the MARS assembler. It cannot be used with any other compiler, assembler, or simulator. The MARS assembler and simulator can be used either through the IDE or from a command prompt.

This Implementation

Dr. Ken Vollmar initiated MARS development in 2002 at Missouri State University. In 2003, Dr. Pete Sanderson of Otterbein College and his student Jason Bumgarner continued implementation. Sanderson implemented the assembler and simulator that summer, and the basic GUI the following summer, 2004.

MARS 1.0 was released in January 2005 and publicized during a poster presentation at SIGCSE 2005.

MARS 2.0 incorporated significant modifications to both the GUI and the assembler (floating point registers and instructions most notably) and was released in September 2005.

MARS 2.1 was released in October 2005 with some bug fixes.

MARS 2.2 was released in March 2006 with additional bug fixes and implemented command line options (run MARS from command line with h option for command line help). This also coincides with our SIGCSE 2006 paper "MARS: An Education-Oriented MIPS Assembly Language Simulator".

MARS 3.0 was released in August 2006, with one bug fix and two major additions.

MARS 3.1 was released in October 2006. The major issues and features are listed here:

MARS 3.2 was released in December 2006. Major accomplishments are:

MARS 3.2.1 was released in January 2007. It is a bug fix release that addresses the following bug in 3.2: a NullPointerException occurs when MIPS program execution terminates by "dropping off the bottom" of the program rather than by using one of the Exit system calls.

The development of Versions 3.1 and 3.2 during fall 2006 was supported by the Otterbein College sabbatical leave program.

MARS is written in Java and requires at least version 1.4 of the J2SE Java Runtime Environment (JRE) to work. The GUI is implemented with Swing. It has been tested and run on Windows XP and Mac OS X.

Questions and Comments

Send MARS questions and comments to Dr. Ken Vollmar at KenVollmar@missouristate.edu or Dr. Pete Sanderson at PSanderson@otterbein.edu. We will respond as quickly as we can but as teaching professors do not have as much time to work on this project as we would like during the school year (aside from the aforementioned fall 2006 sabbatical). We presented papers on MARS at the 2005 CCSC:MW conference and the 2006 SIGCSE Technical Symposium.

This document is available for printing on the MARS home page http://courses.missouristate.edu/KenVollmar/MARS/.