</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>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>
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. An example is:<p>
+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>
cerr << *PN;
</pre><p>
-Note that you should not use the <tt>dyn_cast<></tt> operator in a series
-of chained if statements, use an visitor instead... FIXME: continue.<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>
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 = <a href="#isa">dyn_cast</a><<a href="#CallInst">CallInst</a>>(&*inst)) {
+ 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.
</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* i = dyn_cast<Instruction>(*i)) {
+ cerr << "F is used in instruction:\n\t";
+ cerr << *i << "\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>
+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>
+
<!-- Value::replaceAllUsesWith
User::replaceUsesOfWith
Point out: include/llvm/Transforms/Utils/
-->
-
<!-- *********************************************************************** -->
</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>
<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 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 :}
<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 19:38:23 CDT 2002
+Last modified: Mon Sep 16 17:07:43 CDT 2002
<!-- hhmts end -->
</font></body></html>
projects / oota-llvm.git / blobdiff