GCSpy interface for Jikes RVM  2.3.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Notes. 

In order to run GCSpy, your RVM must interact properly with pthreads. See the
JikesRVM mailing lists for a discussion of this. Out of the box, Red Hat 7.3
and upwards seems to work fine, but Debian did not (last time I looked).

I have not tried with other architectures.

We have assumed that you will place all the GCSpy code and required libraries
in $RVM_ROOT. If you wish to change this, you'll need to modify these 
instructions and the $RVM_ROOT/rvm/config/build/gcspy/GCSpy config file
appropriately.

1. Download
-----------
Download the GCSpy files from 
   http://www.experimentalstuff.com/Technologies/GCspy/.

You want the C infrastructure (not the C++ one) and the Java visualiser. 
The C infrastructure provides a GCSpy server to the JikesRVM.

Note that you will also need the Java Advanced Imaging (JAI) API which you can
get from http://java.sun.com/products/java-media/jai/.

Unpack the GCSpy and JAI sources into $RVM_ROOT. You should then have 
directories:
     $RVM_ROOT/gcspy0.9
 and $RVM_ROOT/jai-1_1_2.

2. Installation
---------------

2.1 First, you must apply a patch to the GCSpy sources:
    % cd $RVM_ROOT
    % patch -p0 < $RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/gcspy.patch

2.2 Make the GCSpy visualiser and server.
    % cd $RVM_ROOT/gcspy0.9/src/
    % make install c java

3. Running
---------
Set up your environment appropriately. We assume
    % export GCSPY_ROOT=$RVM_ROOT/gcspy0.9
    % export GCSPY_CLASSES=$GCSPY_ROOT/src/java/classes

Here's a typical example (probably better executed from 2 windows).

First, build an image:
    [set appropriate Jikes RVM environment variables]
    % export RVM_BUILD=<name of your build>
    % jconfigure BaseBaseSemiSpaceGCSpy
    % cd $RVM_BUILD
    % ./jbuild

Next, start rvm, first adding the GCSpy server library to your
LD_LIBRARY_PATH:
    % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GCSPY_ROOT/src/c/lib
    % rvm -Xms20m -X:gc:gcspyPort=3000 -X:gc:gcspyWait=true SpecApplication _202_jess &

Then, start the GCSpy visualiser:
    % cd $GCSPY_CLASSES
    % java gcspy.Main -server localhost 3000

and click the "Connect" button in thebottom right-hand corner of the visualiser
(alternatively, you can give the server and port arguments in the Connect
dialogue box).

Additional arguments to rvm:

-X:gc:gcspyPort=port
	The number of the port on which to connect to the visualiser
	[default = 0, which means don't connect].
-X:gc:gcspyWait=[true|false]
	Whether RVM should wait for a visualiser to connect.
-X:gc:gcspyTilesize=size
	How many KB are represented by 1 tile [default: 128K]

4. Testing
----------
The easiest way to test is to connect the rvm to the GCSpy trace writing tool.
For example, to test with rvm and the trace tool running on the same server, 
communicating on port 3000:

  % rvm -Xms80M -X:gc:gcspyPort=3000 -X:gc:gcspyWait=true SpecApplication _202_jess >application.out 2>&1 &
  % cd $GCSPY_CLASSES
  % java gcspy.tools.TerminalStoreTrace -server localhost 3000 -overwrite -output gcspy.trace >test.out

In case of a GCSpy failure (e.g. something wrong with the protocol),
. rvm will die with a non-zero exit status and (possibly) a clearly marked
  GCSpy error;
. the trace tool will die with a non-zero exit status and the usual Java
  exception message and stack dump.

5. The GCSpy interface
----------------------
The following files comprise the GCSpy interface:

$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/AbstractTile.java
	Abstract notion of a tile.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/GCSpy.java
	Collector-independent GCSpy functionality to start the GCSpy server.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/README.html
	This file.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/ServerInterpreter.java
	The GCSpy server.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/ServerSpace.java
	The GCspy Space abstraction.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/StreamConstants.java
	Constants used by the GCspy framework.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/Stream.java
	A GCSpy stream.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/Subspace.java
	A convenient abstraction of a sub-Space.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/util/Color.java 
	A simple mechanism for specifying colours.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/util/Util.java
	Various generally useful methods.

and drivers

$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/drivers/AbstractDriver.java
	Parent class for all space drivers
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/drivers/ImmortalSpaceDriver.java
	A space driver for the immortal space.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/drivers/SemiSpaceDriver.java
	A space driver for the SemiSpace collector.
$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/drivers/TreadmillDriver.java
	A space driver for the Treadmill collector.


In addition, in order to be able to sweep through a semispace, gathering
data, we provide a mechanism for keeping track of objects allocated:

$RVM_ROOT/rvm/src/vm/memoryManagers/JMTk/gcspy/util/ObjectMap.java  
