+<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>
projects / oota-llvm.git / blobdiff