<ul>
<li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt>
and <tt>dyn_cast<></tt> templates</a> </li>
- <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt>
+ <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt>
option</a>
<ul>
<li><a href="#DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt>
<li>The <tt>InstVisitor</tt> template
<li>The general graph API
-->
+ <li><a href="#ViewGraph">Viewing graphs while debugging code</a></li>
</ul>
</li>
<li><a href="#common">Helpful Hints for Common Operations</a>
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="isa">The isa<>, cast<> and dyn_cast<> templates</a>
+ <a name="isa">The <tt>isa<></tt>, <tt>cast<></tt> and
+ <tt>dyn_cast<></tt> templates</a>
</div>
<div class="doc_text">
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:
+ 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:
+ <pre>
if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) {
...
}
- </pre>
+ </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>
+ <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>
-
<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
- <tt>InstVisitor</tt> class to dispatch over the instruction type directly.</p>
+ <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
+ <tt>InstVisitor</tt> class to dispatch over the instruction type directly.</p>
- </dd>
+ </dd>
- <dt><tt>cast_or_null<></tt>: </dt>
-
- <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.</dd>
+ <dt><tt>cast_or_null<></tt>: </dt>
+
+ <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.</dd>
- <dt><tt>dyn_cast_or_null<></tt>: </dt>
+ <dt><tt>dyn_cast_or_null<></tt>: </dt>
- <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.</dd>
+ <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.</dd>
- </dl>
+</dl>
<p>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
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt> option</a>
+ <a name="DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt> option</a>
</div>
<div class="doc_text">
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE()</tt> and
+ <a name="DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt> and
the <tt>-debug-only</tt> option</a>
</div>
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="ViewGraph">Viewing graphs while debugging code</a>
+</div>
+
+<div class="doc_text">
+
+<p>Several of the important data structures in LLVM are graphs: for example
+CFGs made out of LLVM <a href="#BasicBlock">BasicBlock</a>s, CFGs made out of
+LLVM <a href="CodeGenerator.html#machinebasicblock">MachineBasicBlock</a>s, and
+<a href="CodeGenerator.html#selectiondag_intro">Instruction Selection
+DAGs</a>. In many cases, while debugging various parts of the compiler, it is
+nice to instantly visualize these graphs.</p>
+
+<p>LLVM provides several callbacks that are available in a debug build to do
+exactly that. If you call the <tt>Function::viewCFG()</tt> method, for example,
+the current LLVM tool will pop up a window containing the CFG for the function
+where each basic block is a node in the graph, and each node contains the
+instructions in the block. Similarly, there also exists
+<tt>Function::viewCFGOnly()</tt> (does not include the instructions), the
+<tt>MachineFunction::viewCFG()</tt> and <tt>MachineFunction::viewCFGOnly()</tt>,
+and the <tt>SelectionDAG::viewGraph()</tt> methods. Within GDB, for example,
+you can usually use something like "<tt>call DAG.viewGraph()</tt>" to pop
+up a window. Alternatively, you can sprinkle calls to these functions in your
+code in places you want to debug.</p>
+
+<p>Getting this to work requires a small amount of configuration. On Unix
+systems with X11, install the <a href="http://www.graphviz.org">graphviz</a>
+toolkit, and make sure 'dot' and 'gv' are in your path. If you are running on
+Mac OS/X, download and install the Mac OS/X <a
+href="http://www.pixelglow.com/graphviz/">Graphviz program</a>, and add
+<tt>/Applications/Graphviz.app/Contents/MacOS/</tt> (or whereever you install
+it) to your path. Once in your system and path are set up, rerun the LLVM
+configure script and rebuild LLVM to enable this functionality.</p>
+
+</div>
+
+
<!-- *********************************************************************** -->
<div class="doc_section">
<a name="common">Helpful Hints for Common Operations</a>
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> cerr << "Basic block (name=" << i->getName() << ") has " <br> << i->size() << " instructions.\n";<br> }<br></pre>
+ <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>
<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
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> cerr << *i << "\n";<br></pre>
+ <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
worklist with its initial contents. For example, if you wanted to
initialize a worklist to contain all instructions in a <tt>Function</tt>
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()) cerr << *it << "\n";<br>}<br></pre>
+ <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>
most-specific common base class is <tt>Instruction</tt>, which includes lots of
less closely-related things. For these cases, LLVM provides a handy wrapper
class called <a
-href="http://llvm.cs.uiuc.edu/doxygen/classllvm_1_1CallSite.html"><tt>CallSite</tt></a>.
+href="http://llvm.org/doxygen/classllvm_1_1CallSite.html"><tt>CallSite</tt></a>.
It is essentially a wrapper around an <tt>Instruction</tt> pointer, with some
methods that provide functionality common to <tt>CallInst</tt>s and
<tt>InvokeInst</tt>s.</p>
<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> cerr << "F is used in instruction:\n";<br> cerr << *Inst << "\n";<br> }<br>}<br></pre>
+ <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>
<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
href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt><br>
doxygen info: <a href="/doxygen/classllvm_1_1GlobalValue.html">GlobalValue
Class</a><br>
-Superclasses: <a href="#User"><tt>User</tt></a>, <a
-href="#Value"><tt>Value</tt></a></p>
+Superclasses: <a href="#Constant"><tt>Constant</tt></a>,
+<a href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
<p>Global values (<a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a
href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are
<p><tt>#include "<a
href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt><br> doxygen
info: <a href="/doxygen/classllvm_1_1Function.html">Function Class</a><br>
-Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
-href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
+Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>,
+<a href="#Constant"><tt>Constant</tt></a>,
+<a href="#User"><tt>User</tt></a>,
+<a href="#Value"><tt>Value</tt></a></p>
<p>The <tt>Function</tt> class represents a single procedure in LLVM. It is
actually one of the more complex classes in the LLVM heirarchy because it must
keep track of a large amount of data. The <tt>Function</tt> class keeps track
-of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a
-href="#Argument"><tt>Argument</tt></a>s, and a <a
-href="#SymbolTable"><tt>SymbolTable</tt></a>.</p>
+of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal
+<a href="#Argument"><tt>Argument</tt></a>s, and a
+<a href="#SymbolTable"><tt>SymbolTable</tt></a>.</p>
<p>The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most
commonly used part of <tt>Function</tt> objects. The list imposes an implicit
href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt>
<br>
doxygen info: <a href="/doxygen/classllvm_1_1GlobalVariable.html">GlobalVariable
-Class</a><br> Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
-href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
+ Class</a><br>
+Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>,
+<a href="#Constant"><tt>Constant</tt></a>,
+<a href="#User"><tt>User</tt></a>,
+<a href="#Value"><tt>Value</tt></a></p>
<p>Global variables are represented with the (suprise suprise)
<tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are also
subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are
always referenced by their address (global values must live in memory, so their
-"name" refers to their address). See <a
-href="#GlobalValue"><tt>GlobalValue</tt></a> for more on this. Global variables
-may have an initial value (which must be a <a
-href="#Constant"><tt>Constant</tt></a>), and if they have an initializer, they
-may be marked as "constant" themselves (indicating that their contents never
-change at runtime).</p>
-
+"name" refers to their constant address). See
+<a href="#GlobalValue"><tt>GlobalValue</tt></a> for more on this. Global
+variables may have an initial value (which must be a
+<a href="#Constant"><tt>Constant</tt></a>), and if they have an initializer,
+they may be marked as "constant" themselves (indicating that their contents
+never change at runtime).</p>
</div>
<!-- _______________________________________________________________________ -->
<a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
- <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
</body>
</html>
-<!-- vim: sw=2 noai
--->
projects / oota-llvm.git / blobdiff