Move TargetData to DataLayout.
[oota-llvm.git] / docs / GarbageCollection.html
index c2236d4d81a4e29910f3116946c71de438cac84d..5bc70f1bb01b5727add17497a7bd5e87b407d935 100644 (file)
@@ -4,7 +4,7 @@
 <head>
   <meta http-equiv="Content-Type" Content="text/html; charset=UTF-8" >
   <title>Accurate Garbage Collection with LLVM</title>
-  <link rel="stylesheet" href="llvm.css" type="text/css">
+  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
   <style type="text/css">
     .rowhead { text-align: left; background: inherit; }
     .indent { padding-left: 1em; }
@@ -13,9 +13,9 @@
 </head>
 <body>
 
-<div class="doc_title">
+<h1>
   Accurate Garbage Collection with LLVM
-</div>
+</h1>
 
 <ol>
   <li><a href="#introduction">Introduction</a>
@@ -26,9 +26,9 @@
 
   <li><a href="#quickstart">Getting started</a>
     <ul>
-    <li><a href="quickstart-compiler">In your compiler</a></li>
-    <li><a href="quickstart-runtime">In your runtime library</a></li>
-    <li><a href="shadow-stack">About the shadow stack</a></li>
+    <li><a href="#quickstart-compiler">In your compiler</a></li>
+    <li><a href="#quickstart-runtime">In your runtime library</a></li>
+    <li><a href="#shadow-stack">About the shadow stack</a></li>
     </ul>
   </li>
 
 </div>
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="introduction">Introduction</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p>Garbage collection is a widely used technique that frees the programmer from
 having to know the lifetimes of heap objects, making software easier to produce
@@ -118,20 +118,18 @@ conservative garbage collectors (though these seem rare in practice).</p>
 they can suffer from degraded scalar optimization of the program. In particular,
 because the runtime must be able to identify and update all pointers active in
 the program, some optimizations are less effective. In practice, however, the
-locality and performance benefits of using aggressive garbage allocation
+locality and performance benefits of using aggressive garbage collection
 techniques dominates any low-level losses.</p>
 
 <p>This document describes the mechanisms and interfaces provided by LLVM to
 support accurate garbage collection.</p>
 
-</div>
-
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="feature">Goals and non-goals</a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <p>LLVM's intermediate representation provides <a href="#intrinsics">garbage
 collection intrinsics</a> that offer support for a broad class of
@@ -151,14 +149,14 @@ collector models. For instance, the intrinsics permit:</p>
 support a broad class of garbage collected languages including Scheme, ML, Java,
 C#, Perl, Python, Lua, Ruby, other scripting languages, and more.</p>
 
-<p>However, LLVM does not itself provide a garbage collector&#151;this should
+<p>However, LLVM does not itself provide a garbage collector&mdash;this should
 be part of your language's runtime library. LLVM provides a framework for
 compile time <a href="#plugin">code generation plugins</a>. The role of these
 plugins is to generate code and data structures which conforms to the <em>binary
 interface</em> specified by the <em>runtime library</em>. This is similar to the
 relationship between LLVM and DWARF debugging info, for example. The
 difference primarily lies in the lack of an established standard in the domain
-of garbage collection&#151;thus the plugins.</p>
+of garbage collection&mdash;thus the plugins.</p>
 
 <p>The aspects of the binary interface with which LLVM's GC support is
 concerned are:</p>
@@ -166,11 +164,12 @@ concerned are:</p>
 <ul>
   <li>Creation of GC-safe points within code where collection is allowed to
       execute safely.</li>
-  <li>Definition of a stack frame descriptor. For each safe point in the code,
-      a frame descriptor maps where object references are located within the
-      frame so that the GC may traverse and perhaps update them.</li>
-  <li>Write barriers when storing object references within the heap. These
-      are commonly used to optimize incremental scans.</li>
+  <li>Computation of the stack map. For each safe point in the code, object
+      references within the stack frame must be identified so that the
+      collector may traverse and perhaps update them.</li>
+  <li>Write barriers when storing object references to the heap. These are
+      commonly used to optimize incremental scans in generational
+      collectors.</li>
   <li>Emission of read barriers when loading object references. These are
       useful for interoperating with concurrent collectors.</li>
 </ul>
@@ -178,10 +177,13 @@ concerned are:</p>
 <p>There are additional areas that LLVM does not directly address:</p>
 
 <ul>
-  <li>Registration of global roots.</li>
-  <li>Discovery or registration of stack frame descriptors.</li>
+  <li>Registration of global roots with the runtime.</li>
+  <li>Registration of stack map entries with the runtime.</li>
   <li>The functions used by the program to allocate memory, trigger a
       collection, etc.</li>
+  <li>Computation or compilation of type maps, or registration of them with
+      the runtime. These are used to crawl the heap for object
+      references.</li>
 </ul>
 
 <p>In general, LLVM's support for GC does not include features which can be
@@ -194,13 +196,15 @@ compiler matures.</p>
 
 </div>
 
+</div>
+
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="quickstart">Getting started</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p>Using a GC with LLVM implies many things, for example:</p>
 
@@ -208,11 +212,11 @@ compiler matures.</p>
   <li>Write a runtime library or find an existing one which implements a GC
       heap.<ol>
     <li>Implement a memory allocator.</li>
-    <li>Design a binary interface for frame descriptors, used to identify
-        references within a stack frame.*</li>
+    <li>Design a binary interface for the stack map, used to identify
+        references within a stack frame on the machine stack.*</li>
     <li>Implement a stack crawler to discover functions on the call stack.*</li>
     <li>Implement a registry for global roots.</li>
-    <li>Design a binary interface for type descriptors, used to map references
+    <li>Design a binary interface for type maps, used to identify references
         within heap objects.</li>
     <li>Implement a collection routine bringing together all of the above.</li>
   </ol></li>
@@ -225,12 +229,13 @@ compiler matures.</p>
         manipulate GC references, if necessary.</li>
     <li>Allocate memory using the GC allocation routine provided by the
         runtime library.</li>
-    <li>Generate type descriptors according to your runtime's binary interface.</li>
+    <li>Generate type maps according to your runtime's binary interface.</li>
   </ul></li>
   <li>Write a compiler plugin to interface LLVM with the runtime library.*<ul>
     <li>Lower <tt>@llvm.gcread</tt> and <tt>@llvm.gcwrite</tt> to appropriate
         code sequences.*</li>
-    <li>Generate stack maps according to the runtime's binary interface.*</li>
+    <li>Compile LLVM's stack map to the binary form expected by the
+        runtime.</li>
   </ul></li>
   <li>Load the plugin into the compiler. Use <tt>llc -load</tt> or link the
       plugin statically with your language's compiler.*</li>
@@ -241,14 +246,12 @@ compiler matures.</p>
 includes a highly portable, built-in ShadowStack code generator. It is compiled
 into <tt>llc</tt> and works even with the interpreter and C backends.</p>
 
-</div>
-
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="quickstart-compiler">In your compiler</a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <p>To turn the shadow stack on for your functions, first call:</p>
 
@@ -271,11 +274,11 @@ switching to a more advanced GC.</p>
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="quickstart-runtime">In your runtime</a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <p>The shadow stack doesn't imply a memory allocation algorithm. A semispace
 collector or building atop <tt>malloc</tt> are great places to start, and can
@@ -287,17 +290,15 @@ doing so is very simple. (This code is heavily commented to help you
 understand the data structure, but there are only 20 lines of meaningful
 code.)</p>
 
-</div>
-
-<div class="doc_code"><pre
->/// @brief A constant shadow stack frame descriptor. The compiler emits one of
-///        these for each function.
+<pre class="doc_code">
+/// @brief The map for a single function's stack frame. One of these is
+///        compiled as constant data into the executable for each function.
 /// 
-/// Storage of metadata values is elided if the %meta parameter to @llvm.gcroot
-/// is null.
+/// Storage of metadata values is elided if the %metadata parameter to
+/// @llvm.gcroot is null.
 struct FrameMap {
   int32_t NumRoots;    //&lt; Number of roots in stack frame.
-  int32_t NumMeta;     //&lt; Number of metadata descriptors. May be &lt; NumRoots.
+  int32_t NumMeta;     //&lt; Number of metadata entries. May be &lt; NumRoots.
   const void *Meta[0]; //&lt; Metadata for each root.
 };
 
@@ -329,27 +330,31 @@ void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) {
     
     // For roots [0, NumMeta), the metadata pointer is in the FrameMap.
     for (unsigned e = R->Map->NumMeta; i != e; ++i)
-      Visitor(&R->Roots[i], R->Map->Meta[i]);
+      Visitor(&amp;R->Roots[i], R->Map->Meta[i]);
     
     // For roots [NumMeta, NumRoots), the metadata pointer is null.
     for (unsigned e = R->Map->NumRoots; i != e; ++i)
-      Visitor(&R->Roots[i], NULL);
+      Visitor(&amp;R->Roots[i], NULL);
   }
-}</pre></div>
+}</pre>
+
+</div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="shadow-stack">About the shadow stack</a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <p>Unlike many GC algorithms which rely on a cooperative code generator to
-generate stack maps, this algorithm carefully maintains a linked list of stack
-root descriptors [<a href="#henderson02">Henderson2002</a>]. This so-called
-"shadow stack" mirrors the machine stack. Maintaining this data structure is
-slower than using stack maps, but has a significant portability advantage
-because it requires no special support from the target code generator.</p>
+compile stack maps, this algorithm carefully maintains a linked list of stack
+roots [<a href="#henderson02">Henderson2002</a>]. This so-called "shadow stack"
+mirrors the machine stack. Maintaining this data structure is slower than using
+a stack map compiled into the executable as constant data, but has a significant
+portability advantage because it requires no special support from the target
+code generator, and does not require tricky platform-specific code to crawl
+the machine stack.</p>
 
 <p>The tradeoff for this simplicity and portability is:</p>
 
@@ -358,17 +363,22 @@ because it requires no special support from the target code generator.</p>
   <li>Not thread-safe.</li>
 </ul>
 
-<p>Still, it's an easy way to get started.</p>
+<p>Still, it's an easy way to get started. After your compiler and runtime are
+up and running, writing a <a href="#plugin">plugin</a> will allow you to take
+advantage of <a href="#collector-algos">more advanced GC features</a> of LLVM
+in order to improve performance.</p>
+
+</div>
 
 </div>
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="core">IR features</a><a name="intrinsics"></a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p>This section describes the garbage collection facilities provided by the
 <a href="LangRef.html">LLVM intermediate representation</a>. The exact behavior
@@ -380,19 +390,17 @@ intended to be a complete interface to any garbage collector. A program will
 need to interface with the GC library using the facilities provided by that
 program.</p>
 
-</div>
-
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a>
-</div>
+</h3>
+
+<div>
 
 <div class="doc_code"><tt>
-  define <i>ty</i> @<i>name</i>(...) <u>gc "<i>name</i>"</u> { ...
+  define <i>ty</i> @<i>name</i>(...) <span style="text-decoration: underline">gc "<i>name</i>"</span> { ...
 </tt></div>
 
-<div class="doc_text">
-
 <p>The <tt>gc</tt> function attribute is used to specify the desired GC style
 to the compiler. Its programmatic equivalent is the <tt>setGC</tt> method of
 <tt>Function</tt>.</p>
@@ -408,20 +416,21 @@ programs that use different garbage collection algorithms (or none at all).</p>
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="gcroot">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a>
-</div>
+</h3>
+
+<div>
 
 <div class="doc_code"><tt>
   void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
 </tt></div>
 
-<div class="doc_text">
-
 <p>The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM that a stack
 variable references an object on the heap and is to be tracked for garbage
 collection. The exact impact on generated code is specified by a <a
-href="#plugin">compiler plugin</a>.</p>
+href="#plugin">compiler plugin</a>. All calls to <tt>llvm.gcroot</tt> <b>must</b> reside
+ inside the first basic block.</p>
 
 <p>A compiler which uses mem2reg to raise imperative code using <tt>alloca</tt>
 into SSA form need only add a call to <tt>@llvm.gcroot</tt> for those variables
@@ -429,7 +438,9 @@ which a pointers into the GC heap.</p>
 
 <p>It is also important to mark intermediate values with <tt>llvm.gcroot</tt>.
 For example, consider <tt>h(f(), g())</tt>. Beware leaking the result of
-<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection.</p>
+<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection. Note, that
+stack variables must be initialized and marked with <tt>llvm.gcroot</tt> in
+function's prologue.</p>
 
 <p>The first argument <b>must</b> be a value referring to an alloca instruction
 or a bitcast of an alloca. The second contains a pointer to metadata that
@@ -445,7 +456,7 @@ the stack frame.</p>
 
 <p>Consider the following fragment of Java code:</p>
 
-<pre>
+<pre class="doc_code">
        {
          Object X;   // A null-initialized reference to an object
          ...
@@ -455,7 +466,7 @@ the stack frame.</p>
 <p>This block (which may be located in the middle of a function or in a loop
 nest), could be compiled to this LLVM code:</p>
 
-<pre>
+<pre class="doc_code">
 Entry:
    ;; In the entry block for the function, allocate the
    ;; stack space for X, which is an LLVM pointer.
@@ -464,7 +475,7 @@ Entry:
    ;; Tell LLVM that the stack space is a stack root.
    ;; Java has type-tags on objects, so we pass null as metadata.
    %tmp = bitcast %Object** %X to i8**
-   call void @llvm.gcroot(i8** %X, i8* null)
+   call void @llvm.gcroot(i8** %tmp, i8* null)
    ...
 
    ;; "CodeBlock" is the block corresponding to the start
@@ -484,11 +495,11 @@ CodeBlock:
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="barriers">Reading and writing references in the heap</a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <p>Some collectors need to be informed when the mutator (the program that needs
 garbage collection) either reads a pointer from or writes a pointer to a field
@@ -515,24 +526,26 @@ for completeness. In this snippet, <tt>%object</tt> is the object pointer, and
     ;; Compute the derived pointer.
     %derived = getelementptr %object, i32 0, i32 2, i32 %n</pre></blockquote>
 
-<p>The use of these intrinsics is naturally optional if the target GC does
-require the corresponding barrier. If so, the GC plugin will replace the
-intrinsic calls with the corresponding <tt>load</tt> or <tt>store</tt>
-instruction if they are used.</p>
+<p>LLVM does not enforce this relationship between the object and derived
+pointer (although a <a href="#plugin">plugin</a> might). However, it would be
+an unusual collector that violated it.</p>
 
-</div>
+<p>The use of these intrinsics is naturally optional if the target GC does
+require the corresponding barrier. Such a GC plugin will replace the intrinsic
+calls with the corresponding <tt>load</tt> or <tt>store</tt> instruction if they
+are used.</p>
 
 <!-- ======================================================================= -->
-<div class="doc_subsubsection">
+<h4>
   <a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a>
-</div>
+</h4>
+
+<div>
 
 <div class="doc_code"><tt>
 void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)
 </tt></div>
 
-<div class="doc_text">
-
 <p>For write barriers, LLVM provides the <tt>llvm.gcwrite</tt> intrinsic
 function. It has exactly the same semantics as a non-volatile <tt>store</tt> to
 the derived pointer (the third argument). The exact code generated is specified
@@ -545,16 +558,16 @@ implement reference counting.</p>
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsubsection">
+<h4>
   <a name="gcread">Read barrier: <tt>llvm.gcread</tt></a>
-</div>
+</h4>
+
+<div>
 
 <div class="doc_code"><tt>
 i8* @llvm.gcread(i8* %object, i8** %derived)<br>
 </tt></div>
 
-<div class="doc_text">
-
 <p>For read barriers, LLVM provides the <tt>llvm.gcread</tt> intrinsic function.
 It has exactly the same semantics as a non-volatile <tt>load</tt> from the
 derived pointer (the second argument). The exact code generated is specified by
@@ -566,13 +579,17 @@ writes.</p>
 
 </div>
 
+</div>
+
+</div>
+
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="plugin">Implementing a collector plugin</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p>User code specifies which GC code generation to use with the <tt>gc</tt>
 function attribute or, equivalently, with the <tt>setGC</tt> method of
@@ -581,15 +598,16 @@ function attribute or, equivalently, with the <tt>setGC</tt> method of
 <p>To implement a GC plugin, it is necessary to subclass
 <tt>llvm::GCStrategy</tt>, which can be accomplished in a few lines of
 boilerplate code. LLVM's infrastructure provides access to several important
-algorithms. For an uncontroversial collector, all that remains may be to emit
-the assembly code for the collector's unique stack map data structure, which
-might be accomplished in as few as 100 LOC.</p>
+algorithms. For an uncontroversial collector, all that remains may be to
+compile LLVM's computed stack map to assembly code (using the binary
+representation expected by the runtime library). This can be accomplished in
+about 100 lines of code.</p>
 
 <p>This is not the appropriate place to implement a garbage collected heap or a
 garbage collector itself. That code should exist in the language's runtime
 library. The compiler plugin is responsible for generating code which
 conforms to the binary interface defined by library, most essentially the
-<a href="stack-map">stack map</a>.</p>
+<a href="#stack-map">stack map</a>.</p>
 
 <p>To subclass <tt>llvm::GCStrategy</tt> and register it with the compiler:</p>
 
@@ -602,7 +620,7 @@ conforms to the binary interface defined by library, most essentially the
 using namespace llvm;
 
 namespace {
-  class VISIBILITY_HIDDEN MyGC : public GCStrategy {
+  class LLVM_LIBRARY_VISIBILITY MyGC : public GCStrategy {
   public:
     MyGC() {}
   };
@@ -611,9 +629,21 @@ namespace {
   X("mygc", "My bespoke garbage collector.");
 }</pre></blockquote>
 
+<p>This boilerplate collector does nothing. More specifically:</p>
+
+<ul>
+  <li><tt>llvm.gcread</tt> calls are replaced with the corresponding
+      <tt>load</tt> instruction.</li>
+  <li><tt>llvm.gcwrite</tt> calls are replaced with the corresponding
+      <tt>store</tt> instruction.</li>
+  <li>No safe points are added to the code.</li>
+  <li>The stack map is not compiled into the executable.</li>
+</ul>
+
 <p>Using the LLVM makefiles (like the <a
 href="http://llvm.org/viewvc/llvm-project/llvm/trunk/projects/sample/">sample
-project</a>), this can be built into a plugin using a simple makefile:</p>
+project</a>), this code can be compiled as a plugin using a simple
+makefile:</p>
 
 <blockquote><pre
 ># lib/MyGC/Makefile
@@ -639,29 +669,18 @@ $ llvm-as &lt; sample.ll | llc -load=MyGC.so</pre></blockquote>
 <p>It is also possible to statically link the collector plugin into tools, such
 as a language-specific compiler front-end.</p>
 
-</div>
-
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="collector-algos">Overview of available features</a>
-</div>
-
-<div class="doc_text">
+</h3>
 
-<p>The boilerplate collector above does nothing. More specifically:</p>
-
-<ul>
-  <li><tt>llvm.gcread</tt> calls are replaced with the corresponding
-      <tt>load</tt> instruction.</li>
-  <li><tt>llvm.gcwrite</tt> calls are replaced with the corresponding
-      <tt>store</tt> instruction.</li>
-  <li>No stack map is emitted, and no safe points are added.</li>
-</ul>
+<div>
 
-<p><tt>Collector</tt> provides a range of features through which a plugin
-collector may do useful work. This matrix summarizes the supported (and planned)
-features and correlates them with the collection techniques which typically
-require them.</p>
+<p><tt>GCStrategy</tt> provides a range of features through which a plugin
+may do useful work. Some of these are callbacks, some are algorithms that can
+be enabled, disabled, or customized. This matrix summarizes the supported (and
+planned) features and correlates them with the collection techniques which
+typically require them.</p>
 
 <table>
   <tr>
@@ -898,8 +917,7 @@ require them.</p>
 
 <dl>
   <dt>Shadow Stack</dt>
-  <dd>The mutator carefully maintains a linked list of stack root
-      descriptors.</dd>
+  <dd>The mutator carefully maintains a linked list of stack roots.</dd>
   <dt>Reference Counting</dt>
   <dd>The mutator maintains a reference count for each object and frees an
       object when its count falls to zero.</dd>
@@ -941,11 +959,38 @@ interest.</p>
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="stack-map">Computing stack maps</a>
-</div>
+</h3>
+
+<div>
+
+<p>LLVM automatically computes a stack map. One of the most important features
+of a <tt>GCStrategy</tt> is to compile this information into the executable in
+the binary representation expected by the runtime library.</p>
+
+<p>The stack map consists of the location and identity of each GC root in the
+each function in the module. For each root:</p>
+
+<ul>
+  <li><tt>RootNum</tt>: The index of the root.</li>
+  <li><tt>StackOffset</tt>: The offset of the object relative to the frame
+      pointer.</li>
+  <li><tt>RootMetadata</tt>: The value passed as the <tt>%metadata</tt>
+      parameter to the <a href="#gcroot"><tt>@llvm.gcroot</tt></a> intrinsic.</li>
+</ul>
+
+<p>Also, for the function as a whole:</p>
 
-<div class="doc_text">
+<ul>
+  <li><tt>getFrameSize()</tt>: The overall size of the function's initial
+      stack frame, not accounting for any dynamic allocation.</li>
+  <li><tt>roots_size()</tt>: The count of roots in the function.</li>
+</ul>
+
+<p>To access the stack map, use <tt>GCFunctionMetadata::roots_begin()</tt> and
+-<tt>end()</tt> from the <tt><a
+href="#assembly">GCMetadataPrinter</a></tt>:</p>
 
 <blockquote><pre
 >for (iterator I = begin(), E = end(); I != E; ++I) {
@@ -962,20 +1007,19 @@ interest.</p>
   }
 }</pre></blockquote>
 
-<p>LLVM automatically computes a stack map. All a <tt>GCStrategy</tt> needs to do
-is access it using <tt>GCFunctionMetadata::roots_begin()</tt> and
--<tt>end()</tt>. If the <tt>llvm.gcroot</tt> intrinsic is eliminated before code
-generation by a custom lowering pass, LLVM's stack map will be empty.</p>
+<p>If the <tt>llvm.gcroot</tt> intrinsic is eliminated before code generation by
+a custom lowering pass, LLVM will compute an empty stack map. This may be useful
+for collector plugins which implement reference counting or a shadow stack.</p>
 
 </div>
 
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="init-roots">Initializing roots to null: <tt>InitRoots</tt></a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <blockquote><pre
 >MyGC::MyGC() {
@@ -996,12 +1040,12 @@ this feature should be used by all GC plugins. It is enabled by default.</p>
 
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="custom">Custom lowering of intrinsics: <tt>CustomRoots</tt>, 
     <tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <p>For GCs which use barriers or unusual treatment of stack roots, these
 flags allow the collector to perform arbitrary transformations of the LLVM
@@ -1027,8 +1071,8 @@ the corresponding intrinsics and instead calls
 <p>LLVM's default action for each intrinsic is as follows:</p>
 
 <ul>
-  <li><tt>llvm.gcroot</tt>: Pass through to the code generator to generate a
-                            stack map.</li>
+  <li><tt>llvm.gcroot</tt>: Leave it alone. The code generator must see it
+                            or the stack map will not be computed.</li>
   <li><tt>llvm.gcread</tt>: Substitute a <tt>load</tt> instruction.</li>
   <li><tt>llvm.gcwrite</tt>: Substitute a <tt>store</tt> instruction.</li>
 </ul>
@@ -1086,11 +1130,11 @@ bool MyGC::performCustomLowering(Function &amp;F) {
 
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="safe-points">Generating safe points: <tt>NeededSafePoints</tt></a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <p>LLVM can compute four kinds of safe points:</p>
 
@@ -1150,15 +1194,15 @@ safe point (because only the topmost function has been patched).</p>
 
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="assembly">Emitting assembly code: <tt>GCMetadataPrinter</tt></a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
-<p>LLVM allows a GC to print arbitrary assembly code before and after the rest
-of a module's assembly code. At the end of the module, the GC can print stack
-maps built by the code generator. (At the beginning, this information is not
+<p>LLVM allows a plugin to print arbitrary assembly code before and after the
+rest of a module's assembly code. At the end of the module, the GC can compile
+the LLVM stack map into assembly code. (At the beginning, this information is not
 yet computed.)</p>
 
 <p>Since AsmWriter and CodeGen are separate components of LLVM, a separate
@@ -1172,6 +1216,8 @@ will look for such a subclass if the <tt>GCStrategy</tt> sets
   UsesMetadata = true;
 }</pre></blockquote>
 
+<p>This separation allows JIT-only clients to be smaller.</p>
+
 <p>Note that LLVM does not currently have analogous APIs to support code
 generation in the JIT, nor using the object writers.</p>
 
@@ -1184,7 +1230,7 @@ generation in the JIT, nor using the object writers.</p>
 using namespace llvm;
 
 namespace {
-  class VISIBILITY_HIDDEN MyGCPrinter : public GCMetadataPrinter {
+  class LLVM_LIBRARY_VISIBILITY MyGCPrinter : public GCMetadataPrinter {
   public:
     virtual void beginAssembly(std::ostream &amp;OS, AsmPrinter &amp;AP,
                                const TargetAsmInfo &amp;TAI);
@@ -1207,7 +1253,7 @@ methods. Here's a realistic example:</p>
 >#include "llvm/CodeGen/AsmPrinter.h"
 #include "llvm/Function.h"
 #include "llvm/Target/TargetMachine.h"
-#include "llvm/Target/TargetData.h"
+#include "llvm/DataLayout.h"
 #include "llvm/Target/TargetAsmInfo.h"
 
 void MyGCPrinter::beginAssembly(std::ostream &amp;OS, AsmPrinter &amp;AP,
@@ -1220,7 +1266,7 @@ void MyGCPrinter::finishAssembly(std::ostream &amp;OS, AsmPrinter &amp;AP,
   // Set up for emitting addresses.
   const char *AddressDirective;
   int AddressAlignLog;
-  if (AP.TM.getTargetData()->getPointerSize() == sizeof(int32_t)) {
+  if (AP.TM.getDataLayout()->getPointerSize() == sizeof(int32_t)) {
     AddressDirective = TAI.getData32bitsDirective();
     AddressAlignLog = 2;
   } else {
@@ -1249,7 +1295,7 @@ void MyGCPrinter::finishAssembly(std::ostream &amp;OS, AsmPrinter &amp;AP,
     // Align to address width.
     AP.EmitAlignment(AddressAlignLog);
     
-    // Emit the symbol by which the stack map can be found.
+    // Emit the symbol by which the stack map entry can be found.
     std::string Symbol;
     Symbol += TAI.getGlobalPrefix();
     Symbol += "__gcmap_";
@@ -1296,14 +1342,15 @@ void MyGCPrinter::finishAssembly(std::ostream &amp;OS, AsmPrinter &amp;AP,
 
 </div>
 
+</div>
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="references">References</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p><a name="appel89">[Appel89]</a> Runtime Tags Aren't Necessary. Andrew
 W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.</p>
@@ -1334,7 +1381,7 @@ Fergus Henderson. International Symposium on Memory Management 2002.</p>
   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
 
   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
-  <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+  <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
   Last modified: $Date$
 </address>