</ul>
</li>
- <li><a href="#intrinsics">Collection intrinsics</a>
+ <li><a href="#core">Core support</a>
<ul>
+ <li><a href="#gcattr">Specifying GC code generation:
+ <tt>gc "..."</tt></a></li>
<li><a href="#gcroot">Identifying GC roots on the stack:
<tt>llvm.gcroot</tt></a></li>
<li><a href="#barriers">Reading and writing references in the heap</a>
<div class="doc_text">
<p>LLVM's intermediate representation provides <a href="#intrinsics">garbage
-collection intrinsics</a> which offer support for a broad class of
+collection intrinsics</a> that offer support for a broad class of
collector models. For instance, the intrinsics permit:</p>
<ul>
<ul>
<li>Emitting compatible code, including initialization in the main
- program.</li>
+ program if necessary.</li>
<li>Loading a compiler plugin if the collector is not statically linked with
your compiler. For <tt>llc</tt>, use the <tt>-load</tt> option.</li>
- <li>Selecting the collection algorithm with <tt>llc -gc=</tt> or by setting
- <tt>llvm::TheCollector</tt>.</li>
+ <li>Selecting the collection algorithm by applying the <tt>gc "..."</tt>
+ attribute to your garbage collected functions, or equivalently with
+ the <tt>setCollector</tt> method.</li>
<li>Linking your final executable with the garbage collector runtime.</li>
</ul>
<table>
<tr>
<th>Collector</th>
- <th><tt>llc</tt> arguments</th>
+ <th><tt>gc</tt> attribute</th>
<th>Linkage</th>
<th><tt>gcroot</tt></th>
<th><tt>gcread</tt></th>
</tr>
<tr valign="baseline">
<td><a href="#semispace">SemiSpace</a></td>
- <td><tt>-gc=shadow-stack</tt></td>
+ <td><tt>gc "shadow-stack"</tt></td>
<td>TODO FIXME</td>
<td>required</td>
<td>optional</td>
</tr>
<tr valign="baseline">
<td><a href="#ocaml">Ocaml</a></td>
- <td><tt>-gc=ocaml</tt></td>
+ <td><tt>gc "ocaml"</tt></td>
<td><i>provided by ocamlopt</i></td>
<td>required</td>
<td>optional</td>
<div class="doc_text">
-<p>The ShadowStack collector is invoked with <tt>llc -gc=shadow-stack</tt>.
+<p>The ShadowStack backend is invoked with the <tt>gc "shadow-stack"</tt>
+function attribute.
Unlike many collectors 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
+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>
program may use <tt>load</tt> and <tt>store</tt> instead of <tt>llvm.gcread</tt>
and <tt>llvm.gcwrite</tt>.</p>
-<p>The ShadowStack collector is a compiler plugin only. It must be paired with a
+<p>ShadowStack is a code generator plugin only. It must be paired with a
compatible runtime.</p>
</div>
<div class="doc_text">
-<p>The SemiSpace runtime implements with the <a href="runtime">suggested
-runtime interface</a> and is compatible the ShadowStack collector's code
-generation.</p>
+<p>The SemiSpace runtime implements the <a href="runtime">suggested
+runtime interface</a> and is compatible with the ShadowStack backend.</p>
<p>SemiSpace is a very simple copying collector. When it starts up, it
allocates two blocks of memory for the heap. It uses a simple bump-pointer
<div class="doc_text">
-<p>The ocaml collector is invoked with <tt>llc -gc=ocaml</tt>. It supports the
+<p>The ocaml backend is invoked with the <tt>gc "ocaml"</tt> function attribute.
+It supports the
<a href="http://caml.inria.fr/">Objective Caml</a> language runtime by emitting
a type-accurate stack map in the form of an ocaml 3.10.0-compatible frametable.
The linkage requirements are satisfied automatically by the <tt>ocamlopt</tt>
<!-- *********************************************************************** -->
<div class="doc_section">
- <a name="intrinsics">Collection intrinsics</a>
+ <a name="core">Core support</a><a name="intrinsics"></a>
</div>
<!-- *********************************************************************** -->
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a>
+</div>
+
+<div class="doc_code"><tt>
+ define <i>ty</i> @<i>name</i>(...) <u>gc "<i>collector</i>"</u> { ...
+</tt></div>
+
+<div class="doc_text">
+
+<p>The <tt>gc</tt> function attribute is used to specify the desired collector
+algorithm to the compiler. It is equivalent to specifying the collector name
+programmatically using the <tt>setCollector</tt> method of
+<tt>Function</tt>.</p>
+
+<p>Specifying the collector on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms.</p>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="gcroot">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a>
</div>
<div class="doc_code"><tt>
- void %llvm.gcroot(i8** %ptrloc, i8* %metadata)
+ 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 of a pointer
-variable on the stack. The first argument <b>must</b> be an alloca instruction
+variable on the stack. 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
should be associated with the pointer, and <b>must</b> be a constant or global
value address. If your target collector uses tags, use a null pointer for
;; 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** %X, i8* null)
...
;; "CodeBlock" is the block corresponding to the start
for completeness. In this snippet, <tt>%object</tt> is the object pointer, and
<tt>%derived</tt> is the derived pointer:</p>
-<blockquote><pre
-> ;; An array type.
+<blockquote><pre>
+ ;; An array type.
%class.Array = type { %class.Object, i32, [0 x %class.Object*] }
-...
+ ...
;; Load the object pointer from a gcroot.
%object = load %class.Array** %object_addr
;; Compute the derived pointer.
- %derived = getelementptr %obj, i32 0, i32 2, i32 %n</pre></blockquote>
+ %derived = getelementptr %object, i32 0, i32 2, i32 %n</pre></blockquote>
</div>
generator that iterates through all of the GC roots on the stack, calling the
specified function pointer with each record. For each GC root, the address of
the pointer and the meta-data (from the <a
-href="#roots"><tt>llvm.gcroot</tt></a> intrinsic) are provided.
+href="#gcroot"><tt>llvm.gcroot</tt></a> intrinsic) are provided.
</p>
</div>
<div class="doc_text">
+<p>User code specifies which collector plugin to use with the <tt>gc</tt>
+function attribute or, equivalently, with the <tt>setCollector</tt> method of
+<tt>Function</tt>.</p>
+
<p>To implement a collector plugin, it is necessary to subclass
<tt>llvm::Collector</tt>, which can be accomplished in a few lines of
boilerplate code. LLVM's infrastructure provides access to several important
};
CollectorRegistry::Add<MyCollector>
- X("mygc", "My custom garbage collector.");
+ X("mygc", "My bespoke garbage collector.");
}</pre></blockquote>
<p>Using the LLVM makefiles (like the <a
include $(LEVEL)/Makefile.common</pre></blockquote>
-<blockquote><pre
-></pre></blockquote>
-
-<p>Once the plugin is compiled, user code may be compiled using <tt>llc
--load=<var>MyGC.so</var> -gc=mygc</tt> (though <var>MyGC.so</var> may have some
-other platform-specific extension).</p>
-
-<!-- BEGIN FIXME: Gross -->
-<p>To use a collector in a tool other than <tt>llc</tt>, simply assign a
-<tt>Collector</tt> to the <tt>llvm::TheCollector</tt> variable:</p>
+<p>Once the plugin is compiled, code using it may be compiled using <tt>llc
+-load=<var>MyGC.so</var></tt> (though <var>MyGC.so</var> may have some other
+platform-specific extension):</p>
<blockquote><pre
->TheCollector = new MyGC();</pre></blockquote>
-<!-- /FIXME GROSS -->
+>$ cat sample.ll
+define void @f() gc "mygc" {
+entry:
+ ret void
+}
+$ llvm-as < 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_text">
<blockquote><pre
->CollectorMetadata &MD = ...;
-unsigned FrameSize = MD.getFrameSize();
-size_t RootCount = MD.roots_size();
-
-for (CollectorMetadata::roots_iterator RI = MD.roots_begin(),
- RE = MD.roots_end(); RI != RE; ++RI) {
- int RootNum = RI->Num;
- int RootStackOffset = RI->StackOffset;
- Constant *RootMetadata = RI->Metadata;
+>for (iterator I = begin(), E = end(); I != E; ++I) {
+ CollectorMetadata *MD = *I;
+ unsigned FrameSize = MD->getFrameSize();
+ size_t RootCount = MD->roots_size();
+
+ for (CollectorMetadata::roots_iterator RI = MD->roots_begin(),
+ RE = MD->roots_end();
+ RI != RE; ++RI) {
+ int RootNum = RI->Num;
+ int RootStackOffset = RI->StackOffset;
+ Constant *RootMetadata = RI->Metadata;
+ }
}</pre></blockquote>
<p>LLVM automatically computes a stack map. All a <tt>Collector</tt> needs to do
CustomWriteBarriers = true;
}
-protected:
- virtual Pass *createCustomLoweringPass() const {
- return new MyGCLoweringFunctionPass();
- }
+ virtual bool initializeCustomLowering(Module &M);
+ virtual bool performCustomLowering(Function &F);
};</pre></blockquote>
<p>If any of these flags are set, then LLVM suppresses its default lowering for
</ul>
<p>If <tt>CustomReadBarriers</tt> or <tt>CustomWriteBarriers</tt> are specified,
-the custom lowering pass <strong>must</strong> eliminate the corresponding
-barriers.</p>
+then <tt>performCustomLowering</tt> <strong>must</strong> eliminate the
+corresponding barriers.</p>
+
+<p><tt>performCustomLowering</tt>, must comply with the same restrictions as <a
+href="WritingAnLLVMPass.html#runOnFunction"><tt>runOnFunction</tt></a>, and
+that <tt>initializeCustomLowering</tt> has the same semantics as <a
+href="WritingAnLLVMPass.html#doInitialization_mod"><tt>doInitialization(Module
+&)</tt></a>.</p>
-<p>This template can be used as a starting point for a lowering pass:</p>
+<p>The following can be used as a template:</p>
<blockquote><pre
->#include "llvm/Function.h"
-#include "llvm/Module.h"
-#include "llvm/Instructions.h"
+>#include "llvm/Module.h"
+#include "llvm/IntrinsicInst.h"
-namespace {
- class VISIBILITY_HIDDEN MyGCLoweringFunctionPass : public FunctionPass {
- static char ID;
- public:
- MyGCLoweringFunctionPass() : FunctionPass(intptr_t(&ID)) {}
-
- const char *getPassName() const { return "Lower GC Intrinsics"; }
-
- bool runOnFunction(Function &F) {
- Module *M = F.getParent();
-
- Function *GCReadInt = M->getFunction("llvm.gcread"),
- *GCWriteInt = M->getFunction("llvm.gcwrite"),
- *GCRootInt = M->getFunction("llvm.gcroot");
-
- bool MadeChange = false;
-
- for (Function::iterator BB = F.begin(), E = F.end(); BB != E; ++BB)
- for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E;)
- if (CallInst *CI = dyn_cast<CallInst>(II++))
- if (Function *F = CI->getCalledFunction())
- if (F == GCWriteInt) {
- // Handle llvm.gcwrite.
- CI->eraseFromParent();
- MadeChange = true;
- } else if (F == GCReadInt) {
- // Handle llvm.gcread.
- CI->eraseFromParent();
- MadeChange = true;
- } else if (F == GCRootInt) {
- // Handle llvm.gcroot.
- CI->eraseFromParent();
- MadeChange = true;
- }
-
- return MadeChange;
- }
- };
+bool MyCollector::initializeCustomLowering(Module &M) {
+ return false;
+}
- char MyGCLoweringFunctionPass::ID = 0;
+bool MyCollector::performCustomLowering(Function &F) {
+ bool MadeChange = false;
+
+ for (Function::iterator BB = F.begin(), E = F.end(); BB != E; ++BB)
+ for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; )
+ if (IntrinsicInst *CI = dyn_cast<IntrinsicInst>(II++))
+ if (Function *F = CI->getCalledFunction())
+ switch (F->getIntrinsicID()) {
+ case Intrinsic::gcwrite:
+ // Handle llvm.gcwrite.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcread:
+ // Handle llvm.gcread.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcroot:
+ // Handle llvm.gcroot.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ }
+
+ return MadeChange;
}</pre></blockquote>
</div>
<p>It can then use the following routines to access safe points.</p>
-<blockquote><pre>
-CollectorMetadata &MD = ...;
-size_t PointCount = MD.size();
-
-for (CollectorMetadata::iterator PI = MD.begin(),
- PE = MD.end(); PI != PE; ++PI) {
- GC::PointKind PointKind = PI->Kind;
- unsigned PointNum = PI->Num;
-}</pre></blockquote>
+<blockquote><pre
+>for (iterator I = begin(), E = end(); I != E; ++I) {
+ CollectorMetadata *MD = *I;
+ size_t PointCount = MD->size();
+
+ for (CollectorMetadata::iterator PI = MD->begin(),
+ PE = MD->end(); PI != PE; ++PI) {
+ GC::PointKind PointKind = PI->Kind;
+ unsigned PointNum = PI->Num;
+ }
+}
+</pre></blockquote>
<p>Almost every collector requires <tt>PostCall</tt> safe points, since these
correspond to the moments when the function is suspended during a call to a
<p>LLVM allows a collector to print arbitrary assembly code before and after
the rest of a module's assembly code. From the latter callback, the collector
-can print stack maps from <tt>CollectorModuleMetadata</tt> populated by the code
-generator.</p>
+can print stack maps built by the code generator.</p>
-<p>Note that LLVM does not currently support garbage collection code generation
-in the JIT, nor using the object writers.</p>
+<p>Note that LLVM does not currently have analogous APIs to support code
+generation in the JIT, nor using the object writers.</p>
<blockquote><pre
>class MyCollector : public Collector {
- virtual void beginAssembly(Module &M, std::ostream &OS, AsmPrinter &AP,
- const TargetAsmInfo &TAI) const;
+public:
+ virtual void beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
- virtual void finishAssembly(Module &M, CollectorModuleMetadata &MMD,
- std::ostream &OS, AsmPrinter &AP,
- const TargetAsmInfo &TAI) const;
+ virtual void finishAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
}</pre></blockquote>
<p>The collector should use <tt>AsmPrinter</tt> and <tt>TargetAsmInfo</tt> to
-print portable assembly code to the <tt>std::ostream</tt>. The collector may
-access the stack maps for the entire module using the methods of
-<tt>CollectorModuleMetadata</tt>. Here's a realistic example:</p>
+print portable assembly code to the <tt>std::ostream</tt>. The collector itself
+contains the stack map for the entire module, and may access the
+<tt>CollectorMetadata</tt> using its own <tt>begin()</tt> and <tt>end()</tt>
+methods. Here's a realistic example:</p>
<blockquote><pre
>#include "llvm/CodeGen/AsmPrinter.h"
#include "llvm/Function.h"
+#include "llvm/Target/TargetMachine.h"
+#include "llvm/Target/TargetData.h"
#include "llvm/Target/TargetAsmInfo.h"
-void MyCollector::finishAssembly(Module &M,
- CollectorModuleMetadata &MMD,
- std::ostream &OS, AsmPrinter &AP,
- const TargetAsmInfo &TAI) const {
+void MyCollector::beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI) {
+ // Nothing to do.
+}
+
+void MyCollector::finishAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI) {
// Set up for emitting addresses.
const char *AddressDirective;
int AddressAlignLog;
- if (TAI.getAddressSize() == sizeof(int32_t)) {
+ if (AP.TM.getTargetData()->getPointerSize() == sizeof(int32_t)) {
AddressDirective = TAI.getData32bitsDirective();
AddressAlignLog = 2;
} else {
AP.SwitchToDataSection(TAI.getDataSection());
// For each function...
- for (CollectorModuleMetadata::iterator FI = MMD.begin(),
- FE = MMD.end(); FI != FE; ++FI) {
+ for (iterator FI = begin(), FE = end(); FI != FE; ++FI) {
CollectorMetadata &MD = **FI;
// Emit this data structure:
<a href="#explicit"><tt>llvm_gc_collect</tt></a> functions. To do this, it will
probably have to <a href="#traceroots">trace through the roots
from the stack</a> and understand the <a href="#gcdescriptors">GC descriptors
-for heap objects</a>. Luckily, there are some <a href="#gcimpls">example
+for heap objects</a>. Luckily, there are some <a href="#usage">example
implementations</a> available.
</p>
</div>
<p>The LLVM garbage collectors are capable of supporting all of these styles of
language, including ones that mix various implementations. To do this, it
allows the source-language to associate meta-data with the <a
-href="#roots">stack roots</a>, and the heap tracing routines can propagate the
+href="#gcroot">stack roots</a>, and the heap tracing routines can propagate the
information. In addition, LLVM allows the front-end to extract GC information
in any form from a specific object pointer (this supports situations #1 and #3).
</p>
projects / oota-llvm.git / blobdiff