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:
a | assemble only, do not simulate |
b | brief - do not display register/memory address along with contents |
d | display MARS debugging statements (of interest mainly to MARS developer) |
dec | display memory or register contents in decimal. |
hex | display memory or register contents in hexadecimal (default) |
h | display this help. Use this option by itself and with no filename. |
np | pseudo-instructions or extended instruction formats are not permitted. |
p | project option - will assemble the specified file and all other assembly files (*.asm; *.s) in its directory. |
n | where n is an integer maximum count of execution steps to simulate.
If 0, negative or not specified, there is no maximum. |
$reg | where 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-n | memory 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.
- Menus and Toolbar: Most menu items have equivalent toolbar icons.
If the function of a toolbar icon is not obvious, just hover the mouse over it and
a tool tip will soon appear. Nearly all menu items also have keyboard shortcuts.
Any menu item not appropriate in a given situation is disabled.
- Editor: MARS includes a basic text editor. Its functionality is
roughly equivalent to Notepad. Notice on the bottom border that the cursor line
and column position is maintained and there is a checkbox to show line numbers.
They are displayed outside the editing area. If you use an external editor, MARS provides
a convenience setting that will automatically assemble a file as soon as it is opened. Check
the Settings menu.
- Message Areas: There are two tabbed read-only message areas at the
bottom of the screen. The Run I/O tab is used at runtime for
displaying console I/O as program execution progresses. User console input
is typed into a pop-up dialog then echoed to the message area.
The MARS Messages tab is used for other messages such as assembly or
runtime errors and informational messages.
- MIPS Registers: MIPS registers are displayed at all times, even
when you are editing and not running a program. While writing your program,
this serves as a useful reference for register names and their conventional
uses (hover mouse over the register name to see tool tips). There are three
register tabs: the Register File (integer registers $0 through $31 plus LO,
HI and the Program Counter), selected Coprocesor 0 registers (exceptions and
interrupts), and Coprocessor 1 floating point registers.
- Assembly: Select Assemble from the Run menu or the
corresponding toolbar icon to assemble the file currently in the Edit tab.
Prior to Version 3.1, only one file could be assembled and run at a time.
Versions 3.1 and later provide a primitive Project capability. To use it, go to the
Settings menu and check Assemble operation applies to all
files in current directory. Subsequently, the assembler will assemble
the current file as the "main" program and also assemble all other assembly
files (*.asm; *.s)
in the same directory. The results are linked and if all these
operations were successful the program can be executed. Labels that are
declared global with the ".globl" directive may be referenced in any of the
other files in the project. There is also a setting that permits
automatic loading and assembly of a selected exception handler file.
- Execution: Once a MIPS program successfully assembles, the
registers are initialized and three windows
in the Execute tab are filled: Text Segment, Data Segment,
and Program Labels. The major execution-time features are described below.
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:
- Execute windows can all be resized, moved, maximized or minimized.
- Their contents are scrollable,
and are updated whenever execution pauses (step mode, breakpoint, or
slow run speed) or
terminates.
- Their columns can be re-ordered (except data segment) or
resized.
- In Step mode, the next instruction to be simulated is highlighted and
memory content displays are updated at each step.
- Select the Go option if you want to simulate continually.
It can also be used to continue simulation
from a paused (step, breakpoint, pause) state.
- Breakpoints are easily set and reset using the check boxes next to each instruction displayed
in the Text Segment window.
- When running in the Go mode, you can select the simulation
speed using the Run Speed slider. Available speeds range
from .05 instructions per second (20 seconds between steps) up to 30
instructions per second, then above this offers an "unlimited" speed.
When using "unlimited" speed, code highlighting and memory display updating
are turned off while simulating (but it executes really fast!).
When a breakpoint is reached, highlighting and updating occur.
Run speed can be adjusted while the program is running.
- When running in the Go mode, you can pause or stop
simulation at any time using the Pause or Stop features.
The former will pause execution and update the display, as if you
were stepping or at a breakpoint. The latter will terminate execution
and display final memory and register values. If running at "unlimited"
speed, the system may not respond immediately but it will respond.
- When program execution is paused or terminated, select Reset
to reset all memory cells and registers to their initial values.
- Memory addresses and values, and register values, can be viewed in either decimal
or hexadecimal format. All data are stored in little-endian byte order (each
word consists of byte 3 followed by byte 2 then 1 then 0). Note that each word
can hold 4 characters of a string and those 4 characters will appear in the
reverse order from that of the string literal.
- Data segment contents are displayed 512 bytes
at a time (with scrolling) starting with the data segment base address (0x10010000).
Navigation buttons are provided to change the display to the next
section of memory, the previous, or back to the initial (home) range. A combo box is
also provided to view memory contents in the vicinity of the stack pointer
(contents of MIPS $sp register), global pointer (contents of MIPS $gp register),
the heap base address (0x10040000), .extern globals (0x10000000),
the kernel data segment (0x90000000), or memory-mapped IO (MMIO, 0xFFFF0000).
- Contents of any data segment memory word and almost any MIPS register can be modified by
editing its displayed table cell. Double-click on a cell to edit it. If you
enter an invalid 32-bit integer, the word INVALID appears in the cell
and memory/register contents are not affected. Values can be entered
in either decimal or hexadecimal (leading "0x"). Negative hexadecimal
values can be entered in either two's complement or signed format. Note
that three of the integer registers (zero, program counter, return address)
cannot be edited.
- Contents of cells representing floating point registers can be edited by
as described above and will accept valid hexadecimal or decimal floating point
values. Since each double-precision register overlays two single-precision
registers, any changes to a double-precision register will affect one or both
of the displayed contents of its corresponding single-precision registers.
Changes to a single-precision register will affect the display of its
corresponding double-precision register. Values entered in hexadecimal
need to conform to IEEE-754 format. Values entered in decimal are entered
using decimal points and E-notation (e.g. 12.5e3 is 12.5 times 10 cubed).
- Cell contents can be edited during program execution and once accepted
will apply starting with the next instruction to be executed.
- Versions 3.0 and later include a Settings menu. Each setting includes a checkbox
for selecting or deselecting it. Settings and their default
values are:
- Display the Labels Window (symbol table) in the Execute tab. Default value is false. If selected, the Labels Window will be
displayed to the right of the Text Segment.
- Permit programs to use extended (pseudo) instructions and formats. Default value is true. This includes all memory addressing
modes other than the MIPS native mode (16 bit constant offset added to register content).
- Assemble a file automatically as soon as it is opened, and initialize the File Open dialog with the most-recently opened file.
Default value is false. This is convenient if you use an external editor for composing your programs.
- Assemble operation applies to all files in current directory. Default value is false.
If selected, the file currently open in the
editor will become the "main" program in a multi-file assemble-and-link operation involving all
assembly files (*.asm; *.s) in its directory. If successful, execution will begin with the currently open file.
- Display memory addresses in hexadecimal. Default value is true. If deselected, addresses will be displayed in decimal.
This setting can also be toggled in a checkbox on the border of the Data Segment Window.
- Display memory and register contents in hexadecimal. Default value is true. If deselected, vlaues will be displayed in decimal.
This setting can also be toggled in a checkbox on the border of the Data Segment Window.
- Beginning with Version 3.2, the Exception Handler dialog. The setting is: Include this
exception handler in all assemble operations. Default value is false. If selected, a button to browse to the desired
file is enabled.
Beginning with Version 3.2 all settings are retained from one interactive session to the next.
These settings are independent of command options given when using MARS from a command line;
neither affects the other. We anticipate future versions will include additional settings and preferences.
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:
- It implements the mars.tools.MarsTool interface.
- It is part of the mars.tools package.
- 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:
- 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).
- It is part of the mars.mips.instructions.syscalls package.
- 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:
- Memory segments (text, data, stack, kernel text, kernel data) are limited to 4MB starting at their
respective base addresses.
- It does not support external device interrupts. It does support exceptions and exception (trap) handlers.
- There is no pipelined mode.
- Delayed branches are not supported.
- Self-modifying code is not supported. This is a program that during
execution modifies the contents of its own text segment (binary instructions).
- If you open a file which is a link or shortcut to another file, MARS will not
open the target file. The file open dialog is implemented using Java Swing's JFileChooser,
which does not support links.
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.
- The bug fix was corrected instruction format for the slti and sltiu instructions.
- One major addition is a greatly expanded MIPS-32 instruction
set (trap instructions are the only significant ones to remain unimplemented). This includes, via
pseudo-instructions, all reasonable memory addressing modes for the load/store instructions.
- The
second major addition is ability to interactively step "backward" through program execution
one instruction at a time to "undo" execution steps. It will buffer up to 2000 of the most
recent execution steps (this limit is stored in a properties file and can be changed).
It will undo changes made to MIPS memory, registers or condition flags,
but not console or file I/O. This should be a great debugging aid.
It is available anytime execution is paused and at termination (even if terminated due to
exception).
- A number of IDE settings, described
above, are now available through the Settings menu.
MARS 3.1 was released in October 2006. The major issues and features are listed here:
- It addressed several minor limits (Tools menu items
could not be run from the JAR file, non-standard shortcuts for Mac users, inflexible and
sometimes inappropriate sizing of
GUI components).
- It changed the way SYSCALLs are implemented, to allow anyone to define
new customized syscall services without modifying MARS.
- It added a primitive
Project capability through the "Assemble operation applies to all files in current directory."
setting (also available as "p" option on the command version). The command version also allows you
to list several file names not necessarily in the same directory to be assembled and linked.
- Multi-file assembly also required implementing the ".globl" and ".extern" directives.
- And although "Mars tools" are not officially part of the release, MARS 3.1 includes the
initial versions of two tools: one for learning about floating point representation and another
for simulating data caching capability.
MARS 3.2 was released in December 2006. Major accomplishments are:
- It fixes several minor bugs, including one that
could cause incorrect file sequencing in the Project feature.
- It includes the
AbstractMarsToolAndApplication abstract class to serve as a framework for easily
constructing "tools" and equivalent free-standing applications that use the MARS assembler
and simulator engines (kudos to the SIGCSE 2006 audience member who suggested this capability!).
A subclass of this abstract class can be used both ways (tool or application).
- The floating
point and data cache tools were elaborated in this release and a new tool for animating and
visualizing memory references was developed. All are AbstractMarsToolAndApplication
subclasses.
- This release includes support for exception handlers: the kernel data and text
segments (.kdata and .ktext directives), the MIPS trap-related instructions, and the ability
to automatically include a selected exception (trap) handler with each assemble operation.
- Items in the Settings menu became persistent with this release.
- Added default assembly file extensions "asm" and "s" to the Config.properties file and used
those not only to filter files for the File Open dialog but also to filter them for the "assemble all"
setting.
- Implemented a limit to the amount of text scrollable in the Mars Messages and Run I/O message
tabs - default 1 MB is set in the Config.properties file.
- For programmer convenience, labels can now be referenced in the operand field of integer
data directives (.word, .half, .byte). The assembler will substitute the label's address (low order
half for .half, low order byte for .byte).
- For programmer convenience, character literals (e.g. 'b', '\n', '\377') can be used anywhere that integer literals are
permitted. The assembler converts them directly to their equivalent 8 bit integer value. Unicode is not supported and
octal values must be exactly 3 digits ranging from '\000' to '\377'.
- Replaced buttons for selecting Data Segment display base addresses with a combo box and added more
base addresses: MMIO (0xFFFF0000), .kdata (0x90000000), .extern (0x10000000).
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/.