<li><a href="#modulestructure">Module Structure</a></li>
<li><a href="#linkage">Linkage Types</a></li>
<li><a href="#callingconv">Calling Conventions</a></li>
+ <li><a href="#namedtypes">Named Types</a></li>
<li><a href="#globalvars">Global Variables</a></li>
<li><a href="#functionstructure">Functions</a></li>
<li><a href="#aliasstructure">Aliases</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>
<i>; Definition of main function</i>
define i32 @main() { <i>; i32()* </i>
- <i>; Convert [13x i8 ]* to i8 *...</i>
+ <i>; Convert [13 x i8]* to i8 *...</i>
%cast210 = <a
- href="#i_getelementptr">getelementptr</a> [13 x i8 ]* @.LC0, i64 0, i64 0 <i>; i8 *</i>
+ href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0 <i>; i8 *</i>
<i>; Call puts function to write out the string to stdout...</i>
<a
<dl>
- <dt><tt><b><a name="linkage_internal">internal</a></b></tt>: </dt>
+ <dt><tt><b><a name="linkage_private">private</a></b></tt>: </dt>
- <dd>Global values with internal linkage are only directly accessible by
+ <dd>Global values with private linkage are only directly accessible by
objects in the current module. In particular, linking code into a module with
- an internal global value may cause the internal to be renamed as necessary to
- avoid collisions. Because the symbol is internal to the module, all
- references can be updated. This corresponds to the notion of the
+ an private global value may cause the private to be renamed as necessary to
+ avoid collisions. Because the symbol is private to the module, all
+ references can be updated. This doesn't show up in any symbol table in the
+ object file.
+ </dd>
+
+ <dt><tt><b><a name="linkage_internal">internal</a></b></tt>: </dt>
+
+ <dd> Similar to private, but the value shows as a local symbol (STB_LOCAL in
+ the case of ELF) in the object file. This corresponds to the notion of the
'<tt>static</tt>' keyword in C.
</dd>
<dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
or variable via a global pointer to a pointer that is set up by the DLL
exporting the symbol. On Microsoft Windows targets, the pointer name is
- formed by combining <code>_imp__</code> and the function or variable name.
+ formed by combining <code>__imp_</code> and the function or variable name.
</dd>
<dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt>: </dt>
<dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
pointer to a pointer in a DLL, so that it can be referenced with the
<tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
- name is formed by combining <code>_imp__</code> and the function or variable
+ name is formed by combining <code>__imp_</code> and the function or variable
name.
</dd>
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="namedtypes">Named Types</a>
+</div>
+
+<div class="doc_text">
+
+<p>LLVM IR allows you to specify name aliases for certain types. This can make
+it easier to read the IR and make the IR more condensed (particularly when
+recursive types are involved). An example of a name specification is:
+</p>
+
+<div class="doc_code">
+<pre>
+%mytype = type { %mytype*, i32 }
+</pre>
+</div>
+
+<p>You may give a name to any <a href="#typesystem">type</a> except "<a
+href="t_void">void</a>". Type name aliases may be used anywhere a type is
+expected with the syntax "%mytype".</p>
+
+<p>Note that type names are aliases for the structural type that they indicate,
+and that you can therefore specify multiple names for the same type. This often
+leads to confusing behavior when dumping out a .ll file. Since LLVM IR uses
+structural typing, the name is not part of the type. When printing out LLVM IR,
+the printer will pick <em>one name</em> to render all types of a particular
+shape. This means that if you have code where two different source types end up
+having the same LLVM type, that the dumper will sometimes print the "wrong" or
+unexpected type. This is an important design point and isn't going to
+change.</p>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="globalvars">Global Variables</a>
<div class="doc_code">
<pre>
-@G = constant float 1.0 addrspace(5), section "foo", align 4
+@G = addrspace(5) constant float 1.0, section "foo", align 4
</pre>
</div>
parameter. The caller is responsible for ensuring that this is the
case. On a function return value, <tt>noalias</tt> additionally indicates
that the pointer does not alias any other pointers visible to the
- caller. Note that this applies only to pointers that can be used to actually
- load/store a value: NULL, unique pointers from malloc(0), and freed pointers
- are considered to not alias anything.</dd>
+ caller. For further details, please see the discussion of the NoAlias
+ response in
+ <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias
+ analysis</a>.</dd>
+
+ <dt><tt>nocapture</tt></dt>
+ <dd>This indicates that the callee does not make any copies of the pointer
+ that outlive the callee itself. This is not a valid attribute for return
+ values.</dd>
<dt><tt>nest</tt></dt>
<dd>This indicates that the pointer parameter can be excised using the
</tr>
</tbody>
</table>
+
+<p>Note that the code generator does not yet support large integer types
+to be used as function return types. The specific limit on how large a
+return type the code generator can currently handle is target-dependent;
+currently it's often 64 bits for 32-bit targets and 128 bits for 64-bit
+targets.</p>
+
</div>
<!-- _______________________________________________________________________ -->
length. This allows implementation of 'pascal style arrays' with the LLVM
type "{ i32, [0 x float]}", for example.</p>
+<p>Note that the code generator does not yet support large aggregate types
+to be used as function return types. The specific limit on how large an
+aggregate return type the code generator can currently handle is
+target-dependent, and also dependent on the aggregate element types.</p>
+
</div>
<!-- _______________________________________________________________________ -->
an <tt>i32</tt>.</td>
</tr>
</table>
+
+<p>Note that the code generator does not yet support large aggregate types
+to be used as function return types. The specific limit on how large an
+aggregate return type the code generator can currently handle is
+target-dependent, and also dependent on the aggregate element types.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<h5>Examples:</h5>
<table class="layout">
<tr class="layout">
- <td class="left"><tt>[4x i32]*</tt></td>
+ <td class="left"><tt>[4 x i32]*</tt></td>
<td class="left">A <a href="#t_pointer">pointer</a> to <a
href="#t_array">array</a> of four <tt>i32</tt> values.</td>
</tr>
<td class="left">Vector of 2 64-bit integer values.</td>
</tr>
</table>
+
+<p>Note that the code generator does not yet support large vector types
+to be used as function return types. The specific limit on how large a
+vector return type codegen can currently handle is target-dependent;
+currently it's often a few times longer than a hardware vector register.</p>
+
</div>
<!-- _______________________________________________________________________ -->
</table>
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="t_uprefs">Type Up-references</a>
+</div>
+
+<div class="doc_text">
+<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 { %t* }
+ { \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 class="doc_section"> <a name="constants">Constants</a> </div>
ret void <i>; Return from a void function</i>
ret { i32, i8 } { i32 4, i8 2 } <i>; Return an aggregate of values 4 and 2</i>
</pre>
+
+<p>Note that the code generator does not yet fully support large
+ return values. The specific sizes that are currently supported are
+ dependent on the target. For integers, on 32-bit targets the limit
+ is often 64 bits, and on 64-bit targets the limit is often 128 bits.
+ For aggregate types, the current limits are dependent on the element
+ types; for example targets are often limited to 2 total integer
+ elements and 2 total floating-point elements.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
<pre>
<i>; Emulate a conditional br instruction</i>
%Val = <a href="#i_zext">zext</a> i1 %value to i32
- switch i32 %Val, label %truedest [i32 0, label %falsedest ]
+ switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
<i>; Emulate an unconditional br instruction</i>
switch i32 0, label %dest [ ]
<i>; Implement a jump table:</i>
- switch i32 %val, label %otherwise [ i32 0, label %onzero
- i32 1, label %onone
- i32 2, label %ontwo ]
+ switch i32 %val, label %otherwise [ i32 0, label %onzero
+ i32 1, label %onone
+ i32 2, label %ontwo ]
</pre>
</div>
<h5>Example:</h5>
<pre>
- %array = malloc [4 x i8 ] <i>; yields {[%4 x i8]*}:array</i>
+ %array = malloc [4 x i8] <i>; yields {[%4 x i8]*}:array</i>
%size = <a href="#i_add">add</a> i32 2, 2 <i>; yields {i32}:size = i32 4</i>
%array1 = malloc i8, i32 4 <i>; yields {i8*}:array1</i>
%array3 = malloc i32, i32 4, align 1024 <i>; yields {i32*}:array3</i>
%array4 = malloc i32, align 1024 <i>; yields {i32*}:array4</i>
</pre>
+
+<p>Note that the code generator does not yet respect the
+ alignment value.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<h5>Syntax:</h5>
<pre>
- free <type> <value> <i>; yields {void}</i>
+ free <type> <value> <i>; yields {void}</i>
</pre>
<h5>Overview:</h5>
<h5>Example:</h5>
<pre>
- %array = <a href="#i_malloc">malloc</a> [4 x i8] <i>; yields {[4 x i8]*}:array</i>
+ %array = <a href="#i_malloc">malloc</a> [4 x i8] <i>; yields {[4 x i8]*}:array</i>
free [4 x i8]* %array
</pre>
</div>
<h5>Example:</h5>
<pre>
- %ptr = alloca i32 <i>; yields {i32*}:ptr</i>
- %ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i>
- %ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i>
- %ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i>
+ %ptr = alloca i32 <i>; yields {i32*}:ptr</i>
+ %ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i>
+ %ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i>
+ %ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i>
</pre>
</div>
<div class="doc_code">
<pre>
-%RT = type { i8 , [10 x [20 x i32]], i8 }
-%ST = type { i32, double, %RT }
+%RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 }
+%ST = <a href="#namedtypes">type</a> { i32, double, %RT }
define i32* %foo(%ST* %s) {
entry:
<result> = icmp ule i16 -4, 5 <i>; yields: result=false</i>
<result> = icmp sge i16 4, 5 <i>; yields: result=false</i>
</pre>
+
+<p>Note that the code generator does not yet support vector types with
+ the <tt>icmp</tt> instruction.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<result> = fcmp olt float 4.0, 5.0 <i>; yields: result=true</i>
<result> = fcmp ueq double 1.0, 2.0 <i>; yields: result=false</i>
</pre>
+
+<p>Note that the code generator does not yet support vector types with
+ the <tt>fcmp</tt> instruction.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<pre>
%X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i>
</pre>
+
+<p>Note that the code generator does not yet support conditions
+ with vector type.</p>
+
</div>
<p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
+<p>Note that the code generator does not yet fully support va_arg
+ on many targets. Also, it does not currently support va_arg with
+ aggregate types on any target.</p>
+
</div>
<!-- *********************************************************************** -->
projects / oota-llvm.git / blobdiff