Ruby/Simics QuickStart for ECE/CS 757
-------------------------------------
By Jayaram Bobba, Feb 2008.
Edited by Polina Dudnik, Feb 2010.

Setting up Simics and Ruby packages
-----------------------------------
NOTE: You will need at least 512 MB of disk space to install, compile and simulate
with Ruby/Simics

- Login to clover-02.cs.wisc.edu using your CS department login

- Extract gems-release2.1.tar.gz to any location in your CS account's home directory
  
  cp gems-release2.1.tar.gz <installation-directory>
  cd <installation-directory>
  tar zxvf gems-release2.1.tar.gz
  cd gems-2.1

- Extract simics-2.2.19-amd64-linux.tar.gz to $GEMS (assuming the environment variable
  GEMS is set to <installation-directory>/gems-2.1 )
 
  tar zxvf simics-2.2.19-amd64-linux.tar.gz 
  ln -s $GEMS/simics-2.0.25 $GEMS/simics

You should see the following three directories among the directories in $GEMS  
  
  ruby/       : Ruby memory system simulator
  protocols/  : Cache Coherence protocols 
  simics/     : Simics full system simulator

- Configure simics

  cd simics
  cd amd64-linux
  ../configure CC=/s/gcc-3.4.1/bin/gcc  

- Create ruby module directory and appropriate symlinks

  cd $GEMS/simics/src/extensions/
  mkdir ruby
  cd ruby
  ln -s ../../../../ruby/module/ruby.c
  ln -s ../../../../ruby/interfaces/mf_api.h
  ln -s ../../../../ruby/module/Makefile
  ln -s ../../../../ruby/module/commands.py
  ln -s ../../../../ruby/simics/commands.h

- Edit $GEMS/simics/config/modules.list-local, and add this line

  ruby | API_2.0 | v9

- Make sure libraries are up to date

  cp /usr/lib/libstdc++.so.5 $GEMS/simics/amd64-linux/sys/lib
  cp /lib/libgcc_s.so.1 $GEMS/simics/amd64-linux/sys/lib/

- Set the following environment variables (also add them to your ~/.cshrc.local file
  for future simulations)

  setenv SIMICS_EXTRA_LIB ./modules
  setenv VTECH_LICENSE_FILE /p/multifacet/projects/simics/licenses/license.dat
  source ~/.cshrc.local

- Extract checkpoints to $GEMS/simics/

  tar zxvf checkpoints.tar.gz
  
  
Compiling Ruby   
--------------
The Simics package comes with pre-compiled binaries. So you only need to compile
Ruby.
  
  cd ruby
  make clean
  make -j 4 PROTOCOL=MESI_CMP_filter_directory DESTINATION=MESI_CMP_filter_directory

This will compile a Ruby module with the 'MESI_CMP_filter_directory' protocol. This 
module can be used to simulate a single CMP chip with private L1 caches and a shared 
L2 cache. The compilation process may take a while. At the end, you should see a new
directory: $GEMS/simics/home/MESI_CMP_filter_directory.
You are now ready to start simulating with Simics/Ruby !!!

Simulating with Simics
----------------------
- Start Simics
  
  cd $GEMS/simics/home/MESI_CMP_filter_directory
  ./simics -stall

- Load multi-processor checkpoint. A couple of multiprocessor checkpoints with a pre-
  installed and booted OS (Solaris) are present in the Simics package. Pick one of the
  checkpoints and load it into the simulator. For example, to load a 16 processor 
  checkpoint

  simics> add-directory /p/multifacet/projects/images/checkpoints-sarek/
  simics> add-directory /p/multifacet/projects/images3/ 
  simics> read-configuration ../../checkpoints/silver-16p.check
  
You should now see a yellow console on your monitor. This is the display console of the 
simulated machine

- Start simulation

  simics> c

The 16 processor 'silver' machine is now being simulated by Simics. Go to the yellow console and
issue your favourite shell commands.

- To stop simulation, Control-c

Simulating with Ruby
--------------------
- Disable cache simulation within Simics. These commands also instruct Simics to deliver
  all instruction fetches to Ruby.

  simics> instruction-fetch-mode instruction-fetch-trace
  simics> istc-disable
  simics> dstc-disable
  simics> cpu-switch-time 1

- Load Ruby

  simics> load-module ruby
  
- Configure Ruby

  simics> ruby0.setparam g_PROCS_PER_CHIP 16
  simics> ruby0.setparam_str REMOVE_SINGLE_CYCLE_DCACHE_FAST_PATH true
  simics> ruby0.setparam_str g_NETWORK_TOPOLOGY PT_TO_PT
  simics> ruby0.setparam NUMBER_OF_VIRTUAL_NETWORKS 5
      
Other ruby configuration parameters can be set dynamically at this point, if necessary.

- Initialize Ruby

  simics> ruby0.init
  
- Start Simulation

  simics> c        

The 'silver' machine is now being simulated by Simics in conjunction with the detailed
memory models in Ruby. Again go to the yellow console and issue your favourite shell 
commands. Notice the extreme slowdown in simulated machine's responsiveness. It is not 
uncommon to see simulation slowdowns in excess of 10000x. An action that could take around
1 sec on a normal machine could take greater than 10000 seconds on the simulated machine !!!
This is an important limitation of full-system multiprocessor simulations. 

- Print Results. First, interrupt simulation by pressing Control-c
  
  simics> ruby0.dump-stats simulation.stats

This will print the statistics of simulation in the file 'simulation.stats'

- Quit simulation and take a break...

  simics> q