[llvm-commits] CVS: llvm/docs/CodeGenerator.html ProgrammersManual.html
Bill Wendling
isanbard at gmail.com
Tue Oct 10 23:30:24 PDT 2006
Changes in directory llvm/docs:
CodeGenerator.html updated: 1.40 -> 1.41
ProgrammersManual.html updated: 1.92 -> 1.93
---
Log message:
Put code example inside of "doc_code" divisions.
---
Diffs of the changes: (+379 -102)
CodeGenerator.html | 29 ++-
ProgrammersManual.html | 451 +++++++++++++++++++++++++++++++++++++++----------
2 files changed, 378 insertions(+), 102 deletions(-)
Index: llvm/docs/CodeGenerator.html
diff -u llvm/docs/CodeGenerator.html:1.40 llvm/docs/CodeGenerator.html:1.41
--- llvm/docs/CodeGenerator.html:1.40 Sun Sep 17 15:25:45 2006
+++ llvm/docs/CodeGenerator.html Wed Oct 11 01:30:10 2006
@@ -1227,7 +1227,16 @@
</div>
<div class="doc_text">
-<p>To Be Written</p>
+
+<p>We now have the information available to perform the liver intervals analysis
+and build the live intervals themselves. We start off by numbering the basic
+blocks and machine instructions. We then handle the "live-in" values. These
+are in physical registers, so the physical register is assumed to be killed by
+the end of the basic block. Live intervals for virtual registers are computed
+for some ordering of the machine instructions <tt>[1,N]</tt>. A live interval
+is an interval <tt>[i,j)</tt>, where <tt>1 <= i <= j < N</tt>, for which a
+variable is live.</p>
+
</ol>
</div>
@@ -1239,14 +1248,14 @@
<div class="doc_text">
-<p>The <i>Register Allocation problem</i> consists in mapping a
-program <i>P<sub>v</sub></i>, that can use an unbounded number of
-virtual registers, to a program <i>P<sub>p</sub></i> that contains a
-finite (possibly small) number of physical registers. Each target
-architecture has a different number of physical registers. If the
-number of physical registers is not enough to accommodate all the
-virtual registers, some of them will have to be mapped into
-memory. These virtuals are called <i>spilled virtuals</i>.</p>
+<p>The <i>Register Allocation problem</i> consists in mapping a program
+<i>P<sub>v</sub></i>, that can use an unbounded number of virtual
+registers, to a program <i>P<sub>p</sub></i> that contains a finite
+(possibly small) number of physical registers. Each target architecture has
+a different number of physical registers. If the number of physical
+registers is not enough to accommodate all the virtual registers, some of
+them will have to be mapped into memory. These virtuals are called
+<i>spilled virtuals</i>.</p>
</div>
@@ -1722,7 +1731,7 @@
<a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
- Last modified: $Date: 2006/09/17 20:25:45 $
+ Last modified: $Date: 2006/10/11 06:30:10 $
</address>
</body>
Index: llvm/docs/ProgrammersManual.html
diff -u llvm/docs/ProgrammersManual.html:1.92 llvm/docs/ProgrammersManual.html:1.93
--- llvm/docs/ProgrammersManual.html:1.92 Mon Oct 2 07:28:07 2006
+++ llvm/docs/ProgrammersManual.html Wed Oct 11 01:30:10 2006
@@ -282,29 +282,32 @@
<dl>
<dt><tt>isa<></tt>: </dt>
- <dd>The <tt>isa<></tt> operator works exactly like the Java
+ <dd><p>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).</dd>
+ be very useful for constraint checking of various sorts (example below).</p>
+ </dd>
<dt><tt>cast<></tt>: </dt>
- <dd>The <tt>cast<></tt> operator is a "checked cast" operation. It
+ <dd><p>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:
-
- <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;
+ and <tt>cast<></tt> template is:</p>
- <i>// Otherwise, it must be an instruction...</i>
- return !L->contains(cast<<a href="#Instruction">Instruction</a>>(V)->getParent());
- }
- </pre>
+<div class="doc_code">
+<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>
+</div>
<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>
@@ -314,20 +317,22 @@
<dt><tt>dyn_cast<></tt>:</dt>
- <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
+ <dd><p>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:
+ statement like this:</p>
- <pre>
- if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) {
- ...
- }
- </pre>
+<div class="doc_code">
+<pre>
+if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) {
+ // ...
+}
+</pre>
+</div>
<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
@@ -344,17 +349,17 @@
<dt><tt>cast_or_null<></tt>: </dt>
- <dd>The <tt>cast_or_null<></tt> operator works just like the
+ <dd><p>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.</dd>
+ you to combine several null checks into one.</p></dd>
<dt><tt>dyn_cast_or_null<></tt>: </dt>
- <dd>The <tt>dyn_cast_or_null<></tt> operator works just like the
+ <dd><p>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.</dd>
+ allowing you to combine several null checks into one.</p></dd>
</dl>
@@ -375,7 +380,7 @@
<p>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
+it, but you may need it again in the future (to work out new bugs that you run
across).</p>
<p> Naturally, because of this, you don't want to delete the debug printouts,
@@ -388,11 +393,22 @@
<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:</p>
- <pre> ... <br> DEBUG(std::cerr << "I am here!\n");<br> ...<br></pre>
+<div class="doc_code">
+<pre>
+DEBUG(std::cerr << "I am here!\n");
+</pre>
+</div>
<p>Then you can run your pass like this:</p>
- <pre> $ opt < a.bc > /dev/null -mypass<br> <no output><br> $ opt < a.bc > /dev/null -mypass -debug<br> I am here!<br> $<br></pre>
+<div class="doc_code">
+<pre>
+$ opt < a.bc > /dev/null -mypass
+<no output>
+$ opt < a.bc > /dev/null -mypass -debug
+I am here!
+</pre>
+</div>
<p>Using the <tt>DEBUG()</tt> macro instead of a home-brewed solution allows you
to not have to create "yet another" command line option for the debug output for
@@ -422,11 +438,38 @@
control, you define the <tt>DEBUG_TYPE</tt> macro and the <tt>-debug</tt> only
option as follows:</p>
- <pre> ...<br> DEBUG(std::cerr << "No debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "foo"<br> DEBUG(std::cerr << "'foo' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "bar"<br> DEBUG(std::cerr << "'bar' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE ""<br> DEBUG(std::cerr << "No debug type (2)\n");<br> ...<br></pre>
+<div class="doc_code">
+<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>
+</div>
<p>Then you can run your pass like this:</p>
- <pre> $ opt < a.bc > /dev/null -mypass<br> <no output><br> $ opt < a.bc > /dev/null -mypass -debug<br> No debug type<br> 'foo' debug type<br> 'bar' debug type<br> No debug type (2)<br> $ opt < a.bc > /dev/null -mypass -debug-only=foo<br> 'foo' debug type<br> $ opt < a.bc > /dev/null -mypass -debug-only=bar<br> 'bar' debug type<br> $<br></pre>
+<div class="doc_code">
+<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>
+</div>
<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
@@ -466,27 +509,71 @@
it are as follows:</p>
<ol>
- <li>Define your statistic like this:
- <pre>static Statistic<> NumXForms("mypassname", "The # of times I did stuff");<br></pre>
+ <li><p>Define your statistic like this:</p>
+
+<div class="doc_code">
+<pre>
+static Statistic<> NumXForms("mypassname", "The # of times I did stuff");
+</pre>
+</div>
<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>
- <li>Whenever you make a transformation, bump the counter:
- <pre> ++NumXForms; // I did stuff<br></pre>
+ <li><p>Whenever you make a transformation, bump the counter:</p>
+
+<div class="doc_code">
+<pre>
+++NumXForms; // I did stuff!
+</pre>
+</div>
+
</li>
</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<br> ... statistic output ...<br></pre>
+<div class="doc_code">
+<pre>
+$ opt -stats -mypassname < program.bc > /dev/null
+... statistic output ...
+</pre>
+</div>
<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<br> 725 bytecodewriter - Number of oversized instructions<br> 129996 bytecodewriter - Number of bytecode bytes written<br> 2817 raise - Number of insts DCEd or constprop'd<br> 3213 raise - Number of cast-of-self removed<br> 5046 raise - Number of expression trees converted<br> 75 raise - Number of other getelementptr's formed<br> 138 raise - Number of load/store peepholes<br> 42 deadtypeelim - Number of unused typenames removed from symtab<br> 392 funcresolve - Number of varargs functions resolved<br> 27 globaldce - Number of global variables removed<br> 2 adce - Number of basic blocks removed<br> 134 cee - Number of branches revectored<br> 49 cee - Number of setcc instruction eliminated<br> 532 gcse - Number of loads removed<br> 2919 gcse - Number !
of instructions removed<br> 86 indvars - Number of canonical indvars added<br> 87 indvars - Number of aux indvars removed<br> 25 instcombine - Number of dead inst eliminate<br> 434 instcombine - Number of insts combined<br> 248 licm - Number of load insts hoisted<br> 1298 licm - Number of insts hoisted to a loop pre-header<br> 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)<br> 75 mem2reg - Number of alloca's promoted<br> 1444 cfgsimplify - Number of blocks simplified<br></pre>
+<div class="doc_code">
+<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>
+</div>
<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
@@ -602,7 +689,17 @@
an example that prints the name of a <tt>BasicBlock</tt> and the number of
<tt>Instruction</tt>s it contains:</p>
- <pre> // func is a pointer to a Function instance<br> for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i) {<br><br> // print out the name of the basic block if it has one, and then the<br> // number of instructions that it contains<br><br> std::cerr << "Basic block (name=" << i->getName() << ") has " <br> << i->size() << " instructions.\n";<br> }<br></pre>
+<div class="doc_code">
+<pre>
+// func is a pointer to a Function instance
+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
+ std::cerr << "Basic block (name=" << i->getName() << ") has "
+ << i->size() << " instructions.\n";
+}
+</pre>
+</div>
<p>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
@@ -626,13 +723,15 @@
<tt>BasicBlock</tt>s. Here's a code snippet that prints out each instruction in
a <tt>BasicBlock</tt>:</p>
+<div class="doc_code">
<pre>
- // blk is a pointer to a BasicBlock instance
- for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
- // the next statement works since operator<<(ostream&,...)
- // is overloaded for Instruction&
- std::cerr << *i << "\n";
+// blk is a pointer to a BasicBlock instance
+for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+ // the next statement works since operator<<(ostream&,...)
+ // is overloaded for Instruction&
+ std::cerr << *i << "\n";
</pre>
+</div>
<p>However, this isn't really the best way to print out the contents of a
<tt>BasicBlock</tt>! Since the ostream operators are overloaded for virtually
@@ -657,12 +756,27 @@
and then instantiate <tt>InstIterator</tt>s explicitly in your code. Here's a
small example that shows how to dump all instructions in a function to the standard error stream:<p>
- <pre>#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"<br>...<br>// Suppose F is a ptr to a function<br>for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)<br> std::cerr << *i << "\n";<br></pre>
-Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
+<div class="doc_code">
+<pre>
+#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)
+ std::cerr << *i << "\n";
+</pre>
+</div>
+
+<p>Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
worklist with its initial contents. For example, if you wanted to
initialize a worklist to contain all instructions in a <tt>Function</tt>
-F, all you would need to do is something like:
- <pre>std::set<Instruction*> worklist;<br>worklist.insert(inst_begin(F), inst_end(F));<br></pre>
+F, all you would need to do is something like:</p>
+
+<div class="doc_code">
+<pre>
+std::set<Instruction*> worklist;
+worklist.insert(inst_begin(F), inst_end(F));
+</pre>
+</div>
<p>The STL set <tt>worklist</tt> would now contain all instructions in the
<tt>Function</tt> pointed to by F.</p>
@@ -683,7 +797,13 @@
Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and <tt>j</tt>
is a <tt>BasicBlock::const_iterator</tt>:</p>
- <pre> Instruction& inst = *i; // grab reference to instruction reference<br> Instruction* pinst = &*i; // grab pointer to instruction reference<br> const Instruction& inst = *j;<br></pre>
+<div class="doc_code">
+<pre>
+Instruction& inst = *i; // grab reference to instruction reference
+Instruction* pinst = &*i; // grab pointer to instruction reference
+const Instruction& inst = *j;
+</pre>
+</div>
<p>However, the iterators you'll be working with in the LLVM framework are
special: they will automatically convert to a ptr-to-instance type whenever they
@@ -693,11 +813,19 @@
(behind the scenes, this is a result of overloading casting mechanisms). Thus
the last line of the last example,</p>
- <pre>Instruction* pinst = &*i;</pre>
+<div class="doc_code">
+<pre>
+Instruction* pinst = &*i;
+</pre>
+</div>
<p>is semantically equivalent to</p>
- <pre>Instruction* pinst = i;</pre>
+<div class="doc_code">
+<pre>
+Instruction* pinst = i;
+</pre>
+</div>
<p>It's also possible to turn a class pointer into the corresponding iterator,
and this is a constant time operation (very efficient). The following code
@@ -705,7 +833,15 @@
iterators. By using these, you can explicitly grab the iterator of something
without actually obtaining it via iteration over some structure:</p>
- <pre>void printNextInstruction(Instruction* inst) {<br> BasicBlock::iterator it(inst);<br> ++it; // after this line, it refers to the instruction after *inst.<br> if (it != inst->getParent()->end()) std::cerr << *it << "\n";<br>}<br></pre>
+<div class="doc_code">
+<pre>
+void printNextInstruction(Instruction* inst) {
+ BasicBlock::iterator it(inst);
+ ++it; // after this line, it refers to the instruction after *inst.
+ if (it != inst->getParent()->end()) std::cerr << *it << "\n";
+}
+</pre>
+</div>
</div>
@@ -725,15 +861,50 @@
you'd do it if you didn't have <tt>InstVisitor</tt> around. In pseudocode, this
is what we want to do:</p>
- <pre>initialize callCounter to zero<br>for each Function f in the Module<br> for each BasicBlock b in f<br> for each Instruction i in b<br> if (i is a CallInst and calls the given function)<br> increment callCounter<br></pre>
+<div class="doc_code">
+<pre>
+initialize callCounter to zero
+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)
+ increment callCounter
+</pre>
+</div>
-<p>And the actual code is (remember, since we're writing a
+<p>And the actual code is (remember, because we're writing a
<tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply has to
-override the <tt>runOnFunction</tt> method...):</p>
+override the <tt>runOnFunction</tt> method):</p>
- <pre>Function* targetFunc = ...;<br><br>class OurFunctionPass : public FunctionPass {<br> public:<br> OurFunctionPass(): callCounter(0) { }<br><br> virtual runOnFunction(Function& F) {<br> for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {<br> for (BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {<br> if (<a
- href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a
- href="#CallInst">CallInst</a>>(&*i)) {<br> // we know we've encountered a call instruction, so we<br> // need to determine if it's a call to the<br> // function pointed to by m_func or not.<br> <br> if (callInst->getCalledFunction() == targetFunc)<br> ++callCounter;<br> }<br> }<br> }<br> <br> private:<br> unsigned callCounter;<br>};<br></pre>
+<div class="doc_code">
+<pre>
+Function* targetFunc = ...;
+
+class OurFunctionPass : public FunctionPass {
+ public:
+ 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 = <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)
+ ++callCounter;
+ }
+ }
+ }
+
+
+ private:
+ unsigned callCounter;
+};
+</pre>
+</div>
</div>
@@ -780,7 +951,18 @@
<i>use</i> <tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain
of <tt>F</tt>:</p>
- <pre>Function* F = ...;<br><br>for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) {<br> if (Instruction *Inst = dyn_cast<Instruction>(*i)) {<br> std::cerr << "F is used in instruction:\n";<br> std::cerr << *Inst << "\n";<br> }<br>}<br></pre>
+<div class="doc_code">
+<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)) {
+ std::cerr << "F is used in instruction:\n";
+ std::cerr << *Inst << "\n";
+ }
+}
+</pre>
+</div>
<p>Alternately, it's common to have an instance of the <a
href="/doxygen/classllvm_1_1User.html">User Class</a> and need to know what
@@ -790,7 +972,16 @@
all of the values that a particular instruction uses (that is, the operands of
the particular <tt>Instruction</tt>):</p>
- <pre>Instruction* pi = ...;<br><br>for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {<br> Value* v = *i;<br> ...<br>}<br></pre>
+<div class="doc_code">
+<pre>
+Instruction* pi = ...;
+
+for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
+ Value* v = *i;
+ ...
+}
+</pre>
+</div>
<!--
def-use chains ("finding all users of"): Value::use_begin/use_end
@@ -829,7 +1020,11 @@
parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i> a
(const-ptr-to) <tt>Type</tt>. Thus:</p>
-<pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre>
+<div class="doc_code">
+<pre>
+AllocaInst* ai = new AllocaInst(Type::IntTy);
+</pre>
+</div>
<p>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>
@@ -853,7 +1048,11 @@
<tt>Function</tt>, and I'm intending to use it within the same
<tt>Function</tt>. I might do:</p>
- <pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre>
+<div class="doc_code">
+<pre>
+AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");
+</pre>
+</div>
<p>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>
@@ -870,7 +1069,15 @@
<tt>BasicBlock</tt>, and a newly-created instruction we wish to insert
before <tt>*pi</tt>, we do the following: </p>
- <pre> BasicBlock *pb = ...;<br> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb<br></pre>
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *pi = ...;
+Instruction *newInst = new Instruction(...);
+
+pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb
+</pre>
+</div>
<p>Appending to the end of a <tt>BasicBlock</tt> is so common that
the <tt>Instruction</tt> class and <tt>Instruction</tt>-derived
@@ -878,11 +1085,23 @@
<tt>BasicBlock</tt> to be appended to. For example code that
looked like: </p>
- <pre> BasicBlock *pb = ...;<br> Instruction *newInst = new Instruction(...);<br> pb->getInstList().push_back(newInst); // appends newInst to pb<br></pre>
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *newInst = new Instruction(...);
+
+pb->getInstList().push_back(newInst); // appends newInst to pb
+</pre>
+</div>
<p>becomes: </p>
- <pre> BasicBlock *pb = ...;<br> Instruction *newInst = new Instruction(..., pb);<br></pre>
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *newInst = new Instruction(..., pb);
+</pre>
+</div>
<p>which is much cleaner, especially if you are creating
long instruction streams.</p></li>
@@ -895,7 +1114,14 @@
thing as the above code without being given a <tt>BasicBlock</tt> by doing:
</p>
- <pre> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pi->getParent()->getInstList().insert(pi, newInst);<br></pre>
+<div class="doc_code">
+<pre>
+Instruction *pi = ...;
+Instruction *newInst = new Instruction(...);
+
+pi->getParent()->getInstList().insert(pi, newInst);
+</pre>
+</div>
<p>In fact, this sequence of steps occurs so frequently that the
<tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes provide
@@ -907,10 +1133,15 @@
<tt>Instruction</tt> constructor with a <tt>insertBefore</tt> (default)
parameter, the above code becomes:</p>
- <pre>Instruction* pi = ...;<br>Instruction* newInst = new Instruction(..., pi);<br></pre>
+<div class="doc_code">
+<pre>
+Instruction* pi = ...;
+Instruction* newInst = new Instruction(..., pi);
+</pre>
+</div>
<p>which is much cleaner, especially if you're creating a lot of
-instructions and adding them to <tt>BasicBlock</tt>s.</p></li>
+ instructions and adding them to <tt>BasicBlock</tt>s.</p></li>
</ul>
</div>
@@ -929,8 +1160,14 @@
pointer to the basic block to get its list of instructions and then use the
erase function to remove your instruction. For example:</p>
- <pre> <a href="#Instruction">Instruction</a> *I = .. ;<br> <a
- href="#BasicBlock">BasicBlock</a> *BB = I->getParent();<br> BB->getInstList().erase(I);<br></pre>
+<div class="doc_code">
+<pre>
+<a href="#Instruction">Instruction</a> *I = .. ;
+<a href="#BasicBlock">BasicBlock</a> *BB = I->getParent();
+
+BB->getInstList().erase(I);
+</pre>
+</div>
</div>
@@ -959,7 +1196,14 @@
<tt>AllocaInst</tt> that allocates memory for a single integer with a null
pointer to an integer.</p>
- <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,<br> Constant::getNullValue(PointerType::get(Type::IntTy)));<br></pre></li>
+<div class="doc_code">
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+
+ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
+ Constant::getNullValue(PointerType::get(Type::IntTy)));
+</pre></div></li>
<li><tt>ReplaceInstWithInst</tt>
@@ -967,7 +1211,14 @@
instruction. The following example illustrates the replacement of one
<tt>AllocaInst</tt> with another.</p>
- <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,<br> new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));<br></pre></li>
+<div class="doc_code">
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+
+ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
+ new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));
+</pre></div></li>
</ul>
<p><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></p>
@@ -1047,33 +1298,37 @@
to be emitted to an output .ll file:
</p>
+<div class="doc_code">
<pre>
- %mylist = type { %mylist*, int }
+%mylist = type { %mylist*, int }
</pre>
+</div>
<p>
To build this, use the following LLVM APIs:
</p>
+<div class="doc_code">
<pre>
- //<i> Create the initial outer struct.</i>
- <a href="#PATypeHolder">PATypeHolder</a> StructTy = OpaqueType::get();
- std::vector<const Type*> Elts;
- Elts.push_back(PointerType::get(StructTy));
- Elts.push_back(Type::IntTy);
- StructType *NewSTy = StructType::get(Elts);
-
- //<i> At this point, NewSTy = "{ opaque*, int }". Tell VMCore that</i>
- //<i> the struct and the opaque type are actually the same.</i>
- cast<OpaqueType>(StructTy.get())-><a href="#refineAbstractTypeTo">refineAbstractTypeTo</a>(NewSTy);
-
- // <i>NewSTy is potentially invalidated, but StructTy (a <a href="#PATypeHolder">PATypeHolder</a>) is</i>
- // <i>kept up-to-date.</i>
- NewSTy = cast<StructType>(StructTy.get());
+//<i> Create the initial outer struct.</i>
+<a href="#PATypeHolder">PATypeHolder</a> StructTy = OpaqueType::get();
+std::vector<const Type*> Elts;
+Elts.push_back(PointerType::get(StructTy));
+Elts.push_back(Type::IntTy);
+StructType *NewSTy = StructType::get(Elts);
+
+//<i> At this point, NewSTy = "{ opaque*, int }". Tell VMCore that</i>
+//<i> the struct and the opaque type are actually the same.</i>
+cast<OpaqueType>(StructTy.get())-><a href="#refineAbstractTypeTo">refineAbstractTypeTo</a>(NewSTy);
+
+// <i>NewSTy is potentially invalidated, but StructTy (a <a href="#PATypeHolder">PATypeHolder</a>) is</i>
+// <i>kept up-to-date.</i>
+NewSTy = cast<StructType>(StructTy.get());
- // <i>Add a name for the type to the module symbol table (optional).</i>
- MyModule->addTypeName("mylist", NewSTy);
+// <i>Add a name for the type to the module symbol table (optional).</i>
+MyModule->addTypeName("mylist", NewSTy);
</pre>
+</div>
<p>
This code shows the basic approach used to build recursive types: build a
@@ -1282,6 +1537,7 @@
the beginning or end of the sequence for both const and non-const. It is
important to keep track of the different kinds of iterators. There are
three idioms worth pointing out:</p>
+
<table>
<tr><th>Units</th><th>Iterator</th><th>Idiom</th></tr>
<tr>
@@ -1291,24 +1547,27 @@
PE = ST.plane_end(); PI != PE; ++PI ) {
PI->first // This is the Type* of the plane
PI->second // This is the SymbolTable::ValueMap of name/Value pairs
+}
</tt></pre></td>
</tr>
<tr>
<td align="left">All name/Type Pairs</td><td>TI</td>
<td align="left"><pre><tt>
for (SymbolTable::type_const_iterator TI = ST.type_begin(),
- TE = ST.type_end(); TI != TE; ++TI )
+ TE = ST.type_end(); TI != TE; ++TI ) {
TI->first // This is the name of the type
TI->second // This is the Type* value associated with the name
+}
</tt></pre></td>
</tr>
<tr>
<td align="left">name/Value pairs in a plane</td><td>VI</td>
<td align="left"><pre><tt>
for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType),
- VE = ST.value_end(SomeType); VI != VE; ++VI )
+ VE = ST.value_end(SomeType); VI != VE; ++VI ) {
VI->first // This is the name of the Value
VI->second // This is the Value* value associated with the name
+}
</tt></pre></td>
</tr>
</table>
@@ -1436,7 +1695,11 @@
method. In addition, all LLVM values can be named. The "name" of the
<tt>Value</tt> is a symbolic string printed in the LLVM code:</p>
- <pre> %<b>foo</b> = add int 1, 2<br></pre>
+<div class="doc_code">
+<pre>
+%<b>foo</b> = add int 1, 2
+</pre>
+</div>
<p><a name="#nameWarning">The name of this instruction is "foo".</a> <b>NOTE</b>
that the name of any value may be missing (an empty string), so names should
@@ -1497,7 +1760,12 @@
produces a constant value (for example through constant folding), you can
replace all uses of the instruction with the constant like this:</p>
- <pre> Inst->replaceAllUsesWith(ConstVal);<br></pre>
+<div class="doc_code">
+<pre>
+Inst->replaceAllUsesWith(ConstVal);
+</pre>
+</div>
+
</ul>
</div>
@@ -2293,7 +2561,7 @@
<a href="mailto:dhurjati at cs.uiuc.edu">Dinakar Dhurjati</a> and
<a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
- Last modified: $Date: 2006/10/02 12:28:07 $
+ Last modified: $Date: 2006/10/11 06:30:10 $
</address>
</body>
More information about the llvm-commits
mailing list