diff options
Diffstat (limited to 'docs/ProgrammersManual.html')
| -rw-r--r-- | docs/ProgrammersManual.html | 324 |
1 files changed, 164 insertions, 160 deletions
diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index b29c582612..060bbb6d91 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -215,7 +215,7 @@ with another <tt>Value</tt></a> </li> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>This document is meant to highlight some of the important classes and interfaces available in the LLVM source-base. This manual is not @@ -247,19 +247,17 @@ href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.</p> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <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> - <!-- ======================================================================= --> <h3> <a name="stl">The C++ Standard Template Library</a> </h3> -<div class="doc_text"> +<div> <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 @@ -309,7 +307,7 @@ to write maintainable code more than where to put your curly braces.</p> <a name="stl">Other useful references</a> </h3> -<div class="doc_text"> +<div> <ol> <li><a href="http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html">Using @@ -318,26 +316,26 @@ static and shared libraries across platforms</a></li> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="apis">Important and useful LLVM APIs</a> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>Here we highlight some LLVM APIs that are generally useful and good to know about when writing transformations.</p> -</div> - <!-- ======================================================================= --> <h3> <a name="isa">The <tt>isa<></tt>, <tt>cast<></tt> and <tt>dyn_cast<></tt> templates</a> </h3> -<div class="doc_text"> +<div> <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> @@ -447,7 +445,7 @@ are lots of examples in the LLVM source base.</p> and <tt>Twine</tt> classes)</a> </h3> -<div class="doc_text"> +<div> <p>Although LLVM generally does not do much string manipulation, we do have several important APIs which take strings. Two important examples are the @@ -461,14 +459,12 @@ clients to perform a heap allocation which is usually unnecessary. Instead, many LLVM APIs use a <tt>StringRef</tt> or a <tt>const Twine&</tt> for passing strings efficiently.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="StringRef">The <tt>StringRef</tt> class</a> </h4> -<div class="doc_text"> +<div> <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 @@ -508,7 +504,7 @@ small and pervasive enough in LLVM that it should always be passed by value.</p> <a name="Twine">The <tt>Twine</tt> class</a> </h4> -<div class="doc_text"> +<div> <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 @@ -539,13 +535,14 @@ accept concatenated strings.</p> </div> +</div> <!-- ======================================================================= --> <h3> <a name="DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt> option</a> </h3> -<div class="doc_text"> +<div> <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 @@ -591,15 +588,13 @@ enable or disable it directly in gdb. Just use "<tt>set DebugFlag=0</tt>" or program hasn't been started yet, you can always just run it with <tt>-debug</tt>.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt> and the <tt>-debug-only</tt> option</a> </h4> -<div class="doc_text"> +<div> <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 @@ -667,13 +662,15 @@ DEBUG_WITH_TYPE("", errs() << "No debug type (2)\n"); </div> +</div> + <!-- ======================================================================= --> <h3> <a name="Statistic">The <tt>Statistic</tt> class & <tt>-stats</tt> option</a> </h3> -<div class="doc_text"> +<div> <p>The "<tt><a href="/doxygen/Statistic_8h-source.html">llvm/ADT/Statistic.h</a></tt>" file @@ -772,7 +769,7 @@ maintainable and useful.</p> <a name="ViewGraph">Viewing graphs while debugging code</a> </h3> -<div class="doc_text"> +<div> <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 @@ -816,13 +813,15 @@ attributes, then you can <tt>call DAG.clearGraphAttrs()</tt>. </p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="datastructure">Picking the Right Data Structure for a Task</a> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>LLVM has a plethora of data structures in the <tt>llvm/ADT/</tt> directory, and we commonly use STL data structures. This section describes the trade-offs @@ -878,24 +877,21 @@ elements (but could contain many), for example, it's much better to use . Doing so avoids (relatively) expensive malloc/free calls, which dwarf the cost of adding the elements to the container. </p> -</div> - <!-- ======================================================================= --> <h3> <a name="ds_sequential">Sequential Containers (std::vector, std::list, etc)</a> </h3> -<div class="doc_text"> +<div> There are a variety of sequential containers available for you, based on your needs. Pick the first in this section that will do what you want. -</div> <!-- _______________________________________________________________________ --> <h4> <a name="dss_arrayref">llvm/ADT/ArrayRef.h</a> </h4> -<div class="doc_text"> +<div> <p>The llvm::ArrayRef class is the preferred class to use in an interface that accepts a sequential list of elements in memory and just reads from them. By taking an ArrayRef, the API can be passed a fixed size array, an std::vector, @@ -910,7 +906,7 @@ needs. Pick the first in this section that will do what you want. <a name="dss_fixedarrays">Fixed Size Arrays</a> </h4> -<div class="doc_text"> +<div> <p>Fixed size arrays are very simple and very fast. They are good if you know exactly how many elements you have, or you have a (low) upper bound on how many you have.</p> @@ -921,7 +917,7 @@ you have.</p> <a name="dss_heaparrays">Heap Allocated Arrays</a> </h4> -<div class="doc_text"> +<div> <p>Heap allocated arrays (new[] + delete[]) are also simple. They are good if the number of elements is variable, if you know how many elements you will need before the array is allocated, and if the array is usually large (if not, @@ -937,7 +933,7 @@ construct those elements actually used).</p> <a name="dss_smallvector">"llvm/ADT/SmallVector.h"</a> </h4> -<div class="doc_text"> +<div> <p><tt>SmallVector<Type, N></tt> is a simple class that looks and smells just like <tt>vector<Type></tt>: it supports efficient iteration, lays out elements in memory order (so you can @@ -966,7 +962,7 @@ SmallVectors are most useful when on the stack.</p> <a name="dss_vector"><vector></a> </h4> -<div class="doc_text"> +<div> <p> std::vector is well loved and respected. It is useful when SmallVector isn't: when the size of the vector is often large (thus the small optimization will @@ -1008,7 +1004,7 @@ the loop.</p> <a name="dss_deque"><deque></a> </h4> -<div class="doc_text"> +<div> <p>std::deque is, in some senses, a generalized version of std::vector. Like std::vector, it provides constant time random access and other similar properties, but it also provides efficient access to the front of the list. It @@ -1024,7 +1020,7 @@ something cheaper.</p> <a name="dss_list"><list></a> </h4> -<div class="doc_text"> +<div> <p>std::list is an extremely inefficient class that is rarely useful. It performs a heap allocation for every element inserted into it, thus having an extremely high constant factor, particularly for small data types. std::list @@ -1042,7 +1038,7 @@ not invalidate iterator or pointers to other elements in the list.</p> <a name="dss_ilist">llvm/ADT/ilist.h</a> </h4> -<div class="doc_text"> +<div> <p><tt>ilist<T></tt> implements an 'intrusive' doubly-linked list. It is intrusive, because it requires the element to store and provide access to the prev/next pointers for the list.</p> @@ -1072,7 +1068,7 @@ Related classes of interest are explained in the following subsections: <a name="dss_ilist_traits">ilist_traits</a> </h4> -<div class="doc_text"> +<div> <p><tt>ilist_traits<T></tt> is <tt>ilist<T></tt>'s customization mechanism. <tt>iplist<T></tt> (and consequently <tt>ilist<T></tt>) publicly derive from this traits class.</p> @@ -1083,7 +1079,7 @@ publicly derive from this traits class.</p> <a name="dss_iplist">iplist</a> </h4> -<div class="doc_text"> +<div> <p><tt>iplist<T></tt> is <tt>ilist<T></tt>'s base and as such supports a slightly narrower interface. Notably, inserters from <tt>T&</tt> are absent.</p> @@ -1097,7 +1093,7 @@ used for a wide variety of customizations.</p> <a name="dss_ilist_node">llvm/ADT/ilist_node.h</a> </h4> -<div class="doc_text"> +<div> <p><tt>ilist_node<T></tt> implements a the forward and backward links that are expected by the <tt>ilist<T></tt> (and analogous containers) in the default manner.</p> @@ -1112,7 +1108,7 @@ in the default manner.</p> <a name="dss_ilist_sentinel">Sentinels</a> </h4> -<div class="doc_text"> +<div> <p><tt>ilist</tt>s have another specialty that must be considered. To be a good citizen in the C++ ecosystem, it needs to support the standard container operations, such as <tt>begin</tt> and <tt>end</tt> iterators, etc. Also, the @@ -1150,7 +1146,7 @@ field in the ghostly sentinel which can be legally accessed.</p> <a name="dss_other">Other Sequential Container options</a> </h4> -<div class="doc_text"> +<div> <p>Other STL containers are available, such as std::string.</p> <p>There are also various STL adapter classes such as std::queue, @@ -1159,27 +1155,25 @@ underlying container but don't affect the cost of the container itself.</p> </div> +</div> <!-- ======================================================================= --> <h3> <a name="ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a> </h3> -<div class="doc_text"> +<div> <p>Set-like containers are useful when you need to canonicalize multiple values into a single representation. There are several different choices for how to do this, providing various trade-offs.</p> -</div> - - <!-- _______________________________________________________________________ --> <h4> <a name="dss_sortedvectorset">A sorted 'vector'</a> </h4> -<div class="doc_text"> +<div> <p>If you intend to insert a lot of elements, then do a lot of queries, a great approach is to use a vector (or other sequential container) with @@ -1201,7 +1195,7 @@ efficiently queried with a standard binary or radix search.</p> <a name="dss_smallset">"llvm/ADT/SmallSet.h"</a> </h4> -<div class="doc_text"> +<div> <p>If you have a set-like data structure that is usually small and whose elements are reasonably small, a <tt>SmallSet<Type, N></tt> is a good choice. This set @@ -1224,7 +1218,7 @@ and erasing, but does not support iteration.</p> <a name="dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a> </h4> -<div class="doc_text"> +<div> <p>SmallPtrSet has all the advantages of <tt>SmallSet</tt> (and a <tt>SmallSet</tt> of pointers is transparently implemented with a <tt>SmallPtrSet</tt>), but also supports iterators. If @@ -1244,7 +1238,7 @@ visited in sorted order.</p> <a name="dss_denseset">"llvm/ADT/DenseSet.h"</a> </h4> -<div class="doc_text"> +<div> <p> DenseSet is a simple quadratically probed hash table. It excels at supporting @@ -1263,7 +1257,7 @@ href="#dss_densemap">DenseMap</a> has. <a name="dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a> </h4> -<div class="doc_text"> +<div> <p> FoldingSet is an aggregate class that is really good at uniquing @@ -1300,7 +1294,7 @@ elements. <a name="dss_set"><set></a> </h4> -<div class="doc_text"> +<div> <p><tt>std::set</tt> is a reasonable all-around set class, which is decent at many things but great at nothing. std::set allocates memory for each element @@ -1325,7 +1319,7 @@ std::set is almost never a good choice.</p> <a name="dss_setvector">"llvm/ADT/SetVector.h"</a> </h4> -<div class="doc_text"> +<div> <p>LLVM's SetVector<Type> is an adapter class that combines your choice of a set-like container along with a <a href="#ds_sequential">Sequential Container</a>. The important property @@ -1365,7 +1359,7 @@ heap traffic.</p> <a name="dss_uniquevector">"llvm/ADT/UniqueVector.h"</a> </h4> -<div class="doc_text"> +<div> <p> UniqueVector is similar to <a href="#dss_setvector">SetVector</a>, but it @@ -1385,7 +1379,7 @@ factors, and produces a lot of malloc traffic. It should be avoided.</p> <a name="dss_otherset">Other Set-Like Container Options</a> </h4> -<div class="doc_text"> +<div> <p> The STL provides several other options, such as std::multiset and the various @@ -1401,22 +1395,23 @@ better.</p> </div> +</div> + <!-- ======================================================================= --> <h3> <a name="ds_map">Map-Like Containers (std::map, DenseMap, etc)</a> </h3> -<div class="doc_text"> +<div> Map-like containers are useful when you want to associate data to a key. As usual, there are a lot of different ways to do this. :) -</div> <!-- _______________________________________________________________________ --> <h4> <a name="dss_sortedvectormap">A sorted 'vector'</a> </h4> -<div class="doc_text"> +<div> <p> If your usage pattern follows a strict insert-then-query approach, you can @@ -1433,7 +1428,7 @@ vectors for sets. <a name="dss_stringmap">"llvm/ADT/StringMap.h"</a> </h4> -<div class="doc_text"> +<div> <p> Strings are commonly used as keys in maps, and they are difficult to support @@ -1467,7 +1462,7 @@ copies a string if a value is inserted into the table.</p> <a name="dss_indexedmap">"llvm/ADT/IndexedMap.h"</a> </h4> -<div class="doc_text"> +<div> <p> IndexedMap is a specialized container for mapping small dense integers (or values that can be mapped to small dense integers) to some other type. It is @@ -1487,7 +1482,7 @@ virtual register ID).</p> <a name="dss_densemap">"llvm/ADT/DenseMap.h"</a> </h4> -<div class="doc_text"> +<div> <p> DenseMap is a simple quadratically probed hash table. It excels at supporting @@ -1513,7 +1508,7 @@ inserted into the map) that it needs internally.</p> <a name="dss_valuemap">"llvm/ADT/ValueMap.h"</a> </h4> -<div class="doc_text"> +<div> <p> ValueMap is a wrapper around a <a href="#dss_densemap">DenseMap</a> mapping @@ -1530,7 +1525,7 @@ a <code>Config</code> parameter to the ValueMap template.</p> <a name="dss_intervalmap">"llvm/ADT/IntervalMap.h"</a> </h4> -<div class="doc_text"> +<div> <p> IntervalMap is a compact map for small keys and values. It maps key intervals instead of single keys, and it will automatically coalesce adjacent @@ -1547,7 +1542,7 @@ as STL iterators. The heavyweight iterators allow a smaller data structure.</p> <a name="dss_map"><map></a> </h4> -<div class="doc_text"> +<div> <p> std::map has similar characteristics to <a href="#dss_set">std::set</a>: it uses @@ -1567,7 +1562,7 @@ another element takes place).</p> <a name="dss_inteqclasses">"llvm/ADT/IntEqClasses.h"</a> </h4> -<div class="doc_text"> +<div> <p>IntEqClasses provides a compact representation of equivalence classes of small integers. Initially, each integer in the range 0..n-1 has its own @@ -1587,7 +1582,7 @@ it can be edited again.</p> <a name="dss_othermap">Other Map-Like Container Options</a> </h4> -<div class="doc_text"> +<div> <p> The STL provides several other options, such as std::multimap and the various @@ -1601,12 +1596,14 @@ always better.</p> </div> +</div> + <!-- ======================================================================= --> <h3> <a name="ds_string">String-like containers</a> </h3> -<div class="doc_text"> +<div> <p> TODO: const char* vs stringref vs smallstring vs std::string. Describe twine, @@ -1620,7 +1617,7 @@ xref to #string_apis. <a name="ds_bit">Bit storage containers (BitVector, SparseBitVector)</a> </h3> -<div class="doc_text"> +<div> <p>Unlike the other containers, there are only two bit storage containers, and choosing when to use each is relatively straightforward.</p> @@ -1630,14 +1627,13 @@ implementation in many common compilers (e.g. commonly available versions of GCC) is extremely inefficient and 2) the C++ standards committee is likely to deprecate this container and/or change it significantly somehow. In any case, please don't use it.</p> -</div> <!-- _______________________________________________________________________ --> <h4> <a name="dss_bitvector">BitVector</a> </h4> -<div class="doc_text"> +<div> <p> The BitVector container provides a dynamic size set of bits for manipulation. It supports individual bit setting/testing, as well as set operations. The set operations take time O(size of bitvector), but operations are performed one word @@ -1652,7 +1648,7 @@ the number of set bits to be high (IE a dense set). <a name="dss_smallbitvector">SmallBitVector</a> </h4> -<div class="doc_text"> +<div> <p> The SmallBitVector container provides the same interface as BitVector, but it is optimized for the case where only a small number of bits, less than 25 or so, are needed. It also transparently supports larger bit counts, but @@ -1671,7 +1667,7 @@ and its operator[] does not provide an assignable lvalue. <a name="dss_sparsebitvector">SparseBitVector</a> </h4> -<div class="doc_text"> +<div> <p> The SparseBitVector container is much like BitVector, with one major difference: Only the bits that are set, are stored. This makes the SparseBitVector much more space efficient than BitVector when the set is sparse, @@ -1681,13 +1677,17 @@ universe). The downside to the SparseBitVector is that setting and testing of r </p> </div> +</div> + +</div> + <!-- *********************************************************************** --> <h2> <a name="common">Helpful Hints for Common Operations</a> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>This section describes how to perform some very simple transformations of LLVM code. This is meant to give examples of common idioms used, showing the @@ -1696,15 +1696,13 @@ you should also read about the main classes that you will be working with. The <a href="#coreclasses">Core LLVM Class Hierarchy Reference</a> contains details and descriptions of the main classes that you should know about.</p> -</div> - <!-- NOTE: this section should be heavy on example code --> <!-- ======================================================================= --> <h3> <a name="inspection">Basic Inspection and Traversal Routines</a> </h3> -<div class="doc_text"> +<div> <p>The LLVM compiler infrastructure have many different data structures that may be traversed. Following the example of the C++ standard template library, the @@ -1721,8 +1719,6 @@ on them, and it is easier to remember how to iterate. First we show a few common examples of the data structures that need to be traversed. Other data structures are traversed in very similar ways.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="iterate_function">Iterating over the </a><a @@ -1730,7 +1726,7 @@ structures are traversed in very similar ways.</p> href="#Function"><tt>Function</tt></a> </h4> -<div class="doc_text"> +<div> <p>It's quite common to have a <tt>Function</tt> instance that you'd like to transform in some way; in particular, you'd like to manipulate its @@ -1765,7 +1761,7 @@ exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.</p> href="#BasicBlock"><tt>BasicBlock</tt></a> </h4> -<div class="doc_text"> +<div> <p>Just like when dealing with <tt>BasicBlock</tt>s in <tt>Function</tt>s, it's easy to iterate over the individual instructions that make up @@ -1796,7 +1792,7 @@ basic block itself: <tt>errs() << *blk << "\n";</tt>.</p> href="#Function"><tt>Function</tt></a> </h4> -<div class="doc_text"> +<div> <p>If you're finding that you commonly iterate over a <tt>Function</tt>'s <tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s <tt>Instruction</tt>s, @@ -1841,7 +1837,7 @@ for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I) vice-versa)</a> </h4> -<div class="doc_text"> +<div> <p>Sometimes, it'll be useful to grab a reference (or pointer) to a class instance when all you've got at hand is an iterator. Well, extracting @@ -1918,7 +1914,7 @@ and <tt>operator*</tt> changed to return a pointer instead of a reference.</p> example</a> </h4> -<div class="doc_text"> +<div> <p>Say that you're writing a FunctionPass and would like to count all the locations in the entire module (that is, across every <tt>Function</tt>) where a @@ -1979,7 +1975,7 @@ class OurFunctionPass : public FunctionPass { <a name="calls_and_invokes">Treating calls and invokes the same way</a> </h4> -<div class="doc_text"> +<div> <p>You may have noticed that the previous example was a bit oversimplified in that it did not deal with call sites generated by 'invoke' instructions. In @@ -2006,7 +2002,7 @@ If you look at its definition, it has only a single pointer member.</p> <a name="iterate_chains">Iterating over def-use & use-def chains</a> </h4> -<div class="doc_text"> +<div> <p>Frequently, we might have an instance of the <a href="/doxygen/classllvm_1_1Value.html">Value Class</a> and we want to @@ -2068,7 +2064,7 @@ calling <tt>use/op_begin()</tt> on <tt>const Value*</tt>s or successors of blocks</a> </h4> -<div class="doc_text"> +<div> <p>Iterating over the predecessors and successors of a block is quite easy with the routines defined in <tt>"llvm/Support/CFG.h"</tt>. Just use code like @@ -2091,13 +2087,14 @@ succ_iterator/succ_begin/succ_end.</p> </div> +</div> <!-- ======================================================================= --> <h3> <a name="simplechanges">Making simple changes</a> </h3> -<div class="doc_text"> +<div> <p>There are some primitive transformation operations present in the LLVM infrastructure that are worth knowing about. When performing @@ -2105,15 +2102,13 @@ transformations, it's fairly common to manipulate the contents of basic blocks. This section describes some of the common methods for doing so and gives example code.</p> -</div> - <!--_______________________________________________________________________--> <h4> <a name="schanges_creating">Creating and inserting new <tt>Instruction</tt>s</a> </h4> -<div class="doc_text"> +<div> <p><i>Instantiating Instructions</i></p> @@ -2253,7 +2248,7 @@ Instruction* newInst = new Instruction(..., pi); <a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a> </h4> -<div class="doc_text"> +<div> <p>Deleting an instruction from an existing sequence of instructions that form a <a href="#BasicBlock"><tt>BasicBlock</tt></a> is very straight-forward: just @@ -2278,7 +2273,7 @@ block but not delete it, you can use the <tt>removeFromParent()</tt> method.</p> <tt>Value</tt></a> </h4> -<div class="doc_text"> +<div> <p><i>Replacing individual instructions</i></p> @@ -2343,7 +2338,7 @@ ReplaceInstWithValue, ReplaceInstWithInst --> <a name="schanges_deletingGV">Deleting <tt>GlobalVariable</tt>s</a> </h4> -<div class="doc_text"> +<div> <p>Deleting a global variable from a module is just as easy as deleting an Instruction. First, you must have a pointer to the global variable that you wish @@ -2360,12 +2355,14 @@ GV->eraseFromParent(); </div> +</div> + <!-- ======================================================================= --> <h3> <a name="create_types">How to Create Types</a> </h3> -<div class="doc_text"> +<div> <p>In generating IR, you may need some complex types. If you know these types statically, you can use <tt>TypeBuilder<...>::get()</tt>, defined @@ -2400,13 +2397,15 @@ comment</a> for more details.</p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="threading">Threads and LLVM</a> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p> This section describes the interaction of the LLVM APIs with multithreading, both on the part of client applications, and in the JIT, in the hosted @@ -2429,14 +2428,13 @@ compiler, consider compiling LLVM and LLVM-GCC in single-threaded mode, and using the resultant compiler to build a copy of LLVM with multithreading support. </p> -</div> <!-- ======================================================================= --> <h3> <a name="startmultithreaded">Entering and Exiting Multithreaded Mode</a> </h3> -<div class="doc_text"> +<div> <p> In order to properly protect its internal data structures while avoiding @@ -2473,7 +2471,7 @@ result in concurrent LLVM API calls. <a name="shutdown">Ending Execution with <tt>llvm_shutdown()</tt></a> </h3> -<div class="doc_text"> +<div> <p> When you are done using the LLVM APIs, you should call <tt>llvm_shutdown()</tt> to deallocate memory used for internal structures. This will also invoke @@ -2493,7 +2491,7 @@ destructor. <a name="managedstatic">Lazy Initialization with <tt>ManagedStatic</tt></a> </h3> -<div class="doc_text"> +<div> <p> <tt>ManagedStatic</tt> is a utility class in LLVM used to implement static initialization of static resources, such as the global type tables. Before the @@ -2522,7 +2520,7 @@ and only if you know what you're doing! <a name="llvmcontext">Achieving Isolation with <tt>LLVMContext</tt></a> </h3> -<div class="doc_text"> +<div> <p> <tt>LLVMContext</tt> is an opaque class in the LLVM API which clients can use to operate multiple, isolated instances of LLVM concurrently within the same @@ -2566,7 +2564,7 @@ isolation is not a concern. <a name="jitthreading">Threads and the JIT</a> </h3> -<div class="doc_text"> +<div> <p> LLVM's "eager" JIT compiler is safe to use in threaded programs. Multiple threads can call <tt>ExecutionEngine::getPointerToFunction()</tt> or @@ -2589,26 +2587,27 @@ access, but we suggest using only the eager JIT in threaded programs. </p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="advanced">Advanced Topics</a> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p> This section describes some of the advanced or obscure API's that most clients do not need to be aware of. These API's tend manage the inner workings of the LLVM system, and only need to be accessed in unusual circumstances. </p> -</div> <!-- ======================================================================= --> <h3> <a name="TypeResolve">LLVM Type Resolution</a> </h3> -<div class="doc_text"> +<div> <p> The LLVM type system has a very simple goal: allow clients to compare types for @@ -2637,14 +2636,12 @@ Third, a concrete type is a type that is not an abstract type (e.g. "<tt>{ i32, float }</tt>"). </p> -</div> - <!-- ______________________________________________________________________ --> <h4> <a name="BuildRecType">Basic Recursive Type Construction</a> </h4> -<div class="doc_text"> +<div> <p> Because the most common question is "how do I build a recursive type with LLVM", @@ -2700,7 +2697,7 @@ href="#PATypeHolder">PATypeHolder class</a>. <a name="refineAbstractTypeTo">The <tt>refineAbstractTypeTo</tt> method</a> </h4> -<div class="doc_text"> +<div> <p> The <tt>refineAbstractTypeTo</tt> method starts the type unification process. While this method is actually a member of the DerivedType class, it is most @@ -2730,7 +2727,7 @@ complex datastructures. <a name="PATypeHolder">The PATypeHolder Class</a> </h4> -<div class="doc_text"> +<div> <p> PATypeHolder is a form of a "smart pointer" for Type objects. When VMCore happily goes about nuking types that become isomorphic to existing types, it @@ -2752,7 +2749,7 @@ Type is maintained by PATypeHolder objects. <a name="AbstractTypeUser">The AbstractTypeUser Class</a> </h4> -<div class="doc_text"> +<div> <p> Some data structures need more to perform more complex updates when types get @@ -2766,6 +2763,7 @@ objects) can never be refined. </p> </div> +</div> <!-- ======================================================================= --> <h3> @@ -2773,7 +2771,7 @@ objects) can never be refined. <tt>TypeSymbolTable</tt> classes</a> </h3> -<div class="doc_text"> +<div> <p>The <tt><a href="http://llvm.org/doxygen/classllvm_1_1ValueSymbolTable.html"> ValueSymbolTable</a></tt> class provides a symbol table that the <a href="#Function"><tt>Function</tt></a> and <a href="#Module"> @@ -2808,7 +2806,7 @@ insert entries into the symbol table.</p> <a name="UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a> </h3> -<div class="doc_text"> +<div> <p>The <tt><a href="http://llvm.org/doxygen/classllvm_1_1User.html"> User</a></tt> class provides a basis for expressing the ownership of <tt>User</tt> towards other <tt><a href="http://llvm.org/doxygen/classllvm_1_1Value.html"> @@ -2823,14 +2821,13 @@ addition and removal.</p> </a> </h4> -<div class="doc_text"> +<div> <p> A subclass of <tt>User</tt> can choose between incorporating its <tt>Use</tt> objects or refer to them out-of-line by means of a pointer. A mixed variant (some <tt>Use</tt>s inline others hung off) is impractical and breaks the invariant that the <tt>Use</tt> objects belonging to the same <tt>User</tt> form a contiguous array. </p> -</div> <p> We have 2 different layouts in the <tt>User</tt> (sub)classes: @@ -2879,17 +2876,18 @@ enforce the following memory layouts:</p> <i>(In the above figures '<tt>P</tt>' stands for the <tt>Use**</tt> that is stored in each <tt>Use</tt> object in the member <tt>Use::Prev</tt>)</i> +</div> + <!-- ______________________________________________________________________ --> <h4> <a name="Waymarking">The waymarking algorithm</a> </h4> -<div class="doc_text"> +<div> <p> Since the <tt>Use</tt> objects are deprived of the direct (back)pointer to their <tt>User</tt> objects, there must be a fast and exact method to recover it. This is accomplished by the following scheme:</p> -</div> A bit-encoding in the 2 LSBits (least significant bits) of the <tt>Use::Prev</tt> allows to find the start of the <tt>User</tt> object: @@ -2920,15 +2918,16 @@ Only the significant number of bits need to be stored between the stops, so that the <i>worst case is 20 memory accesses</i> when there are 1000 <tt>Use</tt> objects associated with a <tt>User</tt>.</p> +</div> + <!-- ______________________________________________________________________ --> <h4> <a name="ReferenceImpl">Reference implementation</a> </h4> -<div class="doc_text"> +<div> <p> The following literate Haskell fragment demonstrates the concept:</p> -</div> <div class="doc_code"> <pre> @@ -3010,11 +3009,15 @@ And here is the result of <deepCheck identityProp>:</p> OK, passed 500 tests. </pre> +</div> + <!-- ______________________________________________________________________ --> <h4> <a name="Tagging">Tagging considerations</a> </h4> +<div> + <p> To maintain the invariant that the 2 LSBits of each <tt>Use**</tt> in <tt>Use</tt> never change after being set up, setters of <tt>Use::Prev</tt> must re-tag the @@ -3029,13 +3032,17 @@ the LSBit set. (Portability is relying on the fact that all known compilers plac </div> - <!-- *********************************************************************** --> +</div> + +</div> + +<!-- *********************************************************************** --> <h2> <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a> </h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p><tt>#include "<a href="/doxygen/Type_8h-source.html">llvm/Type.h</a>"</tt> <br>doxygen info: <a href="/doxygen/classllvm_1_1Type.html">Type Class</a></p> @@ -3044,14 +3051,12 @@ being inspected or transformed. The core LLVM classes are defined in header files in the <tt>include/llvm/</tt> directory, and implemented in the <tt>lib/VMCore</tt> directory.</p> -</div> - <!-- ======================================================================= --> <h3> <a name="Type">The <tt>Type</tt> class and Derived Types</a> </h3> -<div class="doc_text"> +<div> <p><tt>Type</tt> is a superclass of all type classes. Every <tt>Value</tt> has a <tt>Type</tt>. <tt>Type</tt> cannot be instantiated directly but only @@ -3066,14 +3071,13 @@ the <tt>lib/VMCore</tt> directory.</p> be performed with address equality of the Type Instance. That is, given two <tt>Type*</tt> values, the types are identical if the pointers are identical. </p> -</div> <!-- _______________________________________________________________________ --> <h4> <a name="m_Type">Important Public Methods</a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt>bool isIntegerTy() const</tt>: Returns true for any integer type.</li> @@ -3094,7 +3098,7 @@ the <tt>lib/VMCore</tt> directory.</p> <h4> <a name="derivedtypes">Important Derived Types</a> </h4> -<div class="doc_text"> +<div> <dl> <dt><tt>IntegerType</tt></dt> <dd>Subclass of DerivedType that represents integer types of any bit width. @@ -3156,14 +3160,14 @@ the <tt>lib/VMCore</tt> directory.</p> </dl> </div> - +</div> <!-- ======================================================================= --> <h3> <a name="Module">The <tt>Module</tt> class</a> </h3> -<div class="doc_text"> +<div> <p><tt>#include "<a href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt><br> doxygen info: @@ -3178,14 +3182,12 @@ href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few helpful member functions that try to make common operations easy.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="m_Module">Important Public Members of the <tt>Module</tt> class</a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt>Module::Module(std::string name = "")</tt></li> @@ -3284,13 +3286,14 @@ provide a name for it (probably based on the name of the translation unit).</p> </div> +</div> <!-- ======================================================================= --> <h3> <a name="Value">The <tt>Value</tt> class</a> </h3> -<div class="doc_text"> +<div> <p><tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt> <br> @@ -3341,14 +3344,12 @@ the class that represents this value. Although this may take some getting used to, it simplifies the representation and makes it easier to manipulate.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="m_Value">Important Public Members of the <tt>Value</tt> class</a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt>Value::use_iterator</tt> - Typedef for iterator over the @@ -3395,12 +3396,14 @@ Inst->replaceAllUsesWith(ConstVal); </div> +</div> + <!-- ======================================================================= --> <h3> <a name="User">The <tt>User</tt> class</a> </h3> -<div class="doc_text"> +<div> <p> <tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt><br> @@ -3419,14 +3422,12 @@ Single Assignment (SSA) form, there can only be one definition referred to, allowing this direct connection. This connection provides the use-def information in LLVM.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="m_User">Important Public Members of the <tt>User</tt> class</a> </h4> -<div class="doc_text"> +<div> <p>The <tt>User</tt> class exposes the operand list in two ways: through an index access interface and through an iterator based interface.</p> @@ -3449,12 +3450,14 @@ the operands of a <tt>User</tt>.</p></li> </div> +</div> + <!-- ======================================================================= --> <h3> <a name="Instruction">The <tt>Instruction</tt> class</a> </h3> -<div class="doc_text"> +<div> <p><tt>#include "</tt><tt><a href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt><br> @@ -3485,15 +3488,13 @@ href="#CmpInst">CmpInst</a></tt>). Unfortunately, the use of macros in this file confuses doxygen, so these enum values don't show up correctly in the <a href="/doxygen/classllvm_1_1Instruction.html">doxygen output</a>.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="s_Instruction"> Important Subclasses of the <tt>Instruction</tt> class </a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt><a name="BinaryOperator">BinaryOperator</a></tt> <p>This subclasses represents all two operand instructions whose operands @@ -3518,7 +3519,7 @@ this file confuses doxygen, so these enum values don't show up correctly in the </a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt> @@ -3538,12 +3539,14 @@ and it has no name</p></li> </div> +</div> + <!-- ======================================================================= --> <h3> <a name="Constant">The <tt>Constant</tt> class and subclasses</a> </h3> -<div class="doc_text"> +<div> <p>Constant represents a base class for different types of constants. It is subclassed by ConstantInt, ConstantArray, etc. for representing @@ -3551,11 +3554,9 @@ the various types of Constants. <a href="#GlobalValue">GlobalValue</a> is also a subclass, which represents the address of a global variable or function. </p> -</div> - <!-- _______________________________________________________________________ --> <h4>Important Subclasses of Constant</h4> -<div class="doc_text"> +<div> <ul> <li>ConstantInt : This subclass of Constant represents an integer constant of any width. @@ -3603,13 +3604,14 @@ a subclass, which represents the address of a global variable or function. </ul> </div> +</div> <!-- ======================================================================= --> <h3> <a name="GlobalValue">The <tt>GlobalValue</tt> class</a> </h3> -<div class="doc_text"> +<div> <p><tt>#include "<a href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt><br> @@ -3649,8 +3651,6 @@ dereference the pointer with <tt>GetElementPtrInst</tt> first, then its elements can be accessed. This is explained in the <a href="LangRef.html#globalvars">LLVM Language Reference Manual</a>.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="m_GlobalValue"> @@ -3658,7 +3658,7 @@ Language Reference Manual</a>.</p> </a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt>bool hasInternalLinkage() const</tt><br> @@ -3674,12 +3674,14 @@ GlobalValue is currently embedded into.</p></li> </div> +</div> + <!-- ======================================================================= --> <h3> <a name="Function">The <tt>Function</tt> class</a> </h3> -<div class="doc_text"> +<div> <p><tt>#include "<a href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt><br> doxygen @@ -3726,7 +3728,6 @@ href="#Argument"><tt>Argument</tt></a>s in the function body.</p> <p>Note that <tt>Function</tt> is a <a href="#GlobalValue">GlobalValue</a> and therefore also a <a href="#Constant">Constant</a>. The value of the function is its address (after linking) which is guaranteed to be constant.</p> -</div> <!-- _______________________________________________________________________ --> <h4> @@ -3735,7 +3736,7 @@ is its address (after linking) which is guaranteed to be constant.</p> </a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt>Function(const </tt><tt><a href="#FunctionType">FunctionType</a> @@ -3813,12 +3814,14 @@ iterator<br> </div> +</div> + <!-- ======================================================================= --> <h3> <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a> </h3> -<div class="doc_text"> +<div> <p><tt>#include "<a href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt> @@ -3840,7 +3843,6 @@ variables may have an initial value (which must be a <a href="#Constant"><tt>Constant</tt></a>), and if they have an initializer, they may be marked as "constant" themselves (indicating that their contents never change at runtime).</p> -</div> <!-- _______________________________________________________________________ --> <h4> @@ -3849,7 +3851,7 @@ never change at runtime).</p> </a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt>GlobalVariable(const </tt><tt><a href="#Type">Type</a> *Ty, bool @@ -3887,13 +3889,14 @@ never change at runtime).</p> </div> +</div> <!-- ======================================================================= --> <h3> <a name="BasicBlock">The <tt>BasicBlock</tt> class</a> </h3> -<div class="doc_text"> +<div> <p><tt>#include "<a href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt><br> @@ -3918,8 +3921,6 @@ href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type <tt>label</tt>.</p> -</div> - <!-- _______________________________________________________________________ --> <h4> <a name="m_BasicBlock"> @@ -3927,7 +3928,7 @@ like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type </a> </h4> -<div class="doc_text"> +<div> <ul> <li><tt>BasicBlock(const std::string &Name = "", </tt><tt><a @@ -3979,13 +3980,14 @@ returned.</p></li> </div> +</div> <!-- ======================================================================= --> <h3> <a name="Argument">The <tt>Argument</tt> class</a> </h3> -<div class="doc_text"> +<div> <p>This subclass of Value defines the interface for incoming formal arguments to a function. A Function maintains a list of its formal @@ -3993,6 +3995,8 @@ arguments. An argument has a pointer to the parent Function.</p> </div> +</div> + <!-- *********************************************************************** --> <hr> <address> |