diff options
| author | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
|---|---|---|
| committer | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
| commit | e2c3a49c8029ebd9ef530101cc24c66562e3dff5 (patch) | |
| tree | 91bf9600cc8df90cf99751a8f8bafc317cffc91e /docs/ProgrammersManual.html | |
| parent | c10b5afbe8138b0fdf3af4ed3e1ddf96cf3cb4cb (diff) | |
Revert r103213. It broke several sections of live website.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103219 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/ProgrammersManual.html')
| -rw-r--r-- | docs/ProgrammersManual.html | 3950 |
1 files changed, 3950 insertions, 0 deletions
diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html new file mode 100644 index 0000000000..46fd33f40d --- /dev/null +++ b/docs/ProgrammersManual.html @@ -0,0 +1,3950 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <meta http-equiv="Content-type" content="text/html;charset=UTF-8"> + <title>LLVM Programmer's Manual</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<div class="doc_title"> + LLVM Programmer's Manual +</div> + +<ol> + <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></li> +<!-- + <li>The <tt>-time-passes</tt> option</li> + <li>How to use the LLVM Makefile system</li> + <li>How to write a regression test</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> + <li><a href="#string_apis">Passing strings (the <tt>StringRef</tt> +and <tt>Twine</tt> classes)</a> + <ul> + <li><a href="#StringRef">The <tt>StringRef</tt> class</a> </li> + <li><a href="#Twine">The <tt>Twine</tt> class</a> </li> + </ul> + </li> + <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> +and the <tt>-debug-only</tt> option</a> </li> + </ul> + </li> + <li><a href="#Statistic">The <tt>Statistic</tt> class & <tt>-stats</tt> +option</a></li> +<!-- + <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="#datastructure">Picking the Right Data Structure for a Task</a> + <ul> + <li><a href="#ds_sequential">Sequential Containers (std::vector, std::list, etc)</a> + <ul> + <li><a href="#dss_fixedarrays">Fixed Size Arrays</a></li> + <li><a href="#dss_heaparrays">Heap Allocated Arrays</a></li> + <li><a href="#dss_smallvector">"llvm/ADT/SmallVector.h"</a></li> + <li><a href="#dss_vector"><vector></a></li> + <li><a href="#dss_deque"><deque></a></li> + <li><a href="#dss_list"><list></a></li> + <li><a href="#dss_ilist">llvm/ADT/ilist.h</a></li> + <li><a href="#dss_other">Other Sequential Container Options</a></li> + </ul></li> + <li><a href="#ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a> + <ul> + <li><a href="#dss_sortedvectorset">A sorted 'vector'</a></li> + <li><a href="#dss_smallset">"llvm/ADT/SmallSet.h"</a></li> + <li><a href="#dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a></li> + <li><a href="#dss_denseset">"llvm/ADT/DenseSet.h"</a></li> + <li><a href="#dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a></li> + <li><a href="#dss_set"><set></a></li> + <li><a href="#dss_setvector">"llvm/ADT/SetVector.h"</a></li> + <li><a href="#dss_uniquevector">"llvm/ADT/UniqueVector.h"</a></li> + <li><a href="#dss_otherset">Other Set-Like ContainerOptions</a></li> + </ul></li> + <li><a href="#ds_map">Map-Like Containers (std::map, DenseMap, etc)</a> + <ul> + <li><a href="#dss_sortedvectormap">A sorted 'vector'</a></li> + <li><a href="#dss_stringmap">"llvm/ADT/StringMap.h"</a></li> + <li><a href="#dss_indexedmap">"llvm/ADT/IndexedMap.h"</a></li> + <li><a href="#dss_densemap">"llvm/ADT/DenseMap.h"</a></li> + <li><a href="#dss_valuemap">"llvm/ADT/ValueMap.h"</a></li> + <li><a href="#dss_map"><map></a></li> + <li><a href="#dss_othermap">Other Map-Like Container Options</a></li> + </ul></li> + <li><a href="#ds_string">String-like containers</a> + <!--<ul> + todo + </ul>--></li> + <li><a href="#ds_bit">BitVector-like containers</a> + <ul> + <li><a href="#dss_bitvector">A dense bitvector</a></li> + <li><a href="#dss_smallbitvector">A "small" dense bitvector</a></li> + <li><a href="#dss_sparsebitvector">A sparse bitvector</a></li> + </ul></li> + </ul> + </li> + <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> + <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> + <li><a href="#iterate_preds">Iterating over predecessors & +successors of blocks</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> + <li><a href="#schanges_deletingGV">Deleting <tt>GlobalVariable</tt>s</a> </li> + </ul> + </li> + <li><a href="#create_types">How to Create Types</a></li> +<!-- + <li>Working with the Control Flow Graph + <ul> + <li>Accessing predecessors and successors of a <tt>BasicBlock</tt> + <li> + <li> + </ul> +--> + </ul> + </li> + + <li><a href="#threading">Threads and LLVM</a> + <ul> + <li><a href="#startmultithreaded">Entering and Exiting Multithreaded Mode + </a></li> + <li><a href="#shutdown">Ending execution with <tt>llvm_shutdown()</tt></a></li> + <li><a href="#managedstatic">Lazy initialization with <tt>ManagedStatic</tt></a></li> + <li><a href="#llvmcontext">Achieving Isolation with <tt>LLVMContext</tt></a></li> + <li><a href="#jitthreading">Threads and the JIT</a></li> + </ul> + </li> + + <li><a href="#advanced">Advanced Topics</a> + <ul> + <li><a href="#TypeResolve">LLVM Type Resolution</a> + <ul> + <li><a href="#BuildRecType">Basic Recursive Type Construction</a></li> + <li><a href="#refineAbstractTypeTo">The <tt>refineAbstractTypeTo</tt> method</a></li> + <li><a href="#PATypeHolder">The PATypeHolder Class</a></li> + <li><a href="#AbstractTypeUser">The AbstractTypeUser Class</a></li> + </ul></li> + + <li><a href="#SymbolTable">The <tt>ValueSymbolTable</tt> and <tt>TypeSymbolTable</tt> classes</a></li> + <li><a href="#UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a></li> + </ul></li> + + <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a> + <ul> + <li><a href="#Type">The <tt>Type</tt> class</a> </li> + <li><a href="#Module">The <tt>Module</tt> class</a></li> + <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></li> + <li><a href="#Constant">The <tt>Constant</tt> class</a> + <ul> + <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a> + <ul> + <li><a href="#Function">The <tt>Function</tt> class</a></li> + <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li><a href="#BasicBlock">The <tt>BasicBlock</tt> class</a></li> + <li><a href="#Argument">The <tt>Argument</tt> class</a></li> + </ul> + </li> + </ul> + </li> +</ol> + +<div class="doc_author"> + <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>, + <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>, + <a href="mailto:ggreif@gmail.com">Gabor Greif</a>, + <a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a>, + <a href="mailto:rspencer@x10sys.com">Reid Spencer</a> and + <a href="mailto:owen@apple.com">Owen Anderson</a></p> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="introduction">Introduction </a> +</div> +<!-- *********************************************************************** --> + +<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> + +<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> + +</div> + +<!-- *********************************************************************** --> +<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> + +<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 Standard Library +Reference that rivals Dinkumware's, and is unfortunately no longer free since the +book has been 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> + +<li><a href="http://64.78.49.204/"> +Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0 (even better, get +the book).</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"> + +<ol> +<li><a href="http://www.psc.edu/%7Esemke/cvs_branches.html">CVS +Branch and Tag Primer</a></li> +<li><a href="http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html">Using +static and shared libraries across platforms</a></li> +</ol> + +</div> + +<!-- *********************************************************************** --> +<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 <tt>isa<></tt>, <tt>cast<></tt> and + <tt>dyn_cast<></tt> 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>llvm/Support/Casting.h</tt></a> +file (note that you very rarely have to include this file directly).</p> + +<dl> + <dt><tt>isa<></tt>: </dt> + + <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).</p> + </dd> + + <dt><tt>cast<></tt>: </dt> + + <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 class, 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> + +<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> + operator.</p> + + </dd> + + <dt><tt>dyn_cast<></tt>:</dt> + + <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:</p> + +<div class="doc_code"> +<pre> +if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) { + // <i>...</i> +} +</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 + 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> + + </dd> + + <dt><tt>cast_or_null<></tt>: </dt> + + <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.</p></dd> + + <dt><tt>dyn_cast_or_null<></tt>: </dt> + + <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.</p></dd> + +</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 +<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="string_apis">Passing strings (the <tt>StringRef</tt> +and <tt>Twine</tt> classes)</a> +</div> + +<div class="doc_text"> + +<p>Although LLVM generally does not do much string manipulation, we do have +several important APIs which take strings. Two important examples are the +Value class -- which has names for instructions, functions, etc. -- and the +StringMap class which is used extensively in LLVM and Clang.</p> + +<p>These are generic classes, and they need to be able to accept strings which +may have embedded null characters. Therefore, they cannot simply take +a <tt>const char *</tt>, and taking a <tt>const std::string&</tt> requires +clients to perform a heap allocation which is usually unnecessary. Instead, +many LLVM APIs use a <tt>const StringRef&</tt> or a <tt>const +Twine&</tt> for passing strings efficiently.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="StringRef">The <tt>StringRef</tt> class</a> +</div> + +<div class="doc_text"> + +<p>The <tt>StringRef</tt> data type represents a reference to a constant string +(a character array and a length) and supports the common operations available +on <tt>std:string</tt>, but does not require heap allocation.</p> + +<p>It can be implicitly constructed using a C style null-terminated string, +an <tt>std::string</tt>, or explicitly with a character pointer and length. +For example, the <tt>StringRef</tt> find function is declared as:</p> + +<div class="doc_code"> + iterator find(const StringRef &Key); +</div> + +<p>and clients can call it using any one of:</p> + +<div class="doc_code"> +<pre> + Map.find("foo"); <i>// Lookup "foo"</i> + Map.find(std::string("bar")); <i>// Lookup "bar"</i> + Map.find(StringRef("\0baz", 4)); <i>// Lookup "\0baz"</i> +</pre> +</div> + +<p>Similarly, APIs which need to return a string may return a <tt>StringRef</tt> +instance, which can be used directly or converted to an <tt>std::string</tt> +using the <tt>str</tt> member function. See +"<tt><a href="/doxygen/classllvm_1_1StringRef_8h-source.html">llvm/ADT/StringRef.h</a></tt>" +for more information.</p> + +<p>You should rarely use the <tt>StringRef</tt> class directly, because it contains +pointers to external memory it is not generally safe to store an instance of the +class (unless you know that the external storage will not be freed).</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="Twine">The <tt>Twine</tt> class</a> +</div> + +<div class="doc_text"> + +<p>The <tt>Twine</tt> class is an efficient way for APIs to accept concatenated +strings. For example, a common LLVM paradigm is to name one instruction based on +the name of another instruction with a suffix, for example:</p> + +<div class="doc_code"> +<pre> + New = CmpInst::Create(<i>...</i>, SO->getName() + ".cmp"); +</pre> +</div> + +<p>The <tt>Twine</tt> class is effectively a +lightweight <a href="http://en.wikipedia.org/wiki/Rope_(computer_science)">rope</a> +which points to temporary (stack allocated) objects. Twines can be implicitly +constructed as the result of the plus operator applied to strings (i.e., a C +strings, an <tt>std::string</tt>, or a <tt>StringRef</tt>). The twine delays the +actual concatenation of strings until it is actually required, at which point +it can be efficiently rendered directly into a character array. This avoids +unnecessary heap allocation involved in constructing the temporary results of +string concatenation. See +"<tt><a href="/doxygen/classllvm_1_1Twine_8h-source.html">llvm/ADT/Twine.h</a></tt>" +for more information.</p> + +<p>As with a <tt>StringRef</tt>, <tt>Twine</tt> objects point to external memory +and should almost never be stored or mentioned directly. They are intended +solely for use when defining a function which should be able to efficiently +accept concatenated strings.</p> + +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="DEBUG">The <tt>DEBUG()</tt> macro and <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">llvm/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> + +<div class="doc_code"> +<pre> +DEBUG(errs() << "I am here!\n"); +</pre> +</div> + +<p>Then you can run your pass like this:</p> + +<div class="doc_code"> +<pre> +$ opt < a.bc > /dev/null -mypass +<i><no output></i> +$ 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 +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> + +<div class="doc_code"> +<pre> +#undef DEBUG_TYPE +DEBUG(errs() << "No debug type\n"); +#define DEBUG_TYPE "foo" +DEBUG(errs() << "'foo' debug type\n"); +#undef DEBUG_TYPE +#define DEBUG_TYPE "bar" +DEBUG(errs() << "'bar' debug type\n")); +#undef DEBUG_TYPE +#define DEBUG_TYPE "" +DEBUG(errs() << "No debug type (2)\n"); +</pre> +</div> + +<p>Then you can run your pass like this:</p> + +<div class="doc_code"> +<pre> +$ opt < a.bc > /dev/null -mypass +<i><no output></i> +$ 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 +you <tt>#include "llvm/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>The <tt>DEBUG_WITH_TYPE</tt> macro is also available for situations where you +would like to set <tt>DEBUG_TYPE</tt>, but only for one specific <tt>DEBUG</tt> +statement. It takes an additional first parameter, which is the type to use. For +example, the preceding example could be written as:</p> + + +<div class="doc_code"> +<pre> +DEBUG_WITH_TYPE("", errs() << "No debug type\n"); +DEBUG_WITH_TYPE("foo", errs() << "'foo' debug type\n"); +DEBUG_WITH_TYPE("bar", errs() << "'bar' debug type\n")); +DEBUG_WITH_TYPE("", errs() << "No debug type (2)\n"); +</pre> +</div> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="Statistic">The <tt>Statistic</tt> class & <tt>-stats</tt> + option</a> +</div> + +<div class="doc_text"> + +<p>The "<tt><a +href="/doxygen/Statistic_8h-source.html">llvm/ADT/Statistic.h</a></tt>" file +provides a class 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> class 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><p>Define your statistic like this:</p> + +<div class="doc_code"> +<pre> +#define <a href="#DEBUG_TYPE">DEBUG_TYPE</a> "mypassname" <i>// This goes before any #includes.</i> +STATISTIC(NumXForms, "The # of times I did stuff"); +</pre> +</div> + + <p>The <tt>STATISTIC</tt> macro defines a static variable, whose name is + specified by the first argument. The pass name is taken from the DEBUG_TYPE + macro, and the description is taken from the second argument. The variable + defined ("NumXForms" in this case) acts like an unsigned integer.</p></li> + + <li><p>Whenever you make a transformation, bump the counter:</p> + +<div class="doc_code"> +<pre> +++NumXForms; // <i>I did stuff!</i> +</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> + +<div class="doc_code"> +<pre> +$ opt -stats -mypassname < program.bc > /dev/null +<i>... statistics output ...</i> +</pre> +</div> + + <p> When running <tt>opt</tt> on a C file from the SPEC benchmark +suite, it gives a report that looks like this:</p> + +<div class="doc_code"> +<pre> + 7646 bitcodewriter - Number of normal instructions + 725 bitcodewriter - Number of oversized instructions + 129996 bitcodewriter - Number of bitcode 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 +maintainable and useful.</p> + +</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/Ma |