Mars 4.0 was released in August 2010. Enhancements and bug fixes include:
- Coming soon: new text editor (as soon as we resolve display issues on Macs).
- Improved Instruction Help: All the instruction examples in the help tabs (and new popup instruction guides)
now use realistic register names, e.g. $t1, $t2, instead of $1, $2. The instruction format
key displayed above the MIPS help tabs has been expanded to include explanations of the
various addressing modes for load and store instructions and pseudo-instructions.
Descriptions have been added to every example instruction and pseudo-instruction.
- Improved Assembly Error Capability: If the assemble operation results in errors, the first error message
in the Mars Messages text area will be highighted and the corresponding erroneous instruction will be selected in the
text editor. In addition, you can click on any error message in the Mars Messages text area to select the corresponding
erroneous instruction in the text editor. The first feature does not select in every situation (such as when
assemble-on-open is set) but in the situations where it doesn't work no harm is done plus
the second feature, clicking on error messages, can still be used.
- Console input syscalls (5, 6, 7, 8, 12) executed in the IDE now receive input keystrokes directly in the Run I/O text
area instead of through a popup input dialog. Thanks to Ricardo Pascual for providing this feature!
If you prefer the popup dialogs, there is a setting to restore them.
- The floor, ceil, trunc and round operations now all produce the MIPS default result 2^31-1 if the value is
infinity, NaN or out of 32-bit range. For consistency, the sqrt operations now produce the result NaN if the operand is negative
(instead of raising an exception). These cases are all consistent with FCSR (FPU Control and Status Register)
Invalid Operation flag being off. The ideal solution would be to simulate the FCSR register itself so all
MIPS specs for floating point instructions can be implemented, but that hasn't happened yet.
- The Basic column in the Text Segment Window now displays data and addresses in either decimal or
hexadecimal, depending on the current settings. Note that the "address" in branch instructions
is actually an offset relative to the PC, so is treated as data not address. Since data operands in
basic instructions are no more than 16 bits long, their hexadecimal display includes only 4 digits.
- The Source column in the Text Segment Window now preserves tab spacing for a cleaner appearance (tab characters were previously not rendered).
- Instruction mnemonics can now be used as labels, e.g. "b:".
- New syscall 36 will display an integer as an unsigned decimal.
- A new tool, Digital Lab Sim, contributed by Didier Teifreto (email@example.com). This tool
features two seven-segment displays, a hexadecimal keypad, and a counter. It uses MMIO to explore
interrupt-driven I/O in an engaging setting. More information is available from its Help feature. Many thanks!
- MARS 4.0 requires Java 1.5 (5.0) instead of 1.4. If this is an issue for you, let me know.
Mars 3.8 was released in January 2010. Enhancements and bug fixes include:
- A new feature to temporarily suspend breakpoints you have previously set. Use it
when you feel confident enough to run your program without the breakpoints but not
confident enough to clear them! Use the Toggle Breakpoints item in the Run menu, or
simply click on the "Bkpt" column header in the Text Segment window. Repeat, to re-activate.
- Two new Tools contributed by Ingo Kofler of Klagenfurt University in Austria.
One generates instruction statistics and the other simulates branch prediction using
a Branch History Table.
- Two new print syscalls. Syscall 34 prints an integer in hexadecimal format.
Syscall 35 prints an integer in binary format. Suggested by Bernardo Cunha of Portugal.
- A new Setting to control whether or not the MIPS program counter will be
initialized to the statement with global label 'main' if such a statement exists. If
the setting is unchecked or if checked and there is no 'main', the program counter
will be initialized to the default starting address. Release 3.7 was programmed
to automatically initialize it to the statement labeled 'main'. This led to
problems with programs that use the standard SPIM exception handler exceptions.s
because it includes a short statement sequence at the default starting address
to do some initialization then branch to 'main'. Under 3.7 the initialization
sequence was being bypassed. By default this setting is unchecked. This
option can be specified in command mode using the 'sm' (Start at Main) option.
- Mars Tools that exist outside of Mars can now be included in the Tools
menu by placing them in a JAR and including it in a command that launches
the Mars IDE. For example: java -cp plugin.jar;Mars.jar Mars
Thanks to Ingo Kofler for thinking of this technique and providing the
patch to implement it.
- Corrections and general improvements to the MIDI syscalls. Thanks to Max Hailperin
of Gustavus Adolphus College for supplying them.
- Correction to an assembler bug that flagged misidentified invalid MIPS instructions
Mars 3.7 was released in August 2009. Enhancements and bug fixes include:
- A new feature for changing the address space configuration of the
simulated MIPS machine. The 32-bit address space configuration used by
all previous releases remains the default. We have defined two
alternative configurations for a compact 32KB address space. One starts the
text segment at address 0 and the other starts the data segment at address 0.
A 32KB address space permits commonly-used load/store pseudo-instructions
using labels, such as lw $t0,increment, to expand to a single basic
instruction since the label's full address will fit into the 16-bit address
offset field without sign-extending to a negative value. This was done in response to
several requests over the years for smaller addresses and simplified expansions
to make assembly programs easier to comprehend. This release does not
include the ability to define your own customized configuration, although we
anticipate adding it in the future. It is available both through the command
mode (option mc) and the IDE.
See Memory Configuration... at the bottom of the Settings menu.
- Related to the previous item: load and store pseudo-instructions of the form
lw $t0,label and lw $t0,label($t1) will expand to a single
instruction (addi for these examples) if the current memory configuration assures the
label's full address will fit into the low-order 15 bits. Instructions
for which this was implemented are: la, lw, lh, lb, lhu, lbu, lwl, lwr, ll,
lwc1, ldc1, l.s, l.d, sw, sh, sb, swl, swr, sc, swc1, sdc1,
s.s, and s.d.
- If a file contains a global statement label "main" (without quotes, case-sensitive), then execution will
begin at that statement regardless of its address. Previously, program execution
always started at the base address of the text segment. This will be handy for
multi-file projects because you no longer need to have the "main file" opened in
the editor in order to run the project. Note that main has to be declared global
using the .globl directive.
- We have added a Find/Replace feature to the editor. This has been another
frequent request. Access it through the Edit menu or Ctrl-F. Look for major
enhancements to the editor in 2010!
- The syscalls for Open File (13), Read from File (14), and Write to File (15)
all now place their return value into register $v0 instead of $a0. The table
in Computer Organization and Design's Appendix B on SPIM specifies
$a0 but SPIM itself consistently uses $v0 for the return values.
- Pseudo-instructions for div, divu, mulo, mulou, rem, remu, seq, sne, sge,
sgeu, sgt, sgtu, sle, sleu now accept a 16- or 32-bit immediate as their third operand.
Previously the third operand had to be a register.
- Existing Tools were tested using reconfigured memory address space (see first item). Made some
adaptations to the Keyboard and Display Simulator Tool that allow it to be used for
Memory Mapped I/O (MMIO) even under the compact memory model, where the MMIO base address
is 0x00007f00 instead of 0xffff0000. Highlighting is not perfect in this scenario.
- Bug Fix: The syscall for Open File (13) reversed the meanings of the
terms mode and flag. Flags are used to indicate the intended
use of the file (read/write). Mode is used to set file permissions in specific situations.
MARS implements selected flags as supported by Java file streams,
and ignores the mode if specified. For more details, see the Syscalls
tab under Help. The file example in that tab has been corrected.
- Bug Fix: The assembler incorrectly generated an
error on Jump instructions located in the kernel text segment.
- Bug Fix: The project (p) option in the command interface worked incorrectly
when MARS was invoked within the directory containing the files to be assembled.
- Acknowledgement: The development of Release 3.7 was supported by a SIGCSE
Special Projects Grant.
What's New in MARS Version 3.6
3.6 was released in January 2009. Enhancements and bug fixes include:
- We've finally implemented the most requested new feature: memory and register cells will
be highlighted when written to during timed or stepped simulation! The
highlighted memory/register cell thus represents the result of the instruction just completed.
During timed or stepped execution, this is NOT the highlighted instruction. During back-stepping,
this IS the highlighted instruction. The highlighted instruction is the next one
to be executed in the normal (forward) execution sequence.
- In conjunction with cell highlighting, we've added the ability to customize the highlighting
color scheme and font. Select Highlighting in the Settings menu. In the resulting dialog,
you can select highlight background color, text color, and font for the different runtime tables (Text segment,
Data segment, Registers). You can also select them for normal, not just
highlighted, display by even- and odd-numbered row but not by table.
- Cool new Labels Window feature: the table can be sorted in either ascending or descending
order based on either the Label (alphanumeric) or the Address (numeric) column. Just click on
the column heading to select and toggle between ascending (upright triangle) or descending
(inverted triangle). Addresses are sorted based on unsigned 32 bit values.
The setting persists across sessions.
- The Messages panel, which includes the Mars Messages and Run I/O tabs, now displays using
a mono-spaced (fixed character width) font. This facilitates text-based graphics when running
from the IDE.
- The Mars.jar distribution file now contains all files needed to produce
a new jar file. This will make it easier for you to expand the jar, modify source files,
recompile and produce a new jar for local use. CreatMarsJar.bat contains the jar instruction.
- The Help window now includes a tab for Acknowledgements. This recognizes MARS contributors
- We've added a new system call (syscall) for generating MIDI tones synchronously, syscall 33.
The original MIDI call returns immediately when the tone is generated. The new one will not return
until the tone output is complete regardless of its duration.
- The Data Segment display now scrolls 8 rows (half a table) rather than 16 when the
arrow buttons are clicked. This makes it easier to view a sequence of related cells that
happen to cross a table boundary. Note you can hold down either button for rapid scrolling.
The combo box with various data address boundaries also works better now.
- Bug Fix: Two corrections to the Keyboard and Display Simulator Tool. Transmitter Ready bit was
not being reset based on instruction count
when running in the kernel text segment, and the Status register's Exception Level bit was not
tested before enabling the interrupt service routine (could lead to looping if interrupts occur
w/i the interrupt service routine). Thanks to Michael Clancy and Carl Hauser for bringing these
to my attention and suggesting solutions.
- Bug Fix: Stack segment byte addresses not on word boundaries were not being processed
correctly. This applies to little-endian byte order (big-endian is not enabled or tested in MARS).
Thanks to Saul Spatz for recognizing the problem and providing a patch.
- Minor Bug Fixes include: Correcting a fault leading to failure when launching MARS in command
mode, clarifying assembler error message for too-few or too-many operands error, and correcting the
description of lhu and lbu instructions from "unaligned" to "unsigned".
What's New in MARS Version 3.5
3.5 was released on 24 July 2008. Major enhancements and bug fixes include:
ones: .half 1 :
8 # Store the value 1 in 8 consecutive halfwords
- A new Tool, the Keyboard and Display MMIO Simulator, that supports
polled and interrupt-driven input and output operations through
Memory-Mapped I/O (MMIO) memory. The MIPS program writes to memory locations
which serve as registers for simulated devices. Supports keyboard input and
a simulated character-oriented display. Click the tool's Help button for
- A new Tool, the Instruction Counter, contributed by MARS user Felipe
Lessa. It will count the number of MIPS instructions executed along with
percentages for R-format, I-format, and J-format instructions. Thanks,
- Program arguments can now be provided to the MIPS program at runtime,
through either an IDE setting or command mode. See the command mode "pa"
option for more details on command mode operation. The argument count (argc)
is placed in $a0 and the address of an array of null-terminated strings
containing the arguments (argv) is placed in $a1. They are also available on
the runtime stack ($sp).
- Two related changes permit MARS to assemble source code produced by
certain compilers such as gcc. One change is to issue warnings rather than
errors for unrecognized directives. MARS implements a limited number of
directives. Ignore these warnings at your risk, but the assembly can
continue. The second change is to allow statement labels to contain, and
specifically begin with, '$'.
- In command mode, final register values are displayed by giving the
register name as an option. Register names begin with '$', which is
intercepted by certain OS command shells. The convention for escaping it is
not uniform across shells. We have enhanced the options so now you can give
the register name without the '$'. For instance, you can use t0 instead of
$t0 as the option. You cannot refer to registers by number in this manner,
since an integer option is interpreted by the command parser as an
instruction execution limit. Thanks to Lucien Chaubert for reporting this
- Minor enhancements: The command mode dump feature has been extended to
permit memory address ranges as well as segment names. If you enter a new
file extension into the Open dialog, the extension will remain available
throughout the interactive session. The data segment value repetition
operator ':' now works for all numeric directives (.word, .half, .byte,
.float, .double). This allows you to initialize multiple consecutive memory
locations to the same value. For example:
- Major change: Hexadecimal constants containing
less than 8 digits will be interpreted as though the leading digits are 0's.
For instance, 0xFFFF will be interpreted as 0x0000FFFF, not 0xFFFFFFFF as
before. This was causing problems with immediate operands in the range 32768
through 65535, which were misinterpreted by the logical operations as signed
32 bit values rather than unsigned 16 bit values. Signed and unsigned 16 bit
values are now distinguished by the tokenizer based on the prototype symbols
-100 for signed and 100 for unsigned (mainly logical operations). Many
thanks to Eric Shade of Missouri State University and Greg Gibeling of UC
Berkeley for their extended efforts in helping me address this situation.
- Minor Bug Fixes: round.w.s and round.w.d have been
modified to correctly perform IEEE rounding by default. Thanks to Eric Shade
for pointing this out. Syscall 12 (read character) has been changed to leave
the character in $v0 rather then $a0. The original was based on a misprint
in Appendix A of Computer Organization and
would not execute from the executable Mars.jar file if it was stored in a
directory path those directory names contain any non-ASCII characters. This
has been corrected. Thanks to Felipe Lessa for pointing this out and
offering a solution. MARS will now correctly detect the EOF condition when
reading from a file using syscall 14. Thanks to David Reimann for bringing
this to our attention.
What's New in MARS Version 3.4.1
Mars 3.4.1 was released on 23 January 2008. It is a bug fix release to address two bugs.
- One bug shows up in pseudo-instructions in which the expansion includes branch instructions. The fixed branch
offsets were no longer correct due to changes in the calculation of branch offsets in Release 3.4.
At the same time, we addressed the issue of expanding such pseudo-instructions when
delayed branching is enabled. Such expansions will now include a nop instruction following the
- We also addressed an off-by-one error that occurred in generating the lui instruction in the
expansion of conditional branch pseudo-instructions whose second operand is a 32 bit immediate.
- The expansions for a number of pseudo-instructions were modified to eliminate internal branches.
These and other expansions were also optimized for sign-extended loading of 16-bit immediate operands
by replacing the lui/ori or lui/sra sequence with addi. Pseudo-instructions affected by one
or both of these modifications include: abs, bleu, bgtu, beq, bne, seq, sge, sgeu, sle, sleu, sne,
li, sub and subi. These modifications were suggested by Eric Shade of Missouri State University.
What's New in MARS Version 3.4
- A new syscall (32) to support pauses of specified length in milliseconds (sleep) during simulated execution.
- Five new syscalls (40-44) to support the use of pseudo-random number generators. An unlimited number of these generators are available,
each identified by an integer value, and for each you have the ability to: set the seed value, generate a 32 bit integer value from the Java
int range, generate a 32 bit integer value between 0 (inclusive) and a specified upper bound (exclusive), generate a 32-bit float value between 0 (inclusive) and 1 (exclusive),
and generate a 64-bit double value between 0 (inclusive) and 1 (exclusive). All are based on the java.util.Random class.
- Ten new syscalls (50-59) to support message dialog windows and data input dialog windows. The latter are distinguished from
the standard data input syscalls in that a prompting message is specified as a syscall argument and displayed in the input dialog.
All are based on the javax.swing.JOptionPane class.
- The capability to dump .text or .data memory contents to file in various formats. The dump can be performed
before or after program execution from either the IDE (File menu and toolbar) or from command mode. It can also be performed
during an execution pause from the IDE. Look for the "Dump Memory" menu item in the File menu, or the "dump" option in command
mode. A .text dump will include only locations containing an instruction. A .data dump will include a multiple
of 4KB "pages" starting at the segment base address and ending with the last 4KB "page" to be referenced by the
program. Current dump formats include pure binary (java.io.PrintStream.write() method), hexadecimal text with one word (32 bits)
per line, and binary text with one word per line. An interface, abstract class, and format loader have been developed to facilitate
development and deployment of additional dump formats. This capability was prototyped by Greg Gibeling of UC Berkeley.
- Changed the calculation of branch offsets when Delayed Branching setting is disabled.
Branch instruction target addresses are represented by
the relative number of words to branch. With Release 3.4, this value reflects delayed branching,
regardless of whether the Delayed Branching setting is enabled or not.
The generated binary code for branches will now match that of examples in the Computer Organization
and Design textbook. This is a change from the past, and was made after extensive discussions
with several MARS adopters. Previously, the branch offset was 1 lower if the Delayed Branching setting
was enabled -- the instruction label: beq $0,$0,label would generate 0x1000FFFF if
Delayed Branching was enabled and 0x10000000 if it was disabled. Now it will generate 0x1000FFFF in
either case. The simulator will always branch to the correct location; MARS does not allow assembly under one
setting and simulation under the other.
- Bug fix: The mars.jar executable JAR file can now be run from a different working directory. Fix was
suggested by Zachary Kurmas of Grand Valley State University.
- Bug fix: The problem of MARS hanging while assembling a pseudo-instruction with a label operand that
contains the substring "lab", has been fixed.
- Bug fix: No Swing-related code will be executed when MARS is run in command mode. This fixes a problem that
occured when MARS was run on a "headless" system (no monitor). Swing is the Java library to support
programming Graphical User Interfaces. Fix was provided by Greg Gibeling of UC Berkeley.
- The '\0' character is now recognized when it appears in string literals.
What's New in MARS Version 3.3
- Support for MIPS delayed branching. All MIPS
computers implement this but it can be confusing for
programmers, so it is disabled by default. Under
delayed branching, the next instruction after a
branch or jump instruction will always be
executed, even if the branch or jump is taken! Many
programmers and assemblers deal with this by
inserting a do-nothing "nop" instruction after every
branch or jump. The MARS assembler does not
insert a "nop". Certain pseudo-instructions expand
to a sequence that includes a branch; such
instructions will not work correctly under delayed
branching. Delayed branching is available in command
mode with the "db" option.
- A new tool of interest mainly to instructors.
The Screen Magnifier tool, when selected from the
Tools menu, can be used to produce an enlarged
static image of the pixels that lie beneath it. The
image can be annotated by dragging the mouse over it
to produce a scribble line. It enlarges up to 4
times original size.
- You now have the ability to set and modify the
text editor font family, style and size. Select
"Editor..." from the Settings menu to get the
dialog. Click the Apply button to see the new
settings while the dialog is still open. Font
settings are retained from one session to the next.
The font family list begins with 6 fonts commonly
used across platforms (selected from lists found at
followed by a complete list. Two of the six are
monospaced fonts, two are proportional serif, and
two are proportional sans serif.
- The Labels window on the Execute pane, which
displays symbol table information, has been
enhanced. When you click on a label name or its
address, the contents of that address are centered
and highlighted in the Text Segment window or Data
Segment window as appropriate. This makes it easier
to set breakpoints based on text labels, or to find
the value stored at a label's address.
- If you re-order the columns in the Text Segment
window by dragging a column header, the new ordering
will be remembered and applied from that time
forward, even from one MARS session to the next. The
Text Segment window is where source code, basic
code, binary code, code addresses, and breakpoints
- If a MIPS program terminates by "running off the
bottom" of the program, MARS terminates, as before,
without an exception, but now will display a more
descriptive termination message in the Messages
window. Previously, the termination message was the
same as that generated after executing an Exit
- A new system call (syscall) to obtain the system
time is now available. It is service 30 and is not
available in SPIM. Its value is obtained from the
java.util.Date.getTime() method. See the
Syscall tab in MIPS help for further information.
- A new system call (syscall) to produce simulated
MIDI sound through your sound card is now available.
It is service 31 and is not available in SPIM. Its
implementation is based on the javax.sound.midi
package. It has been tested only under Windows. See
the Syscall tab in MIPS help for further
What's New in MARS Version 3.0
In summary, a lot! Version 3.0 fixes one bug from Version 2.2 (February 2006) and adds a number of instructions and
basic instructions were incorrectly coded as R-format
(register) rather than I-format (immediate) instructions. This is now corrected.
Additional MIPS Instructions
Over 40 new basic instructions were added to the MIPS-32 instruction set that
MARS now assembles and simulates. The total is now 141 basic instructions.
It now supports nearly all instructions from Patterson and Hennessy's Computer
Organization and Design textbook. Exceptions are the trap and trap-related
instructions, and branch instructions that assume delayed branching ("likely").
A large number of pseudo-instructions were also added. All the pseudo-instructions
from Appendix A of Patterson and Hennessy's text are now recognized and expanded.
A few others were added for convenience (ADDI with 32 bit constant)
or fun (SUBI).
Most of the pseudo-instruction additions, however, implement alternative
memory addressing modes for the various load and store instructions. Native
MIPS load and store instructions support only one addressing mode: base addressing
of the form 100($1), where 100 is a 16 bit constant
and $1 is a register whose
contents are added to the constant to form the effective address.
MARS now recognizes and expands the following addressing modes for all load
and store operations:
|($1)||register contents plus 0 offset|
|100000||32 bit constant|
|100000($1)||register contents plus 32 bit offset|
|label+100000||labeled address plus 32 bit offset|
|label($1)||register contents plus 32 bit labeled address|
|label+100000($1)||register contents plus sum of 32 bit constant and labeled address|
A comment concerning 32 bit constants. A pseudo-instruction may expand differently
depending on the value of the constant. If it cannot be contained in 16 bits then
its high order 16 bits are loaded into the $at register (LUI) prior to processing.
We have decided to consistently determine the 16 bit "boundary" based on signed
values: -32768 to 32767. Other simulators may interpret the values differently
(e.g. unsigned) depending on the context in which they are used.
New IDE features
- Ability to step "backward" through simulated MIPS program execution, undoing
the results one execution step at a time. Its toolbar icon is a left-pointing
arrow with a "1", to bookend the step icon's right-pointing arrow with "1".
It will undo as many as the most recent 1000 execution steps. Since each
backstep requires a click or keystroke, this should be plenty for debugging
purposes. It is also available at the time of normal or abnormal program
termination. One limit: this feature will only undo writes to memory, registers
or floating point condition flags. SYSCALL operations to external resources
(I/O console, files) are not undone by this feature.
- The Help feature has been expanded and refined somewhat. The MIPS tab now
contains four tabs of its own: a list of basic instructions with descriptions, a list of pseudo
instructions and instruction formats with descriptions, a list of assembler directives, and
documentation for all available SYSCALL functions and their usage. And just
for fun, I've added a tab containing Walter Chang's lyrics to "The MIPS
Instruction Set" that can be sung to a Gilbert and Sullivan tune.
- In the Text Segment display, the source and corresponding basic statements
are now displayed in adjacent columns rather than being concatenated in the
same column. Both are still highlighted when doing a stepped or timed run.
- A Settings menu has been added, to control several true/false options.
The current options 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.
- 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.
- A menu item "Clear all breakpoints" has been added to the Run menu.
It is enabled whenever one or more execution breakpoints have been set. Much more
convenient than having to clear them individually. They can be cleared before,
during, or after execution. Note that all breakpoints are
automatically cleared each time a file is assembled.
- New toolbar and menu item icons.
New Command Line features
A new command switch, "np
", specifies that a MIPS program is not permitted to use
pseudo instructions and/or formats.