Simulating with Ruby/Simics for ECE/CS 757
-------------------------------------
By Jayaram Bobba, Feb 2008.

This tutorial assumes that you have installed and tested Simics/Ruby.

Setting up the Workload
-----------------------
This tutorial will walk you through the steps involved for simulating a workload
using a simple pthreads example.

Extract eg_pthread.tar.gz to $GEMS/microbenchmarks/multiprocessor

  cd $GEMS/microbenchmarks/multiprocessor
  tar zxvf eg_pthread.tar.gz 

The file ruby_magic.h contains macros for interactions between the workload and
the simulator. A "RUBY_MAGIC_CALL" is a special NOP assembly instruction that 
causes the simulator to receive a callback when executed. 
  
  SIMICS_BREAK_EXECUTION tells the simulator to halt execution
  BEGIN_WORKLOAD_TRANSACTION tells the simulator that the workload has started
  executing a new unit of work
  END_WORKLOAD_TRANSACTION tells the simulator that the workload has completed 
  executing a unit of work 

The program eg_pthread.c spans a certain number of threads. Each thread increments 
a global counter for a fixed number of times. Each increment of this counter is
treated as a unit of work. Our goal is simulate the parallel phase of this 
workload.

Since simulation with Ruby is extremely slow, we start off simulation with 
stand-alone Simics. Once the initialization and thread creation phases are done, 
the program informs Simics to halt execution with "SIMICS_BREAK_EXECUTION". This 
also transfers control back to the simulator. We could then load ruby and simulate
the parallel phase with a the detailed memory model. Once the parallel phase of 
execution is completed, the program once again uses "SIMICS_BREAK_EXECUTION" to 
inform the simulator.

Compiling the Workload
----------------------
Since simulation is slow, you will compile the workload natively on a solaris/sparc
machine (chianti.cs.wisc.edu) instead of the 'silver' checkpoints that are SPARC 
machines with OpenSolaris booted on top of them.

- Copy the eg_pthread directory to your account on chianti.cs.wisc.edu using scp.
- Compile using the given Makefile
- Copy the executable eg_pthread back to the original location at 
  $GEMS/microbenchmarks/multiprocessor/eg_pthread/

Running the Simulation
----------------------
You need to do the following to simulate the workload using Ruby/Simics
1) Start Simics
2) Load a multiprocessor checkpoint
3) Copy the workload to the simulated machine
4) Run the workload on the simulated machine
5) Configure and start ruby when workload reaches its parallel phase  
6) Print simulation stats once the parallel phase is complete

A set of scripts have been provided to automate the above steps.
eg_pthread.sh starts Simics and executes a simics script (eg_pthread.simics)
that automates the rest of the steps

  ./eg_pthread.sh

Simulation Stats
----------------      
The Ruby_cycles metric in the ruby stats file gives the runtime of the simulation.
Search for "Ruby_cycles" in the stats file.

The obligatory note about more information:
For more information,
- see the GEMS documentation at http://www.cs.wisc.edu/gems/doc/wiki/moin.cgi
- Bug your TA