"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Writing an LLVM Pass</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<div class="doc_text">
-<p>First thing you need to do is create a new directory somewhere in the LLVM
-source base. For this example, we'll assume that you made
-"<tt>lib/Transforms/Hello</tt>". The first thing you must do is set up a build
-script (Makefile) that will compile the source code for the new pass. To do
-this, copy this into "<tt>Makefile</tt>":</p>
-
-<hr>
+ <p>First, you need to create a new directory somewhere in the LLVM source
+ base. For this example, we'll assume that you made
+ <tt>lib/Transforms/Hello</tt>. Next, you must set up a build script
+ (Makefile) that will compile the source code for the new pass. To do this,
+ copy the following into <tt>Makefile</tt>:</p>
+ <hr/>
<pre>
# Makefile for hello pass
LEVEL = ../../..
# Name of the library to build
-LIBRARYNAME = hello
+LIBRARYNAME = Hello
-# Build a dynamically loadable shared object
+# Build a dynamically linkable shared object
SHARED_LIBRARY = 1
+# Make the shared library become a loadable module so the tools can
+# dlopen/dlsym on the resulting library.
+LOADABLE_MODULE
+
# Include the makefile implementation stuff
include $(LEVEL)/Makefile.common
</pre>
<p>This makefile specifies that all of the <tt>.cpp</tt> files in the current
directory are to be compiled and linked together into a
-<tt>lib/Debug/libhello.so</tt> shared object that can be dynamically loaded by
-the <tt>opt</tt> or <tt>analyze</tt> tools. If your operating system uses a
-suffix other than .so (such as windows or Mac OS/X), the appropriate extension
-will be used.</p>
+<tt>Debug/lib/Hello.so</tt> shared object that can be dynamically loaded by
+the <tt>opt</tt> or <tt>analyze</tt> tools via their <tt>-load</tt> options.
+If your operating system uses a suffix other than .so (such as windows or
+Mac OS/X), the appropriate extension will be used.</p>
<p>Now that we have the build scripts set up, we just need to write the code for
the pass itself.</p>
<p>Now that it's all together, compile the file with a simple "<tt>gmake</tt>"
command in the local directory and you should get a new
-"<tt>lib/Debug/libhello.so</tt> file. Note that everything in this file is
+"<tt>Debug/lib/Hello.so</tt> file. Note that everything in this file is
contained in an anonymous namespace: this reflects the fact that passes are self
contained units that do not need external interfaces (although they can have
them) to be useful.</p>
work):</p>
<pre>
-$ opt -load ../../../lib/Debug/libhello.so -hello < hello.bc > /dev/null
+$ opt -load ../../../Debug/lib/Hello.so -hello < hello.bc > /dev/null
Hello: __main
Hello: puts
Hello: main
<tt>opt</tt> with the <tt>--help</tt> option:</p>
<pre>
-$ opt -load ../../../lib/Debug/libhello.so --help
+$ opt -load ../../../Debug/lib/Hello.so --help
OVERVIEW: llvm .bc -> .bc modular optimizer
USAGE: opt [options] <input bytecode>
example:</p>
<pre>
-$ opt -load ../../../lib/Debug/libhello.so -hello -time-passes < hello.bc > /dev/null
+$ opt -load ../../../Debug/lib/Hello.so -hello -time-passes < hello.bc > /dev/null
Hello: __main
Hello: puts
Hello: main
<li>Modify or inspect any basic blocks outside of the current one</li>
<li>Maintain state across invocations of
<a href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a></li>
-<li>Modify the constrol flow graph (by altering terminator instructions)</li>
-<li>Any of the things verboten for
+<li>Modify the control flow graph (by altering terminator instructions)</li>
+<li>Any of the things forbidden for
<a href="#FunctionPass"><tt>FunctionPass</tt></a>es.</li>
</ol>
<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that
<tt>BasicBlockPass</tt>'s are not allowed to do, but that
<tt>FunctionPass</tt>'s can. The <tt>doInitialization</tt> method is designed
-to do simple initialization type of stuff that does not depend on the
+to do simple initialization that does not depend on the
BasicBlocks being processed. The <tt>doInitialization</tt> method call is not
scheduled to overlap with any other pass executions (thus it should be very
fast).</p>
<div class="doc_text">
<p>
-If you pass requires a previous pass to be executed (an analysis for example),
+If your pass requires a previous pass to be executed (an analysis for example),
it can use one of these methods to arrange for it to be run before your pass.
LLVM has many different types of analyses and passes that can be required,
-spaning the range from <tt>DominatorSet</tt> to <tt>BreakCriticalEdges</tt>.
-requiring <tt>BreakCriticalEdges</tt>, for example, guarantees that there will
+spanning the range from <tt>DominatorSet</tt> to <tt>BreakCriticalEdges</tt>.
+Requiring <tt>BreakCriticalEdges</tt>, for example, guarantees that there will
be no critical edges in the CFG when your pass has been run.
</p>
In particular, it attempts to avoid recomputing data unless it needs to. For
this reason, passes are allowed to declare that they preserve (i.e., they don't
invalidate) an existing analysis if it's available. For example, a simple
-constant folding pass would not modify the CFG, so it can't possible effect the
+constant folding pass would not modify the CFG, so it can't possibly affect the
results of dominator analysis. By default, all passes are assumed to invalidate
all others.
</p>
Lets try it out with the <tt>gcse</tt> and <tt>licm</tt> passes:</p>
<pre>
-$ opt -load ../../../lib/Debug/libhello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
+$ opt -load ../../../Debug/lib/Hello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
Module Pass Manager
Function Pass Manager
Dominator Set Construction
World</a> pass in between the two passes:</p>
<pre>
-$ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
+$ opt -load ../../../Debug/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
Module Pass Manager
Function Pass Manager
Dominator Set Construction
<p>Now when we run our pass, we get this output:</p>
<pre>
-$ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
+$ opt -load ../../../Debug/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
Pass Arguments: -gcse -hello -licm
Module Pass Manager
Function Pass Manager
projects / oota-llvm.git / blobdiff