Ruby Tutorial for ECE/CS 757
----------------------------
By Min Xu, March 2002.

Note: This file is also available in your "ruby" directory after
installation.

What's Ruby
-----------
Ruby is the memory system timing simulator that could be used with Simics.
At this point you should have already done the Simics tutorial. If not, do
it now.

Ruby is developed as a research tool and it has not been polished for
public release. So the system has almost no documentation other than the code
itself. Please read the C++ source code if you later on decided to hack
it for your course project.

In the ruby directory of your installation, two cache coherence protocol
are provided:

  MOSI_bcast_2level                  : snooping protocol with 2 level cache
  MOSI_directory_opt_blocking_2level : directory protocol with 2 level cache

Each directory contains both the source code ( in C++) and the HTML
document about each protocol.

Compile Ruby
------------

*** THIS SECTION IS NOT NECESSARY WITH THE LATEST PACKAGE ***

  cd ruby
  make clean
  make -j 4 module PROTOCOL=MOSI_bcast_opt DESTINATION=MOSI_bcast_opt
  make -j 4 module PROTOCOL=MOSI_directory_opt_blocking_2level DESTINATION=MOSI_directory_opt_blocking_2level

Depends on how fast your machine is, building process may take a while and
a new directory will be create in simics/home/ directory. Note that,
building ruby will consume about 30 MB disk quota. If the building process
failed, check your quota limit first.

Simulate with Ruby
------------------
To simulate the protocol you are interested, e.g. MOSI_bcast_2level:

  cd simics/home/MOSI_bcast_2level
  ./simics

At Simics command line:

  simics> read-conf ../../checkpoints/golden-2p.check 
  simics> load-module ruby

If Simics complains "module not found", it is most likely that some
symbols can not resolved during dynamic link time, use this command
to check:

  simics> list-failed-modules -v ruby

In multiprocessor simulation, due to workload nondeterminism, simulate the
program for only once is often not accurate. To reduce the impact from
nondeterminism, Ruby uses randomization. Hence, for each simulation you
should set the ruby random seed by:

  simics> ruby0.setparam g_RANDOM_SEED <number>

where <number> is an integer.

We now need to initialize ruby:

  simics> ruby0.init

After done this, you can start your simulation by:

  simics> c

If your workload has been properly instrumented, the simulation should
automatically stop after "n" transactions have been completed.

Then you can dump the simulation results by:

  simics> ruby0.dump-stats <filename>

Customize Ruby
--------------
Now you must be wondering "where do I specify the simulation parameters?"

Ruby currently only support changing system parameters at compilation
time. To do that, open ruby/config/RubyConfig.h with an editor. At the
bottom of the file, in section:

//*********************************************
// CACHE & MEMORY PARAMETERS
//*********************************************

You will find the definition of the memory system parameters. To customize
them, simply change them and rebuild ruby.