<li><a href="#general">General Information</a>
<ul>
<li><a href="#stl">The C++ Standard Template Library</a>
+<!--
+ <li>The <tt>-time-passes</tt> option
+ <li>How to use the LLVM Makefile system
+ <li>How to write a regression test
+-->
+ </ul>
+ <li><a href="#apis">Important and useful LLVM APIs</a>
+ <ul>
<li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt> and
<tt>dyn_cast<></tt> templates</a>
+ <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro &
+ <tt>-debug</tt> option</a>
+ <ul>
+ <li><a href="#DEBUG_TYPE">Fine grained debug info with
+ <tt>DEBUG_TYPE</tt> and the <tt>-debug-only</tt> option</a/>
+ </ul>
+ <li><a href="#Statistic">The <tt>Statistic</tt> template &
+ <tt>-stats</tt> option</a>
+<!--
+ <li>The <tt>InstVisitor</tt> template
+ <li>The general graph API
+-->
</ul>
<li><a href="#common">Helpful Hints for Common Operations</a>
<ul>
</ul>
<li><a href="#simplechanges">Making simple changes</a>
<ul>
- <li>Creating and inserting new <tt>Instruction</tt>s
- <li>Deleting <tt>Instruction</tt>s
- <li>Replacing an <tt>Instruction</tt> with another <tt>Value</tt>
+ <li><a href="#schanges_creating">Creating and inserting new
+ <tt>Instruction</tt>s</a>
+ <li><a href="#schanges_deleting">Deleting
+ <tt>Instruction</tt>s</a>
+ <li><a href="#schanges_replacing">Replacing an
+ <tt>Instruction</tt> with another <tt>Value</tt></a>
</ul>
<!--
<li>Working with the Control Flow Graph
<li>
<li>
</ul>
- <li>Useful LLVM APIs
- <ul>
- <li>The general graph API
- <li>The <tt>InstVisitor</tt> template
- <li>The DEBUG() macro
- <li>The <tt>Statistic</tt> template
--->
- </ul>
-<!--
- <li>Useful related topics
- <ul>
- <li>The <tt>-time-passes</tt> option
- <li>How to use the LLVM Makefile system
- <li>How to write a regression test
- <li>
- </ul>
-->
</ul>
<li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
<li>Important iterator invalidation semantics to be aware of
</ul>
- <p><b>Written by <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>
- <a href="mailto:sabre@nondot.org">Chris Lattner</a>, and
+ <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
+ <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>, and
<a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a></b><p>
</ol>
Here are some useful links:<p>
<ol>
-<li><a href="http://www.dinkumware.com/htm_cpl/index.html">Dinkumware C++
+<li><a href="http://www.dinkumware.com/refxcpp.html">Dinkumware C++
Library reference</a> - an excellent reference for the STL and other parts of
-the standard C++ library.<br>
+the standard C++ library.
+
+<li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an
+O'Reilly book in the making. It has a decent <a
+href="http://www.tempest-sw.com/cpp/ch13-libref.html">Standard Library
+Reference</a> that rivals Dinkumware's, and is actually free until the book is
+published.
<li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked
Questions</a>
to write maintainable code more than where to put your curly braces.<p>
+<!-- *********************************************************************** -->
+</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
+<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
+<a name="apis">Important and useful LLVM APIs
+</b></font></td></tr></table><ul>
+<!-- *********************************************************************** -->
+
+Here we highlight some LLVM APIs that are generally useful and good to know
+about when writing transformations.<p>
+
<!-- ======================================================================= -->
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
<tr><td> </td><td width="100%">
<a name="isa">The isa<>, cast<> and dyn_cast<> templates</a>
</b></font></td></tr></table><ul>
+The LLVM source-base makes extensive use of a custom form of RTTI. These
+templates have many similarities to the C++ <tt>dynamic_cast<></tt>
+operator, but they don't have some drawbacks (primarily stemming from the fact
+that <tt>dynamic_cast<></tt> only works on classes that have a v-table).
+Because they are used so often, you must know what they do and how they work.
+All of these templates are defined in the <a
+href="/doxygen/Casting_8h-source.html"><tt>Support/Casting.h</tt></a> file (note
+that you very rarely have to include this file directly).<p>
+
+<dl>
+
+<dt><tt>isa<></tt>:
+
+<dd>The <tt>isa<></tt> operator works exactly like the Java
+"<tt>instanceof</tt>" operator. It returns true or false depending on whether a
+reference or pointer points to an instance of the specified class. This can be
+very useful for constraint checking of various sorts (example below).<p>
+
+
+<dt><tt>cast<></tt>:
+
+<dd>The <tt>cast<></tt> operator is a "checked cast" operation. It
+converts a pointer or reference from a base class to a derived cast, causing an
+assertion failure if it is not really an instance of the right type. This
+should be used in cases where you have some information that makes you believe
+that something is of the right type. An example of the <tt>isa<></tt> and
+<tt>cast<></tt> template is:<p>
+
+<pre>
+static bool isLoopInvariant(const <a href="#Value">Value</a> *V, const Loop *L) {
+ if (isa<<a href="#Constant">Constant</a>>(V) || isa<<a href="#Argument">Argument</a>>(V) || isa<<a href="#GlobalValue">GlobalValue</a>>(V))
+ return true;
+
+ <i>// Otherwise, it must be an instruction...</i>
+ return !L->contains(cast<<a href="#Instruction">Instruction</a>>(V)->getParent());
+</pre><p>
+
+Note that you should <b>not</b> use an <tt>isa<></tt> test followed by a
+<tt>cast<></tt>, for that use the <tt>dyn_cast<></tt> operator.<p>
+
+
+<dt><tt>dyn_cast<></tt>:
+
+<dd>The <tt>dyn_cast<></tt> operator is a "checking cast" operation. It
+checks to see if the operand is of the specified type, and if so, returns a
+pointer to it (this operator does not work with references). If the operand is
+not of the correct type, a null pointer is returned. Thus, this works very much
+like the <tt>dynamic_cast</tt> operator in C++, and should be used in the same
+circumstances. Typically, the <tt>dyn_cast<></tt> operator is used in an
+<tt>if</tt> statement or some other flow control statement like this:<p>
+
+<pre>
+ if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) {
+ ...
+ }
+</pre><p>
+
+This form of the <tt>if</tt> statement effectively combines together a call to
+<tt>isa<></tt> and a call to <tt>cast<></tt> into one statement,
+which is very convenient.<p>
+
+Another common example is:<p>
+
+<pre>
+ <i>// Loop over all of the phi nodes in a basic block</i>
+ BasicBlock::iterator BBI = BB->begin();
+ for (; <a href="#PhiNode">PHINode</a> *PN = dyn_cast<<a href="#PHINode">PHINode</a>>(BBI); ++BBI)
+ cerr << *PN;
+</pre><p>
+
+Note that the <tt>dyn_cast<></tt> operator, like C++'s
+<tt>dynamic_cast</tt> or Java's <tt>instanceof</tt> operator, can be abused. In
+particular you should not use big chained <tt>if/then/else</tt> blocks to check
+for lots of different variants of classes. If you find yourself wanting to do
+this, it is much cleaner and more efficient to use the InstVisitor class to
+dispatch over the instruction type directly.<p>
+
+
+<dt><tt>cast_or_null<></tt>:
+
+<dd>The <tt>cast_or_null<></tt> operator works just like the
+<tt>cast<></tt> operator, except that it allows for a null pointer as an
+argument (which it then propagates). This can sometimes be useful, allowing you
+to combine several null checks into one.<p>
+
+
+<dt><tt>dyn_cast_or_null<></tt>:
+
+<dd>The <tt>dyn_cast_or_null<></tt> operator works just like the
+<tt>dyn_cast<></tt> operator, except that it allows for a null pointer as
+an argument (which it then propagates). This can sometimes be useful, allowing
+you to combine several null checks into one.<p>
+
+</dl>
+
+These five templates can be used with any classes, whether they have a v-table
+or not. To add support for these templates, you simply need to add
+<tt>classof</tt> static methods to the class you are interested casting to.
+Describing this is currently outside the scope of this document, but there are
+lots of examples in the LLVM source base.<p>
+
+
+<!-- ======================================================================= -->
+</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
+<tr><td> </td><td width="100%">
+<font color="#EEEEFF" face="Georgia,Palatino"><b>
+<a name="DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt> option</a>
+</b></font></td></tr></table><ul>
+
+Often when working on your pass you will put a bunch of debugging printouts and
+other code into your pass. After you get it working, you want to remove
+it... but you may need it again in the future (to work out new bugs that you run
+across).<p>
+
+Naturally, because of this, you don't want to delete the debug printouts, but
+you don't want them to always be noisy. A standard compromise is to comment
+them out, allowing you to enable them if you need them in the future.<p>
+
+The "<tt><a href="/doxygen/Debug_8h-source.html">Support/Debug.h</a></tt>" file
+provides a macro named <tt>DEBUG()</tt> that is a much nicer solution to this
+problem. Basically, you can put arbitrary code into the argument of the
+<tt>DEBUG</tt> macro, and it is only executed if '<tt>opt</tt>' (or any other
+tool) is run with the '<tt>-debug</tt>' command line argument:
+
+<pre>
+ ...
+ DEBUG(std::cerr << "I am here!\n");
+ ...
+</pre><p>
+
+Then you can run your pass like this:<p>
+
+<pre>
+ $ opt < a.bc > /dev/null -mypass
+ <no output>
+ $ opt < a.bc > /dev/null -mypass -debug
+ I am here!
+ $
+</pre><p>
+
+Using the <tt>DEBUG()</tt> macro instead of a home-brewed solution allows you to
+now have to create "yet another" command line option for the debug output for
+your pass. Note that <tt>DEBUG()</tt> macros are disabled for optimized builds,
+so they do not cause a performance impact at all (for the same reason, they
+should also not contain side-effects!).<p>
+
+One additional nice thing about the <tt>DEBUG()</tt> macro is that you can
+enable or disable it directly in gdb. Just use "<tt>set DebugFlag=0</tt>" or
+"<tt>set DebugFlag=1</tt>" from the gdb if the program is running. If the
+program hasn't been started yet, you can always just run it with
+<tt>-debug</tt>.<p>
+
+<!-- _______________________________________________________________________ -->
+</ul><h4><a name="DEBUG_TYPE"><hr size=0>Fine grained debug info with
+ <tt>DEBUG_TYPE()</tt> and the <tt>-debug-only</tt> option</a> </h4><ul>
+
+Sometimes you may find yourself in a situation where enabling <tt>-debug</tt>
+just turns on <b>too much</b> information (such as when working on the code
+generator). If you want to enable debug information with more fine-grained
+control, you define the <tt>DEBUG_TYPE</tt> macro and the <tt>-debug</tt> only
+option as follows:<p>
+
+<pre>
+ ...
+ DEBUG(std::cerr << "No debug type\n");
+ #undef DEBUG_TYPE
+ #define DEBUG_TYPE "foo"
+ DEBUG(std::cerr << "'foo' debug type\n");
+ #undef DEBUG_TYPE
+ #define DEBUG_TYPE "bar"
+ DEBUG(std::cerr << "'bar' debug type\n");
+ #undef DEBUG_TYPE
+ #define DEBUG_TYPE ""
+ DEBUG(std::cerr << "No debug type (2)\n");
+ ...
+</pre><p>
+
+Then you can run your pass like this:<p>
+
+<pre>
+ $ opt < a.bc > /dev/null -mypass
+ <no output>
+ $ opt < a.bc > /dev/null -mypass -debug
+ No debug type
+ 'foo' debug type
+ 'bar' debug type
+ No debug type (2)
+ $ opt < a.bc > /dev/null -mypass -debug-only=foo
+ 'foo' debug type
+ $ opt < a.bc > /dev/null -mypass -debug-only=bar
+ 'bar' debug type
+ $
+</pre><p>
+
+Of course, in practice, you should only set <tt>DEBUG_TYPE</tt> at the top of a
+file, to specify the debug type for the entire module (if you do this before you
+<tt>#include "Support/Debug.h"</tt>, you don't have to insert the ugly
+<tt>#undef</tt>'s). Also, you should use names more meaningful that "foo" and
+"bar", because there is no system in place to ensure that names do not conflict:
+if two different modules use the same string, they will all be turned on when
+the name is specified. This allows all, say, instruction scheduling, debug
+information to be enabled with <tt>-debug-type=InstrSched</tt>, even if the
+source lives in multiple files.<p>
+
+
+<!-- ======================================================================= -->
+</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
+<tr><td> </td><td width="100%">
+<font color="#EEEEFF" face="Georgia,Palatino"><b>
+<a name="Statistic">The <tt>Statistic</tt> template & <tt>-stats</tt>
+option</a>
+</b></font></td></tr></table><ul>
+
+The "<tt><a
+href="/doxygen/Statistic_8h-source.html">Support/Statistic.h</a></tt>"
+file provides a template named <tt>Statistic</tt> that is used as a unified way
+to keeping track of what the LLVM compiler is doing and how effective various
+optimizations are. It is useful to see what optimizations are contributing to
+making a particular program run faster.<p>
+
+Often you may run your pass on some big program, and you're interested to see
+how many times it makes a certain transformation. Although you can do this with
+hand inspection, or some ad-hoc method, this is a real pain and not very useful
+for big programs. Using the <tt>Statistic</tt> template makes it very easy to
+keep track of this information, and the calculated information is presented in a
+uniform manner with the rest of the passes being executed.<p>
+
+There are many examples of <tt>Statistic</tt> users, but this basics of using it
+are as follows:<p>
+
+<ol>
+<li>Define your statistic like this:<p>
+
+<pre>
+static Statistic<> NumXForms("mypassname", "The # of times I did stuff");
+</pre><p>
+
+The <tt>Statistic</tt> template can emulate just about any data-type, but if you
+do not specify a template argument, it defaults to acting like an unsigned int
+counter (this is usually what you want).<p>
+
+<li>Whenever you make a transformation, bump the counter:<p>
+
+<pre>
+ ++NumXForms; // I did stuff
+</pre><p>
+</ol><p>
+
+That's all you have to do. To get '<tt>opt</tt>' to print out the statistics
+gathered, use the '<tt>-stats</tt>' option:<p>
+<pre>
+ $ opt -stats -mypassname < program.bc > /dev/null
+ ... statistic output ...
+</pre><p>
+When running <tt>gccas</tt> on a C file from the SPEC benchmark suite, it gives
+a report that looks like this:<p>
+
+<pre>
+ 7646 bytecodewriter - Number of normal instructions
+ 725 bytecodewriter - Number of oversized instructions
+ 129996 bytecodewriter - Number of bytecode bytes written
+ 2817 raise - Number of insts DCEd or constprop'd
+ 3213 raise - Number of cast-of-self removed
+ 5046 raise - Number of expression trees converted
+ 75 raise - Number of other getelementptr's formed
+ 138 raise - Number of load/store peepholes
+ 42 deadtypeelim - Number of unused typenames removed from symtab
+ 392 funcresolve - Number of varargs functions resolved
+ 27 globaldce - Number of global variables removed
+ 2 adce - Number of basic blocks removed
+ 134 cee - Number of branches revectored
+ 49 cee - Number of setcc instruction eliminated
+ 532 gcse - Number of loads removed
+ 2919 gcse - Number of instructions removed
+ 86 indvars - Number of canonical indvars added
+ 87 indvars - Number of aux indvars removed
+ 25 instcombine - Number of dead inst eliminate
+ 434 instcombine - Number of insts combined
+ 248 licm - Number of load insts hoisted
+ 1298 licm - Number of insts hoisted to a loop pre-header
+ 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)
+ 75 mem2reg - Number of alloca's promoted
+ 1444 cfgsimplify - Number of blocks simplified
+</pre><p>
+
+Obviously, with so many optimizations, having a unified framework for this stuff
+is very nice. Making your pass fit well into the framework makes it more
+maintainable and useful.<p>
<!-- *********************************************************************** -->
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
<a name="common">Helpful Hints for Common Operations
-</b></font></td></tr></table><ul>
-<!-- *********************************************************************** -->
+</b></font></td></tr></table><ul> <!--
+*********************************************************************** -->
This section describes how to perform some very simple transformations of LLVM
code. This is meant to give examples of common idioms used, showing the
<pre>
// func is a pointer to a Function instance
- for(Function::iterator i = func->begin(), e = func->end(); i != e; ++i) {
+ for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i) {
// print out the name of the basic block if it has one, and then the
// number of instructions that it contains
Note that i can be used as if it were a pointer for the purposes of
invoking member functions of the <tt>Instruction</tt> class. This is
because the indirection operator is overloaded for the iterator
-classes. In the above code, the expression <tt>i->size()</tt> is
+classes. In the above code, the expression <tt>i->size()</tt> is
exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.
<!-- _______________________________________________________________________ -->
<pre>
// blk is a pointer to a BasicBlock instance
- for(BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+ for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
// the next statement works since operator<<(ostream&,...)
// is overloaded for Instruction&
cerr << *i << "\n";
#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"
...
// Suppose F is a ptr to a function
-for(inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
+for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
cerr << **i << "\n";
</pre>
<pre>Instruction* pinst = i;</pre>
-<b>Caveat emptor</b>: The above syntax works <i>only</i> when you're
-<i>not</i> working with <tt>dyn_cast</tt>. The template definition of
-<tt>dyn_cast</tt> isn't implemented to handle this yet, so you'll
-still need the following in order for things to work properly:
-
-<pre>
-BasicBlock::iterator bbi = ...;
-<a href="#BranchInst">BranchInst</a>* b = <a href="#isa">dyn_cast</a><<a href="#BranchInst">BranchInst</a>>(&*bbi);
-</pre>
-
It's also possible to turn a class pointer into the corresponding
iterator. Usually, this conversion is quite inexpensive. The
following code snippet illustrates use of the conversion constructors
void printNextInstruction(Instruction* inst) {
BasicBlock::iterator it(inst);
++it; // after this line, it refers to the instruction after *inst.
- if(it != inst->getParent()->end()) cerr << *it << "\n";
+ if (it != inst->getParent()->end()) cerr << *it << "\n";
}
</pre>
Of course, this example is strictly pedagogical, because it'd be much
better to explicitly grab the next instruction directly from inst.
-<!-- dereferenced iterator = Class &
- iterators have converting constructor for 'Class *'
- iterators automatically convert to 'Class *' except in dyn_cast<> case
- -->
<!--_______________________________________________________________________-->
</ul><h4><a name="iterate_complex"><hr size=0>Finding call sites: a slightly
Say that you're writing a FunctionPass and would like to count all the
locations in the entire module (that is, across every
-<tt>Function</tt>) where a certain function (i.e. some
-<tt>Function</tt>*) already in scope. As you'll learn later, you may
+<tt>Function</tt>) where a certain function (i.e., some
+<tt>Function</tt>*) is already in scope. As you'll learn later, you may
want to use an <tt>InstVisitor</tt> to accomplish this in a much more
straightforward manner, but this example will allow us to explore how
you'd do it if you didn't have <tt>InstVisitor</tt> around. In
for each Function f in the Module
for each BasicBlock b in f
for each Instruction i in b
- if(i is a CallInst and calls the given function)
+ if (i is a CallInst and calls the given function)
increment callCounter
</pre>
has to override the <tt>runOnFunction</tt> method...):
<pre>
-
Function* targetFunc = ...;
class OurFunctionPass : public FunctionPass {
OurFunctionPass(): callCounter(0) { }
virtual runOnFunction(Function& F) {
- for(Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
- for(BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {
- if (<a href="#CallInst">CallInst</a>* callInst = dyn_cast<<a href="#CallInst">CallInst</a>>(&*inst)) {
+ for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
+ for (BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {
+ if (<a href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a href="#CallInst">CallInst</a>>(&*i)) {
// we know we've encountered a call instruction, so we
// need to determine if it's a call to the
// function pointed to by m_func or not.
- if(callInst->getCalledFunction() == targetFunc)
+ if (callInst->getCalledFunction() == targetFunc)
++callCounter;
}
}
</ul><h4><a name="iterate_chains"><hr size=0>Iterating over def-use &
use-def chains</h4><ul>
+Frequently, we might have an instance of the <a
+href="/doxygen/classValue.html">Value Class</a> and we want to
+determine which <tt>User</tt>s use the <tt>Value</tt>. The list of
+all <tt>User</tt>s of a particular <tt>Value</tt> is called a
+<i>def-use</i> chain. For example, let's say we have a
+<tt>Function*</tt> named <tt>F</tt> to a particular function
+<tt>foo</tt>. Finding all of the instructions that <i>use</i>
+<tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain of
+<tt>F</tt>:
+
+<pre>
+Function* F = ...;
+
+for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) {
+ if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
+ cerr << "F is used in instruction:\n";
+ cerr << *Inst << "\n";
+ }
+}
+</pre>
+
+Alternately, it's common to have an instance of the <a
+href="/doxygen/classUser.html">User Class</a> and need to know what
+<tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used
+by a <tt>User</tt> is known as a <i>use-def</i> chain. Instances of
+class <tt>Instruction</tt> are common <tt>User</tt>s, so we might want
+to iterate over all of the values that a particular instruction uses
+(that is, the operands of the particular <tt>Instruction</tt>):
+
+<pre>
+Instruction* pi = ...;
+
+for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
+ Value* v = *i;
+ ...
+}
+</pre>
+
+
<!--
def-use chains ("finding all users of"): Value::use_begin/use_end
use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
<a name="simplechanges">Making simple changes</a>
</b></font></td></tr></table><ul>
-<!-- Value::replaceAllUsesWith
- User::replaceUsesOfWith
- Point out: include/llvm/Transforms/Utils/
- especially BasicBlockUtils.h with:
- ReplaceInstWithValue, ReplaceInstWithInst
+There are some primitive transformation operations present in the LLVM
+infrastructure that are worth knowing about. When performing
+transformations, it's fairly common to manipulate the contents of
+basic blocks. This section describes some of the common methods for
+doing so and gives example code.
--->
+<!--_______________________________________________________________________-->
+</ul><h4><a name="schanges_creating"><hr size=0>Creating and inserting
+ new <tt>Instruction</tt>s</h4><ul>
+
+<i>Instantiating Instructions</i>
+
+<p>Creation of <tt>Instruction</tt>s is straightforward: simply call the
+constructor for the kind of instruction to instantiate and provide the
+necessary parameters. For example, an <tt>AllocaInst</tt> only
+<i>requires</i> a (const-ptr-to) <tt>Type</tt>. Thus:
+
+<pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre>
+
+will create an <tt>AllocaInst</tt> instance that represents the
+allocation of one integer in the current stack frame, at runtime.
+Each <tt>Instruction</tt> subclass is likely to have varying default
+parameters which change the semantics of the instruction, so refer to
+the <a href="/doxygen/classInstruction.html">doxygen documentation for
+the subclass of Instruction</a> that you're interested in
+instantiating.</p>
+
+<p><i>Naming values</i></p>
+
+<p>
+It is very useful to name the values of instructions when you're able
+to, as this facilitates the debugging of your transformations. If you
+end up looking at generated LLVM machine code, you definitely want to
+have logical names associated with the results of instructions! By
+supplying a value for the <tt>Name</tt> (default) parameter of the
+<tt>Instruction</tt> constructor, you associate a logical name with
+the result of the instruction's execution at runtime. For example,
+say that I'm writing a transformation that dynamically allocates space
+for an integer on the stack, and that integer is going to be used as
+some kind of index by some other code. To accomplish this, I place an
+<tt>AllocaInst</tt> at the first point in the first
+<tt>BasicBlock</tt> of some <tt>Function</tt>, and I'm intending to
+use it within the same <tt>Function</tt>. I might do:
+
+<pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre>
+
+where <tt>indexLoc</tt> is now the logical name of the instruction's
+execution value, which is a pointer to an integer on the runtime
+stack.
+</p>
+
+<p><i>Inserting instructions</i></p>
+
+<p>
+There are essentially two ways to insert an <tt>Instruction</tt> into
+an existing sequence of instructions that form a <tt>BasicBlock</tt>:
+<ul>
+<li>Insertion into an explicit instruction list
+
+<p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within
+that <tt>BasicBlock</tt>, and a newly-created instruction
+we wish to insert before <tt>*pi</tt>, we do the following:
+
+<pre>
+ BasicBlock *pb = ...;
+ Instruction *pi = ...;
+ Instruction *newInst = new Instruction(...);
+ pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb
+</pre>
+</p>
+
+<li>Insertion into an implicit instruction list
+<p><tt>Instruction</tt> instances that are already in
+<tt>BasicBlock</tt>s are implicitly associated with an existing
+instruction list: the instruction list of the enclosing basic block.
+Thus, we could have accomplished the same thing as the above code
+without being given a <tt>BasicBlock</tt> by doing:
+<pre>
+ Instruction *pi = ...;
+ Instruction *newInst = new Instruction(...);
+ pi->getParent()->getInstList().insert(pi, newInst);
+</pre>
+In fact, this sequence of steps occurs so frequently that the
+<tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes
+provide constructors which take (as a default parameter) a pointer to
+an <tt>Instruction</tt> which the newly-created <tt>Instruction</tt>
+should precede. That is, <tt>Instruction</tt> constructors are
+capable of inserting the newly-created instance into the
+<tt>BasicBlock</tt> of a provided instruction, immediately before that
+instruction. Using an <tt>Instruction</tt> constructor with a
+<tt>insertBefore</tt> (default) parameter, the above code becomes:
+<pre>
+Instruction* pi = ...;
+Instruction* newInst = new Instruction(..., pi);
+</pre>
+which is much cleaner, especially if you're creating a lot of
+instructions and adding them to <tt>BasicBlock</tt>s.
+ </p>
+</p>
+</ul>
+
+<!--_______________________________________________________________________-->
+</ul><h4><a name="schanges_deleting"><hr size=0>Deleting
+<tt>Instruction</tt>s</h4><ul>
+
+Deleting an instruction from an existing sequence of instructions that form a <a
+href="#BasicBlock"><tt>BasicBlock</tt></a> is very straightforward. First, you
+must have a pointer to the instruction that you wish to delete. Second, you
+need to obtain the pointer to that instruction's basic block. You use the
+pointer to the basic block to get its list of instructions and then use the
+erase function to remove your instruction.<p>
+
+For example:<p>
+
+<pre>
+ <a href="#Instruction">Instruction</a> *I = .. ;
+ <a href="#BasicBlock">BasicBlock</a> *BB = I->getParent();
+ BB->getInstList().erase(I);
+</pre><p>
+
+<!--_______________________________________________________________________-->
+</ul><h4><a name="schanges_replacing"><hr size=0>Replacing an
+ <tt>Instruction</tt> with another <tt>Value</tt></h4><ul>
+
+<p><i>Replacing individual instructions</i></p>
+<p>
+Including "<a
+href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>" permits use of two very useful replace functions:
+<tt>ReplaceInstWithValue</tt> and <tt>ReplaceInstWithInst</tt>.
+<ul>
+
+<li><tt>ReplaceInstWithValue</tt>
+
+<p>This function replaces all uses (within a basic block) of a given
+instruction with a value, and then removes the original instruction.
+The following example illustrates the replacement of the result of a
+particular <tt>AllocaInst</tt> that allocates memory for a single
+integer with an null pointer to an integer.</p>
+
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
+ Constant::getNullValue(PointerType::get(Type::IntTy)));
+</pre>
+
+<li><tt>ReplaceInstWithInst</tt>
+
+<p>This function replaces a particular instruction with another
+instruction. The following example illustrates the replacement of one
+<tt>AllocaInst</tt> with another.<p>
+
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
+ new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));
+</pre>
+
+</ul>
+<p><i>Replacing multiple uses of <tt>User</tt>s and
+ <tt>Value</tt>s</i></p>
+
+You can use <tt>Value::replaceAllUsesWith</tt> and
+<tt>User::replaceUsesOfWith</tt> to change more than one use at a
+time. See the doxygen documentation for the <a
+href="/doxygen/classValue.html">Value Class</a> and <a
+href="/doxygen/classUser.html">User Class</a>, respectively, for more
+information.
+
+<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
+include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
+ReplaceInstWithValue, ReplaceInstWithInst
+-->
<!-- *********************************************************************** -->
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
<li><tt>void replaceAllUsesWith(Value *V)</tt><p>
This method traverses the use list of a <tt>Value</tt> changing all <a
-href="#User"><tt>User</tt>'s</a> of the current value to refer to "<tt>V</tt>"
+href="#User"><tt>User</tt>s</a> of the current value to refer to "<tt>V</tt>"
instead. For example, if you detect that an instruction always produces a
constant value (for example through constant folding), you can replace all uses
of the instruction with the constant like this:<p>
<tt>getOperand()</tt>/<tt>getNumOperands()</tt> and
<tt>op_begin()</tt>/<tt>op_end()</tt> methods).<p>
+An important file for the <tt>Instruction</tt> class is the
+<tt>llvm/Instruction.def</tt> file. This file contains some meta-data about the
+various different types of instructions in LLVM. It describes the enum values
+that are used as opcodes (for example <tt>Instruction::Add</tt> and
+<tt>Instruction::SetLE</tt>), as well as the concrete sub-classes of
+<tt>Instruction</tt> that implement the instruction (for example <tt><a
+href="#BinaryOperator">BinaryOperator</a></tt> and <tt><a
+href="#SetCondInst">SetCondInst</a></tt>). Unfortunately, the use of macros in
+this file confused doxygen, so these enum values don't show up correctly in the
+<a href="/doxygen/classInstruction.html">doxygen output</a>.<p>
+
<!-- _______________________________________________________________________ -->
</ul><h4><a name="m_Instruction"><hr size=0>Important Public Members of
Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that this
<tt>Instruction</tt> is embedded into.<p>
-<li><tt>bool
hasSideEffects()</tt><p>
+<li><tt>bool
mayWriteToMemory()</tt><p>
-Returns true if the instruction has side effects, i.e. it is a <tt>call</tt>,
+Returns true if the instruction writes to memory, i.e. it is a <tt>call</tt>,
<tt>free</tt>, <tt>invoke</tt>, or <tt>store</tt>.<p>
<li><tt>unsigned getOpcode()</tt><p>
Returns the opcode for the <tt>Instruction</tt>.<p>
+<li><tt><a href="#Instruction">Instruction</a> *clone() const</tt><p>
+
+Returns another instance of the specified instruction, identical in all ways to
+the original except that the instruction has no parent (ie it's not embedded
+into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>), and it has no name.<p>
+
+
+
<!--
\subsection{Subclasses of Instruction :}
\end{itemize}
<li>LoadInst, StoreInst, GetElemPtrInst : These subclasses represent load, store and getelementptr instructions in LLVM.
\begin{itemize}
- <li><tt>Value * getPointerOperand ()</tt>: Returns the Pointer Operand which is typically the 0th operand.
+ <li><tt>Value * getPointerOperand()</tt>: Returns the Pointer Operand which is typically the 0th operand.
\end{itemize}
<li>BranchInst : This is a subclass of TerminatorInst and defines the interface for conditional and unconditional branches in LLVM.
\begin{itemize}
<li><tt>Function::BasicBlockListType &getBasicBlockList()</tt><p>
Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This is
-neccesary to use when you need to update the list or perform a complex action
+necessary to use when you need to update the list or perform a complex action
that doesn't have a forwarding method.<p>
<li><tt>Function::ArgumentListType &getArgumentList()</tt><p>
Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is
-neccesary to use when you need to update the list or perform a complex action
+necessary to use when you need to update the list or perform a complex action
that doesn't have a forwarding method.<p>
-<li><tt><a href="#BasicBlock">BasicBlock</a> &getEntry
Node()</tt><p>
+<li><tt><a href="#BasicBlock">BasicBlock</a> &getEntry
Block()</tt><p>
Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
function. Because the entry block for the function is always the first block,
and returns the return type of the function, or the <a
href="#FunctionType"><tt>FunctionType</tt></a> of the actual function.<p>
-
-<li><tt>bool hasSymbolTable() const</tt><p>
-
-Return true if the <tt>Function</tt> has a symbol table allocated to it and if
-there is at least one entry in it.<p>
-
<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
-<tt>Function</tt> or a null pointer if one has not been allocated (because there
-are no named values in the function).<p>
-
-<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTableSure()</tt><p>
-
-Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
-<tt>Function</tt> or allocate a new <a
-href="#SymbolTable"><tt>SymbolTable</tt></a> if one is not already around. This
-should only be used when adding elements to the <a
-href="#SymbolTable"><tt>SymbolTable</tt></a>, so that empty symbol tables are
-not left laying around.<p>
+<tt>Function</tt>.<p>
<li><tt>Module::FunctionListType &getFunctionList()</tt><p>
Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is
-neccesary to use when you need to update the list or perform a complex action
+necessary to use when you need to update the list or perform a complex action
that doesn't have a forwarding method.<p>
<!-- Global Variable -->
<li><tt>Module::GlobalListType &getGlobalList()</tt><p>
Returns the list of <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s.
-This is neccesary to use when you need to update the list or perform a complex
+This is necessary to use when you need to update the list or perform a complex
action that doesn't have a forwarding method.<p>
<!-- Symbol table stuff -->
<hr size=0>
-<li><tt>bool hasSymbolTable() const</tt><p>
-
-Return true if the <tt>Module</tt> has a symbol table allocated to it and if
-there is at least one entry in it.<p>
-
<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
-Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
-<tt>Module</tt> or a null pointer if one has not been allocated (because there
-are no named values in the function).<p>
-
-<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTableSure()</tt><p>
-
-Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
-<tt>Module</tt> or allocate a new <a
-href="#SymbolTable"><tt>SymbolTable</tt></a> if one is not already around. This
-should only be used when adding elements to the <a
-href="#SymbolTable"><tt>SymbolTable</tt></a>, so that empty symbol tables are
-not left laying around.<p>
+Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for
+this <tt>Module</tt>.<p>
<!-- Convenience methods -->
<li><tt>bool isConstantExpr()</tt>: Returns true if it is a ConstantExpr
+<hr>
+Important Subclasses of Constant<p>
-
-\subsection{Important Subclasses of Constant}
-\begin{itemize}
+<ul>
<li>ConstantSInt : This subclass of Constant represents a signed integer constant.
- \begin{itemize}
- <li><tt>int64_t getValue () const</tt>: Returns the underlying value of this constant.
- \end{itemize}
+<ul>
+ <li><tt>int64_t getValue() const</tt>: Returns the underlying value of this constant.
+</ul>
<li>ConstantUInt : This class represents an unsigned integer.
- \begin{itemize}
- <li><tt>uint64_t getValue () const</tt>: Returns the underlying value of this constant.
- \end{itemize}
+<ul>
+ <li><tt>uint64_t getValue() const</tt>: Returns the underlying value of this constant.
+</ul>
<li>ConstantFP : This class represents a floating point constant.
- \begin{itemize}
- <li><tt>double getValue () const</tt>: Returns the underlying value of this constant.
- \end{itemize}
+<ul>
+ <li><tt>double getValue() const</tt>: Returns the underlying value of this constant.
+</ul>
<li>ConstantBool : This represents a boolean constant.
- \begin{itemize}
- <li><tt>bool getValue () const</tt>: Returns the underlying value of this constant.
- \end{itemize}
+<ul>
+ <li><tt>bool getValue() const</tt>: Returns the underlying value of this constant.
+</ul>
<li>ConstantArray : This represents a constant array.
- \begin{itemize}
- <li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
- \end{itemize}
+<ul>
+ <li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
+</ul>
<li>ConstantStruct : This represents a constant struct.
- \begin{itemize}
- <li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
- \end{itemize}
+<ul>
+ <li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
+</ul>
<li>ConstantPointerRef : This represents a constant pointer value that is initialized to point to a global value, which lies at a constant fixed address.
- \begin{itemize}
+<ul>
<li><tt>GlobalValue *getValue()</tt>: Returns the global value to which this pointer is pointing to.
- \end{itemize}
-\end{itemize}
+</ul>
+</ul>
<!-- ======================================================================= -->
<!-- _______________________________________________________________________ -->
</ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul>
-<li><tt>PrimitiveID getPrimitiveID () const</tt>: Returns the base type of the type.
-<li><tt> bool isSigned () const</tt>: Returns whether an integral numeric type is signed. This is true for SByteTy, ShortTy, IntTy, LongTy. Note that this is not true for Float and Double.
-<li><tt>bool isUnsigned () const</tt>: Returns whether a numeric type is unsigned. This is not quite the complement of isSigned... nonnumeric types return false as they do with isSigned. This returns true for UByteTy, UShortTy, UIntTy, and ULongTy.
-<li><tt> bool isInteger () const</tt>: Equilivent to isSigned() || isUnsigned(), but with only a single virtual function invocation.
-<li><tt>bool isIntegral () const</tt>: Returns true if this is an integral type, which is either Bool type or one of the Integer types.
+<li><tt>PrimitiveID getPrimitiveID() const</tt>: Returns the base type of the type.
+<li><tt> bool isSigned() const</tt>: Returns whether an integral numeric type is signed. This is true for SByteTy, ShortTy, IntTy, LongTy. Note that this is not true for Float and Double.
+<li><tt>bool isUnsigned() const</tt>: Returns whether a numeric type is unsigned. This is not quite the complement of isSigned... nonnumeric types return false as they do with isSigned. This returns true for UByteTy, UShortTy, UIntTy, and ULongTy.
+<li><tt> bool isInteger() const</tt>: Equilivent to isSigned() || isUnsigned(), but with only a single virtual function invocation.
+<li><tt>bool isIntegral() const</tt>: Returns true if this is an integral type, which is either Bool type or one of the Integer types.
-<li><tt>bool isFloatingPoint ()</tt>: Return true if this is one of the two floating point types.
-<li><tt>bool isRecursive () const</tt>: Returns rue if the type graph contains a cycle.
+<li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two floating point types.
+<li><tt>bool isRecursive() const</tt>: Returns rue if the type graph contains a cycle.
<li><tt>isLosslesslyConvertableTo (const Type *Ty) const</tt>: Return true if this type can be converted to 'Ty' without any reinterpretation of bits. For example, uint to int.
-<li><tt>bool isPrimitiveType () const</tt>: Returns true if it is a primitive type.
-<li><tt>bool isDerivedType () const</tt>: Returns true if it is a derived type.
+<li><tt>bool isPrimitiveType() const</tt>: Returns true if it is a primitive type.
+<li><tt>bool isDerivedType() const</tt>: Returns true if it is a derived type.
<li><tt>const Type * getContainedType (unsigned i) const</tt>:
This method is used to implement the type iterator. For derived types, this returns the types 'contained' in the derived type, returning 0 when 'i' becomes invalid. This allows the user to iterate over the types in a struct, for example, really easily.
-<li><tt>unsigned getNumContainedTypes () const</tt>: Return the number of types in the derived type.
+<li><tt>unsigned getNumContainedTypes() const</tt>: Return the number of types in the derived type.
+<p>
+<hr>
+Derived Types<p>
-\subsection{Derived Types}
-\begin{itemize}
+<ul>
<li>SequentialType : This is subclassed by ArrayType and PointerType
- \begin{itemize}
- <li><tt>const Type * getElementType () const</tt>: Returns the type of each of the elements in the sequential type.
- \end{itemize}
+<ul>
+ <li><tt>const Type * getElementType() const</tt>: Returns the type of each of the elements in the sequential type.
+</ul>
<li>ArrayType : This is a subclass of SequentialType and defines interface for array types.
- \begin{itemize}
- <li><tt>unsigned getNumElements () const</tt>: Returns the number of elements in the array.
- \end{itemize}
+<ul>
+ <li><tt>unsigned getNumElements() const</tt>: Returns the number of elements in the array.
+</ul>
<li>PointerType : Subclass of SequentialType for pointer types.
<li>StructType : subclass of DerivedTypes for struct types
<li>FunctionType : subclass of DerivedTypes for function types.
- \begin{itemize}
+
+<ul>
- <li><tt>bool isVarArg () const</tt>: Returns true if its a vararg function
- <li><tt> const Type * getReturnType () const</tt>: Returns the return type of the function.
- <li><tt> const ParamTypes &getParamTypes () const</tt>: Returns a vector of parameter types.
+ <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg function
+ <li><tt> const Type * getReturnType() const</tt>: Returns the return type of the function.
+ <li><tt> const ParamTypes &getParamTypes() const</tt>: Returns a vector of parameter types.
<li><tt>const Type * getParamType (unsigned i)</tt>: Returns the type of the ith parameter.
- <li><tt> const unsigned getNumParams () const</tt>: Returns the number of formal parameters.
- \end{itemize}
-\end{itemize}
+ <li><tt> const unsigned getNumParams() const</tt>: Returns the number of formal parameters.
+</ul>
+</ul>
<a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Aug 6 15:00:33 CDT 2002 -->
<!-- hhmts start -->
-Last modified: Mon Sep 9 14:56:55 CDT 2002
+Last modified: Sat Sep 20 09:25:11 CDT 2003
<!-- hhmts end -->
</font></body></html>
projects / oota-llvm.git / blobdiff