<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>
<ol>
<li><a href="#simpleconstants">Simple Constants</a></li>
- <li><a href="#aggregateconstants">Aggregate Constants</a></li>
+ <li><a href="#complexconstants">Complex Constants</a></li>
<li><a href="#globalconstants">Global Variable and Function Addresses</a></li>
<li><a href="#undefvalues">Undefined Values</a></li>
<li><a href="#constantexprs">Constant Expressions</a></li>
+ <li><a href="#metadata">Embedded Metadata</a></li>
</ol>
</li>
<li><a href="#othervalues">Other Values</a>
<li><a href="#int_part_set">'<tt>llvm.part.set.*</tt>' Intrinsic </a></li>
</ol>
</li>
+ <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a>
+ <ol>
+ <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li>
+ <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li>
+ <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li>
+ <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li>
+ <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li>
+ <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
+ </ol>
+ </li>
<li><a href="#int_debugger">Debugger intrinsics</a></li>
<li><a href="#int_eh">Exception Handling intrinsics</a></li>
<li><a href="#int_trampoline">Trampoline Intrinsic</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>
+ <dt><tt><b><a name="available_externally">available_externally</a></b></tt>:
+ </dt>
+
+ <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted
+ into the object file corresponding to the LLVM module. They exist to
+ allow inlining and other optimizations to take place given knowledge of the
+ definition of the global, which is known to be somewhere outside the module.
+ Globals with <tt>available_externally</tt> linkage are allowed to be discarded
+ at will, and are otherwise the same as <tt>linkonce_odr</tt>. This linkage
+ type is only allowed on definitions, not declarations.</dd>
+
<dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt>
<dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
</dd>
<dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt>: </dt>
+
<dd>The semantics of this linkage follow the ELF object file model: the
symbol is weak until linked, if not linked, the symbol becomes null instead
of being an undefined reference.
</dd>
+ <dt><tt><b><a name="linkage_linkonce">linkonce_odr</a></b></tt>: </dt>
+ <dt><tt><b><a name="linkage_weak">weak_odr</a></b></tt>: </dt>
+ <dd>Some languages allow differing globals to be merged, such as two
+ functions with different semantics. Other languages, such as <tt>C++</tt>,
+ ensure that only equivalent globals are ever merged (the "one definition
+ rule" - "ODR"). Such languages can use the <tt>linkonce_odr</tt>
+ and <tt>weak_odr</tt> linkage types to indicate that the global will only
+ be merged with equivalent globals. These linkage types are otherwise the
+ same as their non-<tt>odr</tt> versions.
+ </dd>
+
<dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
<dd>If none of the above identifiers are used, the global is externally
<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>
</dl>
-<p><a name="linkage_external"></a>For example, since the "<tt>.LC0</tt>"
+<p>For example, since the "<tt>.LC0</tt>"
variable is defined to be internal, if another module defined a "<tt>.LC0</tt>"
variable and was linked with this one, one of the two would be renamed,
preventing a collision. Since "<tt>main</tt>" and "<tt>puts</tt>" are
external (i.e., lacking any linkage declarations), they are accessible
outside of the current module.</p>
<p>It is illegal for a function <i>declaration</i>
-to have any linkage type other than "externally visible", <tt>dllimport</tt>,
+to have any linkage type other than "externally visible", <tt>dllimport</tt>
or <tt>extern_weak</tt>.</p>
-<p>Aliases can have only <tt>external</tt>, <tt>internal</tt> and <tt>weak</tt>
-linkages.</p>
+<p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt>
+or <tt>weak_odr</tt> linkages.</p>
</div>
<!-- ======================================================================= -->
</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>
<div class="doc_code">
<pre>
-declare i32 @printf(i8* noalias , ...)
+declare i32 @printf(i8* noalias nocapture, ...)
declare i32 @atoi(i8 zeroext)
declare signext i8 @returns_signed_char()
</pre>
belong to the caller not the callee (for example,
<tt><a href="#readonly">readonly</a></tt> functions should not write to
<tt>byval</tt> parameters). This is not a valid attribute for return
- values. </dd>
+ values. The byval attribute also supports specifying an alignment with the
+ align attribute. This has a target-specific effect on the code generator
+ that usually indicates a desired alignment for the synthesized stack
+ slot.</dd>
<dt><tt>sret</tt></dt>
<dd>This indicates that the pointer parameter specifies the address of a
return values. </dd>
<dt><tt>noalias</tt></dt>
- <dd>This indicates that the parameter does not alias any global or any other
- parameter. The caller is responsible for ensuring that this is the case,
- usually by placing the value in a stack allocation. This is not a valid
- attribute for return values.</dd>
+ <dd>This indicates that the pointer does not alias any global or any other
+ 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. 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
protector. It is in the form of a "canary"—a random value placed on the
stack before the local variables that's checked upon return from the function to
see if it has been overwritten. A heuristic is used to determine if a function
-needs stack protectors or not.</dd>
+needs stack protectors or not.
+
+<p>If a function that has an <tt>ssp</tt> attribute is inlined into a function
+that doesn't have an <tt>ssp</tt> attribute, then the resulting function will
+have an <tt>ssp</tt> attribute.</p></dd>
-<dt><tt>ssp-req</tt></dt>
+<dt><tt>sspreq</tt></dt>
<dd>This attribute indicates that the function should <em>always</em> emit a
stack smashing protector. This overrides the <tt><a href="#ssp">ssp</a></tt>
-function attribute.</dd>
+function attribute.
+
+<p>If a function that has an <tt>sspreq</tt> attribute is inlined into a
+function that doesn't have an <tt>sspreq</tt> attribute or which has
+an <tt>ssp</tt> attribute, then the resulting function will have
+an <tt>sspreq</tt> attribute.</p></dd>
</dl>
</div>
</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>
<!-- _______________________________________________________________________ -->
</td>
</tr><tr class="layout">
<td class="left"><tt>{i32, i32} (i32)</tt></td>
- <td class="left">A function taking an <tt>i32></tt>, returning two
- <tt> i32 </tt> values as an aggregate of type <tt>{ i32, i32 }</tt>
+ <td class="left">A function taking an <tt>i32</tt>, returning two
+ <tt>i32</tt> values as an aggregate of type <tt>{ i32, i32 }</tt>
</td>
</tr>
</table>
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>
<!-- _______________________________________________________________________ -->
an optional address space attribute defining the target-specific numbered
address space where the pointed-to object resides. The default address space is
zero.</p>
+
+<p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does
+it permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p>
+
<h5>Syntax:</h5>
<pre> <type> *<br></pre>
<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 { %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 class="doc_section"> <a name="constants">Constants</a> </div>
</dl>
-<p>The one non-intuitive notation for constants is the optional hexadecimal form
+<p>The one non-intuitive notation for constants is the hexadecimal form
of floating point constants. For example, the form '<tt>double
0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
4.5e+15</tt>'. The only time hexadecimal floating point constants are required
(and the only time that they are generated by the disassembler) is when a
floating point constant must be emitted but it cannot be represented as a
-decimal floating point number. For example, NaN's, infinities, and other
+decimal floating point number in a reasonable number of digits. For example,
+NaN's, infinities, and other
special values are represented in their IEEE hexadecimal format so that
assembly and disassembly do not cause any bits to change in the constants.</p>
-
+<p>When using the hexadecimal form, constants of types float and double are
+represented using the 16-digit form shown above (which matches the IEEE754
+representation for double); float values must, however, be exactly representable
+as IEE754 single precision.
+Hexadecimal format is always used for long
+double, and there are three forms of long double. The 80-bit
+format used by x86 is represented as <tt>0xK</tt>
+followed by 20 hexadecimal digits.
+The 128-bit format used by PowerPC (two adjacent doubles) is represented
+by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit
+format is represented
+by <tt>0xL</tt> followed by 32 hexadecimal digits; no currently supported
+target uses this format. Long doubles will only work if they match
+the long double format on your target. All hexadecimal formats are big-endian
+(sign bit at the left).</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="aggregateconstants">Aggregate Constants</a>
+<div class="doc_subsection">
+<a name="aggregateconstants"> <!-- old anchor -->
+<a name="complexconstants">Complex Constants</a></a>
</div>
<div class="doc_text">
-<p>Aggregate constants arise from aggregation of simple constants
-and smaller aggregate constants.</p>
+<p>Complex constants are a (potentially recursive) combination of simple
+constants and smaller complex constants.</p>
<dl>
<dt><b>Structure constants</b></dt>
large arrays) and is always exactly equivalent to using explicit zero
initializers.
</dd>
+
+ <dt><b>Metadata node</b></dt>
+
+ <dd>A metadata node is a structure-like constant with the type of an empty
+ struct. For example: "<tt>{ } !{ i32 0, { } !"test" }</tt>". Unlike other
+ constants that are meant to be interpreted as part of the instruction stream,
+ metadata is a place to attach additional information such as debug info.
+ </dd>
</dl>
</div>
<i>really</i> dangerous!</dd>
<dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt>
- <dd>Convert a constant, CST, to another TYPE. The size of CST and TYPE must be
- identical (same number of bits). The conversion is done as if the CST value
- was stored to memory and read back as TYPE. In other words, no bits change
- with this operator, just the type. This can be used for conversion of
- vector types to any other type, as long as they have the same bit width. For
- pointers it is only valid to cast to another pointer type. It is not valid
- to bitcast to or from an aggregate type.
- </dd>
+ <dd>Convert a constant, CST, to another TYPE. The constraints of the operands
+ are the same as those for the <a href="#i_bitcast">bitcast
+ instruction</a>.</dd>
<dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
</dl>
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="metadata">Embedded Metadata</a>
+</div>
+
+<div class="doc_text">
+
+<p>Embedded metadata provides a way to attach arbitrary data to the
+instruction stream without affecting the behaviour of the program. There are
+two metadata primitives, strings and nodes. All metadata has the type of an
+empty struct and is identified in syntax by a preceding exclamation point
+('<tt>!</tt>').
+</p>
+
+<p>A metadata string is a string surrounded by double quotes. It can contain
+any character by escaping non-printable characters with "\xx" where "xx" is
+the two digit hex code. For example: "<tt>!"test\00"</tt>".
+</p>
+
+<p>Metadata nodes are represented with notation similar to structure constants
+(a comma separated list of elements, surrounded by braces and preceeded by an
+exclamation point). For example: "<tt>!{ { } !"test\00", i32 10}</tt>".
+</p>
+
+<p>Optimizations may rely on metadata to provide additional information about
+the program that isn't available in the instructions, or that isn't easily
+computable. Similarly, the code generator may expect a certain metadata format
+to be used to express debugging information.</p>
+</div>
+
<!-- *********************************************************************** -->
<div class="doc_section"> <a name="othervalues">Other Values</a> </div>
<!-- *********************************************************************** -->
<pre>
ret i32 5 <i>; Return an integer value of 5</i>
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>
+ ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct 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>
<p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod 2<sup>n</sup>,
where n is the width of the result. If <tt>op2</tt> is (statically or dynamically) negative or
-equal to or larger than the number of bits in <tt>op1</tt>, the result is undefined.</p>
+equal to or larger than the number of bits in <tt>op1</tt>, the result is undefined.
+If the arguments are vectors, each vector element of <tt>op1</tt> is shifted by the
+corresponding shift amount in <tt>op2</tt>.</p>
<h5>Example:</h5><pre>
<result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i>
<result> = shl i32 4, 2 <i>; yields {i32}: 16</i>
<result> = shl i32 1, 10 <i>; yields {i32}: 1024</i>
<result> = shl i32 1, 32 <i>; undefined</i>
+ <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 2, i32 4></i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<p>This instruction always performs a logical shift right operation. The most
significant bits of the result will be filled with zero bits after the
shift. If <tt>op2</tt> is (statically or dynamically) equal to or larger than
-the number of bits in <tt>op1</tt>, the result is undefined.</p>
+the number of bits in <tt>op1</tt>, the result is undefined. If the arguments are
+vectors, each vector element of <tt>op1</tt> is shifted by the corresponding shift
+amount in <tt>op2</tt>.</p>
<h5>Example:</h5>
<pre>
<result> = lshr i8 4, 3 <i>; yields {i8}:result = 0</i>
<result> = lshr i8 -2, 1 <i>; yields {i8}:result = 0x7FFFFFFF </i>
<result> = lshr i32 1, 32 <i>; undefined</i>
+ <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1></i>
</pre>
</div>
<p>This instruction always performs an arithmetic shift right operation,
The most significant bits of the result will be filled with the sign bit
of <tt>op1</tt>. If <tt>op2</tt> is (statically or dynamically) equal to or
-larger than the number of bits in <tt>op1</tt>, the result is undefined.
-</p>
+larger than the number of bits in <tt>op1</tt>, the result is undefined. If the
+arguments are vectors, each vector element of <tt>op1</tt> is shifted by the
+corresponding shift amount in <tt>op2</tt>.</p>
<h5>Example:</h5>
<pre>
<result> = ashr i8 4, 3 <i>; yields {i8}:result = 0</i>
<result> = ashr i8 -2, 1 <i>; yields {i8}:result = -1</i>
<result> = ashr i32 1, 32 <i>; undefined</i>
+ <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> <i>; yields: result=<2 x i32> < i32 -1, i32 0></i>
</pre>
</div>
<h5>Semantics:</h5>
<p>Memory is allocated using the system "<tt>malloc</tt>" function, and
-a pointer is returned. The result of a zero byte allocattion is undefined. The
+a pointer is returned. The result of a zero byte allocation is undefined. The
result is null if there is insufficient memory available.</p>
<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>
safe.
</p>
<h5>Semantics:</h5>
-<p>The location of memory pointed to is loaded.</p>
+<p>The location of memory pointed to is loaded. If the value being loaded
+is of scalar type then the number of bytes read does not exceed the minimum
+number of bytes needed to hold all bits of the type. For example, loading an
+<tt>i24</tt> reads at most three bytes. When loading a value of a type like
+<tt>i20</tt> with a size that is not an integral number of bytes, the result
+is undefined if the value was not originally written using a store of the
+same type.</p>
<h5>Examples:</h5>
<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
<a
</p>
<h5>Semantics:</h5>
<p>The contents of memory are updated to contain '<tt><value></tt>'
-at the location specified by the '<tt><pointer></tt>' operand.</p>
+at the location specified by the '<tt><pointer></tt>' operand.
+If '<tt><value></tt>' is of scalar type then the number of bytes
+written does not exceed the minimum number of bytes needed to hold all
+bits of the type. For example, storing an <tt>i24</tt> writes at most
+three bytes. When writing a value of a type like <tt>i20</tt> with a
+size that is not an integral number of bytes, it is unspecified what
+happens to the extra bits that do not belong to the type, but they will
+typically be overwritten.</p>
<h5>Example:</h5>
<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
store i32 3, i32* %ptr <i>; yields {void}</i>
<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:
}
</pre>
-<p>Note that it is undefined to access an array out of bounds: array and
-pointer indexes must always be within the defined bounds of the array type.
-The one exception for this rule is zero length arrays. These arrays are
-defined to be accessible as variable length arrays, which requires access
-beyond the zero'th element.</p>
+<p>Note that it is undefined to access an array out of bounds: array
+and pointer indexes must always be within the defined bounds of the
+array type when accessed with an instruction that dereferences the
+pointer (e.g. a load or store instruction). The one exception for
+this rule is zero length arrays. These arrays are defined to be
+accessible as variable length arrays, which requires access beyond the
+zero'th element.</p>
<p>The getelementptr instruction is often confusing. For some more insight
into how it works, see <a href="GetElementPtr.html">the getelementptr
<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>
<!-- *********************************************************************** -->
<div class="doc_text">
<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use llvm.memcpy on any integer bit
+width. Not all targets support all bit widths however.</p>
<pre>
+ declare void @llvm.memcpy.i8(i8 * <dest>, i8 * <src>,
+ i8 <len>, i32 <align>)
+ declare void @llvm.memcpy.i16(i8 * <dest>, i8 * <src>,
+ i16 <len>, i32 <align>)
declare void @llvm.memcpy.i32(i8 * <dest>, i8 * <src>,
i32 <len>, i32 <align>)
declare void @llvm.memcpy.i64(i8 * <dest>, i8 * <src>,
<div class="doc_text">
<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
+width. Not all targets support all bit widths however.</p>
<pre>
+ declare void @llvm.memmove.i8(i8 * <dest>, i8 * <src>,
+ i8 <len>, i32 <align>)
+ declare void @llvm.memmove.i16(i8 * <dest>, i8 * <src>,
+ i16 <len>, i32 <align>)
declare void @llvm.memmove.i32(i8 * <dest>, i8 * <src>,
i32 <len>, i32 <align>)
declare void @llvm.memmove.i64(i8 * <dest>, i8 * <src>,
<div class="doc_text">
<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit
+width. Not all targets support all bit widths however.</p>
<pre>
+ declare void @llvm.memset.i8(i8 * <dest>, i8 <val>,
+ i8 <len>, i32 <align>)
+ declare void @llvm.memset.i16(i8 * <dest>, i8 <val>,
+ i16 <len>, i32 <align>)
declare void @llvm.memset.i32(i8 * <dest>, i8 <val>,
i32 <len>, i32 <align>)
declare void @llvm.memset.i64(i8 * <dest>, i8 <val>,
<p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
width. Not all targets support all bit widths however.</p>
<pre>
- declare i8 @llvm.ctpop.i8 (i8 <src>)
+ declare i8 @llvm.ctpop.i8(i8 <src>)
declare i16 @llvm.ctpop.i16(i16 <src>)
declare i32 @llvm.ctpop.i32(i32 <src>)
declare i64 @llvm.ctpop.i64(i64 <src>)
with the replaced bits.</p>
<h5>Arguments:</h5>
-<p>The first argument, <tt>%val</tt> and the result may be integer types of
-any bit width but they must have the same bit width. <tt>%val</tt> is the value
+<p>The first argument, <tt>%val</tt>, and the result may be integer types of
+any bit width, but they must have the same bit width. <tt>%val</tt> is the value
whose bits will be replaced. The second argument, <tt>%repl</tt> may be an
integer of any bit width. The third and fourth arguments must be <tt>i32</tt>
type since they specify only a bit index.</p>
of operation: forwards and reverse. If <tt>%lo</tt> is greater than
<tt>%hi</tt> then the intrinsic operates in reverse mode. Otherwise it
operates in forward mode.</p>
+
<p>For both modes, the <tt>%repl</tt> value is prepared for use by either
truncating it down to the size of the replacement area or zero extending it
up to that size.</p>
+
<p>In forward mode, the bits between <tt>%lo</tt> and <tt>%hi</tt> (inclusive)
are replaced with corresponding bits from <tt>%repl</tt>. That is the 0th bit
in <tt>%repl</tt> replaces the <tt>%lo</tt>th bit in <tt>%val</tt> and etc. up
to the <tt>%hi</tt>th bit.</p>
+
<p>In reverse mode, a similar computation is made except that the bits are
reversed. That is, the <tt>0</tt>th bit in <tt>%repl</tt> replaces the
<tt>%hi</tt> bit in <tt>%val</tt> and etc. down to the <tt>%lo</tt>th bit.</p>
+
<h5>Examples:</h5>
+
<pre>
llvm.part.set(0xFFFF, 0, 4, 7) -> 0xFF0F
llvm.part.set(0xFFFF, 0, 7, 4) -> 0xFF0F
llvm.part.set(0xFFFF, F, 8, 3) -> 0xFFE7
llvm.part.set(0xFFFF, 0, 3, 8) -> 0xFE07
</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="int_overflow">Arithmetic with Overflow Intrinsics</a>
+</div>
+
+<div class="doc_text">
+<p>
+LLVM provides intrinsics for some arithmetic with overflow operations.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+
+<p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt>
+on any integer bit width.</p>
+
+<pre>
+ declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
+a signed addition of the two arguments, and indicate whether an overflow
+occurred during the signed summation.</p>
+
+<h5>Arguments:</h5>
+
+<p>The arguments (%a and %b) and the first element of the result structure may
+be of integer types of any bit width, but they must have the same bit width. The
+second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt>
+and <tt>%b</tt> are the two values that will undergo signed addition.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
+a signed addition of the two variables. They return a structure — the
+first element of which is the signed summation, and the second element of which
+is a bit specifying if the signed summation resulted in an overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+
+<p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt>
+on any integer bit width.</p>
+
+<pre>
+ declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
+an unsigned addition of the two arguments, and indicate whether a carry occurred
+during the unsigned summation.</p>
+
+<h5>Arguments:</h5>
+
+<p>The arguments (%a and %b) and the first element of the result structure may
+be of integer types of any bit width, but they must have the same bit width. The
+second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt>
+and <tt>%b</tt> are the two values that will undergo unsigned addition.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
+an unsigned addition of the two arguments. They return a structure — the
+first element of which is the sum, and the second element of which is a bit
+specifying if the unsigned summation resulted in a carry.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %carry, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+
+<p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt>
+on any integer bit width.</p>
+
+<pre>
+ declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
+a signed subtraction of the two arguments, and indicate whether an overflow
+occurred during the signed subtraction.</p>
+
+<h5>Arguments:</h5>
+
+<p>The arguments (%a and %b) and the first element of the result structure may
+be of integer types of any bit width, but they must have the same bit width. The
+second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt>
+and <tt>%b</tt> are the two values that will undergo signed subtraction.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
+a signed subtraction of the two arguments. They return a structure — the
+first element of which is the subtraction, and the second element of which is a bit
+specifying if the signed subtraction resulted in an overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt>' Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+
+<p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt>
+on any integer bit width.</p>
+
+<pre>
+ declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
+an unsigned subtraction of the two arguments, and indicate whether an overflow
+occurred during the unsigned subtraction.</p>
+
+<h5>Arguments:</h5>
+
+<p>The arguments (%a and %b) and the first element of the result structure may
+be of integer types of any bit width, but they must have the same bit width. The
+second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt>
+and <tt>%b</tt> are the two values that will undergo unsigned subtraction.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
+an unsigned subtraction of the two arguments. They return a structure — the
+first element of which is the subtraction, and the second element of which is a bit
+specifying if the unsigned subtraction resulted in an overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt>' Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+
+<p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt>
+on any integer bit width.</p>
+
+<pre>
+ declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
+a signed multiplication of the two arguments, and indicate whether an overflow
+occurred during the signed multiplication.</p>
+
+<h5>Arguments:</h5>
+
+<p>The arguments (%a and %b) and the first element of the result structure may
+be of integer types of any bit width, but they must have the same bit width. The
+second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt>
+and <tt>%b</tt> are the two values that will undergo signed multiplication.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
+a signed multiplication of the two arguments. They return a structure —
+the first element of which is the multiplication, and the second element of
+which is a bit specifying if the signed multiplication resulted in an
+overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt>' Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+
+<p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt>
+on any integer bit width.</p>
+
+<pre>
+ declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+
+<p><i><b>Warning:</b> '<tt>llvm.umul.with.overflow</tt>' is badly broken. It is
+actively being fixed, but it should not currently be used!</i></p>
+
+<p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
+a unsigned multiplication of the two arguments, and indicate whether an overflow
+occurred during the unsigned multiplication.</p>
+
+<h5>Arguments:</h5>
+
+<p>The arguments (%a and %b) and the first element of the result structure may
+be of integer types of any bit width, but they must have the same bit width. The
+second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt>
+and <tt>%b</tt> are the two values that will undergo unsigned
+multiplication.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
+an unsigned multiplication of the two arguments. They return a structure —
+the first element of which is the multiplication, and the second element of
+which is a bit specifying if the unsigned multiplication resulted in an
+overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+</pre>
+
</div>
<!-- ======================================================================= -->
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="int_ssp">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
+ <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
</div>
<div class="doc_text">
<h5>Syntax:</h5>
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
projects / oota-llvm.git / blobdiff