diff options
Diffstat (limited to 'docs/ProgrammersManual.html')
| -rw-r--r-- | docs/ProgrammersManual.html | 3292 |
1 files changed, 1568 insertions, 1724 deletions
diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index bacb0d6b81..1ac08b42f4 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -1,68 +1,75 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>LLVM Programmer's Manual</title></head> - -<body bgcolor=white> - -<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> -<tr><td> <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>LLVM Programmer's Manual</b></font></td> -</tr></table> - +<html> +<head> + <title>LLVM Programmer's Manual</title> +</head> +<body style="background-color: white;"> +<table width="100%" bgcolor="#330077" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <tr> + <td> <font size="+3" color="#eeeeff" + face="Georgia,Palatino,Times,Roman"><b>LLVM Programmer's Manual</b></font></td> + </tr> + </tbody> +</table> <ol> - <li><a href="#introduction">Introduction</a> + <li><a href="#introduction">Introduction</a> </li> <li><a href="#general">General Information</a> - <ul> - <li><a href="#stl">The C++ Standard Template Library</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> + </ul> + </li> <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><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> +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> </li> + </ul> + </li> + <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> - <li><a href="#inspection">Basic Inspection and Traversal Routines</a> - <ul> - <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s - in a <tt>Function</tt></a> - <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s - in a <tt>BasicBlock</tt></a> - <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s - in a <tt>Function</tt></a> - <li><a href="#iterate_convert">Turning an iterator into a class - pointer</a> - <li><a href="#iterate_complex">Finding call sites: a more complex - example</a> - <li><a href="#calls_and_invokes">Treating calls and invokes the - same way</a> - <li><a href="#iterate_chains">Iterating over def-use & use-def - chains</a> +--> </li> </ul> - <li><a href="#simplechanges">Making simple changes</a> + </li> + <li><a href="#common">Helpful Hints for Common Operations</a> <ul> - <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><a href="#inspection">Basic Inspection and Traversal Routines</a> + <ul> + <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s +in a <tt>Function</tt></a> </li> + <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s +in a <tt>BasicBlock</tt></a> </li> + <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s +in a <tt>Function</tt></a> </li> + <li><a href="#iterate_convert">Turning an iterator into a +class pointer</a> </li> + <li><a href="#iterate_complex">Finding call sites: a more +complex example</a> </li> + <li><a href="#calls_and_invokes">Treating calls and invokes +the same way</a> </li> + <li><a href="#iterate_chains">Iterating over def-use & +use-def chains</a> </li> + </ul> + </li> + <li><a href="#simplechanges">Making simple changes</a> + <ul> + <li><a href="#schanges_creating">Creating and inserting new + <tt>Instruction</tt>s</a> </li> + <li><a href="#schanges_deleting">Deleting <tt>Instruction</tt>s</a> </li> + <li><a href="#schanges_replacing">Replacing an <tt>Instruction</tt> +with another <tt>Value</tt></a> </li> + </ul> <!-- <li>Working with the Control Flow Graph <ul> @@ -70,1769 +77,1606 @@ <li> <li> </ul> ---> - </ul> +--> </li> + </ul> + </li> <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a> - <ul> - <li><a href="#Value">The <tt>Value</tt> class</a> <ul> - <li><a href="#User">The <tt>User</tt> class</a> - <ul> - <li><a href="#Instruction">The <tt>Instruction</tt> class</a> - <ul> - <li> - </ul> - <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a> + <li><a href="#Value">The <tt>Value</tt> class</a> <ul> - <li><a href="#BasicBlock">The <tt>BasicBlock</tt> class</a> - <li><a href="#Function">The <tt>Function</tt> class</a> - <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a> + <li><a href="#User">The <tt>User</tt> class</a> + <ul> + <li><a href="#Instruction">The <tt>Instruction</tt> class</a> + <ul> + <li> <a href="#GetElementPtrInst">The <span + style="font-family: monospace;">GetElementPtrInst</span> class</a><br> + </li> + </ul> + </li> + <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a> + <ul> + <li><a href="#BasicBlock">The <tt>BasicBlock</tt> +class</a> </li> + <li><a href="#Function">The <tt>Function</tt> class</a> </li> + <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> +class</a> </li> + </ul> + </li> + <li><a href="#Module">The <tt>Module</tt> class</a> </li> + <li><a href="#Constant">The <tt>Constant</tt> class</a> + <ul> + <li> <br> + </li> + <li> <br> + </li> + </ul> + </li> + </ul> + </li> + <li><a href="#Type">The <tt>Type</tt> class</a> </li> + <li><a href="#Argument">The <tt>Argument</tt> class</a> </li> </ul> - <li><a href="#Module">The <tt>Module</tt> class</a> - <li><a href="#Constant">The <tt>Constant</tt> class</a> + </li> + <li>The <tt>SymbolTable</tt> class </li> + <li>The <tt>ilist</tt> and <tt>iplist</tt> classes <ul> - <li> - <li> + <li>Creating, inserting, moving and deleting from LLVM lists </li> </ul> - </ul> - <li><a href="#Type">The <tt>Type</tt> class</a> - <li><a href="#Argument">The <tt>Argument</tt> class</a> - </ul> - <li>The <tt>SymbolTable</tt> class - <li>The <tt>ilist</tt> and <tt>iplist</tt> classes - <ul> - <li>Creating, inserting, moving and deleting from LLVM lists + </li> + <li>Important iterator invalidation semantics to be aware of </li> </ul> - <li>Important iterator invalidation semantics to be aware of - </ul> - - <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> + <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> + <p> </p> + </li> </ol> - - -<!-- *********************************************************************** --> -<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="introduction">Introduction -</b></font></td></tr></table><ul> <!-- *********************************************************************** --> - -This document is meant to highlight some of the important classes and interfaces -available in the LLVM source-base. This manual is not intended to explain what -LLVM is, how it works, and what LLVM code looks like. It assumes that you know -the basics of LLVM and are interested in writing transformations or otherwise -analyzing or manipulating the code.<p> - -This document should get you oriented so that you can find your way in the -continuously growing source code that makes up the LLVM infrastructure. Note -that this manual is not intended to serve as a replacement for reading the -source code, so if you think there should be a method in one of these classes to -do something, but it's not listed, check the source. Links to the <a -href="/doxygen/">doxygen</a> sources are provided to make this as easy as -possible.<p> - -The first section of this document describes general information that is useful -to know when working in the LLVM infrastructure, and the second describes the -Core LLVM classes. In the future this manual will be extended with information -describing how to use extension libraries, such as dominator information, CFG -traversal routines, and useful utilities like the <tt><a -href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.<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="general">General Information -</b></font></td></tr></table><ul> +<table width="100%" bgcolor="#330077" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <tr> + <td align="center"><font color="#eeeeff" size="+2" + face="Georgia,Palatino"><b> <a name="introduction">Introduction </a></b></font></td> + </tr> + </tbody> +</table> +<ul> <!-- *********************************************************************** --> - -This section contains general information that is useful if you are working in -the LLVM source-base, but that isn't specific to any particular API.<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="stl">The C++ Standard Template Library</a> -</b></font></td></tr></table><ul> - -LLVM makes heavy use of the C++ Standard Template Library (STL), perhaps much -more than you are used to, or have seen before. Because of this, you might want -to do a little background reading in the techniques used and capabilities of the -library. There are many good pages that discuss the STL, and several books on -the subject that you can get, so it will not be discussed in this document.<p> - -Here are some useful links:<p> - -<ol> -<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. - -<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> - -<li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's Guide</a> - -Contains a useful <a -href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the -STL</a>. - -<li><a href="http://www.research.att.com/~bs/C++.html">Bjarne Stroustrup's C++ -Page</a> - -</ol><p> - -You are also encouraged to take a look at the <a -href="CodingStandards.html">LLVM Coding Standards</a> guide which focuses on how -to write maintainable code more than where to put your curly braces.<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="stl">Other useful references</a> -</b></font></td></tr></table><ul> - -LLVM is currently using CVS as its source versioning system. You may find this -reference handy:<p> - -<ol> -<li><a href="http://www.psc.edu/~semke/cvs_branches.html">CVS Branch and Tag -Primer</a></li> -</ol><p> - +This document is meant to highlight some of the important classes and +interfaces available in the LLVM source-base. This manual is not +intended to explain what LLVM is, how it works, and what LLVM code looks +like. It assumes that you know the basics of LLVM and are interested +in writing transformations or otherwise analyzing or manipulating the +code. + <p> This document should get you oriented so that you can find your +way in the continuously growing source code that makes up the LLVM +infrastructure. Note that this manual is not intended to serve as a +replacement for reading the source code, so if you think there should be +a method in one of these classes to do something, but it's not listed, +check the source. Links to the <a href="/doxygen/">doxygen</a> sources +are provided to make this as easy as possible.</p> + <p> The first section of this document describes general information +that is useful to know when working in the LLVM infrastructure, and the +second describes the Core LLVM classes. In the future this manual will +be extended with information describing how to use extension libraries, +such as dominator information, CFG traversal routines, and useful +utilities like the <tt><a href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> +template.</p> + <p><!-- *********************************************************************** --> </p> +</ul> +<table width="100%" bgcolor="#330077" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <tr> + <td align="center"><font color="#eeeeff" size="+2" + face="Georgia,Palatino"><b> <a name="general">General Information </a></b></font></td> + </tr> + </tbody> +</table> +<ul> <!-- *********************************************************************** --> -</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> +This section contains general information that is useful if you are +working in the LLVM source-base, but that isn't specific to any +particular API. + <p><!-- ======================================================================= --> </p> +</ul> +<table width="100%" bgcolor="#441188" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <tr> + <td> </td> + <td width="100%"> <font color="#eeeeff" + face="Georgia,Palatino"><b> <a name="stl">The C++ Standard Template +Library</a> </b></font></td> + </tr> + </tbody> +</table> +<ul> +LLVM makes heavy use of the C++ Standard Template Library (STL), +perhaps much more than you are used to, or have seen before. Because of +this, you might want to do a little background reading in the +techniques used and capabilities of the library. There are many good +pages that discuss the STL, and several books on the subject that you +can get, so it will not be discussed in this document. + <p> Here are some useful links:</p> + <p> </p> + <ol> + <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. </li> + <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> + <li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently +Asked Questions</a> </li> + <li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's +Guide</a> - Contains a useful <a + href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction +to the STL</a>. </li> + <li><a href="http://www.research.att.com/%7Ebs/C++.html">Bjarne +Stroustrup's C++ Page</a> </li> + </ol> + <p> You are also encouraged to take a look at the <a + href="CodingStandards.html">LLVM Coding Standards</a> guide which +focuses on how to write maintainable code more than where to put your +curly braces.</p> + <p><!-- ======================================================================= --> </p> +</ul> +<table width="100%" bgcolor="#441188" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <tr> + <td> </td> + <td width="100%"> <font color="#eeeeff" + face="Georgia,Palatino"><b> <a name="stl">Other useful references</a> </b></font></td> + </tr> + </tbody> +</table> +<ul> +LLVM is currently using CVS as its source versioning system. You may +find this reference handy: + <p> </p> + <ol> + <li><a href="http://www.psc.edu/%7Esemke/cvs_branches.html">CVS +Branch and Tag Primer</a></li> + </ol> + <p><!-- *********************************************************************** --> </p> +</ul> +<table width="100%" bgcolor="#330077" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <tr> + <td align="center"><font color="#eeeeff" size="+2" + face="Georgia,Palatino"><b> <a name="apis">Important and useful LLVM +APIs </a></b></font></td> + </tr> + </tbody> +</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%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<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> - +Here we highlight some LLVM APIs that are generally useful and good to +know about when writing transformations. + <p><!-- ======================================================================= --> </p> +</ul> +<table width="100%" bgcolor="#441188" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <tr> + <td> </td> + <td width="100%"> <font color="#eeeeff" + face="Georgia,Palatino"><b> <a name="isa">The isa<>, +cast<> and dyn_cast<> templates</a> </b></font></td> + </tr> + </tbody> +</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> </p> + <dl> + <dt><tt>isa<></tt>: </dt> + <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> </p> + </dd> + <dt><tt>cast<></tt>: </dt> + <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> </p> + <pre>static bool isLoopInvariant(const <a href="#Value">Value</a> *V, const Loop *L) {<br> if (isa<<a + href="#Constant">Constant</a>>(V) || isa<<a href="#Argument">Argument</a>>(V) || isa<<a + href="#GlobalValue">GlobalValue</a>>(V))<br> return true;<br><br> <i>// Otherwise, it must be an instruction...</i><br> return !L->contains(cast<<a + href="#Instruction">Instruction</a>>(V)->getParent());<br></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> + <p> </p> + </dd> + <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 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> </p> + <pre> if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a + href="#AllocationInst">AllocationInst</a>>(Val)) {<br> ...<br> }<br></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> Another common example is:</p> + <p> </p> + <pre> <i>// Loop over all of the phi nodes in a basic block</i><br> BasicBlock::iterator BBI = BB->begin();<br> for (; <a + href="#PhiNode">PHINode</a> *PN = dyn_cast<<a href="#PHINode">PHINode</a>>(BBI); ++BBI)<br> cerr << *PN;<br></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> + <p> </p> + </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. + <p> </p> + </dd> + <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. + <p> </p> + </dd> + </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><!-- ======================================================================= --> </p> +</ul> +<table width="100%" bgcolor="#441188" border="0" cellpadding="4" + cellspacing="0"> + <tbody> + <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> + </tbody> +</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> + <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: </p> + <pre> ... <br> DEBUG(std::cerr << "I am here!\n");<br> ...<br></pre> + <p> Then you can run your pass like this:</p> + <p> </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> + <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> + <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> + <p><!-- _______________________________________________________________________ --> </p> +</ul> +<h4><a name="DEBUG_TYPE"> |