<title>LLVM Assembly Language Reference Manual</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="author" content="Chris Lattner">
- <meta name="description"
+ <meta name="description"
content="LLVM Assembly Language Reference Manual.">
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<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="#namedmetadatastructure">Named Metadata</a></li>
<li><a href="#paramattrs">Parameter Attributes</a></li>
<li><a href="#fnattrs">Function Attributes</a></li>
<li><a href="#gc">Garbage Collector Names</a></li>
<li><a href="#typesystem">Type System</a>
<ol>
<li><a href="#t_classifications">Type Classifications</a></li>
- <li><a href="#t_primitive">Primitive Types</a>
+ <li><a href="#t_primitive">Primitive Types</a>
<ol>
<li><a href="#t_integer">Integer Type</a></li>
<li><a href="#t_floating">Floating Point Types</a></li>
</li>
<li><a href="#t_derived">Derived Types</a>
<ol>
- <li><a href="#t_array">Array Type</a></li>
+ <li><a href="#t_aggregate">Aggregate Types</a>
+ <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_union">Union 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_struct">Structure Type</a></li>
- <li><a href="#t_pstruct">Packed Structure Type</a></li>
- <li><a href="#t_vector">Vector Type</a></li>
<li><a href="#t_opaque">Opaque Type</a></li>
</ol>
</li>
<li><a href="#undefvalues">Undefined Values</a></li>
<li><a href="#blockaddress">Addresses of Basic Blocks</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>
<ol>
<li><a href="#inlineasm">Inline Assembler Expressions</a></li>
+ <li><a href="#metadata">Metadata Nodes and Metadata Strings</a></li>
</ol>
</li>
<li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
<li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
</ol>
</li>
+ <li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a>
+ <ol>
+ <li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li>
+ <li><a href="#int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</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>
'<tt>llvm.trap</tt>' Intrinsic</a></li>
<li><a href="#int_stackprotector">
'<tt>llvm.stackprotector</tt>' Intrinsic</a></li>
+ <li><a href="#int_objectsize">
+ '<tt>llvm.objectsize</tt>' Intrinsic</a></li>
</ol>
</li>
</ol>
<i>; Call puts function to write out the string to stdout.</i>
<a href="#i_call">call</a> i32 @puts(i8 * %cast210) <i>; i32</i>
- <a href="#i_ret">ret</a> i32 0<br>}<br>
+ <a href="#i_ret">ret</a> i32 0<br>}
+
+<i>; Named metadata</i>
+!1 = metadata !{i32 41}
+!foo = !{!1, null}
</pre>
</div>
<p>This example is made up of a <a href="#globalvars">global variable</a> named
- "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and
+ "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function,
a <a href="#functionstructure">function definition</a> for
- "<tt>main</tt>".</p>
+ "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a>
+ "<tt>foo"</tt>.</p>
<p>In general, a module is made up of a list of global values, where both
functions and global variables are global values. Global values are
<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
- the same name when linkage occurs. This is typically used to implement
- inline functions, templates, or other code which must be generated in each
- translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are
- allowed to be discarded.</dd>
+ the same name when linkage occurs. This can be used to implement
+ some forms of inline functions, templates, or other code which must be
+ generated in each translation unit that uses it, but where the body may
+ be overridden with a more definitive definition later. Unreferenced
+ <tt>linkonce</tt> globals are allowed to be discarded. Note that
+ <tt>linkonce</tt> linkage does not actually allow the optimizer to
+ inline the body of this function into callers because it doesn't know if
+ this definition of the function is the definitive definition within the
+ program or whether it will be overridden by a stronger definition.
+ To enable inlining and other optimizations, use "<tt>linkonce_odr</tt>"
+ linkage.</dd>
<dt><tt><b><a name="linkage_weak">weak</a></b></tt></dt>
<dd>"<tt>weak</tt>" linkage has the same merging semantics as
Symbols with "<tt>common</tt>" linkage are merged in the same way as
<tt>weak symbols</tt>, and they may not be deleted if unreferenced.
<tt>common</tt> symbols may not have an explicit section,
- must have a zero initializer, and may not be marked '<a
+ must have a zero initializer, and may not be marked '<a
href="#globalvars"><tt>constant</tt></a>'. Functions and aliases may not
have common linkage.</dd>
(e.g. by passing things in registers). This calling convention allows the
target to use whatever tricks it wants to produce fast code for the
target, without having to conform to an externally specified ABI
- (Application Binary Interface). Implementations of this convention should
- allow arbitrary <a href="CodeGenerator.html#tailcallopt">tail call
- optimization</a> to be supported. This calling convention does not
- support varargs and requires the prototype of all callees to exactly match
- the prototype of the function definition.</dd>
+ (Application Binary Interface).
+ <a href="CodeGenerator.html#tailcallopt">Tail calls can only be optimized
+ when this or the GHC convention is used.</a> This calling convention
+ does not support varargs and requires the prototype of all callees to
+ exactly match the prototype of the function definition.</dd>
<dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
<dd>This calling convention attempts to make code in the caller as efficient
does not support varargs and requires the prototype of all callees to
exactly match the prototype of the function definition.</dd>
+ <dt><b>"<tt>cc <em>10</em></tt>" - GHC convention</b>:</dt>
+ <dd>This calling convention has been implemented specifically for use by the
+ <a href="http://www.haskell.org/ghc">Glasgow Haskell Compiler (GHC)</a>.
+ It passes everything in registers, going to extremes to achieve this by
+ disabling callee save registers. This calling convention should not be
+ used lightly but only for specific situations such as an alternative to
+ the <em>register pinning</em> performance technique often used when
+ implementing functional programming languages.At the moment only X86
+ supports this convention and it has the following limitations:
+ <ul>
+ <li>On <em>X86-32</em> only supports up to 4 bit type parameters. No
+ floating point types are supported.</li>
+ <li>On <em>X86-64</em> only supports up to 10 bit type parameters and
+ 6 floating point parameters.</li>
+ </ul>
+ This calling convention supports
+ <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> but
+ requires both the caller and callee are using it.
+ </dd>
+
<dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt>
<dd>Any calling convention may be specified by number, allowing
target-specific calling conventions to be used. Target specific calling
<div class="doc_text">
-<p>LLVM function definitions consist of the "<tt>define</tt>" keyord, an
+<p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an
optional <a href="#linkage">linkage type</a>, an optional
<a href="#visibility">visibility style</a>, an optional
<a href="#callingconv">calling convention</a>, a return type, an optional
<p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
optional <a href="#linkage">linkage type</a>, an optional
- <a href="#visibility">visibility style</a>, an optional
+ <a href="#visibility">visibility style</a>, an optional
<a href="#callingconv">calling convention</a>, a return type, an optional
<a href="#paramattrs">parameter attribute</a> for the return type, a function
name, a possibly empty list of arguments, an optional alignment, and an
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="namedmetadatastructure">Named Metadata</a>
+</div>
+
+<div class="doc_text">
+
+<p>Named metadata is a collection of metadata. <a href="#metadata">Metadata
+ nodes</a> (but not metadata strings) and null are the only valid operands for
+ a named metadata.</p>
+
+<h5>Syntax:</h5>
+<div class="doc_code">
+<pre>
+!1 = metadata !{metadata !"one"}
+!name = !{null, !1}
+</pre>
+</div>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div>
</div>
<dl>
+ <dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt>
+ <dd>This attribute indicates that, when emitting the prologue and epilogue,
+ the backend should forcibly align the stack pointer. Specify the
+ desired alignment, which must be a power of two, in parentheses.
+
<dt><tt><b>alwaysinline</b></tt></dt>
<dd>This attribute indicates that the inliner should attempt to inline this
function into callers whenever possible, ignoring any active inlining size
location.</dd>
<dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
+ <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
<i>preferred</i> alignments. All sizes are in bits. Specifying
the <i>pref</i> alignment is optional. If omitted, the
preceding <tt>:</tt> should be omitted too.</dd>
<i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
<dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the alignment for a vector type of a given bit
+ <dd>This specifies the alignment for a vector type of a given bit
<i>size</i>.</dd>
<dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the alignment for a floating point type of a given bit
+ <dd>This specifies the alignment for a floating point type of a given bit
<i>size</i>. The value of <i>size</i> must be either 32 (float) or 64
(double).</dd>
<dd>This specifies a set of native integer widths for the target CPU
in bits. For example, it might contain "n32" for 32-bit PowerPC,
"n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64. Elements of
- this set are considered to support most general arithmetic
+ this set are considered to support most general arithmetic
operations efficiently.</dd>
</dl>
<ul>
<li><tt>E</tt> - big endian</li>
- <li><tt>p:32:64:64</tt> - 32-bit pointers with 64-bit alignment</li>
+ <li><tt>p:64:64:64</tt> - 64-bit pointers with 64-bit alignment</li>
<li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
<li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
<li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
<a href="#t_pointer">pointer</a>,
<a href="#t_vector">vector</a>,
<a href="#t_struct">structure</a>,
+ <a href="#t_union">union</a>,
<a href="#t_array">array</a>,
<a href="#t_label">label</a>,
<a href="#t_metadata">metadata</a>.
</tr>
<tr>
<td><a href="#t_derived">derived</a></td>
- <td><a href="#t_integer">integer</a>,
- <a href="#t_array">array</a>,
+ <td><a href="#t_array">array</a>,
<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_union">union</a>,
<a href="#t_vector">vector</a>,
<a href="#t_opaque">opaque</a>.
</td>
</tr>
</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>
<!-- _______________________________________________________________________ -->
possible to have a two dimensional array, using an array as the element type
of another array.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="t_aggregate">Aggregate Types</a> </div>
+
+<div class="doc_text">
+
+<p>Aggregate Types are a subset of derived types that can contain multiple
+ member types. <a href="#t_array">Arrays</a>,
+ <a href="#t_struct">structs</a>, <a href="#t_vector">vectors</a> and
+ <a href="#t_union">unions</a> are aggregate types.</p>
+
+</div>
+
</div>
<!-- _______________________________________________________________________ -->
</tr>
</table>
-<p>Except when the <tt>inbounds</tt> keyword is present, there is no limitation
- on indexing beyond the end of the array implied by the static type (though
- any loads or stores must of course be within the bounds of the allocated
- object!). This means that single-dimension 'variable sized array' addressing
- can be implemented in LLVM with a zero length array type. An implementation
- of 'pascal style arrays' in LLVM could use the type
- "<tt>{ i32, [0 x float]}</tt>", 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>
+<p>There is no restriction on indexing beyond the end of the array implied by
+ a static type (though there are restrictions on indexing beyond the bounds
+ of an allocated object in some cases). This means that single-dimension
+ 'variable sized array' addressing can be implemented in LLVM with a zero
+ length array type. An implementation of 'pascal style arrays' in LLVM could
+ use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p>
</div>
<h5>Overview:</h5>
<p>The function type can be thought of as a function signature. It consists of
a return type and a list of formal parameter types. The return type of a
- function type is a scalar type, a void type, or a struct type. If the return
- type is a struct type then all struct elements must be of first class types,
- and the struct must have at least one element.</p>
+ function type is a scalar type, a void type, a struct type, or a union
+ type. If the return type is a struct type then all struct elements must be
+ of first class types, and the struct must have at least one element.</p>
<h5>Syntax:</h5>
<pre>
which indicates that the function takes a variable number of arguments.
Variable argument functions can access their arguments with
the <a href="#int_varargs">variable argument handling intrinsic</a>
- functions. '<tt><returntype></tt>' is a any type except
+ functions. '<tt><returntype></tt>' is any type except
<a href="#t_label">label</a>.</p>
<h5>Examples:</h5>
<td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
</td>
</tr><tr class="layout">
- <td class="left"><tt>float (i16 signext, i32 *) *
+ <td class="left"><tt>float (i16, i32 *) *
</tt></td>
- <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
- an <tt>i16</tt> that should be sign extended and a
- <a href="#t_pointer">pointer</a> to <tt>i32</tt>, returning
- <tt>float</tt>.
+ <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
+ an <tt>i16</tt> and a <a href="#t_pointer">pointer</a> to <tt>i32</tt>,
+ returning <tt>float</tt>.
</td>
</tr><tr class="layout">
<td class="left"><tt>i32 (i8*, ...)</tt></td>
- <td class="left">A vararg function that takes at least one
- <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
- which returns an integer. This is the signature for <tt>printf</tt> in
+ <td class="left">A vararg function that takes at least one
+ <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
+ which returns an integer. This is the signature for <tt>printf</tt> in
LLVM.
</td>
</tr><tr class="layout">
underlying processor. The elements of a 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>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
+ with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.
+ 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>
<h5>Syntax:</h5>
<pre>
{ <type list> }
</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>
<!-- _______________________________________________________________________ -->
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="t_union">Union Type</a> </div>
+
+<div class="doc_text">
+
+<h5>Overview:</h5>
+<p>A union type describes an object with size and alignment suitable for
+ an object of any one of a given set of types (also known as an "untagged"
+ union). It is similar in concept and usage to a
+ <a href="#t_struct">struct</a>, except that all members of the union
+ have an offset of zero. The elements of a union may be any type that has a
+ size. Unions must have at least one member - empty unions are not allowed.
+ </p>
+
+<p>The size of the union as a whole will be the size of its largest member,
+ and the alignment requirements of the union as a whole will be the largest
+ alignment requirement of any member.</p>
+
+<p>Union members 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.
+ Since all members are at offset zero, the getelementptr instruction does
+ not affect the address, only the type of the resulting pointer.</p>
+
+<h5>Syntax:</h5>
+<pre>
+ union { <type list> }
+</pre>
+
+<h5>Examples:</h5>
+<table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>union { i32, i32*, float }</tt></td>
+ <td class="left">A union of three types: an <tt>i32</tt>, a pointer to
+ an <tt>i32</tt>, and a <tt>float</tt>.</td>
+ </tr><tr class="layout">
+ <td class="left">
+ <tt>union { float, i32 (i32) * }</tt></td>
+ <td class="left">A union, 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>
+</table>
+
+</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
<div class="doc_text">
<h5>Overview:</h5>
-<p>As in many languages, the pointer type represents a pointer or reference to
- another object, which must live in memory. Pointer types may have 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>The pointer type is used to specify memory locations.
+ Pointers are commonly used to reference objects in memory.</p>
+
+<p>Pointer types may have an optional address space attribute defining the
+ numbered address space where the pointed-to object resides. The default
+ address space is number zero. The semantics of non-zero address
+ spaces are target-specific.</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>
<p>A vector type is a simple derived type that represents a vector of elements.
Vector types are used when multiple primitive data are operated in parallel
using a single instruction (SIMD). A vector type requires a size (number of
- elements) and an underlying primitive data type. Vectors must have a power
- of two length (1, 2, 4, 8, 16 ...). Vector types are considered
+ elements) and an underlying primitive data type. Vector types are considered
<a href="#t_firstclass">first class</a>.</p>
<h5>Syntax:</h5>
</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>
<!-- _______________________________________________________________________ -->
the number and types of elements must match those specified by the
type.</dd>
+ <dt><b>Union constants</b></dt>
+ <dd>Union constants are represented with notation similar to a structure with
+ a single element - that is, a single typed element surrounded
+ by braces (<tt>{}</tt>)). For example: "<tt>{ i32 4 }</tt>". The
+ <a href="#t_union">union type</a> can be initialized with a single-element
+ struct as long as the type of the struct element matches the type of
+ one of the union members.</dd>
+
<dt><b>Array constants</b></dt>
<dd>Array constants are represented with notation similar to array type
definitions (a comma separated list of elements, surrounded by square
<dt><b>Zero initialization</b></dt>
<dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
- value to zero of <em>any</em> type, including scalar and aggregate types.
+ value to zero of <em>any</em> type, including scalar and
+ <a href="#t_aggregate">aggregate</a> types.
This is often used to avoid having to print large zero initializers
(e.g. for large arrays) and is always exactly equivalent to using explicit
zero initializers.</dd>
For example, if "%X" has a zero bit, then the output of the 'and' operation will
always be a zero, no matter what the corresponding bit from the undef is. As
such, it is unsafe to optimize or assume that the result of the and is undef.
-However, it is safe to assume that all bits of the undef could be 0, and
-optimize the and to 0. Likewise, it is safe to assume that all the bits of
-the undef operand to the or could be set, allowing the or to be folded to
+However, it is safe to assume that all bits of the undef could be 0, and
+optimize the and to 0. Likewise, it is safe to assume that all the bits of
+the undef operand to the or could be set, allowing the or to be folded to
-1.</p>
<div class="doc_code">
<div class="doc_code">
<pre>
%A = xor undef, undef
-
+
%B = undef
%C = xor %B, %B
it: since the undefined operation "can't happen", the optimizer can assume that
it occurs in dead code.
</p>
-
+
<div class="doc_code">
<pre>
a: store undef -> %X
</div>
<p>These examples reiterate the fdiv example: a store "of" an undefined value
-can be assumed to not have any effect: we can assume that the value is
+can be assumed to not have any effect: we can assume that the value is
overwritten with bits that happen to match what was already there. However, a
store "to" an undefined location could clobber arbitrary memory, therefore, it
has undefined behavior.</p>
<p>The '<tt>blockaddress</tt>' constant computes the address of the specified
basic block in the specified function, and always has an i8* type. Taking
the address of the entry block is illegal.</p>
-
+
<p>This value only has defined behavior when used as an operand to the
'<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction or for comparisons
against null. Pointer equality tests between labels addresses is undefined
pointer sized value as long as the bits are not inspected. This allows
<tt>ptrtoint</tt> and arithmetic to be performed on these values so long as
the original value is reconstituted before the <tt>indirectbr</tt>.</p>
-
+
<p>Finally, some targets may provide defined semantics when
using the value as the operand to an inline assembly, but that is target
specific.
</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
- <tt>metadata</tt> type 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 preceded by an
- exclamation point). For example: "<tt>!{ metadata !"test\00", i32
- 10}</tt>".</p>
-
-<p>A metadata node will attempt to track changes to the values it holds. In the
- event that a value is deleted, it will be replaced with a typeless
- "<tt>null</tt>", such as "<tt>metadata !{null, 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>
<!-- *********************************************************************** -->
documented here. Constraints on what can be done (e.g. duplication, moving,
etc need to be documented). This is probably best done by reference to
another document that covers inline asm from a holistic perspective.</p>
+</div>
+
+<div class="doc_subsubsection">
+<a name="inlineasm_md">Inline Asm Metadata</a>
+</div>
+
+<div class="doc_text">
+
+<p>The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode
+ attached to it that contains a constant integer. If present, the code
+ generator will use the integer as the location cookie value when report
+ errors through the LLVMContext error reporting mechanisms. This allows a
+ front-end to corrolate backend errors that occur with inline asm back to the
+ source code that produced it. For example:</p>
+
+<div class="doc_code">
+<pre>
+call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
+...
+!42 = !{ i32 1234567 }
+</pre>
+</div>
+
+<p>It is up to the front-end to make sense of the magic numbers it places in the
+ IR.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="metadata">Metadata Nodes and Metadata
+ Strings</a>
+</div>
+
+<div class="doc_text">
+<p>LLVM IR allows metadata to be attached to instructions in the program that
+ can convey extra information about the code to the optimizers and code
+ generator. One example application of metadata is source-level debug
+ information. There are two metadata primitives: strings and nodes. All
+ metadata has the <tt>metadata</tt> type 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 preceded by an
+ exclamation point). For example: "<tt>!{ metadata !"test\00", i32
+ 10}</tt>". Metadata nodes can have any values as their operand.</p>
+
+<p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of
+ metadata nodes, which can be looked up in the module symbol table. For
+ example: "<tt>!foo = metadata !{!4, !3}</tt>".
+
+<p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt>
+ function is using two metadata arguments.
+
+ <div class="doc_code">
+ <pre>
+ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
+ </pre>
+ </div></p>
+
+<p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is
+ attached with <tt>add</tt> instruction using <tt>!dbg</tt> identifier.
+
+ <div class="doc_code">
+ <pre>
+ %indvar.next = add i64 %indvar, 1, !dbg !21
+ </pre>
+ </div></p>
</div>
control flow, not values (the one exception being the
'<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
-<p>There are six different terminator instructions: the
+<p>There are seven different terminator instructions: the
'<a href="#i_ret"><tt>ret</tt></a>' instruction, the
'<a href="#i_br"><tt>br</tt></a>' instruction, the
'<a href="#i_switch"><tt>switch</tt></a>' instruction, the
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>
rest of the arguments indicate the full set of possible destinations that the
address may point to. Blocks are allowed to occur multiple times in the
destination list, though this isn't particularly useful.</p>
-
+
<p>This destination list is required so that dataflow analysis has an accurate
understanding of the CFG.</p>
function to be invoked. </li>
<li>'<tt>function args</tt>': argument list whose types match the function
- signature argument types. If the function signature indicates the
- function accepts a variable number of arguments, the extra arguments can
- be specified.</li>
+ signature argument types and parameter attributes. All arguments must be
+ of <a href="#t_firstclass">first class</a> type. If the function
+ signature indicates the function accepts a variable number of arguments,
+ the extra arguments can be specified.</li>
<li>'<tt>normal label</tt>': the label reached when the called function
executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
block to the "normal" label. If the callee unwinds then no return value is
available.</p>
+<p>Note that the code generator does not yet completely support unwind, and
+that the invoke/unwind semantics are likely to change in future versions.</p>
+
<h5>Example:</h5>
<pre>
%retval = invoke i32 @Test(i32 15) to label %Continue
specified by the <tt>invoke</tt> instruction. If there is no <tt>invoke</tt>
instruction in the dynamic call chain, undefined behavior results.</p>
+<p>Note that the code generator does not yet completely support unwind, and
+that the invoke/unwind semantics are likely to change in future versions.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<p>The two arguments to the '<tt>mul</tt>' instruction must
be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
integer values. Both arguments must have identical types.</p>
-
+
<h5>Semantics:</h5>
<p>The value produced is the integer product of the two operands.</p>
<p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p>
<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>udiv</tt>' instruction must be
+<p>The two arguments to the '<tt>udiv</tt>' instruction must be
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
values. Both arguments must have identical types.</p>
<p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p>
<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>sdiv</tt>' instruction must be
+<p>The two arguments to the '<tt>sdiv</tt>' instruction must be
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
values. Both arguments must have identical types.</p>
division of its two arguments.</p>
<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>urem</tt>' instruction must be
+<p>The two arguments to the '<tt>urem</tt>' instruction must be
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
values. Both arguments must have identical types.</p>
elements must be integers.</p>
<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>srem</tt>' instruction must be
+<p>The two arguments to the '<tt>srem</tt>' instruction must be
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
values. Both arguments must have identical types.</p>
<p>Both arguments to the '<tt>shl</tt>' instruction must be the
same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
integer type. '<tt>op2</tt>' is treated as an unsigned value.</p>
-
+
<h5>Semantics:</h5>
<p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod
2<sup>n</sup>, where <tt>n</tt> is the width of the result. If <tt>op2</tt>
operand shifted to the right a specified number of bits with zero fill.</p>
<h5>Arguments:</h5>
-<p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
+<p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
type. '<tt>op2</tt>' is treated as an unsigned value.</p>
extension.</p>
<h5>Arguments:</h5>
-<p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
+<p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
type. '<tt>op2</tt>' is treated as an unsigned value.</p>
operands.</p>
<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>and</tt>' instruction must be
+<p>The two arguments to the '<tt>and</tt>' instruction must be
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
values. Both arguments must have identical types.</p>
two operands.</p>
<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>or</tt>' instruction must be
+<p>The two arguments to the '<tt>or</tt>' instruction must be
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
values. Both arguments must have identical types.</p>
complement" operation, which is the "~" operator in C.</p>
<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>xor</tt>' instruction must be
+<p>The two arguments to the '<tt>xor</tt>' instruction must be
<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
values. Both arguments must have identical types.</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<div class="doc_subsection">
<a name="vectorops">Vector Operations</a>
</div>
<h5>Example:</h5>
<pre>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
<4 x i32> <i32 0, i32 4, i32 1, i32 5> <i>; yields <4 x i32></i>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
<4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i> - Identity shuffle.
- <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
+ <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
<4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
<8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > <i>; yields <8 x i32></i>
</pre>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<div class="doc_subsection">
<a name="aggregateops">Aggregate Operations</a>
</div>
<div class="doc_text">
-<p>LLVM supports several instructions for working with aggregate values.</p>
+<p>LLVM supports several instructions for working with
+ <a href="#t_aggregate">aggregate</a> values.</p>
</div>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>extractvalue</tt>' instruction extracts the value of a struct field
- or array element from an aggregate value.</p>
+<p>The '<tt>extractvalue</tt>' instruction extracts the value of a member field
+ from an <a href="#t_aggregate">aggregate</a> value.</p>
<h5>Arguments:</h5>
<p>The first operand of an '<tt>extractvalue</tt>' instruction is a value
- of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. The
- operands are constant indices to specify which value to extract in a similar
- manner as indices in a
+ of <a href="#t_struct">struct</a>, <a href="#t_union">union</a> or
+ <a href="#t_array">array</a> type. The operands are constant indices to
+ specify which value to extract in a similar manner as indices in a
'<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
<h5>Semantics:</h5>
<h5>Syntax:</h5>
<pre>
- <result> = insertvalue <aggregate type> <val>, <ty> <val>, <idx> <i>; yields <n x <ty>></i>
+ <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx> <i>; yields <aggregate type></i>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>insertvalue</tt>' instruction inserts a value into a struct field or
- array element in an aggregate.</p>
-
+<p>The '<tt>insertvalue</tt>' instruction inserts a value into a member field
+ in an <a href="#t_aggregate">aggregate</a> value.</p>
<h5>Arguments:</h5>
<p>The first operand of an '<tt>insertvalue</tt>' instruction is a value
- of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. The
- second operand is a first-class value to insert. The following operands are
- constant indices indicating the position at which to insert the value in a
- similar manner as indices in a
+ of <a href="#t_struct">struct</a>, <a href="#t_union">union</a> or
+ <a href="#t_array">array</a> type. The second operand is a first-class
+ value to insert. The following operands are constant indices indicating
+ the position at which to insert the value in a similar manner as indices in a
'<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. The
value to insert must have the same type as the value identified by the
indices.</p>
<h5>Example:</h5>
<pre>
- <result> = insertvalue {i32, float} %agg, i32 1, 0 <i>; yields {i32, float}</i>
+ %agg1 = insertvalue {i32, float} undef, i32 1, 0 <i>; yields {i32 1, float undef}</i>
+ %agg2 = insertvalue {i32, float} %agg1, float %val, 1 <i>; yields {i32 1, float %val}</i>
</pre>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<div class="doc_subsection">
<a name="memoryops">Memory Access and Addressing Operations</a>
</div>
<h5>Syntax:</h5>
<pre>
- <result> = load <ty>* <pointer>[, align <alignment>]
- <result> = volatile load <ty>* <pointer>[, align <alignment>]
+ <result> = load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ <result> = volatile load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ !<index> = !{ i32 1 }
</pre>
<h5>Overview:</h5>
marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the
number or order of execution of this <tt>load</tt> with other
volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
- instructions. </p>
+ instructions.</p>
-<p>The optional constant "align" argument specifies the alignment of the
+<p>The optional constant <tt>align</tt> argument specifies the alignment of the
operation (that is, the alignment of the memory address). A value of 0 or an
- omitted "align" argument means that the operation has the preferential
+ omitted <tt>align</tt> argument means that the operation has the preferential
alignment for the target. It is the responsibility of the code emitter to
ensure that the alignment information is correct. Overestimating the
- alignment results in an undefined behavior. Underestimating the alignment may
+ alignment results in undefined behavior. Underestimating the alignment may
produce less efficient code. An alignment of 1 is always safe.</p>
+<p>The optional <tt>!nontemporal</tt> metadata must reference a single
+ metatadata name <index> corresponding to a metadata node with
+ one <tt>i32</tt> entry of value 1. The existence of
+ the <tt>!nontemporal</tt> metatadata on the instruction tells the optimizer
+ and code generator that this load is not expected to be reused in the cache.
+ The code generator may select special instructions to save cache bandwidth,
+ such as the <tt>MOVNT</tt> instruction on x86.</p>
+
<h5>Semantics:</h5>
<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
<h5>Syntax:</h5>
<pre>
- store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i>
- volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i>
+ store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
+ volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
</pre>
<h5>Overview:</h5>
alignment results in an undefined behavior. Underestimating the alignment may
produce less efficient code. An alignment of 1 is always safe.</p>
+<p>The optional !nontemporal metadata must reference a single metatadata
+ name <index> corresponding to a metadata node with one i32 entry of
+ value 1. The existence of the !nontemporal metatadata on the
+ instruction tells the optimizer and code generator that this load is
+ not expected to be reused in the cache. The code generator may
+ select special instructions to save cache bandwidth, such as the
+ MOVNT instruction on x86.</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. If
<h5>Overview:</h5>
<p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
- subelement of an aggregate data structure. It performs address calculation
- only and does not access memory.</p>
+ subelement of an <a href="#t_aggregate">aggregate</a> data structure.
+ It performs address calculation only and does not access memory.</p>
<h5>Arguments:</h5>
<p>The first argument is always a pointer, and forms the basis of the
indexes the pointer value given as the first argument, the second index
indexes a value of the type pointed to (not necessarily the value directly
pointed to, since the first index can be non-zero), etc. The first type
- indexed into must be a pointer value, subsequent types can be arrays, vectors
- and structs. Note that subsequent types being indexed into can never be
- pointers, since that would require loading the pointer before continuing
- calculation.</p>
+ indexed into must be a pointer value, subsequent types can be arrays,
+ vectors, structs and unions. Note that subsequent types being indexed into
+ can never be pointers, since that would require loading the pointer before
+ continuing calculation.</p>
<p>The type of each index argument depends on the type it is indexing into.
- When indexing into a (optionally packed) structure, only <tt>i32</tt> integer
- <b>constants</b> are allowed. When indexing into an array, pointer or
- vector, integers of any width are allowed, and they are not required to be
+ When indexing into a (optionally packed) structure or union, only <tt>i32</tt>
+ integer <b>constants</b> are allowed. When indexing into an array, pointer
+ or vector, integers of any width are allowed, and they are not required to be
constant.</p>
<p>For example, let's consider a C code fragment and how it gets compiled to
</pre>
<h5>Overview:</h5>
-<p>The '<tt>zext</tt>' instruction zero extends its operand to type
+<p>The '<tt>zext</tt>' instruction zero extends its operand to type
<tt>ty2</tt>.</p>
<h5>Arguments:</h5>
-<p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
+<p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
<a href="#t_integer">integer</a> type, and a type to cast it to, which must
also be of <a href="#t_integer">integer</a> type. The bit size of the
- <tt>value</tt> must be smaller than the bit size of the destination type,
+ <tt>value</tt> must be smaller than the bit size of the destination type,
<tt>ty2</tt>.</p>
<h5>Semantics:</h5>
<p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
<h5>Arguments:</h5>
-<p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of
+<p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of
<a href="#t_integer">integer</a> type, and a type to cast it to, which must
also be of <a href="#t_integer">integer</a> type. The bit size of the
- <tt>value</tt> must be smaller than the bit size of the destination type,
+ <tt>value</tt> must be smaller than the bit size of the destination type,
<tt>ty2</tt>.</p>
<h5>Semantics:</h5>
<p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
point</a> value to cast and a <a href="#t_floating">floating point</a> type
to cast it to. The size of <tt>value</tt> must be larger than the size of
- <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
+ <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
<i>no-op cast</i>.</p>
<h5>Semantics:</h5>
<p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
- <a href="#t_floating">floating point</a> type to a smaller
+ <a href="#t_floating">floating point</a> type to a smaller
<a href="#t_floating">floating point</a> type. If the value cannot fit
within the destination type, <tt>ty2</tt>, then the results are
undefined.</p>
floating point value.</p>
<h5>Arguments:</h5>
-<p>The '<tt>fpext</tt>' instruction takes a
+<p>The '<tt>fpext</tt>' instruction takes a
<a href="#t_floating">floating point</a> <tt>value</tt> to cast, and
a <a href="#t_floating">floating point</a> type to cast it to. The source
type must be smaller than the destination type.</p>
vector integer type with the same number of elements as <tt>ty</tt></p>
<h5>Semantics:</h5>
-<p>The '<tt>fptoui</tt>' instruction converts its
+<p>The '<tt>fptoui</tt>' instruction converts its
<a href="#t_floating">floating point</a> operand into the nearest (rounding
towards zero) unsigned integer value. If the value cannot fit
in <tt>ty2</tt>, the results are undefined.</p>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>fptosi</tt>' instruction converts
+<p>The '<tt>fptosi</tt>' instruction converts
<a href="#t_floating">floating point</a> <tt>value</tt> to
type <tt>ty2</tt>.</p>
vector integer type with the same number of elements as <tt>ty</tt></p>
<h5>Semantics:</h5>
-<p>The '<tt>fptosi</tt>' instruction converts its
+<p>The '<tt>fptosi</tt>' instruction converts its
<a href="#t_floating">floating point</a> operand into the nearest (rounding
towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
the results are undefined.</p>
<pre>
%X = bitcast i8 255 to i8 <i>; yields i8 :-1</i>
%Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i>
- %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i>
+ %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i>
</pre>
</div>
result, as follows:</p>
<ol>
- <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
+ <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
<tt>false</tt> otherwise. No sign interpretation is necessary or
performed.</li>
- <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
+ <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
<tt>false</tt> otherwise. No sign interpretation is necessary or
performed.</li>
<ol>
<li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
- <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
<tt>op1</tt> is equal to <tt>op2</tt>.</li>
<li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
- <tt>op1</tt> is greather than <tt>op2</tt>.</li>
+ <tt>op1</tt> is greater than <tt>op2</tt>.</li>
- <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
<tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
- <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
<tt>op1</tt> is less than <tt>op2</tt>.</li>
- <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
<tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
- <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
<tt>op1</tt> is not equal to <tt>op2</tt>.</li>
<li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
- <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
<tt>op1</tt> is equal to <tt>op2</tt>.</li>
- <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
<tt>op1</tt> is greater than <tt>op2</tt>.</li>
- <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
<tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
- <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
<tt>op1</tt> is less than <tt>op2</tt>.</li>
- <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
<tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
- <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
<tt>op1</tt> is not equal to <tt>op2</tt>.</li>
<li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
<p>This instruction requires several arguments:</p>
<ol>
- <li>The optional "tail" marker indicates whether the callee function accesses
- any allocas or varargs in the caller. If the "tail" marker is present,
- the function call is eligible for tail call optimization. Note that calls
- may be marked "tail" even if they do not occur before
- a <a href="#i_ret"><tt>ret</tt></a> instruction.</li>
+ <li>The optional "tail" marker indicates that the callee function does not
+ access any allocas or varargs in the caller. Note that calls may be
+ marked "tail" even if they do not occur before
+ a <a href="#i_ret"><tt>ret</tt></a> instruction. If the "tail" marker is
+ present, the function call is eligible for tail call optimization,
+ but <a href="CodeGenerator.html#tailcallopt">might not in fact be
+ optimized into a jump</a>. The code generator may optimize calls marked
+ "tail" with either 1) automatic <a href="CodeGenerator.html#sibcallopt">
+ sibling call optimization</a> when the caller and callee have
+ matching signatures, or 2) forced tail call optimization when the
+ following extra requirements are met:
+ <ul>
+ <li>Caller and callee both have the calling
+ convention <tt>fastcc</tt>.</li>
+ <li>The call is in tail position (ret immediately follows call and ret
+ uses value of call or is void).</li>
+ <li>Option <tt>-tailcallopt</tt> is enabled,
+ or <code>llvm::GuaranteedTailCallOpt</code> is <code>true</code>.</li>
+ <li><a href="CodeGenerator.html#tailcallopt">Platform specific
+ constraints are met.</a></li>
+ </ul>
+ </li>
<li>The optional "cconv" marker indicates which <a href="#callingconv">calling
convention</a> the call should use. If none is specified, the call
- defaults to using C calling conventions.</li>
+ defaults to using C calling conventions. The calling convention of the
+ call must match the calling convention of the target function, or else the
+ behavior is undefined.</li>
<li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
to function value.</li>
<li>'<tt>function args</tt>': argument list whose types match the function
- signature argument types. All arguments must be of
- <a href="#t_firstclass">first class</a> type. If the function signature
- indicates the function accepts a variable number of arguments, the extra
- arguments can be specified.</li>
+ signature argument types and parameter attributes. All arguments must be
+ of <a href="#t_firstclass">first class</a> type. If the function
+ signature indicates the function accepts a variable number of arguments,
+ the extra arguments can be specified.</li>
<li>The optional <a href="#fnattrs">function attributes</a> list. Only
'<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
standard C99 library as being the C99 library functions, and may perform
optimizations or generate code for them under that assumption. This is
something we'd like to change in the future to provide better support for
-freestanding environments and non-C-based langauges.</p>
+freestanding environments and non-C-based languages.</p>
</div>
suffix is required. Because the argument's type is matched against the return
type, it does not require its own name suffix.</p>
-<p>To learn how to add an intrinsic function, please see the
+<p>To learn how to add an intrinsic function, please see the
<a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
</div>
<h5>Semantics:</h5>
<p>This intrinsic does not modify the behavior of the program. Backends that do
- not support this intrinisic may ignore it.</p>
+ not support this intrinsic may ignore it.</p>
</div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any
- integer bit width. Not all targets support all bit widths however.</p>
+ integer bit width and for different address spaces. 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>,
- i64 <len>, i32 <align>)
+ declare void @llvm.memcpy.p0i8.p0i8.i32(i8 * <dest>, i8 * <src>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memcpy.p0i8.p0i8.i64(i8 * <dest>, i8 * <src>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
</pre>
<h5>Overview:</h5>
source location to the destination location.</p>
<p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
- intrinsics do not return a value, and takes an extra alignment argument.</p>
+ intrinsics do not return a value, takes extra alignment/isvolatile arguments
+ and the pointers can be in specified address spaces.</p>
<h5>Arguments:</h5>
+
<p>The first argument is a pointer to the destination, the second is a pointer
to the source. The third argument is an integer argument specifying the
- number of bytes to copy, and the fourth argument is the alignment of the
- source and destination locations.</p>
+ number of bytes to copy, the fourth argument is the alignment of the
+ source and destination locations, and the fifth is a boolean indicating a
+ volatile access.</p>
-<p>If the call to this intrinisic has an alignment value that is not 0 or 1,
+<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
then the caller guarantees that both the source and destination pointers are
aligned to that boundary.</p>
+<p>Volatile accesses should not be deleted if dead, but the access behavior is
+ not very cleanly specified and it is unwise to depend on it.</p>
+
<h5>Semantics:</h5>
+
<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
source location to the destination location, which are not allowed to
overlap. It copies "len" bytes of memory over. If the argument is known to
<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>
+ width and for different address space. 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>,
- i64 <len>, i32 <align>)
+ declare void @llvm.memmove.p0i8.p0i8.i32(i8 * <dest>, i8 * <src>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memmove.p0i8.p0i8.i64(i8 * <dest>, i8 * <src>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
</pre>
<h5>Overview:</h5>
overlap.</p>
<p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
- intrinsics do not return a value, and takes an extra alignment argument.</p>
+ intrinsics do not return a value, takes extra alignment/isvolatile arguments
+ and the pointers can be in specified address spaces.</p>
<h5>Arguments:</h5>
+
<p>The first argument is a pointer to the destination, the second is a pointer
to the source. The third argument is an integer argument specifying the
- number of bytes to copy, and the fourth argument is the alignment of the
- source and destination locations.</p>
+ number of bytes to copy, the fourth argument is the alignment of the
+ source and destination locations, and the fifth is a boolean indicating a
+ volatile access.</p>
-<p>If the call to this intrinisic has an alignment value that is not 0 or 1,
+<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
then the caller guarantees that the source and destination pointers are
aligned to that boundary.</p>
+<p>Volatile accesses should not be deleted if dead, but the access behavior is
+ not very cleanly specified and it is unwise to depend on it.</p>
+
<h5>Semantics:</h5>
+
<p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the
source location to the destination location, which may overlap. It copies
"len" bytes of memory over. If the argument is known to be aligned to some
<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>
+ width and for different address spaces. 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>,
- i64 <len>, i32 <align>)
+ declare void @llvm.memset.p0i8.i32(i8 * <dest>, i8 <val>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memset.p0i8.i64(i8 * <dest>, i8 <val>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
</pre>
<h5>Overview:</h5>
particular byte value.</p>
<p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt>
- intrinsic does not return a value, and takes an extra alignment argument.</p>
+ intrinsic does not return a value, takes extra alignment/volatile arguments,
+ and the destination can be in an arbitrary address space.</p>
<h5>Arguments:</h5>
<p>The first argument is a pointer to the destination to fill, the second is the
specifying the number of bytes to fill, and the fourth argument is the known
alignment of destination location.</p>
-<p>If the call to this intrinisic has an alignment value that is not 0 or 1,
+<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
then the caller guarantees that the destination pointer is aligned to that
boundary.</p>
+<p>Volatile accesses should not be deleted if dead, but the access behavior is
+ not very cleanly specified and it is unwise to depend on it.</p>
+
<h5>Semantics:</h5>
<p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting
at the destination location. If the argument is known to be aligned to some
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="int_fp16">Half Precision Floating Point Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<p>Half precision floating point is a storage-only format. This means that it is
+ a dense encoding (in memory) but does not support computation in the
+ format.</p>
+
+<p>This means that code must first load the half-precision floating point
+ value as an i16, then convert it to float with <a
+ href="#int_convert_from_fp16"><tt>llvm.convert.from.fp16</tt></a>.
+ Computation can then be performed on the float value (including extending to
+ double etc). To store the value back to memory, it is first converted to
+ float if needed, then converted to i16 with
+ <a href="#int_convert_to_fp16"><tt>llvm.convert.to.fp16</tt></a>, then
+ storing as an i16 value.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare i16 @llvm.convert.to.fp16(f32 %a)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
+ a conversion from single precision floating point format to half precision
+ floating point format.</p>
+
+<h5>Arguments:</h5>
+<p>The intrinsic function contains single argument - the value to be
+ converted.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
+ a conversion from single precision floating point format to half precision
+ floating point format. The return value is an <tt>i16</tt> which
+ contains the converted number.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %res = call i16 @llvm.convert.to.fp16(f32 %a)
+ store i16 %res, i16* @x, align 2
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare f32 @llvm.convert.from.fp16(i16 %a)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs
+ a conversion from half precision floating point format to single precision
+ floating point format.</p>
+
+<h5>Arguments:</h5>
+<p>The intrinsic function contains single argument - the value to be
+ converted.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs a
+ conversion from half single precision floating point format to single
+ precision floating point format. The input half-float value is represented by
+ an <tt>i16</tt> value.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %a = load i16* @x, align 2
+ %res = call f32 @llvm.convert.from.fp16(i16 %a)
+</pre>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="int_debugger">Debugger Intrinsics</a>
<h5>Arguments:</h5>
<p>The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments.
The first four arguments enables a specific barrier as listed below. The
- fith argument specifies that the barrier applies to io or device or uncached
+ fifth argument specifies that the barrier applies to io or device or uncached
memory.</p>
<ul>
<ul>
<li><tt>ll</tt>: All loads before the barrier must complete before any load
after the barrier begins.</li>
- <li><tt>ls</tt>: All loads before the barrier must complete before any
+ <li><tt>ls</tt>: All loads before the barrier must complete before any
store after the barrier begins.</li>
- <li><tt>ss</tt>: All stores before the barrier must complete before any
+ <li><tt>ss</tt>: All stores before the barrier must complete before any
store after the barrier begins.</li>
- <li><tt>sl</tt>: All stores before the barrier must complete before any
+ <li><tt>sl</tt>: All stores before the barrier must complete before any
load after the barrier begins.</li>
</ul>
</pre>
<h5>Overview:</h5>
-<p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at
+<p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at
<tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p>
<h5>Arguments:</h5>
</pre>
<h5>Overview:</h5>
-<p>These intrinsics takes the signed or unsigned minimum or maximum of
+<p>These intrinsics takes the signed or unsigned minimum or maximum of
<tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the
original value at <tt>ptr</tt>.</p>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare i32 @llvm.objectsize.i32( i8* <object>, i1 <type> )
+ declare i64 @llvm.objectsize.i64( i8* <object>, i1 <type> )
+</pre>
+
+<h5>Overview:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information
+ to the optimizers to discover at compile time either a) when an
+ operation like memcpy will either overflow a buffer that corresponds to
+ an object, or b) to determine that a runtime check for overflow isn't
+ necessary. An object in this context means an allocation of a
+ specific class, structure, array, or other object.</p>
+
+<h5>Arguments:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments. The first
+ argument is a pointer to or into the <tt>object</tt>. The second argument
+ is a boolean 0 or 1. This argument determines whether you want the
+ maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or
+ 1, variables are not allowed.</p>
+
+<h5>Semantics:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic is lowered to either a constant
+ representing the size of the object concerned or <tt>i32/i64 -1 or 0</tt>
+ (depending on the <tt>type</tt> argument if the size cannot be determined
+ at compile time.</p>
+
+</div>
+
<!-- *********************************************************************** -->
<hr>
<address>
projects / oota-llvm.git / blobdiff