diff options
| author | Misha Brukman <brukman+llvm@gmail.com> | 2004-01-15 00:14:41 +0000 |
|---|---|---|
| committer | Misha Brukman <brukman+llvm@gmail.com> | 2004-01-15 00:14:41 +0000 |
| commit | 13fd15ccbdd9a1b16e561eb5c989cf092b2b5382 (patch) | |
| tree | 0f884a1ae61c0bcbcb6d38b24fa57bb3518921d2 /docs/ProgrammersManual.html | |
| parent | 5a141db9d847c4e44fc3c5b079195bca462bf8e1 (diff) | |
* Conform to HTML 4.01 strict DTD
* Use stylesheets instead of hard-coding formatting
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@10868 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/ProgrammersManual.html')
| -rw-r--r-- | docs/ProgrammersManual.html | 2720 |
1 files changed, 1438 insertions, 1282 deletions
diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 56751e2bd4..dfd8a20128 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -1,20 +1,18 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>LLVM Programmer's Manual</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> </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> +<body> + +<div class="doc_title"> + LLVM Programmer's Manual +</div> + <ol> - <li><a href="#introduction">Introduction</a> </li> + <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><!-- @@ -82,29 +80,25 @@ with another <tt>Value</tt></a> </li> </li> <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a> <ul> - <li><a href="#Value">The <tt>Value</tt> class</a> + <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="#User">The <tt>User</tt> class</a> + <li><a href="#Instruction">The <tt>Instruction</tt> class</a> + <ul> + <li><a href="#GetElementPtrInst">The <tt>GetElementPtrInst</tt> + class</a></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><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> @@ -125,779 +119,874 @@ class</a> </li> </li> <li>Important iterator invalidation semantics to be aware of </li> </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> </p> </li> </ol> + +<div class="doc_text"> + <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> +</div> + <!-- *********************************************************************** --> -<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> +<div class="doc_section"> + <a name="introduction">Introduction </a> +</div> <!-- *********************************************************************** --> -This document is meant to highlight some of the important classes and + +<div class="doc_text"> + +<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 +code.</p> + +<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> + +<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> + +</div> + <!-- *********************************************************************** --> -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), +<div class="doc_section"> + <a name="general">General Information</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>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> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="stl">The C++ Standard Template Library</a> +</div> + +<div class="doc_text"> + +<p>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 +can get, so it will not be discussed in this document.</p> + +<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> + +<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> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="stl">Other useful references</a> +</div> + +<div class="doc_text"> + +<p>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/%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> +</ol> + +</div> + <!-- *********************************************************************** --> -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. +<div class="doc_section"> + <a name="apis">Important and useful LLVM APIs</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>Here we highlight some LLVM APIs that are generally useful and good to +know about when writing transformations.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="isa">The isa<>, cast<> and dyn_cast<> templates</a> +</div> + +<div class="doc_text"> + +<p>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> +file (note that you very rarely have to include this file directly).</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).</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: + + <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> + + </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: + + <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> + + <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> + </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> + + <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> - <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> + + <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> -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> + +<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 +<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> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt> option</a> +</div> + +<div class="doc_text"> + +<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 +across).</p> + +<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> + +<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> - <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 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"> -<hr size="1">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> </p> + +<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 +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> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE()</tt> and + the <tt>-debug-only</tt> option</a> +</div> + +<div class="doc_text"> + +<p>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> ...<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> - <p> Then you can run your pass like this:</p> - <p> </p> + +<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> - <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 than "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, for example, all debug information for -instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>, + +<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 than "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, for example, all debug information +for instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>, even if the source lives in multiple files.</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="Statistic">The <tt>Statistic</tt> -template & <tt>-stats</tt> option</a> </b></font></td> - </tr> - </tbody> -</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 keep 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> - <p> There are many examples of <tt>Statistic</tt> uses, but the basics -of using it are as follows:</p> - <p> </p> - <ol> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="Statistic">The <tt>Statistic</tt> template & <tt>-stats</tt> + option</a> +</div> + +<div class="doc_text"> + +<p>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 +keep 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> + +<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> + +<p>There are many examples of <tt>Statistic</tt> uses, but the basics of using +it are as follows:</p> + +<ol> <li>Define your statistic like this: - <p> </p> <pre>static Statistic<> NumXForms("mypassname", "The # of times I did stuff");<br></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> - <p> </p> - </li> + + <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: - <p> </p> <pre> ++NumXForms; // I did stuff<br></pre> - <p> </p> </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> - <p> </p> |