Getting Started

MARSS is designed to be easy to setup and run full-system simulations. This guide will help to get started with MARSS.

System Requirements

MARSS requires a Linux platform with the following minimum requirements:

• x86_64 CPU cores with a minimum 2GHz clock and 2GB RAM (4GB RAM is preferred)
• C/C++ compiler, gcc or icc
• SCons compilation tool minimum version 1.2 - SCons website
• SDL Development Libraries (required for QEMU)

Download MARSS Source Code

Please visit our Download page to get the latest source code for MARSS. It is preferable that you check out the latest code from the git repository as it contains latest bug fixes and enhancements.

You can also download the disk images from the Disk Images page and use them for simulations.

Compiling MARSS

Setup SCons

To compile the MARSS we use SCons compilation tool, version 1.2 or later versions. If you do not have SCons installed in your system, you can easily install it using standard software installation tools such as apt-get or yum.

If you don't have privileges to install scons in your system you can still set it up by following the directions given here . You can download the latest scons tarball and install it to your $HOME using following command:

 $ python setup.py install --prefix=$HOME

Compile MARSS

Once you have setup the SCons, compiling MARSS is simple. Go to the directory where you have the source code of MARSS (we will refer this directory as $MARSS now on), and issue the following commands:

 $ cd $MARSS
 $ scons -Q

SCons script files are designed to configure the QEMU for the MARSS and compile all source code in one command. The configuration will give errors if it can not find the required libraries installed on your system.

By default, MARSS is compiled without any debugging support functions such as asserts, logable(), etc.. To compile MARSS with debugging support, use the following command:

 $ scons -Q debug=1

or this command to provide even more debugging information:

 $ scons -Q debug=2

Note: To improve the compilation time, by default the SConstruct script finds the number of CPUs available in system and runs the compilation scripts with an optimized number of threads (which is roughly around NUM_CPUS+1). To override this, you can specify the maximum number of threads used from the command line as follows:

 $ scons -Q -j[NUM_THREADS]

By default it will compile the MARSS for single simulated core. To simulate more than one core, for SMP or CMP configuration, add an option 'c=NUM_CORES' to compilation as shown below:

 $ scons -Q c=8

Above command will compile the MARSS to simulate 8 cores. The reason for setting the number of simulated cores at compile time is because there are many places where the source code needs hard-coded value of the number of cores.

Clean Binaries

To clean up the compiled binaries, use the following command:

 $ scons -Q -c

Running MARSS

NOTE : In latest version we have changed 'simulate' command to 'simconfig'

After the successful compilation of MARSS, use following commands to run MARSS:

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

You can use all of the regular QEMU commands. Once the VM is booted you can start the benchmark application in the VM console. To start the simulation, switch to QEMU's monitor console using 'Ctrl-Alt-2' key and issue following commands in that console:

 (qemu) simulate -run -stopinsns 100m -stats [stats-filename]
 (qemu) simconfig -run -stopinsns 100m -stats [stats-filename] -machine MACHINE_NAME

NOTE: -machine option is required for version 0.2 or higher

After you issue the command above, MARSS will switch from QEMU's emulation mode to the MARRSS simulation mode. To switch back to the VM window, press 'Ctrl-Alt-1'. To list all the simulation options , issue the 'simulate' command without any options to list all of the available options on 'stdout':

 (qemu) simulate
 (qemu) simconfig

You can also specify the simulation configuration parameters using a config file. You can write a simple text file with all configuration parameters as shown below. You can also add comments to config file by adding '#' at start of line. (Note: # in middle of line is not considered as comment)

 # Sample Marss simconfig file
 -machine private_L2
 
 # Logging options
 -logfile test.log
 -loglevel 4
 # Start logging after 10million cycles
 -startlog 10m
 
 # Stats file
 -stats test.stats

Specify this configuration file at the command line when you start QEMU shown as below:

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

For full debugging and logging support in the simulation mode, make sure that you have compiled MARSS with debug=1 option.

To run MARSS under gdb, you can start the QEMU in gdb.

 $ gdb qemu/qemu-system-x86_64

QEMU uses user-level signals to generate interrupts to the VM, you can disable the signal handling within gdb using following command:

 (gdb) handle SIGUSR1 SIGUSR2 noprint nostop

Run Multicore Configuration

To run MARSS with a multiple core configuration, do the following:

• Recompile the MARSS with 'c=NUM_CORES' command-line option
• Run with your default command line parameters

Simulation Results/Statistics

MARSS uses new stats collection framework that stores the stats in YAML format. MARSS provides a utility script 'mstats.py' in 'util/' folder to easily extract selected stats. Visit Statistics Collection To find more information about stats collection and mstats utility.

Running Simulation With Checkpoints

MARSS supports checkpoints to start/stop the simulation at pre-determined locations within the VM or within the benchmark. MARSS uses QCOW2 disk image feature of Snapshots to supports checkpoints. You can learn more about checkpoints, how to create them and run your simulation from checkpoints from here.