SF.net SVN: jikesrvm:[15707] rvmroot/tags/3.1.0/userguide

Revision: 15707
          http://jikesrvm.svn.sourceforge.net/jikesrvm/?rev=15707&view=rev
Author:   dgrove-oss
Date:     2009-06-10 14:20:23 +0000 (Wed, 10 Jun 2009)

Log Message:
-----------
exported userguide

Added Paths:
-----------
    rvmroot/tags/3.1.0/userguide/html/
    rvmroot/tags/3.1.0/userguide/html/RVM/
    rvmroot/tags/3.1.0/userguide/html/RVM/AOS Controller.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Adaptive Optimization System.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Adding a New GC.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Architecture.html
    rvmroot/tags/3.1.0/userguide/html/RVM/BURS.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Baseline Compiler.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Bootstrap.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Building Patched Versions.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Building a Hybrid Collector.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Building a Mark-sweep Collector.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Building on Windows.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Building the RVM.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Care and Feeding.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Class and Code Management.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Coding Conventions.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Coding Style.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Compiler DNA.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Compiler Intrinsics.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Compiler Optimization Comparison Chart.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Compilers.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Configuring the RVM.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Core Runtime Services.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Cost Benefit Model.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Cross-Platform Building.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Debugging the RVM.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Editing JikesRVM in an IDE.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Exception Management.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Experimental Guidelines.html
    rvmroot/tags/3.1.0/userguide/html/RVM/External Test Resources.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Get The Source.html
    rvmroot/tags/3.1.0/userguide/html/RVM/IR.html
    rvmroot/tags/3.1.0/userguide/html/RVM/JNI Compiler.html
    rvmroot/tags/3.1.0/userguide/html/RVM/JNI.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Jikes RVM's compilers.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Life Cycle of a Compiled Method.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Logging and Debugging.html
    rvmroot/tags/3.1.0/userguide/html/RVM/MMTk Tutorial Mark-Sweep.html
    rvmroot/tags/3.1.0/userguide/html/RVM/MMTk Tutorial Preliminaries.html
    rvmroot/tags/3.1.0/userguide/html/RVM/MMTk Tutorial.html
    rvmroot/tags/3.1.0/userguide/html/RVM/MMTk.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Magic.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Method Compilation.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Modifying the RVM.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Object Model.html
    rvmroot/tags/3.1.0/userguide/html/RVM/OptTestHarness.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Optimizing Compiler.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Preliminaries.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Primordial Class List.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Profiling Applications with Jikes RVM.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Quick Start Guide.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Raw Memory Access.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Running the RVM.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Test Run Descriptions.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Testing the RVM.html
    rvmroot/tags/3.1.0/userguide/html/RVM/The MMTk Test Harness.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Thread Management.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Threading and Yieldpoints.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Unboxed Types.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Uninterruptible Code.html
    rvmroot/tags/3.1.0/userguide/html/RVM/User Guide.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Using Distributed And Local Version Control Tools.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Using GCSpy.html
    rvmroot/tags/3.1.0/userguide/html/RVM/Using buildit.html
    rvmroot/tags/3.1.0/userguide/html/RVM/VM Callbacks.html
    rvmroot/tags/3.1.0/userguide/html/RVM/VM Conventions.html
    rvmroot/tags/3.1.0/userguide/html/RVM/download/
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/74349/
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/74349/jtoc.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/76400/
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/76400/ImportWizard1.jpg
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/76400/ImportWizard2.jpg
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/93093975/
    rvmroot/tags/3.1.0/userguide/html/RVM/download/attachments/93093975/compiledMethod.eps
    rvmroot/tags/3.1.0/userguide/html/RVM/images/
    rvmroot/tags/3.1.0/userguide/html/RVM/images/border/
    rvmroot/tags/3.1.0/userguide/html/RVM/images/border/spacer.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/bullet_blue.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/check.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/error.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/forbidden.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/help_16.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/information.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/smile.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/star_red.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/images/icons/emoticons/warning.gif
    rvmroot/tags/3.1.0/userguide/html/RVM/index.html
    rvmroot/tags/3.1.0/userguide/html/RVM/styles/
    rvmroot/tags/3.1.0/userguide/html/RVM/styles/site.css
    rvmroot/tags/3.1.0/userguide/userguide.pdf

Added: rvmroot/tags/3.1.0/userguide/html/RVM/AOS Controller.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/AOS Controller.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/AOS Controller.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,43 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : AOS Controller</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : AOS Controller
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Jul 07, 2008 by <font color="#0050B2">dgrove</font>.
+    </div>
+
+    <p>A primary design goal for the adaptive optimization system is to enable research in online feedback-directed optimization. Therefore, we require the controller implementation to be flexible and extensible. As we gained experience with the system, the controller component went through several major redesigns to better support our goals.</p>
+
+<p>The controller is a single Java thread that runs an infinite event loop. After initializing AOS, the controller enters the event loop and attempts to dequeue an event. If no event is available, the dequeue operation blocks (suspending the controller thread) until an event is available. All controller events implement an interface with a single method: process. Thus, after successfully dequeuing an event the controller thread simply invokes its process method and then, the work for that event having been completed, returns to the top of the event loop and attempts to dequeue another event. This design makes it easy to add new kinds of events to the system (and thus, extend the controller's behavior), as all of the logic to process an event is defined by the event's process method, not in the code of the controller thread.</p>
+
+<p>A further level of abstraction is accomplished by representing the recompilation strategy as an abstract class with several subclasses. The process method of a hot method event invokes methods of the recompilation strategy to determine whether or not a method should be recompiled, and if so at what optimization level. The cost-benefit model itself is also reified in a class hierarchy of models to enable extension and variation. This set of abstractions enable a single controller implementation to execute a variety of strategies.</p>
+
+<p>Another useful mechanism for experimentation is the ability to easily change the input parameters to AOS that define the expected compilation rates and execution speed of compiled code for the various compilers. By varying these parameters, one can easily cause the default multi-level cost-benefit model to simulate a single-level model (by defining all but one optimization level to be unprofitable). One can also explore other aspects of the system, for example the sensitivity of the model to the accuracy of these parameters. We found this capability to be so useful that the system supports a command line argument (-X:aos:dna=<filename>) that causes it to optionally read these parameters from a file. </p>
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Adaptive Optimization System.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Adaptive Optimization System.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Adaptive Optimization System.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,72 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Adaptive Optimization System</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Adaptive Optimization System
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Jul 07, 2008 by <font color="#0050B2">dgrove</font>.
+    </div>
+
+    <p>A comprehensive discussion of the design and implementation of the original Jikes RVM adaptive optimization system is given in the<a href="http://docs.codehaus.org/display/RVM/Publications#Publications-aos">OOPSLA 2000 paper</a> by Arnold, Fink, Grove, Hind and Sweeney. A number of aspects of the system have been changed since 2000, so a better resource is a technical report <a href="http://domino.research.ibm.com/comm/research_people.nsf/pages/dgrove.RC23429.html">Nov. 2004 technical report</a> that describes the architecture and implementation in some detail. This section of the userguide is based on section 5 of the 2004 technical report.
+<br clear="all" /></p>
+
+<p>The implementation of the Jikes RVM adaptive optimization system uses a number of Java threads: several organizer threads in the runtime measurements component, the controller thread, and the compilation thread. The various threads are loosely coupled, communicating with each other through shared queues and/or the other in memory data structures. All queues in the system are blocking priority queues; if a consumer thread performs a dequeue operation when the queue is empty, it suspends until a producer thread performs an enqueue operation.</p>
+
+<p>The adaptive optimization system performs two primary tasks: selective optimization and profile-directed inlining.</p>
+
+
+<h3><a name="AdaptiveOptimizationSystem-SelectiveOptimization"></a>Selective Optimization</h3>
+
+<p>The goal of selective optimization is to identify regions of code in which the application spends significant execution time (often called ``hot spots''), determine if overall application performance is likely to be improved by further optimizing one or more hot spots, and if so to invoke the optimizing compiler and install the resulting optimized code in the virtual machine.</p>
+
+<p>In Jikes RVM, the unit of optimization is a method.  Thus, to perform selective optimization, first the runtime measurements component must identify candidate methods (``hot methods'') for the controller to consider. To this end, it installs a listener that periodically samples the currently executing method at every taken yieldpoint.  When it is time to take a sample, the listener inspects the thread's call stack and records a single compiled method id into a buffer. If the yieldpoint occurs in the prologue of a method, then the listener additionally records the compiled method id of the current activation's caller.  If the taken yieldpoint occurs on a loop backedge or method epilogue, then the listener records the compiled method id of the current method. </p>
+
+<p>When the buffer of samples is full, the sampling window ends. The listener then unregisters itself (stops taking samples) and wakes the sleeping Hot Method Organizer.  The Hot Method Organizer processes the buffer of compiled method ids by updating the Method Sample Data.  This data structure maintains, for every compiled method, the total number of times that it has been sampled. Careful design of this data structure (MethodCountData.java) was critical to achieving low profiling overhead. In addition to supporting lookups and updates by compiled method id, it must also efficiently enumerate all methods that have been sampled more times than a (varying) threshold value. After updating the Method Sample Data, the Hot Method Organizer creates an event for each method that has been sampled in this window and adds it to the controller's priority queue, using the sample value as its priority. The event contains the compiled method and the <em>total</em> number of times it has been sampled  since the beginning of execution.  After enqueuing the last event, the Hot Method Organizer re-registers the method listener and then sleeps until the next buffer of samples is ready to be processed.</p>
+
+<p>When the priority queue delivers an event to the controller, the controller dequeues the event and applies the model-driven recompilation policy to determine what action (if any) to take for the indicated method.  If the controller decides to recompile the method, it creates a recompilation event that describes the method to be compiled and the optimization plan to use and places it on the recompilation queue. The recompilation queue prioritizes events based on the cost-benefit computation.</p>
+
+<p>When an event is available on the recompilation queue, the recompilation thread removes it and performs the compilation activity specified by the event. It invokes the optimizing compiler at the specified optimization level and installs the resulting compiled method into the VM. </p>
+
+<p>Although the overall structure of selective optimization in Jikes RVM is similar to that originally described in Arnold et al's OOPSLA 2000 paper, we have made several changes and improvements based on further experience with the system. The most significant change is that in the previous system, the method sample organizer attempted to filter the set of methods it presented to the controller.  The organizer passed along to the controller only methods considered "hot".  The organizer deemed a method "hot'' if the percentage of samples attributed to the method exceeded a dynamically adjusted threshold value. Method samples were periodically decayed to give more weight to recent samples. The controller dynamically adjusted this threshold value and the size of the sampling window in an attempt to reduce the overhead of processing the samples.</p>
+
+<p>Later, significant algorithmic improvements in key data structures and additional performance tuning of the listeners, organizers, and<br/>
+controller reduced AOS overhead by two orders of magnitude.  These overhead reductions obviate the need to filter events passed<br/>
+to the controller.  This resulted in a more effective system with fewer parameters to tune and a sounder theoretical basis.  In general, as we gained experience with the adaptive system implementation, we strove to reduce the number of tuning  parameters.  We believe that the closer the implementation matches the basic theoretical cost-benefit model, the more likely it will perform well and make reasonable and understandable decisions.</p>
+
+<h3><a name="AdaptiveOptimizationSystem-ProfileDirectedInlining"></a>Profile-Directed Inlining</h3>
+
+<p>Profile-directed inlining attempts to identify frequently traversed call graph edges, which represent caller-callee relationships, and determine whether it is beneficial to recompile the caller methods<br/>
+to allow inlining of the callee methods. In Jikes RVM, profile-directed inlining augments a number of static<br/>
+inlining heuristics. The role of profile-directed inlining is to identify high cost-high benefit inlining opportunities that evade the static heuristics and to predict the likely target(s) of invokevirtual and invokeinterface calls that could not be statically bound at compile time.</p>
+
+<p>To accomplish this goal, the system takes a statistical sample of the method calls in the running application and maintains an approximation of the dynamic call graph based on this data. The system installs a listener that samples call edges whenever a yieldpoint is taken in the prologue or epilogue of a method. To sample the call edge, it records the compiled method id of the caller and callee methods and the offset of the call instruction in the caller's machine code into a buffer. When the buffer of samples is full, the sampling window ends.<br/>
+The listener then unregisters itself (stops taking samples) and wakes an organizer to update the dynamic call graph with the new profile data.  The optimizing compiler's Inline Oracle uses the dynamic call graph to guide it's inline decisions.</p>
+
+<p>The system currently used is based on Arnold & Grove's CGO 2005 paper.  More details of the sampling scheme and the inlining oracle can be found there, or in the source code.</p>
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Adding a New GC.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Adding a New GC.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Adding a New GC.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,143 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Adding a New GC</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Adding a New GC
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Jun 30, 2008 by <font color="#0050B2">steveblackburn</font>.
+    </div>
+
+    <h1><a name="AddingaNewGC-Overview"></a>Overview</h1>
+
+<p>This document describes how to add a new garbage collector to Jikes RVM.  We don't address how to design a new GC algorithm, just how to add a "new" GC to the system and then build it.  We do this by cloning an existing GC.  We leave it to you to design your own GC!</p>
+
+<h2><a name="AddingaNewGC-"></a></h2>
+
+
+<h1><a name="AddingaNewGC-Prerequisites"></a>Prerequisites</h1>
+
+<p>Ensure that you have got a clean copy of the <a href="Get The Source.html" title="Get The Source">source</a> (either a recent release or the svn head) and can correctly and successfully build one of the base garbage collectors.  There's little point in trying to build your own until you can reliably build an existing one.  I suggest you start with MarkSweep, and that you use the <a href="Using buildit.html" title="Using buildit">buildit</a> script:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">$ bin/buildit <targetmachine> BaseBase MarkSweep</pre>
+</div></div>
+<p> Then test your GC:</p>
+<div class="panel" style="border-width: 1px;"><div class="panelContent">
+<p>$ bin/buildit <targetmachine> -t gctest BaseBase MarkSweep</p>
+</div></div>
+<p> You should have seen some output like this:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">test:
+     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] InlineAllocation (<span class="code-keyword">default</span>) : SUCCESS
+     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] ReferenceTest (<span class="code-keyword">default</span>) : SUCCESS
+     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] ReferenceStress (<span class="code-keyword">default</span>) : SUCCESS
+     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] FixedLive (<span class="code-keyword">default</span>) : SUCCESS
+     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] LargeAlloc (<span class="code-keyword">default</span>) : SUCCESS
+     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] Exhaust (<span class="code-keyword">default</span>) : SUCCESS  </pre>
+</div></div>
+<p>If this is not working, you should probably go and (re) read the <a href="Care and Feeding.html" title="Care and Feeding">section in the user guide</a> on how to build and run the VM.</p>
+
+<h1><a name="AddingaNewGC-CloningtheMarkSweepGC"></a>Cloning the MarkSweep GC</h1>
+
+<p> The best way to do this is in eclipse or a similar tool (see <a href="Editing JikesRVM in an IDE.html" title="Editing JikesRVM in an IDE">here</a> for how to work with eclipse):</p>
+<ol>
+ <li>Clone the <em>org.mmtk.plan.marksweep</em> as <em>org.mmtk.plan.</em><b><em>mygc</em></b>
+ <ul>
+ <li>You can do this with <b>Eclipse</b>:
+ <ol>
+ <li>Navigagte to <em>org.mmtk.plan.marksweep</em> (within <em>MMTk/src</em>)</li>
+ <li>Right click over <em>org.mmtk.plan.marksweep</em> and select "Copy"</li>
+ <li>Right click again, and select "Paste", and name the target <em>org.mmtk.plan.</em><b><em>mygc</em></b> (or whatever you like)</li>
+ <li>This will have cloned the marksweep GC in a new package called <em>org.mmtk.plan.mygc</em></li>
+ </ol>
+ </li>
+ <li>or <b>by hand</b>:
+ <ol>
+ <li>Copy the directory <em>MMTk/org/mmtk/plan/marksweep</em> to <em>MMTk/org/mmtk/plan/</em><b><em>mygc</em></b></li>
+ <li>Edit each file within <em>MMTk/org/mmtk/plan/</em><b><em>mygc</em></b> and change its package declaration to <em>org.mmtk.plan.</em><b><em>mygc</em></b></li>
+ </ol>
+ </li>
+ <li>We can leave the GC called "MS" for now (the file names will all be <em>MMTk/org/mmtk/plan/</em><b><em>mygc</em></b><em>/MS*.java)</em></li>
+ </ul>
+ </li>
+ <li>Clone the BaseBaseMarkSweep.properties file as <em>BaseBase</em><b><em>MyGC</em></b><em>.properties</em>:
+ <ol>
+ <li>Go to <em>build/configs</em>, and right click over <em>BaseBaseMarkSweep.properties</em>, and select "Copy"</li>
+ <li>Right click and select "Paste", and paste as <em>BaseBaseMyGC.properties</em></li>
+ <li>Edit BaseBaseMyGC.properties, changing the text: "<em>config.mmtk.plan=org.mmtk.plan.</em><em>marksweep</em><em>.MS</em>" to "<em>config.mmtk.plan=org.mmtk.plan.</em><b><em>mygc</em></b><em>.MS</em>"</li>
+ </ol>
+ </li>
+ <li>Now test your new GC:</li>
+</ol>
+
+
+<div class="panel" style="border-width: 1px;"><div class="panelContent">
+<p>$ bin/buildit <targetmachine> -t gctest BaseBase <b>MyGC</b></p>
+</div></div>
+<p>You should have got similar output to your test of MarkSweep above.</p>
+
+<p>That's it.  You're done. <img class="emoticon" src="images/icons/emoticons/smile.gif" height="20" width="20" align="absmiddle" alt="" border="0"/></p>
+
+<h1><a name="AddingaNewGC-"></a></h1>
+
+
+<h1><a name="AddingaNewGC-MakingitPrettier"></a><b>Making it Prettier</b></h1>
+
+<p>You may have noticed that when you cloned the package <em>org.mmtk.plan.marksweep</em>, all the classes retained their old names (although in your new namespace; <em>org.mmtk.plan.</em><b><em>mygc</em></b>).  You can trivially change the class names in an IDE like eclipse.  You can do the same with your favorite text editor, but you'll need to be sure that you change the references carefully.  To change the class names in eclipse, just follow the procedure below for each class in <em>org.mmtk.plan.</em><b><em>mygc</em></b>:</p>
+<ol>
+ <li>Navigate to the class you want changed (eg  <em>org.mmtk.plan.</em><b><em>mygc</em></b><em>.MS)</em></li>
+ <li>Right click on the class (MS) and select <em>"Refactor->Rename..."</em> and then type in your new name, (eg <em>MyGC</em>)</li>
+ <li><em>Do the same for each of the other classes:</em>#* <em>MS -> MyGC</em>#* <em>MSCollector -> MyGCCollector</em>
+ <ul>
+ <li><em>MSConstraints -> MyGCConstraints</em></li>
+ <li><em>MSMutator -> MyGCMutator</em></li>
+ <li><em>MSTraceLocal -> MyGCTraceLocal</em></li>
+ </ul>
+ </li>
+ <li>Edit your configuration/s to ensure they refer to the renamed classes (since your IDE is unlikely to have done this automatically for you)
+ <ul>
+ <li>Go to <em>build/configs</em>, and edit each file <em>*MyGC.properties</em> to refer to your renamed classes</li>
+ </ul>
+ </li>
+</ol>
+
+
+<h1><a name="AddingaNewGC-"></a></h1>
+
+
+<h1><a name="AddingaNewGC-BeyondBaseBaseMyGC"></a>Beyond BaseBaseMyGC</h1>
+
+<p>You probably want to build with configurations other than just BaseBase.  If so, clone configurations from MarkSweep, just as you did above (for example, clone <em>FastAdaptiveMarkSweep</em> as <em>FastAdaptive</em><b><em>MyGC</em></b>).</p>
+
+<h1><a name="AddingaNewGC-WhatNext%3F"></a>What Next?</h1>
+
+<p>Once you have this working, you have successfully created and tested your own GC without writing a line of code!! You are ready to start the slightly more tricky process of writing your own garbage collector code.</p>
+
+<p>If you are writing a new GC, you should definitely be aware of the MMTk <a href="The MMTk Test Harness.html" title="The MMTk Test Harness">test harness</a>, which allows you to test and debug MMTk in a very well contained pure Java environment, without the rest of Jikes RVM.  This allows you to write unit tests and corner cases, and moreover, allows you to edit and debug MMTk entirely from within your IDE
+<br clear="all" /></p>
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Architecture.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Architecture.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Architecture.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,44 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Architecture</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Architecture
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Mar 24, 2008 by <font color="#0050B2">steveblackburn</font>.
+    </div>
+
+    <p>This section describes the architecture of Jikes RVM. The RVM can be divided into the following components:</p>
+<ul>
+ <li><a href="Core Runtime Services.html" title="Core Runtime Services">Core Runtime Services</a>: (thread scheduler, class loader, library support, verifier, etc.) This element is responsible for  managing all the underlying data structures required to execute applications and interfacing with libraries.</li>
+ <li><a href="Compilers.html" title="Compilers">Compilers</a>: (baseline, optimizing, JNI) This component is responsible for generating executable code from bytecodes.</li>
+ <li><a href="MMTk.html" title="MMTk">Memory managers</a>: This component is responsible for the allocation and collection of objects during the execution of an application.</li>
+ <li><a href="Adaptive Optimization System.html" title="Adaptive Optimization System">Adaptive Optimization System</a>: This component is responsible for profiling an executing application and judiciously using the optimizing compiler to improve its performance.</li>
+</ul>
+
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/BURS.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/BURS.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/BURS.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,113 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : BURS</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : BURS
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Jul 02, 2008 by <font color="#0050B2">dgrove</font>.
+    </div>
+
+    <p>The optimizing compiler uses the Bottom-Up Rewrite System (BURS) for instruction selection.  BURS is essentially a tree pattern matching system derived from Iburg by David R. Hanson. (See "Engineering a Simple, Efficient Code-Generator Generator" by Fraser, Hanson, and Proebsting, LOPLAS 1(3), Sept. 1992.) The instruction selection rules for each architecture are specified in an architecture-specific fileslocated in <tt>$RVM_ROOT/rvm/src-generated/opt-burs/${arch</tt>}, where ${arch} is the specific instruction architecture of interest. The rules are used in generating a parser, which transforms the IR.</p>
+
+<p>Each rule is defined by a four-line record, consisting of:</p>
+<ul>
+ <li><tt>PRODUCTION</tt>: the tree pattern to be matched.  The format of each pattern is explained below.</li>
+ <li><tt>COST</tt>: the cost of matching the pattern as opposed to skipping it.  It is a Java<a href="http://docs.codehaus.org/display/RVM/Trademarks" title="Trademarks">™</a> expression that evaluates to an integer.</li>
+ <li><tt>FLAGS</tt>: The flags for the operation:
+ <ul>
+ <li>NOFLAGS: this production performs no operation</li>
+ <li>EMIT_INSTRUCTION: this production will emit instructions</li>
+ <li>LEFT_CHILD_FIRST: visit child on left-and side of production first</li>
+ <li>RIGHT_CHILD_FIRST: visit child on right-hand side of production first</li>
+ </ul>
+ </li>
+ <li><tt>TEMPLATE</tt>: Java code to emit</li>
+</ul>
+
+
+<p>Each production has a <em>non-terminal</em>, which denotes a value, followed by a colon (":"), followed by a dependence tree that produces that value. For example, the rule resulting in memory add on the INTEL architecture is expressed in the following way:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>stm:    INT_STORE(INT_ADD_ACC(INT_LOAD(r,riv),riv),OTHER_OPERAND(r, riv))
+ADDRESS_EQUAL(P(p), PLL(p), 17)
+EMIT_INSTRUCTION
+EMIT(MIR_BinaryAcc.mutate(P(p), IA32_ADD, MO_S(P(p), DW), BinaryAcc.getValue(PL(p))));
+</pre>
+</div></div>
+<p>The production in this rule represents the following tree:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>         r     riv
+          \    /
+         INT_LOAD  riv
+             \     /
+           INT_ADD_ACC  r  riv
+                    \   |  /
+                   INT_STORE
+</pre>
+</div></div>
+<p>where <tt>r</tt> is a non-terminal that represents a register or a tree producing a register, <tt>riv</tt> is a non-terminal that represents a register (or a tree producing one) or an immediate value, and <tt>INT_LOAD</tt>, <tt>INT_ADD_ACC</tt> and <tt>INT_STORE</tt> are operators (<em>terminals</em>). <tt>OTHER_OPERAND</tt> is just an abstraction to make the tree binary.</p>
+
+<p>There are multiple helper functions that can be used in Java code (both cost expressions and generation templates).  In all code sequences the name <tt>p</tt> is reserved for the current tree node. Some of the helper methods are shortcuts for accessing properties of tree nodes:</p>
+<ul>
+ <li><tt>P(p)</tt> is used to access the instruction associated with the current (root) node,</li>
+ <li><tt>PL(p)</tt> is used to access the instruction associated with the left child of the current (root) node (provided it exists),</li>
+ <li><tt>PR(p)</tt> is used to access the instruction associated with the right child of the current (root) node (provided it exists),</li>
+ <li>similarly, <tt>PLL(p)</tt>, <tt>PLR(p)</tt>, <tt>PRL(p)</tt> and <tt>PRR(p)</tt> are used to access the instruction associated with the left child of the left child, right child of the left child, left child of the right child and right child of the right child, respectively, of the current (root) node (provided they exist).</li>
+</ul>
+
+
+<p>What the above rule basically reads is the following:<br/>
+If a tree shown above is seen, evaluate the cost expression (which, in this case, calls a helper function to test whether the addresses in the <tt>STORE</tt> (<tt>P(p)</tt>) and the <tt>LOAD</tt> (<tt>PLL(p)</tt>) instructions are equal.  The function returns 17 if they are, and a special value <tt>INFINITE</tt> if not), and if the cost is acceptable, emit the <tt>STORE</tt> instruction (<tt>P(p)</tt>) mutated in place into a machine-dependent add-accumulate instruction (<tt>IA32_ADD</tt>) that adds a given value to the contents of a given memory location.</p>
+
+<p>The rules file is used to generate a file called <tt>ir.brg</tt>, which, in turn, is used to produce a file called <tt>BURS_STATE.java</tt>.</p>
+
+<p>For more information on helper functions look at <tt>BURS_Helpers.java</tt>. For more information on the BURS algorithm see <tt>BURS.java</tt>.</p>
+
+<h2><a name="BURS-Futuredirections"></a>Future directions</h2>
+
+<p>Whilst jburg allows us to do good instruction selection there are a number of areas where it is lacking:</p>
+
+<h3><a name="BURS-Vectoroperations"></a>Vector operations</h3>
+
+<p>We can't write productions for vector operations unless we match an entire tree of operations. For example, it would be nice to write a rule of the form:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>(r, r): ADD(r,r), ADD(r,r)
+</pre>
+</div></div>
+<p>if say the architecture supported a vector add operation (ie SIMD). Unfortunately we can't have tuples on the LHS of expressions and the comma represents that matching two coverings is necessary. <a href="#BURS-leupers">Leupers</a> has shown how with a modified BURS system they can achieve this result. Their syntax is:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>r: ADD(r,r)
+r: ADD(r,r)
+</pre>
+</div></div>
+<p><a name="BURS-leupers"></a></p>
+<ul>
+ <li><a href="http://doi.acm.org/10.1145/343647.343679">Rainer Leupers, Code selection for media processors with SIMD instructions, 2000</a></li>
+</ul>
+
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Baseline Compiler.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Baseline Compiler.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Baseline Compiler.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,50 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Baseline Compiler</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Baseline Compiler
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Jul 02, 2008 by <font color="#0050B2">dgrove</font>.
+    </div>
+
+    <h2><a name="BaselineCompiler-GeneralArchitecture"></a>General Architecture</h2>
+
+<p>The goal of the baseline compiler is to efficiently generate code that is "obviously correct." It also needs to be easy to port to a new platform and self contained (the entire baseline compiler must be included in all Jikes RVM boot images to support dynamically loading other compilers).<br/>
+Roughly two thirds of the baseline compiler is machine-independent. The main file is <tt>BaselineCompiler</tt> and its parent <tt>TemplateCompilerFramework</tt>. The main platform-dependent file is <tt>BaselineCompilerImpl</tt>.</p>
+
+<p>Baseline compilation consists of two main steps: GC map computation (discussed below) and code generation.  Code generation is straightforward, consisting of a single pass through the bytecodes of the method being compiled. The compiler does not try to optimize register usage, instead the bytecode operand stack is held in memory. This leads to bytecodes that push a constant onto the stack, creating a memory write in the generated machine code. The number of memory accesses in the baseline compiler corresponds directly to the number of bytecodes. <tt>TemplateCompilerFramework</tt> contains the main code generation switch statement that invokes the appropriate <tt><em>emit</em><bytecode>_</tt> method of <tt>BaselineCompilerImpl</tt>.</p>
+
+<h2><a name="BaselineCompiler-GCMaps"></a>GC Maps</h2>
+
+<p>The baseline compiler computes GC maps by abstractly interpreting the bytecodes to determine which expression stack slots and local variables contain references at the start of each bytecode. There are additional compilations to handle <tt>JSR</tt>s; see the source code for details. This strategy of computing a single GC map that applies to all the internal GC points for each bytecode slightly constrains code generation. The code generator must ensure that the GC map remains valid at all GC points (including implicit GC points introduced by null pointer exceptions). It also forces the baseline compiler to report reference parameters for the various <tt>invoke</tt> bytecodes as live in the GC map for the call (because the GC map also needs to cover the various internal GC points that happen before the call is actually performed). Note that this is not an issue for the optimizing compiler which computes GC maps for each machine code instruction that is a GC point.</p>
+
+<h2><a name="BaselineCompiler-CommandLineOptions"></a>Command-Line Options</h2>
+
+<p>The command-line options to the baseline compiler are stored as fields in an object of type <tt>BaselineOptions</tt>; this file is mechanically generated by the build process. To add or modify the command-line options in <tt>BaselineOptions.java</tt>, you must modify either <tt>BooleanOptions.dat</tt>, or <tt>ValueOptions.dat</tt>. You should describe your desired command-line option in a format described below in the appendix; you will also find the details for the optimizing compiler's command-line options. Some options are common to both the baseline compiler and optimizing compiler. They are defined by the <tt>SharedBooleanOptions.dat</tt> and <tt>SharedValueOptions.dat</tt> files found in the <tt>rvm/src-generated/options</tt> directory. </p>
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Bootstrap.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Bootstrap.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Bootstrap.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,97 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Bootstrap</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Bootstrap
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on May 30, 2009 by <font color="#0050B2">pizlo</font>.
+    </div>
+
+    <p>The RVM is started up by a boot program written in C. This program is responsible for</p>
+<ul>
+ <li>registering signal handlers to deal with the hardware errors generated by the RVM</li>
+ <li>establishing the initial virtual memory map employed by the RVM</li>
+ <li>mapping the RVM image files</li>
+ <li>installing the addresses of the C wrapper functions which are invoked by the runtime to interact with the underlying operating system into the boot record of at the start of the RVM image area</li>
+ <li>setting up the JTOC and TR registers for its <tt>RVMThread</tt>/pthread</li>
+ <li>switching the pthread into the bootstrap Java stack running the bootstrap Java method in the bootstrap Java thread</li>
+</ul>
+
+
+<p>At this point all further initialization of the RVM is done either in Java or by employing the wrapper callbacks located in the boot record.</p>
+
+<p>The initial bootstrap routine is <tt>VM.boot()</tt>. It sets up the initial thread environment so that it looks like any other thread created by a call to Thread.start() then performs a variety of Java boot operations, including initialising the memory manager subsystem, the runtime compiler, the system classloader and the time classes.</p>
+
+<p>The bootstrap routine needs to rerun class initializers for a variety of the runtime and Classpath classes which are already loaded and compiled into the image file. This is necessary because some of the data generated by these initialization routines will not be valid in the RVM runtime. The data may be invalid as the host environment that generated the boot image may differ from the current environment.</p>
+
+<p>The boot process the enables the Java scheduler and locking system, setting up the data structures necessary to launch additional threads.  The scheduler also starts the <tt>FinalizerThread} and multiple garbage collector threads {{CollectorThread</tt>.</p>
+
+<p>Next, the boot routine boots the the JNI subsystem which enables calls to native code to be compiled and executed then re-initialises a few more classes whose init methods require a functional JNI (i.e. <tt>java.io.FileDescriptor</tt>).</p>
+
+<p>Finally, the boot routine loads the boot application class supplied on the rvm command line, creates and schedules a Java main thread to execute this class's main method, then exits, switching execution to the main thread. Execution continues until the application thread and all non-daemon threads have exited. Once there are no runnable threads (other than system threads such as the idle threads, collector threads etc) execution of the RVM runtime terminates and the rvm process exits.</p>
+
+<h2><a name="Bootstrap-MemoryMap"></a>Memory Map</h2>
+
+<p>The RVM divides its available virtual memory space into various segments containing either code, or data or a combination of the two. The basic map is as follows:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>                   +--> BOOT_IMAGE_START   MAX_MAPPABLE_ADDRESS <--+
+                   |<- SEGMENT_SIZE ->                             |
++-------------------------------------------------------------------------+
++ Platform specific| RVM Image       | RVM Heap                    | Plat +
++ ( booter code/ ) | ( initial code )| ( meta data, immortal data )| spec +
++ ( data, shlibs ) | (  & data      )| ( large & small objects    )|      +
++-------------------------------------------------------------------------+
+</pre>
+</div></div>
+
+<h3><a name="Bootstrap-BootSegment"></a>Boot Segment</h3>
+
+<p>The bottom segment of the address space is left for the underlying platform to locate the boot program (including statically linked library code) and any dynamically allocated data and library code.</p>
+
+<h3><a name="Bootstrap-RVMImageSegment"></a>RVM Image Segment</h3>
+
+<p>The next area is the one initialized by the boot program to contain the all the initial static data, instance data and compiled method code required in order for the runtime to be able to function. The required memory data is loaded from an image file created by an off line Java program, the boot image writer.</p>
+
+<p>This image file is carefully constructed to contain data which, when loaded at the correct address, will populate the runtime data area with a memory image containing:</p>
+<ul>
+ <li>a JTOC</li>
+ <li>all the TIBs, static method code arrays and static field data directly referenced from the JTOC</li>
+ <li>all the dynamic method code arrays indirectly referenced from the TIBS</li>
+ <li>all the classloader's internal class and method instances indirectly referenced via the TIBS</li>
+ <li>ancillary structures attached to these class and method instances such as class bytecode arrays, compilation records, garbage collection maps etc</li>
+ <li>a single bootstrap Java thread instance in which Java execution commences</li>
+ <li>a single bootstrap thread stack used by the bootstrap thread.</li>
+ <li>a master boot record located at the start of the image load area containing references to all the other key objects in the image (such as the JTOC, the bootstrap thread etc) plus linkage slots in which the booter writes the addresses of its C callback functions.</li>
+</ul>
+
+
+<h3><a name="Bootstrap-RVMHeapSegment"></a>RVM Heap Segment</h3>
+
+<p>The RVM heap segment is used to provide storage for code and data created during Java execution. The RVM can be configured to employ various different allocation managers taken from the <a href="MMTk.html" title="MMTk">MMTk</a> memory management toolkit.</p>
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Building Patched Versions.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Building Patched Versions.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Building Patched Versions.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,50 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Building Patched Versions</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Building Patched Versions
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Jul 07, 2007 by <font color="#0050B2">pdonald</font>.
+    </div>
+
+    <p>As part of the research process there will be a need to evaluate a set of changes to the source tree. To make this process easier the property named <tt>patch.name</tt> can be set to a non-empty string. This will cause the output directory to have the name <tt>${config.name}_${target.name}_${config.variant</tt>} rather than <tt>${config.name}_${target.name</tt>}, thus making it easy to differentiate between the patched and unpatched runtimes. </p>
+
+<p>The following steps will create a runtime without the patch in <tt>dist/prototype_ia32-linux</tt> and a runtime with the patch applied in <tt>dist/prototype_ia32-linux_ReadBarriers</tt>. </p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>% cd $RVM_ROOT
+% ant -Dconfig.name=prototype -Dhost.name=ia32-linux
+% patch -p0 < ReadBarriers.diff
+% ant -Dconfig.variant=ReadBarriers -Dconfig.name=prototype -Dhost.name=ia32-linux
+% patch -R -p0 < ReadBarriers.diff
+</pre>
+</div></div>
+
+<p>The <tt>config.variant</tt> property is also supported and reported as part of the test infrastructure.</p>
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Building a Hybrid Collector.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Building a Hybrid Collector.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Building a Hybrid Collector.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,178 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Building a Hybrid Collector</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Building a Hybrid Collector
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Mar 31, 2009 by <font color="#0050B2">steveblackburn</font>.
+    </div>
+
+    <p>Extend the Tutorial plan to create a "copy-MS" collector, which allocates into a copying nursery and at collection time, copies nursery survivors into a mark-sweep space. This plan does not require a write barrier (it is not strictly generational, as it will collect the whole heap each time the heap is full). Later we will extended it with a write barrier, allowing the nursery to be collected in isolation. Such a collector would be a generational mark-sweep collector, similar to GenMS. </p>
+
+<h5><a name="BuildingaHybridCollector-AddaCopyingNursery"></a>Add a Copying Nursery</h5>
+
+<ol>
+ <li>In <tt>TutorialConstraints</tt>, make the following changes:
+ <ol>
+ <li>Override the <tt>movesObjects()</tt> method to return <tt>true</tt>, reflecting that we are now building a copying collector:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-object">boolean</span> movesObjects() { <span class="code-keyword">return</span> <span class="code-keyword">true</span>; }</pre>
+</div></div></li>
+ <li>Remove the restriction on default alloc bytes (since default allocation will now go to a bump-pointed space).  To do this, remove the override of <tt>maxNonLOSDefaultAllocBytes()</tt>.</li>
+ <li>Add a restriction on the maximum size that may be copied into the (default) non-LOS mature space:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-object">int</span> maxNonLOSCopyBytes() { <span class="code-keyword">return</span> SegregatedFreeListSpace.MAX_FREELIST_OBJECT_BYTES;}</pre>
+</div></div></li>
+ </ol>
+ </li>
+ <li>In <tt>Tutorial</tt>, add a nursery space:
+ <ol>
+ <li>Create a new space, <tt>nurserySpace</tt>, of type <tt>CopySpace</tt>. The new space will initially be a <em>from-space</em>, so provide <tt>false</tt> as the third argument. Initialize the space with a <em>contiguous</em> virtual memory region consuming 0.15 of the heap by passing "<tt>0.15</tt>" and "<tt>true</tt>" as arguments to the constructor of <tt>VMRequest</tt> (more on this later).  Create and initialize a new integer constant to hold the descriptor for this new space:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> CopySpace nurserySpace = <span class="code-keyword">new</span> CopySpace(<span class="code-quote">"nursery"</span>, DEFAULT_POLL_FREQUENCY, <span class="code-keyword">false</span>, VMRequest.create(0.15f, <span class="code-keyword">true</span>));
+<span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">int</span> NURSERY = nurserySpace.getDescriptor();</pre>
+</div></div></li>
+ <li>Add the necessary import statements</li>
+ <li>Add <tt>nurserySpace</tt> to the <tt>PREPARE</tt> and <tt>RELEASE</tt> phases of <tt>collectionPhase()</tt>, prior to the existing calls to <tt>msTrace</tt>.  Pass <tt>true</tt> to <tt>nurserySpace.prepare()</tt> indicating that the nursery is a <em>from-space</em> during collection.</li>
+ <li>Fix accounting so that <tt>Tutorial</tt> accounts for space consumed by <tt>nurserySpace</tt>:
+ <ol>
+ <li>Add <tt>nurserySpace</tt> to the equation in <tt>getPagesUsed()</tt>,</li>
+ </ol>
+ </li>
+ <li>Since initial allocation will be into a copying space, we need to account for copy reserve:
+ <ol>
+ <li>Change <tt>getPagesRequired()</tt>, replacing <tt>msSpace.requiredPages()</tt> with <tt>(nurserySpace.requiredPages() * 2)</tt></li>
+ <li>Add a method to override <tt>getCollectionReserve()</tt> which returns <tt>nurserySpace.reservedPages() + super.getCollectionReserve()</tt>,</li>
+ <li>Add a method to override <tt>getPagesAvail()</tt>, returning <tt>super.getPagesAvail()/2</tt>,</li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+</ol>
+
+
+<h5><a name="BuildingaHybridCollector-Addnurseryallocation"></a>Add nursery allocation</h5>
+
+<p>In <tt>TutorialMutator</tt>, replace the free-list allocator (<tt>MarkSweepLocal</tt>) with add a nursery allocator.  Add an instance of <tt>CopyLocal</tt>, calling it <tt>nursery</tt>.   The constructor argument should be <tt>Tutorial.nurserySpace</tt>:</p>
+<ol>
+ <li>change <tt>alloc()</tt> to use <tt>nursery.alloc()</tt> rather than <tt>ms.alloc()</tt>.</li>
+ <li>remove the call to <tt>msSpace.postAlloc()</tt> from <tt>postAlloc()</tt> since there is no special post-allocation work necessary for the new copy space.  The call to <tt>super.postAlloc()</tt> should remain conditional on <tt>allocator != Tutorial.ALLOC_DEFAULT</tt>.</li>
+ <li>change the check within <tt>getAllocatorFromSpace()</tt> to check against <tt>Tutorial.nurserySpace</tt> and to return <tt>nursery</tt>.</li>
+ <li>adjust <tt>collectionPhase</tt>
+ <ol>
+ <li>replace call to <tt>ms.prepare()</tt> with <tt>nursery.reset()</tt></li>
+ <li>remove call to <tt>ms.release()</tt> since there are no actions necessary for the nursery allocator upon release.</li>
+ </ol>
+ </li>
+</ol>
+
+
+
+<h5><a name="BuildingaHybridCollector-Addcopyingtothecollector"></a>Add copying to the collector</h5>
+
+<p>In <tt>TutorialCollector</tt> add the capacity for the collector to allocate (copy), since our new hybrid collector will perform copying.</p>
+
+<ol>
+ <li>Add local allocators for both large object space and the mature space:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">private</span> <span class="code-keyword">final</span> LargeObjectLocal los = <span class="code-keyword">new</span> LargeObjectLocal(Plan.loSpace);
+  <span class="code-keyword">private</span> <span class="code-keyword">final</span> MarkSweepLocal mature = <span class="code-keyword">new</span> MarkSweepLocal(Tutorial.msSpace);</pre>
+</div></div></li>
+</ol>
+
+
+<ol>
+ <li>Add an <tt>allocCopy()</tt> method that conditionally allocates to the LOS or mature space:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-keyword">final</span> Address allocCopy(ObjectReference original, <span class="code-object">int</span> bytes,
+                               <span class="code-object">int</span> align, <span class="code-object">int</span> offset, <span class="code-object">int</span> allocator) {
+  <span class="code-keyword">if</span> (allocator == Plan.ALLOC_LOS)
+    <span class="code-keyword">return</span> los.alloc(bytes, align, offset);
+  <span class="code-keyword">else</span>
+    <span class="code-keyword">return</span> mature.alloc(bytes, align, offset);
+}</pre>
+</div></div></li>
+ <li>Add a <tt>postCopy()</tt> method that conditionally calls LOS or mature space post-copy actions:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-keyword">final</span> void postCopy(ObjectReference object, ObjectReference typeRef,
+                           <span class="code-object">int</span> bytes, <span class="code-object">int</span> allocator) {
+  <span class="code-keyword">if</span> (allocator == Plan.ALLOC_LOS)
+    Plan.loSpace.initializeHeader(object, <span class="code-keyword">false</span>);
+  <span class="code-keyword">else</span>
+    Tutorial.msSpace.postCopy(object, <span class="code-keyword">true</span>);
+}</pre>
+</div></div></li>
+</ol>
+
+
+<h5><a name="BuildingaHybridCollector-Makenecessarychangesto%7B%7BTutorialTraceLocal%7D%7D"></a>Make necessary changes to <tt>TutorialTraceLocal</tt></h5>
+<ol>
+ <li>Add <tt>nurserySpace</tt> clauses to <tt>isLive()</tt> and <tt>traceObject()</tt>:
+ <ol>
+ <li>Add the following to <tt>isLive()</tt>:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (Space.isInSpace(Tutorial.NURSERY, object))
+  <span class="code-keyword">return</span> Tutorial.nurserySpace.isLive(object);</pre>
+</div></div></li>
+ <li>Add the following to <tt>traceObject()</tt>:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (Space.isInSpace(Tutorial.NURSERY, object))
+  <span class="code-keyword">return</span> Tutorial.nurserySpace.traceObject(<span class="code-keyword">this</span>, object, Tutorial.ALLOC_DEFAULT);</pre>
+</div></div></li>
+ </ol>
+ </li>
+ <li>Add a new <tt>precopyObject()</tt> method, which is necessary for all copying collectors:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> ObjectReference precopyObject(ObjectReference object) {
+  <span class="code-keyword">if</span> (object.isNull()) <span class="code-keyword">return</span> object;
+  <span class="code-keyword">else</span> <span class="code-keyword">if</span> (Space.isInSpace(Tutorial.NURSERY, object))
+    <span class="code-keyword">return</span> Tutorial.nurserySpace.traceObject(<span class="code-keyword">this</span>, object, Tutorial.ALLOC_DEFAULT);
+  <span class="code-keyword">else</span>
+    <span class="code-keyword">return</span> object;
+}</pre>
+</div></div></li>
+ <li>Add a new <tt>willNotMoveInCurrentCollection()</tt> method, which identifies those objects which do not move (necessary for copying collectors):
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-object">boolean</span> willNotMoveInCurrentCollection(ObjectReference object) {
+  <span class="code-keyword">return</span> !Space.isInSpace(Tutorial.NURSERY, object);
+}</pre>
+</div></div></li>
+</ol>
+
+
+<p>With these changes, Tutorial should now work.  You should be able to again build a BaseBaseTutorial image and test it against any benchmark.  Again, if you use <tt>-X:gc:verbose=3</tt> you can see the movement of data among the spaces at each garbage collection.</p>
+<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Checkpoint</b><br />
+<p>This <a href="http://cs.anu.edu.au/people/Steve.Blackburn/misc/mmtk-tutorial/tutorial-04.zip">zip file</a> captures all of the above steps with respect to Jikes RVM 3.0.1.  You can use the archive to verify you've completed the above steps correctly.</p></td></tr></table></div>
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Building a Mark-sweep Collector.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Building a Mark-sweep Collector.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Building a Mark-sweep Collector.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,270 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Building a Mark-sweep Collector</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Building a Mark-sweep Collector
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Mar 31, 2009 by <font color="#0050B2">steveblackburn</font>.
+    </div>
+
+    <p>We will now modify the <tt>Tutorial</tt> collector to perform allocation and collection according to a mark-sweep policy.  First we will change the allocation from bump-allocation to free-list allocation (but still no collector whatsoever), and then we will add a mark-sweep collection policy, yielding a complete mark-sweep collector.</p>
+
+<h5><a name="BuildingaMark-sweepCollector-FreelistAllocation"></a>Free-list Allocation</h5>
+
+<p>This step will change your simple collector from using a bump pointer to a free list (but still without any garbage collection).</p>
+
+<ol>
+ <li>Update the constraints for this collector to reflect the constraints of a mark-sweep system, by updating <tt>TutorialConstraints</tt> as follows:
+ <ul>
+ <li><tt>gcHeaderBits()</tt> should return <tt>MarkSweepSpace.LOCAL_GC_BITS_REQUIRED</tt>.</li>
+ <li><tt>gcHeaderWords()</tt> should return <tt>MarkSweepSpace.GC_HEADER_WORDS_REQUIRED</tt>.</li>
+ <li>The <tt>maxNonLOSDefaultAllocBytes()</tt> method should be added, overriding one provided by the base class, and should return <tt>SegregatedFreeListSpace.MAX_FREELIST_OBJECT_BYTES</tt> (because this reflects the largest object size that can be allocated with the free list allocator).</li>
+ </ul>
+ </li>
+ <li>In <tt>Tutorial</tt>, replace the <tt>ImmortalSpace</tt> with a <tt>MarkSweepSpace</tt>:
+ <ul>
+ <li>rename the variable <tt>noGCSpace</tt> to <tt>msSpace</tt> (right-click, Refactor→Rename...)</li>
+ <li>rename the variable <tt>NOGC</tt> to <tt>MARK_SWEEP</tt> (right-click, Refactor→Rename...)</li>
+ <li>change the string that identifies the space from "default" to "mark-sweep"</li>
+ <li>change the type and static initialization of <tt>msSpace</tt> appropriately (<tt>MarkSweepSpace msSpace = new MarkSweepSpace("ms", DEFAULT_POLL_FREQUENCY, VMRequest.create())</tt>).</li>
+ <li>add an import for <tt>MarkSweepSpace</tt> and remove the redundant import for <tt>ImmortalSpace</tt>.</li>
+ </ul>
+ </li>
+ <li>In <tt>TutorialMutator</tt>, replace the <tt>ImmortalLocal</tt> (a bump pointer) with a<br/>
+<tt>MarkSweepLocal</tt> (a free-list allocator)
+ <ul>
+ <li>change the type of <tt>nogc</tt> and change the static initializer appropriately.</li>
+ <li>change the appropriate import statement from <tt>ImmortalLocal</tt> to <tt>MarkSweepLocal</tt>.</li>
+ <li>rename the variable <tt>nogc</tt> to <tt>ms</tt> (right-click, Refactor→Rename...)</li>
+ </ul>
+ </li>
+ <li>Fix <tt>postAlloc()</tt> to initialize the mark-sweep header:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (allocator == Tutorial.ALLOC_DEFAULT) {
+  Tutorial.msSpace.postAlloc(ref);
+} <span class="code-keyword">else</span> {
+  <span class="code-keyword">super</span>.postAlloc(ref, typeRef, bytes, allocator);
+}</pre>
+</div></div></li>
+</ol>
+
+
+<p>With these changes, Tutorial should now work, just as it did before, only exercising a free list (mark-sweep) allocator rather than a bump pointer (immortal) allocator. Create a <tt>BaseBaseTutorial</tt> build, and test your system to ensure it performs just as it did before. You may notice that its memory is exhausted slightly earlier because the free list allocator is slightly less efficient in space utilization than the bump pointer allocator.</p>
+<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Checkpoint</b><br />
+<p>This <a href="http://cs.anu.edu.au/people/Steve.Blackburn/misc/mmtk-tutorial/tutorial-1.zip">zip file</a> captures all of the above steps with respect to Jikes RVM 3.0.2.  You can use the files in the archive to verify you've completed the above steps correctly.</p></td></tr></table></div>
+
+<h5><a name="BuildingaMark-sweepCollector-MarksweepCollection."></a>Mark-sweep Collection.</h5>
+
+<p>The next change required is to perform mark-and-sweep collection whenever the heap is exhausted. The poll() method of a plan is called at appropriate intervals by other MMTk components to ask the plan whether a collection is required.</p>
+<ol>
+ <li>Change <tt>TutorialConstraints</tt> so that it inherits constraints from a collecting plan:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> class TutorialConstraints <span class="code-keyword">extends</span> StopTheWorldConstraints</pre>
+</div></div></li>
+ <li>The plan needs to know how to perform a garbage collection.  Collections are performed in phases, coordinated by data structures defined in <tt>StopTheWorld</tt>, and have global and thread-local components.  First ensure the global components are behaving correctly.  These are defined in <tt>Tutorial</tt> (which is implicitly <em>global</em>).
+ <ul>
+ <li>Make <tt>Tutorial</tt> extend <tt>StopTheWorld</tt> (for stop-the-world garbage collection) rather than <tt>Plan</tt> (the superclass of <tt>StopTheWorld</tt>: <tt>public class Tutorial extends StopTheWorld</tt></li>
+ <li>Rename the <tt>trace</tt> variable to <tt>msTrace</tt> (right-click, Refactor→Rename...)</li>
+ <li>Add code to ensure that Tutorial performs the correct global collection phases in <tt>collectionPhase()</tt>:
+ <ul>
+ <li>First remove the assertion that the code is never called (<tt>if (VM.VERIFY_ASSERTIONS) VM.assertions._assert(false);</tt>).</li>
+ <li>Add the <em>prepare</em> phase, preparing both the global tracer (<tt>msTrace</tt>) and the space (<tt>msSpace</tt>), after first performing the preparation phases associated with the superclasses. Using the commented template in <tt>Tutorial.collectionPhase()</tt>, set the following within the clause for <tt>phaseId == PREPARE</tt>:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == PREPARE) {
+  <span class="code-keyword">super</span>.collectionPhase(phaseId);
+  msTrace.prepare();
+  msSpace.prepare(<span class="code-keyword">true</span>);
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Add the <em>closure</em> phase, again preparing the global tracer (<tt>msTrace</tt>):
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == CLOSURE) {
+  msTrace.prepare();
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Add the <em>release</em> phase, releasing the global tracer (<tt>msTrace</tt>) and the space (<tt>msSpace</tt>) before performing the release phases associated with the superclass:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == RELEASE) {
+  msTrace.release();
+  msSpace.release();
+  <span class="code-keyword">super</span>.collectionPhase(phaseId);
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Finally ensure that for all other cases, the phases are delegated to the superclass, uncommenting the following after all of the above conditionals:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">super</span>.collectionPhase(phaseId);</pre>
+</div></div></li>
+ </ul>
+ </li>
+ <li>Add a new accounting method that determines how much space a collection needs to yield to the mutator.  The method, <tt>getPagesRequired</tt>, overrides the one provided in the <tt>StopTheWorld</tt> superclass:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-object">int</span> getPagesRequired() {
+  <span class="code-keyword">return</span> <span class="code-keyword">super</span>.getPagesRequired() + msSpace.requiredPages();
+}</pre>
+</div></div></li>
+ <li>Add a new method that determines whether an object will move during collection:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-object">boolean</span> willNeverMove(ObjectReference object) {
+  <span class="code-keyword">if</span> (Space.isInSpace(MARK_SWEEP, object))
+    <span class="code-keyword">return</span> <span class="code-keyword">true</span>;
+  <span class="code-keyword">return</span> <span class="code-keyword">super</span>.willNeverMove(object);
+}</pre>
+</div></div></li>
+ </ul>
+ </li>
+ <li>Next ensure that Tutorial correctly performs <em>local</em> collection phases.  These are defined in <tt>TutorialCollector</tt>.
+ <ul>
+ <li>Make <tt>TutorialCollector</tt> extend <tt>StopTheWorldCollector</tt>:
+ <ul>
+ <li>Extend the class (<tt>public class TutorialCollector extends StopTheWorldCollector</tt>).</li>
+ <li>Import <tt>StopTheWorldCollector</tt>.</li>
+ <li>Remove some methods now implemented by <tt>StopTheWorldCollector</tt>: <tt>collect()</tt>, <tt>concurrentCollect()</tt>, and <tt>concurrentCollectionPhase()</tt>.</li>
+ </ul>
+ </li>
+ <li>Add code to ensure that <tt>TutorialCollector</tt> performs the correct global collection phases in <tt>collectionPhase()</tt>:
+ <ul>
+ <li>First remove the assertion that the code is never called (<tt>if (VM.VERIFY_ASSERTIONS) VM.assertions._assert(false);</tt>).</li>
+ <li>Add the <em>prepare</em> phase, preparing the local tracer (<tt>trace</tt>) after first performing the preparation phases associated with the superclasses. Using the commented template in <tt>Tutorial.collectionPhase()</tt>, set the following within the clause for <tt>phaseId == PREPARE</tt>:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == Tutorial.PREPARE) {
+  <span class="code-keyword">super</span>.collectionPhase(phaseId, primary);
+  trace.prepare();
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Add the <em>closure</em> phase, again preparing the local tracer (<tt>trace</tt>):
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == Tutorial.CLOSURE) {
+  trace.completeTrace();
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Add the <em>release</em> phase, releasing the local tracer (<tt>trace</tt>) before performing the release phases associated with the superclass:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == Tutorial.RELEASE) {
+  trace.release();
+  <span class="code-keyword">super</span>.collectionPhase(phaseId, primary);
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Finally ensure that for all other cases, the phases are delegated to the superclass, uncommenting the following after all of the above conditionals:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">super</span>.collectionPhase(phaseId, primary);</pre>
+</div></div></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>Finally ensure that Tutorial correctly performs local mutator-related collection activities:
+ <ul>
+ <li>Make <tt>TutorialMutator</tt> extend <tt>StopTheWorldMutator</tt>:
+ <ul>
+ <li>Extend the class: <tt>public class TutorialMutator extends StopTheWorldMutator</tt>.</li>
+ <li>Import <tt>StopTheWorldMutator</tt>.</li>
+ </ul>
+ </li>
+ <li>Update the mutator-side collection phases:
+ <ul>
+ <li>Add the <em>prepare</em> phase to <tt>collectionPhase()</tt> which prepares mutator-side data structures(namely the per-thread free lists) for the <em>start</em> of a collection:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == MS.PREPARE) {
+  <span class="code-keyword">super</span>.collectionPhase(phaseId, primary);
+  ms.prepare();
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Add the <em>release</em> phase to <tt>collectionPhase()</tt> which re-initializes mutator-side data structures (namely the per-thread free lists) after the <em>end</em> of a collection:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">if</span> (phaseId == MS.RELEASE) {
+  ms.release();
+  <span class="code-keyword">super</span>.collectionPhase(phaseId, primary);
+  <span class="code-keyword">return</span>;
+}</pre>
+</div></div></li>
+ <li>Finally, delegate all other phases to the superclass:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">super</span>.collectionPhase(phaseId, primary);</pre>
+</div></div></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ol>
+
+
+
+<p>With these changes, Tutorial should now work with both mark-sweep allocation <em>and</em> collection. Create a <tt>BaseBaseTutorial</tt> build, and test your system to ensure it performs just as it did before. You can observe the effect of garbage collection as the program runs by adding <tt>-X:gc:verbose=1</tt> to your command line as the first argument after <tt>rvm</tt>.  If you run a very simple program (such as <tt>HelloWorld</tt>), you might not observe any garbage collection.  In that case, try running a larger program such as a DaCapo benchmark.  You may also observe that the output from <tt>-X:gc:verbose=1</tt> indicates that the heap is growing.   Dynamic heap resizing is normal default behavior for a JVM.  You can override this by providing minimum (<tt>-Xms</tt>) and maximum (<tt>-Xmx</tt>) heap sizes (these are standard arguments respected by all JVMs.  The heap size should be specified in bytes as an integer and a unit (<tt>K</tt>, <tt>M</tt>, <tt>G</tt>), for example: <tt>-Xms20M -Xmx20M</tt>.</p>
+
+<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Checkpoint</b><br />
+<p>This <a href="http://cs.anu.edu.au/people/Steve.Blackburn/misc/mmtk-tutorial/tutorial-2.zip">zip file</a> captures all of the above steps with respect to Jikes RVM 3.0.2.  You can use the patch to verify you've completed the above steps correctly.</p></td></tr></table></div>
+
+<h5><a name="BuildingaMark-sweepCollector-OptimizedMarksweepCollection."></a>Optimized Mark-sweep Collection.</h5>
+
+<p>MMTk has a unique capacity to allow specialization of the performance-critical scanning loop.  This is particularly valuable in collectors which have more than one mode of collection (such as in a generational collector), so each of the collection paths is explicitly specialized at build time, removing conditionals from the hot portion of the tracing loop at the core of the collector. Enabling this involves just two small steps:</p>
+
+<ol>
+ <li>Indicate the number of specialized scanning loops and give each a symbolic name, which at this stage is just one since we have a very simple collector:
+ <ul>
+ <li>Override the <tt>numSpecializedScans()</tt> getter method in <tt>TutorialConstraints</tt>:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">@Override
+<span class="code-keyword">public</span> <span class="code-object">int</span> numSpecializedScans() { <span class="code-keyword">return</span> 1; }</pre>
+</div></div></li>
+ <li>Define a constant to represent our (only) specialized scan in <tt>Tutorial</tt> (we will call this scan "mark"):
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">int</span> SCAN_MARK = 0;</pre>
+</div></div></li>
+ </ul>
+ </li>
+ <li>Register the specialized method:
+ <ul>
+ <li>Add the following line to <tt>registerSpecializedMethods()</tt> method in <tt>Tutorial</tt>.:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">TransitiveClosure.registerSpecializedScan(SCAN_MARK, TutorialTraceLocal.class);</pre>
+</div></div></li>
+ <li>Add <tt>Tutorial.SCAN_MARK</tt> as the first argument to the superclass constructor for <tt>TutorialTraceLocal</tt>:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> TutorialTraceLocal(Trace trace) {
+  <span class="code-keyword">super</span>(Tutorial.SCAN_MARK, trace);
+}</pre>
+</div></div></li>
+ </ul>
+ </li>
+</ol>
+
+
+<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Checkpoint</b><br />
+<p>This <a href="http://cs.anu.edu.au/people/Steve.Blackburn/misc/mmtk-tutorial/tutorial-3.zip">zip file</a> captures all of the above steps with respect to Jikes RVM 3.0.2.  You can use the archive to verify you've completed the above steps correctly.</p></td></tr></table></div>
+
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Building on Windows.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Building on Windows.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Building on Windows.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,55 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Building on Windows</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Building on Windows
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Aug 13, 2008 by <font color="#0050B2">ianrogers</font>.
+    </div>
+
+    <p>Windows support is still a work in progress, the following is collecting current wisdom.</p>
+
+<h2><a name="BuildingonWindows-Prerequisites"></a>Prerequisites</h2>
+
+<ul>
+ <li><a href="http://en.wikipedia.org/wiki/Microsoft_Windows_SDK">Windows SDK</a> (free)</li>
+ <li><a href="http://www.microsoft.com/express/download/#webInstall">Visual C++</a> (the free Express Edition is ok)</li>
+ <li><a href="http://ant.apache.org/">Apache Ant</a></li>
+ <li>An installed Java Development Kit (JDK)</li>
+ <li><a href="http://www.cygwin.com/">Cygwin</a> - in particular you need: svn, bison, byacc, gcc, perl</li>
+</ul>
+
+
+<h2><a name="BuildingonWindows-EnvironmentVariables"></a>Environment Variables</h2>
+
+<ul>
+ <li><em>JAVA_HOME</em> - point at JDK installation directory</li>
+</ul>
+
+
+    
+                        </td>
+    </tr>
+    </table>
+    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
+ </tr>
+    <tr>
+    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
+    </tr>
+    </table>
+    </body>
+</html>
\ No newline at end of file

Added: rvmroot/tags/3.1.0/userguide/html/RVM/Building the RVM.html
===================================================================
--- rvmroot/tags/3.1.0/userguide/html/RVM/Building the RVM.html                        (rev 0)
+++ rvmroot/tags/3.1.0/userguide/html/RVM/Building the RVM.html 2009-06-10 14:20:23 UTC (rev 15707)
@@ -0,0 +1,342 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+    <head>
+        <title>RVM : Building the RVM</title>
+    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">    
+    </head>
+
+    <body>
+    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+    <tr>
+    <td valign="top" class="pagebody">
+    <div class="pageheader">
+    <span class="pagetitle">
+                            RVM : Building the RVM
+                                                    </span>
+    </div>
+    <div class="pagesubheading">
+    This page last changed on Nov 12, 2008 by <font color="#0050B2">aleksey.shipilev</font>.
+    </div>
+
+    <p>This guide describes how to build Jikes RVM. The first section is an overview of the Jikes RVM build process and this is followed by your system requirements and a detailed description of the steps required to build Jikes RVM.</p>
+<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Note</b><br />
+<p>Once you have things working, as described below, the <a href="Using buildit.html" title="Using buildit">buildit</a>  script will provide a fast and easy way to build the system.  We recommend you get things working as described below first, so you can be sure you've met the requisite dependencies etc.</p></td></tr></table></div>
+
+<h2><a name="BuildingtheRVM-Overview"></a>Overview</h2>
+
+
+<h3><a name="BuildingtheRVM-Compilingthesourcecode"></a>Compiling the source code</h3>
+
+<p>The majority of Jikes RVM is written in Java and will be compiled into class files just as with other Java applications. There is also a small portion of Jikes RVM that is written in C that must be compiled with a C compiler such as gcc.  Jikes RVM uses <a href="http://ant.apache.org">Ant</a> version 1.6.5 or later as the build tool that orchestrates the build process and executes the steps required in building Jikes RVM.</p>
+<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Note</b><br />
+<p>Jikes RVM requires a complete install of ant, including the optional tasks. These are present if you download and install ant manually. Some Linux distributions have decided to break ant into multiple packages. So if you are installing on a platform such as Debian you may need to install another package such as 'ant-optional'.</p></td></tr></table></div>
+
+<h3><a name="BuildingtheRVM-Generatingsourcecode"></a>Generating source code</h3>
+
+<p>The build process also generates Java and C source code based on build time constants such as the selected instruction architecture, garbage collectors and compilers. The generation of the source code occurs prior to the compilation phase.</p>
+
+<h3><a name="BuildingtheRVM-BootstrappingtheRVM"></a>Bootstrapping the RVM</h3>
+
+<p>Jikes RVM compiles Java class files and produces arrays of code and data. To build itself Jikes RVM will execute on an existing Java Virtual Machine and compiles a copy of it's own class files into a <b>boot image</b> for the code and data using the <b>boot image writer</b> tool. The set of files compiled is called the <a href="Primordial Class List.html" title="Primordial Class List">Primordial Class List</a>. The <b>boot image runner</b> is a small C program that loads the boot image and transfers control flow into Jikes RVM.</p>
+
+<h3><a name="BuildingtheRVM-Classlibraries"></a>Class libraries</h3>
+
+<p>The Java class library is the mechanism by which Java programs communicate with the outside world. Jikes RVM has configurable class library support, the most mature of which is the the <a href="http://www.gnu.org/software/classpath/">GNU Classpath</a> class library. In the release version of Jikes RVM is support for the <a href="http://harmony.apache.org/">Apache Harmony</a> class library.</p>
+
+<p>For GNU Classpath, the developer can either specify a particular version of GNU Classpath to use. By default the build process will download and build GNU Classpath.</p>
+
+<p>Setting the ant property <b>classlib.provider</b> to <b>Harmony</b> (<a href="#BuildingtheRVM-DefiningAntproperties">see how to define ant properties</a>) will change the build process to download and build the Apache Harmony class library.</p>
+
+<h2><a name="BuildingtheRVM-TargetRequirements"></a>Target Requirements</h2>
+
+<p>Jikes RVM is known to build and work on certain combinations of instruction architectures and operating systems. The following sections detail the supported architectures and operating systems.</p>
+
+<h3><a name="BuildingtheRVM-Architectures%26nbsp%3B"></a>Architectures </h3>
+
+<p>The PowerPC (or ppc) and ia32 instruction set architectures are supported by Jikes RVM.</p>
+
+<h4><a name="BuildingtheRVM-Intel"></a>Intel</h4>
+
+<p>Intel's Instruction Set Architectures (ISAs) get known by different names:</p>
+<ul>
+ <li><b>IA-32</b> is the name used to describe processors such as 386, 486 and the Pentium processors. It is popularly called <b>x86</b> or sometimes in our documentation as x86-32.</li>
+ <li><b>IA-32e</b> is the name used to describe the extension of the IA-32 architecture to support 8 more registers and a 64-bit address space. It is popularly called <b>x86_64</b> or <b>AMD64</b>, as AMD chips were the first to support it. It is found in processors such AMD's Opteron and Athlon 64, as well as in Intel's own Pentium 4 processors that have <b>EM64T</b> in their name.</li>
+ <li><b>IA-64</b> is the name of Intel's Itanium processor ISA.</li>
+</ul>
+
+
+<p>Jikes RVM currently supports the IA-32 ISA. As IA-32e is backward compatible with IA-32, Jikes RVM can be built and run upon IA-32e processors. The IA-64 architecture supports IA-32 code through a compatibility mode or through emulation and Jikes RVM should run in this configuration.</p>
+
+<h3><a name="BuildingtheRVM-OperatingSystems"></a>Operating Systems</h3>
+
+<p>Jikes RVM is capable of running on any operating system that is supported by the <a href="http://www.gnu.org/software/classpath/">GNU Classpath</a> library, low level library support is implemented and memory layout is defined. The low level library support includes interaction with the threading and signal libraries, memory management facilities and dynamic library loading services. The memory layout must also be known, as Jikes RVM will attempt to locate the boot image code and data at specific memory locations. These memory locations must not conflict with where the native compiler places it's code and data. Operating systems that are known to work include AIX, Linux and OSX. At one stage a port to win32 was completed but it was never integrated into the main Jikes RVM codebase.</p>
+
+<p><b>Note:</b> Current implementation of Jikes RVM implies that system native libraries (like GTK+) have been compiled <b>with</b> frame pointers. Most of Linux distribution have frame pointers enabled in most of the packages, but some explicitly use -fomit-frame-pointer thus producing the library that can't be used with JikesRVM. See <a href="http://www.nabble.com/-rvm-research---DaCapo:chart-is-broken--td20438748.html">this issue</a> for example.</p>
+
+
+<h3><a name="BuildingtheRVM-SupportMatrix"></a>Support Matrix</h3>
+
+<p>The following table details the targets that have historically been supported and the current status of the support. The target.name column is the identifier that Jikes RVM uses to identify this target.</p>
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> target.name </th>
+<th class='confluenceTh'> Operating System </th>
+<th class='confluenceTh'> Instruction Architecture </th>
+<th class='confluenceTh'> Address Size </th>
+<th class='confluenceTh'> Status </th>
+</tr>
+<tr>
+<td class='confluenceTd'> ia32-linux </td>
+<td class='confluenceTd'> Linux <br clear="all" /> </td>
+<td class='confluenceTd'> ia32 <br clear="all" /> </td>
+<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ia32-osx </td>
+<td class='confluenceTd'> OSX <br clear="all" /> </td>
+<td class='confluenceTd'> ia32 <br clear="all" /> </td>
+<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ia32-solaris </td>
+<td class='confluenceTd'> Solaris </td>
+<td class='confluenceTd'> ia32 </td>
+<td class='confluenceTd'> 32 bits </td>
+<td class='confluenceTd'> OK </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ia32-cygwin </td>
+<td class='confluenceTd'> Windows </td>
+<td class='confluenceTd'> ia32 </td>
+<td class='confluenceTd'> 32 bits </td>
+<td class='confluenceTd'> <a href="http://jira.codehaus.org/browse/RVM-630">WIP</a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ppc32-aix </td>
+<td class='confluenceTd'> AIX </td>
+<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
+<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ppc32-linux <br clear="all" /> </td>
+<td class='confluenceTd'> Linux <br clear="all" /> </td>
+<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
+<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ppc32-osx <br clear="all" /> </td>
+<td class='confluenceTd'> OSX <br clear="all" /> </td>
+<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
+<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ppc64-aix <br clear="all" /> </td>
+<td class='confluenceTd'> AIX <br clear="all" /> </td>
+<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
+<td class='confluenceTd'> 64 bits <br clear="all" /> </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> ppc64-linux <br clear="all" /> </td>
+<td class='confluenceTd'> Linux <br clear="all" /> </td>
+<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
+<td class='confluenceTd'> 64 bits </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> x86_64-linux <br clear="all" /> </td>
+<td class='confluenceTd'> Linux <br clear="all" /> </td>
+<td class='confluenceTd'> ia32 <br clear="all" /> </td>
+<td class='confluenceTd'> 32 bits* <br clear="all" /> </td>
+<td class='confluenceTd'> OK <br clear="all" /> </td>
+</tr>
+</tbody></table>
+<ul>
+ <li>x86_64 is currently only supported using the legacy 32bit addressing mode and instructions (<a href="http://jira.codehaus.org/browse/RVM-169">track progress on full 64bit support here</a>)</li>
+</ul>
+
+
+<h2><a name="BuildingtheRVM-ToolRequirements"></a>Tool Requirements</h2>
+
+
+<h3><a name="BuildingtheRVM-JavaVirtualMachine"></a>Java Virtual Machine</h3>
+
+<p>Jikes RVM requires an existing Java Virtual Machine that conforms to Java 5.0 such as <a href="http://java.sun.com">Sun JDK 1.5</a> or IBM JDK 5.0. Some Java Virtual Machines are unable to cope with compiling the Java class library so it is recomended that you install one of the above mentioned JVMs if they are not already installed on your system. The remaining build instructions assume that this Java Virtual Machine on your path. You can run "<tt>java -version</tt>" to check you are using the correct JVM.</p>
+
+<h3><a name="BuildingtheRVM-Ant"></a>Ant</h3>
+
+<p><a href="http://ant.apache.org">Ant</a> version 1.6.5 or later is the tool required to orchestrate the build process. You can download and install the Ant tool from <a href="http://ant.apache.org/">http://ant.apache.org/</a> if it is not already installed on your system. The remaining build instructions assume that $ANT_HOME/bin is on your path. You can run "<tt>ant -version</tt>" to check you are running the correct version of ant.</p>
+
+<h3><a name="BuildingtheRVM-CToolChain"></a>C Tool Chain</h3>
+
+<p>Jikes RVM assumes that the GNU C Tool Chain is present on the system or a tool chain that is reasonably compatible. Most modern *nix environments satisfy this requirement.</p>
+
+<h3><a name="BuildingtheRVM-Bison"></a>Bison</h3>
+
+<p>As part of the build process, Jikes RVM uses the bison tool which should be present on most modern *nix environments.</p>
+
+<h3><a name="BuildingtheRVM-Perl"></a>Perl</h3>
+
+<p>Perl is trivially used as part of the build process but this requirement may be removed in future releases of Jikes RVM. Perl is also used as part of the regression and performance testing framework.</p>
+
+<h3><a name="BuildingtheRVM-Awk"></a>Awk</h3>
+
+<p>GNU Awk is required as part of the regression and performance testing framework but is not required when building Jikes RVM.</p>
+
+<h3><a name="BuildingtheRVM-ExtratoolsrecommendedforSolaris"></a>Extra tools recommended for Solaris</h3>
+
+<p>pkg-get will greatly simplify installing GNU packages on Solaris. Our patches require that GNU patch is picked up in preference to Sun's, to achieve this, for example, you can create a symbolic link to /usr/bin/gpatch from /opt/csw/bin/patch and make sure /opt/csw/bin is in your path before /usr/bin.</p>
+
+<h2><a name="BuildingtheRVM-Instructions"></a>Instructions</h2>
+
+
+<h3><a name="BuildingtheRVM-DefiningAntproperties"></a>Defining Ant properties</h3>
+
+<p>There are a number of ant properties that are used to control the build process of Jikes RVM. These properties may either be specified on the command line by "<tt>-Dproperty=variable</tt>" or they may be specified in a file named "<tt>.ant.properties</tt>" in the base directory of the jikesrvm source tree. The "<tt>.ant.properties</tt>" file is a standard Java proeprty file with each line containing a "<tt>property=variable</tt>" and comments starting with a <em>#</em> and finishing at the end of the line. The following table describes some properties that are commonly specified.</p>
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> Property </th>
+<th class='confluenceTh'> Description </th>
+<th class='confluenceTh'> Default </th>
+</tr>
+<tr>
+<td class='confluenceTd'> host.name </td>
+<td class='confluenceTd'> The name of the host environment used for building Jikes RVM. The name should match one of the files located in the <a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/hosts/"><tt>build/hosts/</tt></a> directory minus the '<tt>.properties</tt>' extension. <br clear="all" /> </td>
+<td class='confluenceTd'> None </td>
+</tr>
+<tr>
+<td class='confluenceTd'> target.name </td>
+<td class='confluenceTd'> The name of the target environment for Jikes RVM. The name should match one of the files located in the <a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/targets/"><tt>build/targets/</tt></a> directory minus the '<tt>.properties</tt>' extension. This should only be specified when cross compiling the Jikes RVM. See <a href="Cross-Platform Building.html" title="Cross-Platform Building">Cross-Platform Building</a> for a detailed description of cross compilation. <br clear="all" /> </td>
+<td class='confluenceTd'> <tt>${host.name</tt>} <br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> config.name </td>
+<td class='confluenceTd'> The name of the configuration used when building Jikes RVM. The name should match one of the files located in the <a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/configs/"><tt>build/configs/</tt></a> directory minus the '<tt>.properties</tt>' extension. This setting is further described in the section <a href="Configuring the RVM.html" title="Configuring the RVM">Configuring the RVM</a>. </td>
+<td class='confluenceTd'> None </td>
+</tr>
+<tr>

@@ Diff output truncated at 100000 characters. @@

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
Jikesrvm-commits mailing list
Jikesrvm-commits@...
https://lists.sourceforge.net/lists/listinfo/jikesrvm-commits