diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/LangRef.html | 149 | ||||
| -rw-r--r-- | docs/ProgrammersManual.html | 196 |
2 files changed, 44 insertions, 301 deletions
diff --git a/docs/LangRef.html b/docs/LangRef.html index 08d84df4a8..5959b3d5dc 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -74,16 +74,14 @@ <ol> <li><a href="#t_array">Array Type</a></li> <li><a href="#t_struct">Structure Type</a></li> - <li><a href="#t_pstruct">Packed Structure Type</a></li> + <li><a href="#t_opaque">Opaque Type</a></li> <li><a href="#t_vector">Vector Type</a></li> </ol> </li> <li><a href="#t_function">Function Type</a></li> <li><a href="#t_pointer">Pointer Type</a></li> - <li><a href="#t_opaque">Opaque Type</a></li> </ol> </li> - <li><a href="#t_uprefs">Type Up-references</a></li> </ol> </li> <li><a href="#constants">Constants</a> @@ -1535,7 +1533,6 @@ synchronization behavior.</p> <a href="#t_function">function</a>, <a href="#t_pointer">pointer</a>, <a href="#t_struct">structure</a>, - <a href="#t_pstruct">packed structure</a>, <a href="#t_vector">vector</a>, <a href="#t_opaque">opaque</a>. </td> @@ -1703,7 +1700,9 @@ synchronization behavior.</p> possible to have a two dimensional array, using an array as the element type of another array.</p> - +</div> + + <!-- _______________________________________________________________________ --> <h4> <a name="t_aggregate">Aggregate Types</a> @@ -1842,9 +1841,7 @@ synchronization behavior.</p> <h5>Overview:</h5> <p>The structure type is used to represent a collection of data members together - in memory. The packing of the field types is defined to match the ABI of the - underlying processor. The elements of a structure may be any type that has a - size.</p> + in memory. The elements of a structure may be any type that has a size.</p> <p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>' and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field @@ -1852,66 +1849,76 @@ synchronization behavior.</p> Structures in registers are accessed using the '<tt><a href="#i_extractvalue">extractvalue</a></tt>' and '<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p> + +<p>Structures may optionally be "packed" structures, which indicate that the + alignment of the struct is one byte, and that there is no padding between + the elements. In non-packed structs, padding between field types is defined + by the target data string to match the underlying processor.</p> + +<p>Structures can either be "anonymous" or "named". An anonymous structure is + defined inline with other types (e.g. <tt>{i32, i32}*</tt>) and a named types + are always defined at the top level with a name. Anonmyous types are uniqued + by their contents and can never be recursive since there is no way to write + one. Named types can be recursive. +</p> + <h5>Syntax:</h5> <pre> - { <type list> } + %T1 = type { <type list> } <i>; Named normal struct type</i> + %T2 = type <{ <type list> }> <i>; Named packed struct type</i> </pre> - + <h5>Examples:</h5> <table class="layout"> <tr class="layout"> <td class="left"><tt>{ i32, i32, i32 }</tt></td> <td class="left">A triple of three <tt>i32</tt> values</td> - </tr><tr class="layout"> + </tr> + <tr class="layout"> <td class="left"><tt>{ float, i32 (i32) * }</tt></td> <td class="left">A pair, where the first element is a <tt>float</tt> and the second element is a <a href="#t_pointer">pointer</a> to a <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning an <tt>i32</tt>.</td> </tr> + <tr class="layout"> + <td class="left"><tt><{ i8, i32 }></tt></td> + <td class="left">A packed struct known to be 5 bytes in size.</td> + </tr> </table> </div> - + <!-- _______________________________________________________________________ --> <h4> - <a name="t_pstruct">Packed Structure Type</a> + <a name="t_opaque">Opaque Type</a> </h4> <div> <h5>Overview:</h5> -<p>The packed structure type is used to represent a collection of data members - together in memory. There is no padding between fields. Further, the - alignment of a packed structure is 1 byte. The elements of a packed - structure may be any type that has a size.</p> - -<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and - '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with - the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> +<p>Opaque types are used to represent named structure types that do not have a + body specified. This corresponds (for example) to the C notion of a forward + declared structure.</p> <h5>Syntax:</h5> <pre> - < { <type list> } > + %X = type opaque + %52 = type opaque </pre> <h5>Examples:</h5> <table class="layout"> <tr class="layout"> - <td class="left"><tt>< { i32, i32, i32 } ></tt></td> - <td class="left">A triple of three <tt>i32</tt> values</td> - </tr><tr class="layout"> - <td class="left"> -<tt>< { float, i32 (i32)* } ></tt></td> - <td class="left">A pair, where the first element is a <tt>float</tt> and the - second element is a <a href="#t_pointer">pointer</a> to a - <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning - an <tt>i32</tt>.</td> + <td class="left"><tt>opaque</tt></td> + <td class="left">An opaque type.</td> </tr> </table> </div> + + <!-- _______________________________________________________________________ --> <h4> <a name="t_pointer">Pointer Type</a> @@ -1999,86 +2006,6 @@ synchronization behavior.</p> </div> -<!-- _______________________________________________________________________ --> -<h4> - <a name="t_opaque">Opaque Type</a> -</h4> - -<div> - -<h5>Overview:</h5> -<p>Opaque types are used to represent unknown types in the system. This - corresponds (for example) to the C notion of a forward declared structure - type. In LLVM, opaque types can eventually be resolved to any type (not just - a structure type).</p> - -<h5>Syntax:</h5> -<pre> - opaque -</pre> - -<h5>Examples:</h5> -<table class="layout"> - <tr class="layout"> - <td class="left"><tt>opaque</tt></td> - <td class="left">An opaque type.</td> - </tr> -</table> - -</div> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="t_uprefs">Type Up-references</a> -</h3> - -<div> - -<h5>Overview:</h5> -<p>An "up reference" allows you to refer to a lexically enclosing type without - requiring it to have a name. For instance, a structure declaration may - contain a pointer to any of the types it is lexically a member of. Example - of up references (with their equivalent as named type declarations) - include:</p> - -<pre> - { \2 * } %x = type { %x* } - { \2 }* %y = type { %y }* - \1* %z = type %z* -</pre> - -<p>An up reference is needed by the asmprinter for printing out cyclic types - when there is no declared name for a type in the cycle. Because the - asmprinter does not want to print out an infinite type string, it needs a - syntax to handle recursive types that have no names (all names are optional - in llvm IR).</p> - -<h5>Syntax:</h5> -<pre> - \<level> -</pre> - -<p>The level is the count of the lexical type that is being referred to.</p> - -<h5>Examples:</h5> -<table class="layout"> - <tr class="layout"> - <td class="left"><tt>\1*</tt></td> - <td class="left">Self-referential pointer.</td> - </tr> - <tr class="layout"> - <td class="left"><tt>{ { \3*, i8 }, i32 }</tt></td> - <td class="left">Recursive structure where the upref refers to the out-most - structure.</td> - </tr> -</table> - -</div> - -</div> - <!-- *********************************************************************** --> <h2><a name="constants">Constants</a></h2> <!-- *********************************************************************** --> diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 49a76ee414..c1edd2a60a 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -160,15 +160,8 @@ with another <tt>Value</tt></a> </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="#SymbolTable">The <tt>ValueSymbolTable</tt> class</a></li> <li><a href="#UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a></li> </ul></li> @@ -2645,173 +2638,10 @@ 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> + <!-- ======================================================================= --> <h3> - <a name="TypeResolve">LLVM Type Resolution</a> -</h3> - -<div> - -<p> -The LLVM type system has a very simple goal: allow clients to compare types for -structural equality with a simple pointer comparison (aka a shallow compare). -This goal makes clients much simpler and faster, and is used throughout the LLVM -system. -</p> - -<p> -Unfortunately achieving this goal is not a simple matter. In particular, -recursive types and late resolution of opaque types makes the situation very -difficult to handle. Fortunately, for the most part, our implementation makes -most clients able to be completely unaware of the nasty internal details. The -primary case where clients are exposed to the inner workings of it are when -building a recursive type. In addition to this case, the LLVM bitcode reader, -assembly parser, and linker also have to be aware of the inner workings of this -system. -</p> - -<p> -For our purposes below, we need three concepts. First, an "Opaque Type" is -exactly as defined in the <a href="LangRef.html#t_opaque">language -reference</a>. Second an "Abstract Type" is any type which includes an -opaque type as part of its type graph (for example "<tt>{ opaque, i32 }</tt>"). -Third, a concrete type is a type that is not an abstract type (e.g. "<tt>{ i32, -float }</tt>"). -</p> - -<!-- ______________________________________________________________________ --> -<h4> - <a name="BuildRecType">Basic Recursive Type Construction</a> -</h4> - -<div> - -<p> -Because the most common question is "how do I build a recursive type with LLVM", -we answer it now and explain it as we go. Here we include enough to cause this -to be emitted to an output .ll file: -</p> - -<div class="doc_code"> -<pre> -%mylist = type { %mylist*, i32 } -</pre> -</div> - -<p> -To build this, use the following LLVM APIs: -</p> - -<div class="doc_code"> -<pre> -// <i>Create the initial outer struct</i> -<a href="#PATypeHolder">PATypeHolder</a> StructTy = OpaqueType::get(); -std::vector<const Type*> Elts; -Elts.push_back(PointerType::getUnqual(StructTy)); -Elts.push_back(Type::Int32Ty); -StructType *NewSTy = StructType::get(Elts); - -// <i>At this point, NewSTy = "{ opaque*, i32 }". Tell VMCore that</i> -// <i>the struct and the opaque type are actually the same.</i> -cast<OpaqueType>(StructTy.get())-><a href="#refineAbstractTypeTo">refineAbstractTypeTo</a>(NewSTy); - -// <i>NewSTy is potentially invalidated, but StructTy (a <a href="#PATypeHolder">PATypeHolder</a>) is</i> -// <i>kept up-to-date</i> -NewSTy = cast<StructType>(StructTy.get()); - -// <i>Add a name for the type to the module symbol table (optional)</i> -MyModule->addTypeName("mylist", NewSTy); -</pre> -</div> - -<p> -This code shows the basic approach used to build recursive types: build a -non-recursive type using 'opaque', then use type unification to close the cycle. -The type unification step is performed by the <tt><a -href="#refineAbstractTypeTo">refineAbstractTypeTo</a></tt> method, which is -described next. After that, we describe the <a -href="#PATypeHolder">PATypeHolder class</a>. -</p> - -</div> - -<!-- ______________________________________________________________________ --> -<h4> - <a name="refineAbstractTypeTo">The <tt>refineAbstractTypeTo</tt> method</a> -</h4> - -<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 -often used on OpaqueType instances. Type unification is actually a recursive -process. After unification, types can become structurally isomorphic to -existing types, and all duplicates are deleted (to preserve pointer equality). -</p> - -<p> -In the example above, the OpaqueType object is definitely deleted. -Additionally, if there is an "{ \2*, i32}" type already created in the system, -the pointer and struct type created are <b>also</b> deleted. Obviously whenever -a type is deleted, any "Type*" pointers in the program are invalidated. As -such, it is safest to avoid having <i>any</i> "Type*" pointers to abstract types -live across a call to <tt>refineAbstractTypeTo</tt> (note that non-abstract -types can never move or be deleted). To deal with this, the <a -href="#PATypeHolder">PATypeHolder</a> class is used to maintain a stable -reference to a possibly refined type, and the <a -href="#AbstractTypeUser">AbstractTypeUser</a> class is used to update more -complex datastructures. -</p> - -</div> - -<!-- ______________________________________________________________________ --> -<h4> - <a name="PATypeHolder">The PATypeHolder Class</a> -</h4> - -<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 -automatically updates all PATypeHolder objects to point to the new type. In the -example above, this allows the code to maintain a pointer to the resultant -resolved recursive type, even though the Type*'s are potentially invalidated. -</p> - -<p> -PATypeHolder is an extremely light-weight object that uses a lazy union-find -implementation to update pointers. For example the pointer from a Value to its -Type is maintained by PATypeHolder objects. -</p> - -</div> - -<!-- ______________________________________________________________________ --> -<h4> - <a name="AbstractTypeUser">The AbstractTypeUser Class</a> -</h4> - -<div> - -<p> -Some data structures need more to perform more complex updates when types get -resolved. To support this, a class can derive from the AbstractTypeUser class. -This class -allows it to get callbacks when certain types are resolved. To register to get -callbacks for a particular type, the DerivedType::{add/remove}AbstractTypeUser -methods can be called on a type. Note that these methods only work for <i> - abstract</i> types. Concrete types (those that do not include any opaque -objects) can never be refined. -</p> -</div> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="SymbolTable">The <tt>ValueSymbolTable</tt> and - <tt>TypeSymbolTable</tt> classes</a> + <a name="SymbolTable">The <tt>ValueSymbolTable</tt> class</a> </h3> <div> @@ -2820,9 +2650,7 @@ ValueSymbolTable</a></tt> class provides a symbol table that the <a href="#Function"><tt>Function</tt></a> and <a href="#Module"> <tt>Module</tt></a> classes use for naming value definitions. The symbol table can provide a name for any <a href="#Value"><tt>Value</tt></a>. -The <tt><a href="http://llvm.org/doxygen/classllvm_1_1TypeSymbolTable.html"> -TypeSymbolTable</a></tt> class is used by the <tt>Module</tt> class to store -names for types.</p> +</p> <p>Note that the <tt>SymbolTable</tt> class should not be directly accessed by most clients. It should only be used when iteration over the symbol table @@ -2832,13 +2660,12 @@ all LLVM an empty name) do not exist in the symbol table. </p> -<p>These symbol tables support iteration over the values/types in the symbol +<p>Symbol tables support iteration over the values in the symbol table with <tt>begin/end/iterator</tt> and supports querying to see if a specific name is in the symbol table (with <tt>lookup</tt>). The <tt>ValueSymbolTable</tt> class exposes no public mutator methods, instead, simply call <tt>setName</tt> on a value, which will autoinsert it into the -appropriate symbol table. For types, use the Module::addTypeName method to -insert entries into the symbol table.</p> +appropriate symbol table.</p> </div> @@ -3128,9 +2955,6 @@ the <tt>lib/VMCore</tt> directory.</p> <li><tt>bool isFloatingPointTy()</tt>: Return true if this is one of the five floating point types.</li> - <li><tt>bool isAbstract()</tt>: Return true if the type is abstract (contains - an OpaqueType anywhere in its definition).</li> - <li><tt>bool isSized()</tt>: Return true if the type has known size. Things that don't have a size are abstract types, labels and void.</li> @@ -3192,14 +3016,6 @@ the <tt>lib/VMCore</tt> directory.</p> number of formal parameters.</li> </ul> </dd> - <dt><tt>OpaqueType</tt></dt> - <dd>Sublcass of DerivedType for abstract types. This class - defines no content and is used as a placeholder for some other type. Note - that OpaqueType is used (temporarily) during type resolution for forward - references of types. Once the referenced type is resolved, the OpaqueType - is replaced with the actual type. OpaqueType can also be used for data - abstraction. At link time opaque types can be resolved to actual types - of the same name.</dd> </dl> </div> |