MARSS-x86 : Micro-Architecture & System Simulator for x86
=========================================================

Copyright 2010 Avadh Patel (apatel @ cs.binghamton.edu)

Marss-x86 is a simulation tool for x86-64 based Computing Systems.  It is based
on two independent open-source projects QEMU (http://www.qemu.org/) and
PTLsim (http://www.ptlsim.org/).  Marss-x86 is developed at Computer
Architecture Group of SUNY Binghamton by Avadh Patel and other group Members.

You can find out more details about Marss go to (http://www.marss86.org/). 


System Requirements
-------------------
To compile Marss on your system, you will need following:
* 2.5GHz CPU with minimum 2GB RAM (4GB Preferred)
* Standard C++ compiler, like g++ or icc
* SCons tool for compiling Marss (Minimum version 1.2.0)
* SDL Development Libraries (Required for QEMU)


Compiling
---------
Before attempting to build MARSS, you must fetch the qemu submodule. After
cloning the MARSS repository, give the following commands in the top-level
directory:

    $ git submodule init
    $ git submodule update

From time to time, you may find that you need to pull in bugfixes or new
features from MARSS's qemu team. To do so, give the following command in the
top-level directory at any time:

    $ git submodule update

On to building! If you don't have SCons installed, install it using your
standard application installation program like apt-get or yum.

Once you have SCons install go to Marss directory and give following command:

    $ scons -Q 

Default compile disables debugging and logging functionalities, to compile with
logging functions enable give following command:

    $ scons -Q debug=1

Default compile process compile simulator for single-core configuration.  To
compile Marss for Multi-Core SMP configuration give following command:

    $ scons -Q c=[num_cores]

To clean your compilation:

    $ scons -Q -c

Running
-------
After successfull compilation, to run Marss you have to be in the root of Marss
source directory.  Then give the following command:

    $ qemu/qemu-system-x86_64 -m [memory_size] [path-to-qemu-disk-image]

You can use all the regular QEMU command here, like start VM window in VNC give
'vnc :10' etc.  Once the system is booted, you can switch to Monitor mode using
'Ctrl-Alt-2' key and give following command to switch to simulation mode:

    (qemu) simconfig -run -stopinsns 100m -stats [stats-file-name]

You can also save simulation configuration parameters into a config file and
pass that as argument when you start qemu with '-simconfig' option.

    $ qemu/qemu-system-x86_64 -m [memory_size] [path-to-qemu-disk-image] -simconfig [simulator-config-file]

To get the list of available simulation options give following command:

    (qemu) simconfig

It will print all the simulation options on STDOUT.


For more information on using and modifying Marss please visit our website :
    http://www.marss86.org/

Happy Hacking.