<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>
<ol>
<li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li>
<li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li>
+ <li><a href="#linkage_linker_private_weak">'<tt>linker_private_weak</tt>' Linkage</a></li>
+ <li><a href="#linkage_linker_private_weak_def_auto">'<tt>linker_private_weak_def_auto</tt>' Linkage</a></li>
<li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li>
<li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li>
<li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li>
<li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li>
<li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li>
<li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li>
- <li><a href="#linkage_linkonce">'<tt>linkonce_odr</tt>' Linkage</a></li>
+ <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li>
<li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li>
<li><a href="#linkage_external">'<tt>externally visible</tt>' Linkage</a></li>
<li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</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="#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="#moduleasm">Module-Level Inline Assembly</a></li>
<li><a href="#datalayout">Data Layout</a></li>
<li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
+ <li><a href="#volatile">Volatile Memory Accesses</a></li>
</ol>
</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><a href="#t_x86mmx">X86mmx Type</a></li>
<li><a href="#t_void">Void Type</a></li>
<li><a href="#t_label">Label Type</a></li>
<li><a href="#t_metadata">Metadata Type</a></li>
</li>
<li><a href="#t_derived">Derived Types</a>
<ol>
- <li><a href="#t_integer">Integer Type</a></li>
- <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_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="#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="#trapvalues">Trap 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="#i_ret">'<tt>ret</tt>' Instruction</a></li>
<li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
<li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
+ <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li>
<li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
<li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li>
<li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
</li>
<li><a href="#memoryops">Memory Access and Addressing Operations</a>
<ol>
- <li><a href="#i_malloc">'<tt>malloc</tt>' Instruction</a></li>
- <li><a href="#i_free">'<tt>free</tt>' Instruction</a></li>
<li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li>
<li><a href="#i_load">'<tt>load</tt>' Instruction</a></li>
<li><a href="#i_store">'<tt>store</tt>' Instruction</a></li>
<li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
<li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
<li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
- <li><a href="#int_readcyclecounter"><tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
+ <li><a href="#int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
</ol>
</li>
<li><a href="#int_libc">Standard C Library Intrinsics</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>
<li><a href="#int_atomic_load_umin"><tt>llvm.atomic.load.umin</tt></a></li>
</ol>
</li>
+ <li><a href="#int_memorymarkers">Memory Use Markers</a>
+ <ol>
+ <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li>
+ <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li>
+ <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li>
+ <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li>
+ </ol>
+ </li>
<li><a href="#int_general">General intrinsics</a>
<ol>
<li><a href="#int_var_annotation">
'<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>
IR's", allowing many source languages to be mapped to them). By providing
type information, LLVM can be used as the target of optimizations: for
example, through pointer analysis, it can be proven that a C automatic
- variable is never accessed outside of the current function... allowing it to
+ variable is never accessed outside of the current function, allowing it to
be promoted to a simple SSA value instead of a memory location.</p>
</div>
what is considered 'well formed'. For example, the following instruction is
syntactically okay, but not well formed:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%x = <a href="#i_add">add</a> i32 1, %x
</pre>
-</div>
-<p>...because the definition of <tt>%x</tt> does not dominate all of its
- uses. The LLVM infrastructure provides a verification pass that may be used
- to verify that an LLVM module is well formed. This pass is automatically run
- by the parser after parsing input assembly and by the optimizer before it
- outputs bitcode. The violations pointed out by the verifier pass indicate
- bugs in transformation passes or input to the parser.</p>
+<p>because the definition of <tt>%x</tt> does not dominate all of its uses. The
+ LLVM infrastructure provides a verification pass that may be used to verify
+ that an LLVM module is well formed. This pass is automatically run by the
+ parser after parsing input assembly and by the optimizer before it outputs
+ bitcode. The violations pointed out by the verifier pass indicate bugs in
+ transformation passes or input to the parser.</p>
</div>
<p>The easy way:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%result = <a href="#i_mul">mul</a> i32 %X, 8
</pre>
-</div>
<p>After strength reduction:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%result = <a href="#i_shl">shl</a> i32 %X, i8 3
</pre>
-</div>
<p>And the hard way:</p>
-<div class="doc_code">
-<pre>
-<a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i>
-<a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i>
+<pre class="doc_code">
+%0 = <a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i>
+%1 = <a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i>
%result = <a href="#i_add">add</a> i32 %1, %1
</pre>
-</div>
<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
lexical features of LLVM:</p>
<li>Unnamed temporaries are numbered sequentially</li>
</ol>
-<p>...and it also shows a convention that we follow in this document. When
+<p>It also shows a convention that we follow in this document. When
demonstrating instructions, we will follow an instruction with a comment that
defines the type and name of value produced. Comments are shown in italic
text.</p>
forward declarations, and merges symbol table entries. Here is an example of
the "hello world" module:</p>
-<div class="doc_code">
-<pre><i>; Declare the string constant as a global constant...</i>
-<a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a
- href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i>
+<pre class="doc_code">
+<i>; Declare the string constant as a global constant.</i>
+<a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i>
-<i>; External declaration of the puts function</i>
-<a href="#functionstructure">declare</a> i32 @puts(i8 *) <i>; i32(i8 *)* </i>
+<i>; External declaration of the puts function</i>
+<a href="#functionstructure">declare</a> i32 @puts(i8*) <i>; i32 (i8*)* </i>
<i>; Definition of main function</i>
-define i32 @main() { <i>; i32()* </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>
+define i32 @main() { <i>; i32()* </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>
- <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>
+ <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
+}
+
+<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
linkage:</p>
<dl>
- <dt><tt><b><a name="linkage_private">private</a></b></tt>: </dt>
- <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
- 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_linker_private">linker_private</a></b></tt>: </dt>
- <dd>Similar to private, but the symbol is passed through the assembler and
- removed by the linker after evaluation.</dd>
-
- <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 "<tt>private</tt>" linkage are only directly accessible
+ by objects in the current module. In particular, linking code into a
+ module with 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_linker_private">linker_private</a></b></tt></dt>
+ <dd>Similar to <tt>private</tt>, but the symbol is passed through the
+ assembler and evaluated by the linker. Unlike normal strong symbols, they
+ are removed by the linker from the final linked image (executable or
+ dynamic library).</dd>
+
+ <dt><tt><b><a name="linkage_linker_private_weak">linker_private_weak</a></b></tt></dt>
+ <dd>Similar to "<tt>linker_private</tt>", but the symbol is weak. Note that
+ <tt>linker_private_weak</tt> symbols are subject to coalescing by the
+ linker. The symbols are removed by the linker from the final linked image
+ (executable or dynamic library).</dd>
+
+ <dt><tt><b><a name="linkage_linker_private_weak_def_auto">linker_private_weak_def_auto</a></b></tt></dt>
+ <dd>Similar to "<tt>linker_private_weak</tt>", but it's known that the address
+ of the object is not taken. For instance, functions that had an inline
+ definition, but the compiler decided not to inline it. Note,
+ unlike <tt>linker_private</tt> and <tt>linker_private_weak</tt>,
+ <tt>linker_private_weak_def_auto</tt> may have only <tt>default</tt>
+ visibility. The symbols are removed by the linker from the final linked
+ image (executable or dynamic library).</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
(<tt>STB_LOCAL</tt> 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="linkage_available_externally">available_externally</a></b></tt>: </dt>
+ <dt><tt><b><a name="linkage_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
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>
+ <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>
-
- <dt><tt><b><a name="linkage_common">common</a></b></tt>: </dt>
- <dd>"<tt>common</tt>" linkage is exactly the same as <tt>linkonce</tt>
- linkage, except that unreferenced <tt>common</tt> globals may not be
- discarded. This is used for globals that may be emitted in multiple
- translation units, but that are not guaranteed to be emitted into every
- translation unit that uses them. One example of this is tentative
- definitions in C, such as "<tt>int X;</tt>" at global scope.</dd>
-
- <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
- <dd>"<tt>weak</tt>" linkage is the same as <tt>common</tt> linkage, except
- that some targets may choose to emit different assembly sequences for them
- for target-dependent reasons. This is used for globals that are declared
- "weak" in C source code.</dd>
-
- <dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt>
+ 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
+ <tt>linkonce</tt> linkage, except that unreferenced globals with
+ <tt>weak</tt> linkage may not be discarded. This is used for globals that
+ are declared "weak" in C source code.</dd>
+
+ <dt><tt><b><a name="linkage_common">common</a></b></tt></dt>
+ <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
+ they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
+ global scope.
+ 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
+ href="#globalvars"><tt>constant</tt></a>'. Functions and aliases may not
+ have common linkage.</dd>
+
+
+ <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt>
<dd>"<tt>appending</tt>" linkage may only be applied to global variables of
pointer to array type. When two global variables with appending linkage
are linked together, the two global arrays are appended together. This is
the LLVM, typesafe, equivalent of having the system linker append together
"sections" with identical names when .o files are linked.</dd>
- <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt>: </dt>
+ <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>
+ <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt></dt>
+ <dt><tt><b><a name="linkage_weak_odr">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>
+ 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>
DLLs (Dynamic Link Libraries).</p>
<dl>
- <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt>: </dt>
+ <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt>
<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.</dd>
- <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt>: </dt>
+ <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
(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
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>
+<pre class="doc_code">
%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
+ "<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,
region of memory, and all memory objects in LLVM are accessed through
pointers.</p>
+<p>Global variables can be marked with <tt>unnamed_addr</tt> which indicates
+ that the address is not significant, only the content. Constants marked
+ like this can be merged with other constants if they have the same
+ initializer. Note that a constant with significant address <em>can</em>
+ be merged with a <tt>unnamed_addr</tt> constant, the result being a
+ constant whose address is significant.</p>
+
<p>A global variable may be declared to reside in a target-specific numbered
address space. For targets that support them, address spaces may affect how
optimizations are performed and/or what target instructions are used to
<p>LLVM allows an explicit section to be specified for globals. If the target
supports it, it will emit globals to the section specified.</p>
-<p>An explicit alignment may be specified for a global. If not present, or if
- the alignment is set to zero, the alignment of the global is set by the
- target to whatever it feels convenient. If an explicit alignment is
- specified, the global is forced to have at least that much alignment. All
- alignments must be a power of 2.</p>
+<p>An explicit alignment may be specified for a global, which must be a power
+ of 2. If not present, or if the alignment is set to zero, the alignment of
+ the global is set by the target to whatever it feels convenient. If an
+ explicit alignment is specified, the global is forced to have exactly that
+ alignment. Targets and optimizers are not allowed to over-align the global
+ if the global has an assigned section. In this case, the extra alignment
+ could be observable: for example, code could assume that the globals are
+ densely packed in their section and try to iterate over them as an array,
+ alignment padding would break this iteration.</p>
<p>For example, the following defines a global in a numbered address space with
an initializer, section, and alignment:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
@G = addrspace(5) constant float 1.0, section "foo", align 4
</pre>
-</div>
</div>
<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
+ <a href="#callingconv">calling convention</a>,
+ an optional <tt>unnamed_addr</tt> attribute, a return type, an optional
<a href="#paramattrs">parameter attribute</a> for the return type, a function
name, a (possibly empty) argument list (each with optional
<a href="#paramattrs">parameter attributes</a>), 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="#callingconv">calling convention</a>, a return type, an optional
+ <a href="#visibility">visibility style</a>, an optional
+ <a href="#callingconv">calling convention</a>,
+ an optional <tt>unnamed_addr</tt> attribute, 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
optional <a href="#gc">garbage collector name</a>.</p>
specified, the function is forced to have at least that much alignment. All
alignments must be a power of 2.</p>
+<p>If the <tt>unnamed_addr</tt> attribute is given, the address is know to not
+ be significant and two identical functions can be merged</p>.
+
<h5>Syntax:</h5>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
[<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>]
<ResultType> @<FunctionName> ([argument list])
[<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N]
[<a href="#gc">gc</a>] { ... }
</pre>
-</div>
</div>
optional <a href="#visibility">visibility style</a>.</p>
<h5>Syntax:</h5>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
@<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
</pre>
+
+</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) are the only valid operands for
+ a named metadata.</p>
+
+<h5>Syntax:</h5>
+<pre class="doc_code">
+; Some unnamed metadata nodes, which are referenced by the named metadata.
+!0 = metadata !{metadata !"zero"}
+!1 = metadata !{metadata !"one"}
+!2 = metadata !{metadata !"two"}
+; A named metadata.
+!name = !{!0, !1, !2}
+</pre>
+
</div>
<!-- ======================================================================= -->
multiple parameter attributes are needed, they are space separated. For
example:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
declare i32 @printf(i8* noalias nocapture, ...)
declare i32 @atoi(i8 zeroext)
declare signext i8 @returns_signed_char()
</pre>
-</div>
<p>Note that any attributes for the function result (<tt>nounwind</tt>,
<tt>readonly</tt>) come immediately after the argument list.</p>
<p>Currently, only the following parameter attributes are defined:</p>
<dl>
- <dt><tt>zeroext</tt></dt>
+ <dt><tt><b>zeroext</b></tt></dt>
<dd>This indicates to the code generator that the parameter or return value
- should be zero-extended to a 32-bit value by the caller (for a parameter)
- or the callee (for a return value).</dd>
+ should be zero-extended to the extent required by the target's ABI (which
+ is usually 32-bits, but is 8-bits for a i1 on x86-64) by the caller (for a
+ parameter) or the callee (for a return value).</dd>
- <dt><tt>signext</tt></dt>
+ <dt><tt><b>signext</b></tt></dt>
<dd>This indicates to the code generator that the parameter or return value
- should be sign-extended to a 32-bit value by the caller (for a parameter)
- or the callee (for a return value).</dd>
+ should be sign-extended to the extent required by the target's ABI (which
+ is usually 32-bits) by the caller (for a parameter) or the callee (for a
+ return value).</dd>
- <dt><tt>inreg</tt></dt>
+ <dt><tt><b>inreg</b></tt></dt>
<dd>This indicates that this parameter or return value should be treated in a
special target-dependent fashion during while emitting code for a function
call or return (usually, by putting it in a register as opposed to memory,
though some targets use it to distinguish between two different kinds of
registers). Use of this attribute is target-specific.</dd>
- <dt><tt><a name="byval">byval</a></tt></dt>
- <dd>This indicates that the pointer parameter should really be passed by value
- to the function. The attribute implies that a hidden copy of the pointee
+ <dt><tt><b><a name="byval">byval</a></b></tt></dt>
+ <dd><p>This indicates that the pointer parameter should really be passed by
+ value to the function. The attribute implies that a hidden copy of the
+ pointee
is made between the caller and the callee, so the callee is unable to
modify the value in the callee. This attribute is only valid on LLVM
pointer arguments. It is generally used to pass structs and arrays by
to 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. 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>
+ values.</p>
+
+ <p>The byval attribute also supports specifying an alignment with
+ the align attribute. It indicates the alignment of the stack slot to
+ form and the known alignment of the pointer specified to the call site. If
+ the alignment is not specified, then the code generator makes a
+ target-specific assumption.</p></dd>
+
+ <dt><tt><b><a name="sret">sret</a></b></tt></dt>
<dd>This indicates that the pointer parameter specifies the address of a
structure that is the return value of the function in the source program.
This pointer must be guaranteed by the caller to be valid: loads and
may only be applied to the first parameter. This is not a valid attribute
for return values. </dd>
- <dt><tt>noalias</tt></dt>
- <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>
+ <dt><tt><b><a name="noalias">noalias</a></b></tt></dt>
+ <dd>This indicates that pointer values
+ <a href="#pointeraliasing"><i>based</i></a> on the argument or return
+ value do not alias pointer values which are not <i>based</i> on it,
+ ignoring certain "irrelevant" dependencies.
+ For a call to the parent function, dependencies between memory
+ references from before or after the call and from those during the call
+ are "irrelevant" to the <tt>noalias</tt> keyword for the arguments and
+ return value used in that call.
+ The caller shares the responsibility with the callee for ensuring that
+ these requirements are met.
+ For further details, please see the discussion of the NoAlias response in
+ <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.<br>
+<br>
+ Note that this definition of <tt>noalias</tt> is intentionally
+ similar to the definition of <tt>restrict</tt> in C99 for function
+ arguments, though it is slightly weaker.
+<br>
+ For function return values, C99's <tt>restrict</tt> is not meaningful,
+ while LLVM's <tt>noalias</tt> is.
+ </dd>
+
+ <dt><tt><b><a name="nocapture">nocapture</a></b></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>
+ <dt><tt><b><a name="nest">nest</a></b></tt></dt>
<dd>This indicates that the pointer parameter can be excised using the
<a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid
attribute for return values.</dd>
<p>Each function may specify a garbage collector name, which is simply a
string:</p>
-<div class="doc_code">
-<pre>
-define void @f() gc "name" { ...
+<pre class="doc_code">
+define void @f() gc "name" { ... }
</pre>
-</div>
<p>The compiler declares the supported values of <i>name</i>. Specifying a
collector which will cause the compiler to alter its output in order to
<p>Function attributes are simple keywords that follow the type specified. If
multiple attributes are needed, they are space separated. For example:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
define void @f() noinline { ... }
define void @f() alwaysinline { ... }
define void @f() alwaysinline optsize { ... }
-define void @f() optsize
+define void @f() optsize { ... }
</pre>
-</div>
<dl>
- <dt><tt>alwaysinline</tt></dt>
+ <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
threshold for this caller.</dd>
- <dt><tt>noinline</tt></dt>
+ <dt><tt><b>hotpatch</b></tt></dt>
+ <dd>This attribute indicates that the function should be 'hotpatchable',
+ meaning the function can be patched and/or hooked even while it is
+ loaded into memory. On x86, the function prologue will be preceded
+ by six bytes of padding and will begin with a two-byte instruction.
+ Most of the functions in the Windows system DLLs in Windows XP SP2 or
+ higher were compiled in this fashion.</dd>
+
+ <dt><tt><b>inlinehint</b></tt></dt>
+ <dd>This attribute indicates that the source code contained a hint that inlining
+ this function is desirable (such as the "inline" keyword in C/C++). It
+ is just a hint; it imposes no requirements on the inliner.</dd>
+
+ <dt><tt><b>naked</b></tt></dt>
+ <dd>This attribute disables prologue / epilogue emission for the function.
+ This can have very system-specific consequences.</dd>
+
+ <dt><tt><b>noimplicitfloat</b></tt></dt>
+ <dd>This attributes disables implicit floating point instructions.</dd>
+
+ <dt><tt><b>noinline</b></tt></dt>
<dd>This attribute indicates that the inliner should never inline this
function in any situation. This attribute may not be used together with
the <tt>alwaysinline</tt> attribute.</dd>
- <dt><tt>optsize</tt></dt>
- <dd>This attribute suggests that optimization passes and code generator passes
- make choices that keep the code size of this function low, and otherwise
- do optimizations specifically to reduce code size.</dd>
+ <dt><tt><b>noredzone</b></tt></dt>
+ <dd>This attribute indicates that the code generator should not use a red
+ zone, even if the target-specific ABI normally permits it.</dd>
- <dt><tt>noreturn</tt></dt>
+ <dt><tt><b>noreturn</b></tt></dt>
<dd>This function attribute indicates that the function never returns
normally. This produces undefined behavior at runtime if the function
ever does dynamically return.</dd>
- <dt><tt>nounwind</tt></dt>
+ <dt><tt><b>nounwind</b></tt></dt>
<dd>This function attribute indicates that the function never returns with an
unwind or exceptional control flow. If the function does unwind, its
runtime behavior is undefined.</dd>
- <dt><tt>readnone</tt></dt>
+ <dt><tt><b>optsize</b></tt></dt>
+ <dd>This attribute suggests that optimization passes and code generator passes
+ make choices that keep the code size of this function low, and otherwise
+ do optimizations specifically to reduce code size.</dd>
+
+ <dt><tt><b>readnone</b></tt></dt>
<dd>This attribute indicates that the function computes its result (or decides
to unwind an exception) based strictly on its arguments, without
dereferencing any pointer arguments or otherwise accessing any mutable
exceptions by calling the <tt>C++</tt> exception throwing methods, but
could use the <tt>unwind</tt> instruction.</dd>
- <dt><tt><a name="readonly">readonly</a></tt></dt>
+ <dt><tt><b><a name="readonly">readonly</a></b></tt></dt>
<dd>This attribute indicates that the function does not write through any
pointer arguments (including <tt><a href="#byval">byval</a></tt>
arguments) or otherwise modify any state (e.g. memory, control registers,
exception by calling the <tt>C++</tt> exception throwing methods, but may
use the <tt>unwind</tt> instruction.</dd>
- <dt><tt><a name="ssp">ssp</a></tt></dt>
+ <dt><tt><b><a name="ssp">ssp</a></b></tt></dt>
<dd>This attribute indicates that the function should emit a stack smashing
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 that doesn't have an <tt>ssp</tt> attribute, then the resulting
function will have an <tt>ssp</tt> attribute.</dd>
- <dt><tt>sspreq</tt></dt>
+ <dt><tt><b>sspreq</b></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.<br>
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.</dd>
-
- <dt><tt>noredzone</tt></dt>
- <dd>This attribute indicates that the code generator should not use a red
- zone, even if the target-specific ABI normally permits it.</dd>
-
- <dt><tt>noimplicitfloat</tt></dt>
- <dd>This attributes disables implicit floating point instructions.</dd>
-
- <dt><tt>naked</tt></dt>
- <dd>This attribute disables prologue / epilogue emission for the function.
- This can have very system-specific consequences.</dd>
</dl>
</div>
concatenated by LLVM and treated as a single unit, but may be separated in
the <tt>.ll</tt> file if desired. The syntax is very simple:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
module asm "inline asm code goes here"
module asm "more can go here"
</pre>
-</div>
<p>The strings can contain any character by escaping non-printable characters.
The escape sequence used is simply "\xx" where "xx" is the two digit hex code
data is to be laid out in memory. The syntax for the data layout is
simply:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
target datalayout = "<i>layout specification</i>"
</pre>
-</div>
<p>The <i>layout specification</i> consists of a list of specifications
separated by the minus sign character ('-'). Each specification starts with
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
- <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64
- (double).</dd>
+ <dd>This specifies the alignment for a floating point type of a given bit
+ <i>size</i>. Only values of <i>size</i> that are supported by the target
+ will work. 32 (float) and 64 (double) are supported on all targets;
+ 80 or 128 (different flavors of long double) are also supported on some
+ targets.
<dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
<dd>This specifies the alignment for an aggregate type of a given bit
<dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
<dd>This specifies the alignment for a stack object of a given bit
<i>size</i>.</dd>
+
+ <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt>
+ <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
+ operations efficiently.</dd>
</dl>
<p>When constructing the data layout for a given target, LLVM starts with a
- default set of specifications which are then (possibly) overriden by the
+ default set of specifications which are then (possibly) overridden by the
specifications in the <tt>datalayout</tt> keyword. The default specifications
are given in this list:</p>
<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>
<div class="doc_text">
-<p>Any memory access must be done though a pointer value associated
+<p>Any memory access must be done through a pointer value associated
with an address range of the memory access, otherwise the behavior
is undefined. Pointer values are associated with address ranges
according to the following rules:</p>
<ul>
- <li>A pointer value formed from a <tt>getelementptr</tt> instruction is
- associated with the addresses associated with the first operand of
- the <tt>getelementptr</tt>.</li>
- <li>An addresses of a global variable is associated with the address
+ <li>A pointer value is associated with the addresses associated with
+ any value it is <i>based</i> on.
+ <li>An address of a global variable is associated with the address
range of the variable's storage.</li>
<li>The result value of an allocation instruction is associated with
the address range of the allocated storage.</li>
<li>A null pointer in the default address-space is associated with
- no addresses.</li>
- <li>A pointer value formed by an <tt>inttoptr</tt> is associated with
- all address ranges of all pointer values that contribute (directly
- or indirectly) to the computation of the pointer's value.</li>
- <li>The result value of a <tt>bitcast</tt> is associated with all
- addresses associated with the operand of the <tt>bitcast</tt>.</li>
+ no address.</li>
<li>An integer constant other than zero or a pointer value returned
from a function not defined within LLVM may be associated with address
ranges allocated through mechanisms other than those provided by
- LLVM. Such ranges shall not overlap with any ranges of address
+ LLVM. Such ranges shall not overlap with any ranges of addresses
allocated by mechanisms provided by LLVM.</li>
- </ul>
+</ul>
+
+<p>A pointer value is <i>based</i> on another pointer value according
+ to the following rules:</p>
+
+<ul>
+ <li>A pointer value formed from a
+ <tt><a href="#i_getelementptr">getelementptr</a></tt> operation
+ is <i>based</i> on the first operand of the <tt>getelementptr</tt>.</li>
+ <li>The result value of a
+ <tt><a href="#i_bitcast">bitcast</a></tt> is <i>based</i> on the operand
+ of the <tt>bitcast</tt>.</li>
+ <li>A pointer value formed by an
+ <tt><a href="#i_inttoptr">inttoptr</a></tt> is <i>based</i> on all
+ pointer values that contribute (directly or indirectly) to the
+ computation of the pointer's value.</li>
+ <li>The "<i>based</i> on" relationship is transitive.</li>
+</ul>
+
+<p>Note that this definition of <i>"based"</i> is intentionally
+ similar to the definition of <i>"based"</i> in C99, though it is
+ slightly weaker.</p>
<p>LLVM IR does not associate types with memory. The result type of a
-<tt>load</tt> merely indicates the size and alignment of the memory from
-which to load, as well as the interpretation of the value. The first
-operand of a <tt>store</tt> similarly only indicates the size and
-alignment of the store.</p>
+<tt><a href="#i_load">load</a></tt> merely indicates the size and
+alignment of the memory from which to load, as well as the
+interpretation of the value. The first operand type of a
+<tt><a href="#i_store">store</a></tt> similarly only indicates the size
+and alignment of the store.</p>
<p>Consequently, type-based alias analysis, aka TBAA, aka
<tt>-fstrict-aliasing</tt>, is not applicable to general unadorned
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="volatile">Volatile Memory Accesses</a>
+</div>
+
+<div class="doc_text">
+
+<p>Certain memory accesses, such as <a href="#i_load"><tt>load</tt></a>s, <a
+href="#i_store"><tt>store</tt></a>s, and <a
+href="#int_memcpy"><tt>llvm.memcpy</tt></a>s may be marked <tt>volatile</tt>.
+The optimizers must not change the number of volatile operations or change their
+order of execution relative to other volatile operations. The optimizers
+<i>may</i> change the order of volatile operations relative to non-volatile
+operations. This is not Java's "volatile" and has no cross-thread
+synchronization behavior.</p>
+
+</div>
+
<!-- *********************************************************************** -->
<div class="doc_section"> <a name="typesystem">Type System</a> </div>
<!-- *********************************************************************** -->
<td><a href="#t_primitive">primitive</a></td>
<td><a href="#t_label">label</a>,
<a href="#t_void">void</a>,
+ <a href="#t_integer">integer</a>,
<a href="#t_floating">floating point</a>,
+ <a href="#t_x86mmx">x86mmx</a>,
<a href="#t_metadata">metadata</a>.</td>
</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>,
<p>The <a href="#t_firstclass">first class</a> types are perhaps the most
important. Values of these types are the only ones which can be produced by
- instructions, passed as arguments, or used as operands to instructions.</p>
+ instructions.</p>
</div>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
+
+<div class="doc_text">
+
+<h5>Overview:</h5>
+<p>The integer type is a very simple type that simply specifies an arbitrary
+ bit width for the integer type desired. Any bit width from 1 bit to
+ 2<sup>23</sup>-1 (about 8 million) can be specified.</p>
+
+<h5>Syntax:</h5>
+<pre>
+ iN
+</pre>
+
+<p>The number of bits the integer will occupy is specified by the <tt>N</tt>
+ value.</p>
+
+<h5>Examples:</h5>
+<table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>i1</tt></td>
+ <td class="left">a single-bit integer.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>i32</tt></td>
+ <td class="left">a 32-bit integer.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>i1942652</tt></td>
+ <td class="left">a really big integer of over 1 million bits.</td>
+ </tr>
+</table>
+
+</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="t_x86mmx">X86mmx Type</a> </div>
+
+<div class="doc_text">
+
+<h5>Overview:</h5>
+<p>The x86mmx type represents a value held in an MMX register on an x86 machine. The operations allowed on it are quite limited: parameters and return values, load and store, and bitcast. User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type. There are no arrays, vectors or constants of this type.</p>
+
+<h5>Syntax:</h5>
+<pre>
+ x86mmx
+</pre>
+
+</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div>
<div class="doc_text">
<h5>Overview:</h5>
-<p>The metadata type represents embedded metadata. The only derived type that
- may contain metadata is <tt>metadata*</tt> or a function type that returns or
- takes metadata typed parameters, but not pointer to metadata types.</p>
+<p>The metadata type represents embedded metadata. No derived types may be
+ created from metadata except for <a href="#t_function">function</a>
+ arguments.
<h5>Syntax:</h5>
<pre>
<p>The real power in LLVM comes from the derived types in the system. This is
what allows a programmer to represent arrays, functions, pointers, and other
- useful types. Note that these derived types may be recursive: For example,
- it is possible to have a two dimensional array.</p>
+ useful types. Each of these types contain one or more element types which
+ may be a primitive type, or another derived type. For example, it is
+ 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_integer">Integer Type</a> </div>
+<div class="doc_subsubsection"> <a name="t_aggregate">Aggregate Types</a> </div>
<div class="doc_text">
-<h5>Overview:</h5>
-<p>The integer type is a very simple derived type that simply specifies an
- arbitrary bit width for the integer type desired. Any bit width from 1 bit to
- 2^23-1 (about 8 million) can be specified.</p>
-
-<h5>Syntax:</h5>
-<pre>
- iN
-</pre>
-
-<p>The number of bits the integer will occupy is specified by the <tt>N</tt>
- value.</p>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>i1</tt></td>
- <td class="left">a single-bit integer.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i32</tt></td>
- <td class="left">a 32-bit integer.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i1942652</tt></td>
- <td class="left">a really big integer of over 1 million bits.</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>
+<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>, and <a href="#t_vector">vectors</a> are
+ aggregate types.</p>
</div>
</tr>
</table>
-<p>Note that 'variable sized arrays' can be implemented in LLVM with a zero
- length array. Normally, accesses past the end of an array are undefined in
- LLVM (e.g. it is illegal to access the 5th element of a 3 element array). As
- a special case, however, zero length arrays are recognized to be variable
- length. This allows implementation of 'pascal style arrays' with the LLVM
- 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 first class type or a void type.</p>
<h5>Syntax:</h5>
<pre>
- <returntype list> (<parameter list>)
+ <returntype> (<parameter list>)
</pre>
<p>...where '<tt><parameter list></tt>' is a comma-separated list of type
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 list></tt>' is a comma-separated list of
- <a href="#t_firstclass">first class</a> type specifiers.</p>
+ functions. '<tt><returntype></tt>' is any type except
+ <a href="#t_label">label</a>.</p>
<h5>Examples:</h5>
<table class="layout">
<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">
<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 a
+ <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
</td>
</tr>
</table>
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 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>
href="#t_array">array</a> of four <tt>i32</tt> values.</td>
</tr>
<tr class="layout">
- <td class="left"><tt>i32 (i32 *) *</tt></td>
+ <td class="left"><tt>i32 (i32*) *</tt></td>
<td class="left"> 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>
<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>
< <# elements> x <elementtype> >
</pre>
-<p>The number of elements is a constant integer value; elementtype may be any
- integer or floating point type.</p>
+<p>The number of elements is a constant integer value larger than 0; elementtype
+ may be any integer or floating point type. Vectors of size zero are not
+ allowed, and pointers are not allowed as the element type.</p>
<h5>Examples:</h5>
<table class="layout">
</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>
<!-- _______________________________________________________________________ -->
<dl>
<dt><b>Boolean constants</b></dt>
<dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
- constants of the <tt><a href="#t_primitive">i1</a></tt> type.</dd>
+ constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd>
<dt><b>Integer constants</b></dt>
<dd>Standard integers (such as '4') are constants of
they match the long double format on your target. All hexadecimal formats
are big-endian (sign bit at the left).</p>
+<p>There are no constants of type x86mmx.</p>
</div>
<!-- ======================================================================= -->
<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>
have <a href="#t_pointer">pointer</a> type. For example, the following is a
legal LLVM file:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
@X = global i32 17
@Y = global i32 42
@Z = global [2 x i32*] [ i32* @X, i32* @Y ]
</pre>
-</div>
</div>
<div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
<div class="doc_text">
-<p>The string '<tt>undef</tt>' is recognized as a type-less constant that has no
- specific value. Undefined values may be of any type and be used anywhere a
- constant is permitted.</p>
+<p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
+ indicates that the user of the value may receive an unspecified bit-pattern.
+ Undefined values may be of any type (other than '<tt>label</tt>'
+ or '<tt>void</tt>') and be used anywhere a constant is permitted.</p>
+
+<p>Undefined values are useful because they indicate to the compiler that the
+ program is well defined no matter what value is used. This gives the
+ compiler more freedom to optimize. Here are some examples of (potentially
+ surprising) transformations that are valid (in pseudo IR):</p>
+
+
+<pre class="doc_code">
+ %A = add %X, undef
+ %B = sub %X, undef
+ %C = xor %X, undef
+Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+</pre>
+
+<p>This is safe because all of the output bits are affected by the undef bits.
+ Any output bit can have a zero or one depending on the input bits.</p>
+
+<pre class="doc_code">
+ %A = or %X, undef
+ %B = and %X, undef
+Safe:
+ %A = -1
+ %B = 0
+Unsafe:
+ %A = undef
+ %B = undef
+</pre>
+
+<p>These logical operations have bits that are not always affected by the input.
+ For example, if <tt>%X</tt> has a zero bit, then the output of the
+ '<tt>and</tt>' operation will always be a zero for that bit, no matter what
+ the corresponding bit from the '<tt>undef</tt>' is. As such, it is unsafe to
+ optimize or assume that the result of the '<tt>and</tt>' is '<tt>undef</tt>'.
+ However, it is safe to assume that all bits of the '<tt>undef</tt>' could be
+ 0, and optimize the '<tt>and</tt>' to 0. Likewise, it is safe to assume that
+ all the bits of the '<tt>undef</tt>' operand to the '<tt>or</tt>' could be
+ set, allowing the '<tt>or</tt>' to be folded to -1.</p>
+
+<pre class="doc_code">
+ %A = select undef, %X, %Y
+ %B = select undef, 42, %Y
+ %C = select %X, %Y, undef
+Safe:
+ %A = %X (or %Y)
+ %B = 42 (or %Y)
+ %C = %Y
+Unsafe:
+ %A = undef
+ %B = undef
+ %C = undef
+</pre>
+
+<p>This set of examples shows that undefined '<tt>select</tt>' (and conditional
+ branch) conditions can go <em>either way</em>, but they have to come from one
+ of the two operands. In the <tt>%A</tt> example, if <tt>%X</tt> and
+ <tt>%Y</tt> were both known to have a clear low bit, then <tt>%A</tt> would
+ have to have a cleared low bit. However, in the <tt>%C</tt> example, the
+ optimizer is allowed to assume that the '<tt>undef</tt>' operand could be the
+ same as <tt>%Y</tt>, allowing the whole '<tt>select</tt>' to be
+ eliminated.</p>
+
+<pre class="doc_code">
+ %A = xor undef, undef
+
+ %B = undef
+ %C = xor %B, %B
+
+ %D = undef
+ %E = icmp lt %D, 4
+ %F = icmp gte %D, 4
+
+Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+ %D = undef
+ %E = undef
+ %F = undef
+</pre>
+
+<p>This example points out that two '<tt>undef</tt>' operands are not
+ necessarily the same. This can be surprising to people (and also matches C
+ semantics) where they assume that "<tt>X^X</tt>" is always zero, even
+ if <tt>X</tt> is undefined. This isn't true for a number of reasons, but the
+ short answer is that an '<tt>undef</tt>' "variable" can arbitrarily change
+ its value over its "live range". This is true because the variable doesn't
+ actually <em>have a live range</em>. Instead, the value is logically read
+ from arbitrary registers that happen to be around when needed, so the value
+ is not necessarily consistent over time. In fact, <tt>%A</tt> and <tt>%C</tt>
+ need to have the same semantics or the core LLVM "replace all uses with"
+ concept would not hold.</p>
+
+<pre class="doc_code">
+ %A = fdiv undef, %X
+ %B = fdiv %X, undef
+Safe:
+ %A = undef
+b: unreachable
+</pre>
+
+<p>These examples show the crucial difference between an <em>undefined
+ value</em> and <em>undefined behavior</em>. An undefined value (like
+ '<tt>undef</tt>') is allowed to have an arbitrary bit-pattern. This means that
+ the <tt>%A</tt> operation can be constant folded to '<tt>undef</tt>', because
+ the '<tt>undef</tt>' could be an SNaN, and <tt>fdiv</tt> is not (currently)
+ defined on SNaN's. However, in the second example, we can make a more
+ aggressive assumption: because the <tt>undef</tt> is allowed to be an
+ arbitrary value, we are allowed to assume that it could be zero. Since a
+ divide by zero has <em>undefined behavior</em>, we are allowed to assume that
+ the operation does not execute at all. This allows us to delete the divide and
+ all code after it. Because the undefined operation "can't happen", the
+ optimizer can assume that it occurs in dead code.</p>
+
+<pre class="doc_code">
+a: store undef -> %X
+b: store %X -> undef
+Safe:
+a: <deleted>
+b: unreachable
+</pre>
+
+<p>These examples reiterate the <tt>fdiv</tt> example: a store <em>of</em> an
+ undefined value 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 <em>to</em> an undefined location could clobber arbitrary
+ memory, therefore, it has undefined behavior.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="trapvalues">Trap Values</a></div>
+<div class="doc_text">
+
+<p>Trap values are similar to <a href="#undefvalues">undef values</a>, however
+ instead of representing an unspecified bit pattern, they represent the
+ fact that an instruction or constant expression which cannot evoke side
+ effects has nevertheless detected a condition which results in undefined
+ behavior.</p>
+
+<p>There is currently no way of representing a trap value in the IR; they
+ only exist when produced by operations such as
+ <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p>
+
+<p>Trap value behavior is defined in terms of value <i>dependence</i>:</p>
+
+<ul>
+<li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
+ their operands.</li>
+
+<li><a href="#i_phi"><tt>Phi</tt></a> nodes depend on the operand corresponding
+ to their dynamic predecessor basic block.</li>
+
+<li>Function arguments depend on the corresponding actual argument values in
+ the dynamic callers of their functions.</li>
+
+<li><a href="#i_call"><tt>Call</tt></a> instructions depend on the
+ <a href="#i_ret"><tt>ret</tt></a> instructions that dynamically transfer
+ control back to them.</li>
+
+<li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the
+ <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_unwind"><tt>unwind</tt></a>,
+ or exception-throwing call instructions that dynamically transfer control
+ back to them.</li>
+
+<li>Non-volatile loads and stores depend on the most recent stores to all of the
+ referenced memory addresses, following the order in the IR
+ (including loads and stores implied by intrinsics such as
+ <a href="#int_memcpy"><tt>@llvm.memcpy</tt></a>.)</li>
+
+<!-- TODO: In the case of multiple threads, this only applies if the store
+ "happens-before" the load or store. -->
+
+<!-- TODO: floating-point exception state -->
+
+<li>An instruction with externally visible side effects depends on the most
+ recent preceding instruction with externally visible side effects, following
+ the order in the IR. (This includes
+ <a href="#volatile">volatile operations</a>.)</li>
+
+<li>An instruction <i>control-depends</i> on a
+ <a href="#terminators">terminator instruction</a>
+ if the terminator instruction has multiple successors and the instruction
+ is always executed when control transfers to one of the successors, and
+ may not be executed when control is transfered to another.</li>
+
+<li>Dependence is transitive.</li>
+
+</ul>
+
+<p>Whenever a trap value is generated, all values which depend on it evaluate
+ to trap. If they have side effects, the evoke their side effects as if each
+ operand with a trap value were undef. If they have externally-visible side
+ effects, the behavior is undefined.</p>
+
+<p>Here are some examples:</p>
+
+<pre class="doc_code">
+entry:
+ %trap = sub nuw i32 0, 1 ; Results in a trap value.
+ %still_trap = and i32 %trap, 0 ; Whereas (and i32 undef, 0) would return 0.
+ %trap_yet_again = getelementptr i32* @h, i32 %still_trap
+ store i32 0, i32* %trap_yet_again ; undefined behavior
+
+ store i32 %trap, i32* @g ; Trap value conceptually stored to memory.
+ %trap2 = load i32* @g ; Returns a trap value, not just undef.
+
+ volatile store i32 %trap, i32* @g ; External observation; undefined behavior.
+
+ %narrowaddr = bitcast i32* @g to i16*
+ %wideaddr = bitcast i32* @g to i64*
+ %trap3 = load 16* %narrowaddr ; Returns a trap value.
+ %trap4 = load i64* %widaddr ; Returns a trap value.
+
+ %cmp = icmp i32 slt %trap, 0 ; Returns a trap value.
+ %br i1 %cmp, %true, %end ; Branch to either destination.
+
+true:
+ volatile store i32 0, i32* @g ; This is control-dependent on %cmp, so
+ ; it has undefined behavior.
+ br label %end
+
+end:
+ %p = phi i32 [ 0, %entry ], [ 1, %true ]
+ ; Both edges into this PHI are
+ ; control-dependent on %cmp, so this
+ ; always results in a trap value.
+
+ volatile store i32 0, i32* @g ; %end is control-equivalent to %entry
+ ; so this is defined (ignoring earlier
+ ; undefined behavior in this example).
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="blockaddress">Addresses of Basic
+ Blocks</a></div>
+<div class="doc_text">
+
+<p><b><tt>blockaddress(@function, %block)</tt></b></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>Undefined values indicate to the compiler that the program is well defined no
- matter what value is used, giving the compiler more freedom to optimize.</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
+ results in undefined behavior — though, again, comparison against null
+ is ok, and no label is equal to the null pointer. This may be passed around
+ as an opaque 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>
+ instruction.</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.</p>
</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
</div>
to be used as constants. Constant expressions may be of
any <a href="#t_firstclass">first class</a> type and may involve any LLVM
operation that does not have side effects (e.g. load and call are not
- supported). The following is the syntax for constant expressions:</p>
+ supported). The following is the syntax for constant expressions:</p>
<dl>
- <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>trunc (CST to TYPE)</tt></b></dt>
<dd>Truncate a constant to another type. The bit size of CST must be larger
than the bit size of TYPE. Both types must be integers.</dd>
- <dt><b><tt>zext ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>zext (CST to TYPE)</tt></b></dt>
<dd>Zero extend a constant to another type. The bit size of CST must be
- smaller or equal to the bit size of TYPE. Both types must be
- integers.</dd>
+ smaller than the bit size of TYPE. Both types must be integers.</dd>
- <dt><b><tt>sext ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>sext (CST to TYPE)</tt></b></dt>
<dd>Sign extend a constant to another type. The bit size of CST must be
- smaller or equal to the bit size of TYPE. Both types must be
- integers.</dd>
+ smaller than the bit size of TYPE. Both types must be integers.</dd>
- <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>fptrunc (CST to TYPE)</tt></b></dt>
<dd>Truncate a floating point constant to another floating point type. The
size of CST must be larger than the size of TYPE. Both types must be
floating point.</dd>
- <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>fpext (CST to TYPE)</tt></b></dt>
<dd>Floating point extend a constant to another type. The size of CST must be
smaller or equal to the size of TYPE. Both types must be floating
point.</dd>
- <dt><b><tt>fptoui ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>fptoui (CST to TYPE)</tt></b></dt>
<dd>Convert a floating point constant to the corresponding unsigned integer
constant. TYPE must be a scalar or vector integer type. CST must be of
scalar or vector floating point type. Both CST and TYPE must be scalars,
or vectors of the same number of elements. If the value won't fit in the
integer type, the results are undefined.</dd>
- <dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>fptosi (CST to TYPE)</tt></b></dt>
<dd>Convert a floating point constant to the corresponding signed integer
constant. TYPE must be a scalar or vector integer type. CST must be of
scalar or vector floating point type. Both CST and TYPE must be scalars,
or vectors of the same number of elements. If the value won't fit in the
integer type, the results are undefined.</dd>
- <dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>uitofp (CST to TYPE)</tt></b></dt>
<dd>Convert an unsigned integer constant to the corresponding floating point
constant. TYPE must be a scalar or vector floating point type. CST must be
of scalar or vector integer type. Both CST and TYPE must be scalars, or
vectors of the same number of elements. If the value won't fit in the
floating point type, the results are undefined.</dd>
- <dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>sitofp (CST to TYPE)</tt></b></dt>
<dd>Convert a signed integer constant to the corresponding floating point
constant. TYPE must be a scalar or vector floating point type. CST must be
of scalar or vector integer type. Both CST and TYPE must be scalars, or
vectors of the same number of elements. If the value won't fit in the
floating point type, the results are undefined.</dd>
- <dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>ptrtoint (CST to TYPE)</tt></b></dt>
<dd>Convert a pointer typed constant to the corresponding integer constant
<tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer
type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to
make it fit in <tt>TYPE</tt>.</dd>
- <dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>inttoptr (CST to TYPE)</tt></b></dt>
<dd>Convert a integer constant to a pointer constant. TYPE must be a pointer
type. CST must be of integer type. The CST value is zero extended,
truncated, or unchanged to make it fit in a pointer size. This one is
<i>really</i> dangerous!</dd>
- <dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt>
+ <dt><b><tt>bitcast (CST to TYPE)</tt></b></dt>
<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>
+ <dt><b><tt>getelementptr (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
+ <dt><b><tt>getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
<dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
constants. As with the <a href="#i_getelementptr">getelementptr</a>
instruction, the index list may have zero or more indexes, which are
required to make sense for the type of "CSTPTR".</dd>
- <dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt>
+ <dt><b><tt>select (COND, VAL1, VAL2)</tt></b></dt>
<dd>Perform the <a href="#i_select">select operation</a> on constants.</dd>
- <dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt>
+ <dt><b><tt>icmp COND (VAL1, VAL2)</tt></b></dt>
<dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
- <dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt>
+ <dt><b><tt>fcmp COND (VAL1, VAL2)</tt></b></dt>
<dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
- <dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt>
+ <dt><b><tt>extractelement (VAL, IDX)</tt></b></dt>
<dd>Perform the <a href="#i_extractelement">extractelement operation</a> on
constants.</dd>
- <dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt>
+ <dt><b><tt>insertelement (VAL, ELT, IDX)</tt></b></dt>
<dd>Perform the <a href="#i_insertelement">insertelement operation</a> on
constants.</dd>
- <dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt>
+ <dt><b><tt>shufflevector (VEC1, VEC2, IDXMASK)</tt></b></dt>
<dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on
constants.</dd>
- <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt>
+ <dt><b><tt>extractvalue (VAL, IDX0, IDX1, ...)</tt></b></dt>
+ <dd>Perform the <a href="#i_extractvalue">extractvalue operation</a> on
+ constants. The index list is interpreted in a similar manner as indices in
+ a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
+ index value must be specified.</dd>
+
+ <dt><b><tt>insertvalue (VAL, ELT, IDX0, IDX1, ...)</tt></b></dt>
+ <dd>Perform the <a href="#i_insertvalue">insertvalue operation</a> on
+ constants. The index list is interpreted in a similar manner as indices in
+ a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
+ index value must be specified.</dd>
+
+ <dt><b><tt>OPCODE (LHS, RHS)</tt></b></dt>
<dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
be any of the <a href="#binaryops">binary</a>
or <a href="#bitwiseops">bitwise binary</a> operations. The constraints
</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 preceeded 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>
<!-- *********************************************************************** -->
to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of
a special value. This value represents the inline assembler as a string
(containing the instructions to emit), a list of operand constraints (stored
- as a string), and a flag that indicates whether or not the inline asm
- expression has side effects. An example inline assembler expression is:</p>
+ as a string), a flag that indicates whether or not the inline asm
+ expression has side effects, and a flag indicating whether the function
+ containing the asm needs to align its stack conservatively. An example
+ inline assembler expression is:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
i32 (i32) asm "bswap $0", "=r,r"
</pre>
-</div>
<p>Inline assembler expressions may <b>only</b> be used as the callee operand of
a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we
have:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
</pre>
-</div>
<p>Inline asms with side effects not visible in the constraint list must be
marked as having side effects. This is done through the use of the
'<tt>sideeffect</tt>' keyword, like so:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
call void asm sideeffect "eieio", ""()
</pre>
-</div>
+
+<p>In some cases inline asms will contain code that will not work unless the
+ stack is aligned in some way, such as calls or SSE instructions on x86,
+ yet will not contain code that does that alignment within the asm.
+ The compiler should make conservative assumptions about what the asm might
+ contain and should generate its usual stack alignment code in the prologue
+ if the '<tt>alignstack</tt>' keyword is present:</p>
+
+<pre class="doc_code">
+call void asm alignstack "eieio", ""()
+</pre>
+
+<p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come
+ first.</p>
<p>TODO: The format of the asm and constraints string still need to be
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 list of constant integers. 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 correlate backend errors that occur with inline asm back to the
+ source code that produced it. For example:</p>
+
+<pre class="doc_code">
+call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
+...
+!42 = !{ i32 1234567 }
+</pre>
+
+<p>It is up to the front-end to make sense of the magic numbers it places in the
+ IR. If the MDNode contains multiple constants, the code generator will use
+ the one that corresponds to the line of the asm that the error occurs on.</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.</p>
+
+<div class="doc_code">
+<pre>
+call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
+</pre>
+</div>
+
+<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.</p>
+
+<div class="doc_code">
+<pre>
+%indvar.next = add i64 %indvar, 1, !dbg !21
+</pre>
+</div>
</div>
</div>
<div class="doc_text">
-
-<p>TODO: Describe this.</p>
+<pre>
+%0 = type { i32, void ()* }
+@llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
+</pre>
+<p>The <tt>@llvm.global_ctors</tt> array contains a list of constructor functions and associated priorities. The functions referenced by this array will be called in ascending order of priority (i.e. lowest first) when the module is loaded. The order of functions with the same priority is not defined.
+</p>
</div>
</div>
<div class="doc_text">
+<pre>
+%0 = type { i32, void ()* }
+@llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
+</pre>
-<p>TODO: Describe this.</p>
+<p>The <tt>@llvm.global_dtors</tt> array contains a list of destructor functions and associated priorities. The functions referenced by this array will be called in descending order of priority (i.e. highest first) when the module is loaded. The order of functions with the same priority is not defined.
+</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
+ '<a href="#i_indirectbr">'<tt>indirectbr</tt></a>' Instruction, the
'<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the
'<a href="#i_unwind"><tt>unwind</tt></a>' instruction, and the
'<a href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
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>
<p>The <tt>switch</tt> instruction specifies a table of values and
destinations. When the '<tt>switch</tt>' instruction is executed, this table
is searched for the given value. If the value is found, control flow is
- transfered to the corresponding destination; otherwise, control flow is
- transfered to the default destination.</p>
+ transferred to the corresponding destination; otherwise, control flow is
+ transferred to the default destination.</p>
<h5>Implementation:</h5>
<p>Depending on properties of the target machine and the particular
</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>indirectbr</tt>' instruction implements an indirect branch to a label
+ within the current function, whose address is specified by
+ "<tt>address</tt>". Address must be derived from a <a
+ href="#blockaddress">blockaddress</a> constant.</p>
+
+<h5>Arguments:</h5>
+
+<p>The '<tt>address</tt>' argument is the address of the label to jump to. The
+ 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>
+
+<h5>Semantics:</h5>
+
+<p>Control transfers to the block specified in the address argument. All
+ possible destination blocks must be listed in the label list, otherwise this
+ instruction has undefined behavior. This implies that jumps to labels
+ defined in other functions have undefined behavior as well.</p>
+
+<h5>Implementation:</h5>
+
+<p>This is typically implemented with a jump through a register.</p>
+
+<h5>Example:</h5>
+<pre>
+ indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
+</pre>
+
+</div>
+
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
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>
<!-- _______________________________________________________________________ -->
<h5>Syntax:</h5>
<pre>
<result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
<tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
- is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
+ is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
+ respectively, occurs.</p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
<result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
<tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
- is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
+ is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
+ respectively, occurs.</p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
<result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<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><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
<tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
- is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
+ is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
+ respectively, occurs.</p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
- <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = udiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<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>Division by zero leads to undefined behavior.</p>
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+ <tt>udiv</tt> is a <a href="#trapvalues">trap value</a> if %op1 is not a
+ multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p>
+
+
<h5>Example:</h5>
<pre>
<result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
<h5>Syntax:</h5>
<pre>
<result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = exact sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sdiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<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>
a 32-bit division of -2147483648 by -1.</p>
<p>If the <tt>exact</tt> keyword is present, the result value of the
- <tt>sdiv</tt> is undefined if the result would be rounded or if overflow
- would occur.</p>
+ <tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would
+ be rounded.</p>
<h5>Example:</h5>
<pre>
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>
<h5>Semantics:</h5>
<p>This instruction returns the <i>remainder</i> of a division (where the result
- has the same sign as the dividend, <tt>op1</tt>), not the <i>modulo</i>
- operator (where the result has the same sign as the divisor, <tt>op2</tt>) of
- a value. For more information about the difference,
+ is either zero or has the same sign as the dividend, <tt>op1</tt>), not the
+ <i>modulo</i> operator (where the result is either zero or has the same sign
+ as the divisor, <tt>op2</tt>) of a value.
+ For more information about the difference,
see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
Math Forum</a>. For a table of how this is implemented in various languages,
please see <a href="http://en.wikipedia.org/wiki/Modulo_operation">
<h5>Syntax:</h5>
<pre>
- <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = shl nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = shl nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = shl nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<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>
vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
shift amount in <tt>op2</tt>.</p>
+<p>If the <tt>nuw</tt> keyword is present, then the shift produces a
+ <a href="#trapvalues">trap value</a> if it shifts out any non-zero bits. If
+ the <tt>nsw</tt> keyword is present, then the shift produces a
+ <a href="#trapvalues">trap value</a> if it shifts out any bits that disagree
+ with the resultant sign bit. As such, NUW/NSW have the same semantics as
+ they would if the shift were expressed as a mul instruction with the same
+ nsw/nuw bits in (mul %op1, (shl 1, %op2)).</p>
+
<h5>Example:</h5>
<pre>
<result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i>
<h5>Syntax:</h5>
<pre>
- <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = lshr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
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>
vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
shift amount in <tt>op2</tt>.</p>
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+ <tt>lshr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits
+ shifted out are non-zero.</p>
+
+
<h5>Example:</h5>
<pre>
<result> = lshr i32 4, 1 <i>; yields {i32}:result = 2</i>
<h5>Syntax:</h5>
<pre>
- <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = ashr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
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>
the arguments are vectors, each vector element of <tt>op1</tt> is shifted by
the corresponding shift amount in <tt>op2</tt>.</p>
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+ <tt>ashr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits
+ shifted out are non-zero.</p>
+
<h5>Example:</h5>
<pre>
<result> = ashr i32 4, 1 <i>; yields {i32}:result = 2</i>
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 = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i>
+ <result> = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i>
</pre>
</div>
<h5>Example:</h5>
<pre>
- %result = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i>
+ <result> = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i>
</pre>
</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> 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>
+ <p>The major differences to <tt>getelementptr</tt> indexing are:</p>
+ <ul>
+ <li>Since the value being indexed is not a pointer, the first index is
+ omitted and assumed to be zero.</li>
+ <li>At least one index must be specified.</li>
+ <li>Not only struct indices but also array indices must be in
+ bounds.</li>
+ </ul>
<h5>Semantics:</h5>
<p>The result is the value at the position in the aggregate specified by the
<h5>Example:</h5>
<pre>
- %result = extractvalue {i32, float} %agg, 0 <i>; yields i32</i>
+ <result> = extractvalue {i32, float} %agg, 0 <i>; yields i32</i>
</pre>
</div>
<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
- '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. The
+ 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
+ '<tt><a href="#i_extractvalue">extractvalue</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>
<p>A key design point of an SSA-based representation is how it represents
memory. In LLVM, no memory locations are in SSA form, which makes things
- very simple. This section describes how to read, write, allocate, and free
+ very simple. This section describes how to read, write, and allocate
memory in LLVM.</p>
</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Syntax:</h5>
-<pre>
- <result> = malloc <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>malloc</tt>' instruction allocates memory from the system heap and
- returns a pointer to it. The object is always allocated in the generic
- address space (address space zero).</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>malloc</tt>' instruction allocates
- <tt>sizeof(<type>)*NumElements</tt> bytes of memory from the operating
- system and returns a pointer of the appropriate type to the program. If
- "NumElements" is specified, it is the number of elements allocated, otherwise
- "NumElements" is defaulted to be one. If a constant alignment is specified,
- the value result of the allocation is guaranteed to be aligned to at least
- that boundary. If not specified, or if zero, the target can choose to align
- the allocation on any convenient boundary compatible with the type.</p>
-
-<p>'<tt>type</tt>' must be a sized type.</p>
-
-<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 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>
-
- %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>
- %array2 = malloc [12 x i8], i32 %size <i>; yields {[12 x i8]*}:array2</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>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_free">'<tt>free</tt>' Instruction</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Syntax:</h5>
-<pre>
- free <type> <value> <i>; yields {void}</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>free</tt>' instruction returns memory back to the unused memory heap
- to be reallocated in the future.</p>
-
-<h5>Arguments:</h5>
-<p>'<tt>value</tt>' shall be a pointer value that points to a value that was
- allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.</p>
-
-<h5>Semantics:</h5>
-<p>Access to the memory pointed to by the pointer is no longer defined after
- this instruction executes. If the pointer is null, the operation is a
- noop.</p>
-
-<h5>Example:</h5>
-<pre>
- %array = <a href="#i_malloc">malloc</a> [4 x i8] <i>; yields {[4 x i8]*}:array</i>
- free [4 x i8]* %array
-</pre>
-
-</div>
-
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
<h5>Syntax:</h5>
<pre>
- <result> = alloca <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
+ <result> = alloca <type>[, <ty> <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
</pre>
<h5>Overview:</h5>
<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>
from which to load. The pointer must point to
a <a href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
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>
+ number or order of execution of this <tt>load</tt> with other <a
+ href="#volatile">volatile operations</a>.</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>
and an address at which to store it. The type of the
'<tt><pointer></tt>' operand must be a pointer to
the <a href="#t_firstclass">first class</a> type of the
- '<tt><value></tt>' operand. If the <tt>store</tt> is marked
- as <tt>volatile</tt>, then the optimizer is not allowed to modify the number
- or order of execution of this <tt>store</tt> with other
- volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
- instructions.</p>
+ '<tt><value></tt>' operand. If the <tt>store</tt> is marked as
+ <tt>volatile</tt>, then the optimizer is not allowed to modify the number or
+ order of execution of this <tt>store</tt> with other <a
+ href="#volatile">volatile operations</a>.</p>
<p>The optional constant "align" argument specifies the alignment of the
operation (that is, the alignment of the memory address). A value of 0 or an
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>Syntax:</h5>
<pre>
<result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
+ <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}*
</pre>
<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
- calculation. The remaining arguments are indices, that indicate which of the
+ calculation. The remaining arguments are indices that indicate which of the
elements of the aggregate object are indexed. The interpretation of each
index is dependent on the type being indexed into. The first index always
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, and structs. 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 (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 (also non-constants).</p>
+ 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
+ constant.</p>
<p>For example, let's consider a C code fragment and how it gets compiled to
LLVM:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
struct RT {
char A;
int B[10][20];
return &s[1].Z.B[5][13];
}
</pre>
-</div>
<p>The LLVM code generated by the GCC frontend is:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 }
%ST = <a href="#namedtypes">type</a> { i32, double, %RT }
ret i32* %reg
}
</pre>
-</div>
<h5>Semantics:</h5>
<p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
}
</pre>
+<p>If the <tt>inbounds</tt> keyword is present, the result value of the
+ <tt>getelementptr</tt> is a <a href="#trapvalues">trap value</a> if the
+ base pointer is not an <i>in bounds</i> address of an allocated object,
+ or if any of the addresses that would be formed by successive addition of
+ the offsets implied by the indices to the base address with infinitely
+ precise arithmetic are not an <i>in bounds</i> address of that allocated
+ object. The <i>in bounds</i> addresses for an allocated object are all
+ the addresses that point into the object, plus the address one byte past
+ the end.</p>
+
+<p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
+ the base address with silently-wrapping two's complement arithmetic, and
+ the result value of the <tt>getelementptr</tt> may be outside the object
+ pointed to by the base pointer. The result value may not necessarily be
+ used to access memory though, even if it happens to point into allocated
+ storage. See the <a href="#pointeraliasing">Pointer Aliasing Rules</a>
+ section for more information.</p>
+
<p>The getelementptr instruction is often confusing. For some more insight into
how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
type <tt>ty2</tt>.</p>
<h5>Arguments:</h5>
-<p>The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must
- be an <a href="#t_integer">integer</a> type, and a type that specifies the
- size and type of the result, which must be
- an <a href="#t_integer">integer</a> type. The bit size of <tt>value</tt> must
- be larger than the bit size of <tt>ty2</tt>. Equal sized types are not
- allowed.</p>
+<p>The '<tt>trunc</tt>' instruction takes a value to trunc, and a type to trunc it to.
+ Both types must be of <a href="#t_integer">integer</a> types, or vectors
+ of the same number of integers.
+ The bit size of the <tt>value</tt> must be larger than
+ the bit size of the destination type, <tt>ty2</tt>.
+ Equal sized types are not allowed.</p>
<h5>Semantics:</h5>
<p>The '<tt>trunc</tt>' instruction truncates the high order bits
<h5>Example:</h5>
<pre>
- %X = trunc i32 257 to i8 <i>; yields i8:1</i>
- %Y = trunc i32 123 to i1 <i>; yields i1:true</i>
- %Y = trunc i32 122 to i1 <i>; yields i1:false</i>
+ %X = trunc i32 257 to i8 <i>; yields i8:1</i>
+ %Y = trunc i32 123 to i1 <i>; yields i1:true</i>
+ %Z = trunc i32 122 to i1 <i>; yields i1:false</i>
+ %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> <i>; yields <i8 8, i8 7></i>
</pre>
</div>
</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
- <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,
+<p>The '<tt>zext</tt>' instruction takes a value to cast, and a type to cast it to.
+ Both types must be of <a href="#t_integer">integer</a> types, or vectors
+ of the same number of integers.
+ The bit size of the <tt>value</tt> must be smaller than
+ the bit size of the destination type,
<tt>ty2</tt>.</p>
<h5>Semantics:</h5>
<pre>
%X = zext i32 257 to i64 <i>; yields i64:257</i>
%Y = zext i1 true to i32 <i>; yields i32:1</i>
+ %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i>
</pre>
</div>
<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
- <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,
+<p>The '<tt>sext</tt>' instruction takes a value to cast, and a type to cast it to.
+ Both types must be of <a href="#t_integer">integer</a> types, or vectors
+ of the same number of integers.
+ The bit size of the <tt>value</tt> must be smaller than
+ the bit size of the destination type,
<tt>ty2</tt>.</p>
<h5>Semantics:</h5>
<pre>
%X = sext i8 -1 to i16 <i>; yields i16 :65535</i>
%Y = sext i1 true to i32 <i>; yields i32:-1</i>
+ %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i>
</pre>
</div>
<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>
%X = fptoui double 123.0 to i32 <i>; yields i32:123</i>
%Y = fptoui float 1.0E+300 to i1 <i>; yields undefined:1</i>
- %X = fptoui float 1.04E+17 to i8 <i>; yields undefined:1</i>
+ %Z = fptoui float 1.04E+17 to i8 <i>; yields undefined:1</i>
</pre>
</div>
</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 = fptosi double -123.0 to i32 <i>; yields i32:-123</i>
%Y = fptosi float 1.0E-247 to i1 <i>; yields undefined:1</i>
- %X = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i>
+ %Z = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i>
</pre>
</div>
<h5>Example:</h5>
<pre>
%X = inttoptr i32 255 to i32* <i>; yields zero extension on 64-bit architecture</i>
- %X = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i>
- %Y = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i>
+ %Y = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i>
+ %Z = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i>
</pre>
</div>
<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>
<h5>Semantics:</h5>
<p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the
condition code given as <tt>cond</tt>. The comparison performed always yields
- either an <a href="#t_primitive"><tt>i1</tt></a> or vector of <tt>i1</tt>
+ either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt>
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>
values based on comparison of its operands.</p>
<p>If the operands are floating point scalars, then the result type is a boolean
-(<a href="#t_primitive"><tt>i1</tt></a>).</p>
+(<a href="#t_integer"><tt>i1</tt></a>).</p>
<p>If the operands are floating point vectors, then the result type is a vector
of boolean with the same number of elements as the operands being
<p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt>
according to the condition code given as <tt>cond</tt>. If the operands are
vectors, then the vectors are compared element by element. Each comparison
- performed always yields an <a href="#t_primitive">i1</a> result, as
+ performed always yields an <a href="#t_integer">i1</a> result, as
follows:</p>
<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
<h5>Example:</h5>
<pre>
%retval = call i32 @test(i32 %argc)
- call i32 (i8 *, ...)* @printf(i8 * %msg, i32 12, i8 42) <i>; yields i32</i>
+ call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) <i>; yields i32</i>
%X = tail call i32 @foo() <i>; yields i32</i>
%Y = tail call <a href="#callingconv">fastcc</a> i32 @foo() <i>; yields i32</i>
call void %foo(i8 97 signext)
%ZZ = call zeroext i32 @bar() <i>; Return value is %zero extended</i>
</pre>
+<p>llvm treats calls to some functions with names and arguments that match the
+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 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>
instruction and the variable argument handling intrinsic functions are
used.</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
define i32 @test(i32 %X, ...) {
; Initialize variable argument processing
%ap = alloca i8*
declare void @llvm.va_copy(i8*, i8*)
declare void @llvm.va_end(i8*)
</pre>
-</div>
</div>
<h5>Syntax:</h5>
<pre>
- declare i8 *@llvm.frameaddress(i32 <level>)
+ declare i8* @llvm.frameaddress(i32 <level>)
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- declare i8 *@llvm.stacksave()
+ declare i8* @llvm.stacksave()
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- declare void @llvm.stackrestore(i8 * %ptr)
+ declare void @llvm.stackrestore(i8* %ptr)
</pre>
<h5>Overview:</h5>
<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>
<pre>
- declare i64 @llvm.readcyclecounter( )
+ declare i64 @llvm.readcyclecounter()
</pre>
<h5>Overview:</h5>
<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>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+ <tt>llvm.memcpy</tt> call is a <a href="#volatile">volatile operation</a>.
+ The detailed 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>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+ <tt>llvm.memmove</tt> call is a <a href="#volatile">volatile operation</a>.
+ The detailed 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. However, not all targets support all
+ bit widths.</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 and takes extra alignment/volatile
+ arguments. Also, 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
- byte value to fill it with, the third argument is an integer argument
+ byte value with which to fill it, the third argument is an integer argument
specifying the number of bytes to fill, and the fourth argument is the known
- alignment of destination location.</p>
+ alignment of the 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>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+ <tt>llvm.memset</tt> call is a <a href="#volatile">volatile operation</a>.
+ The detailed 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>
<div class="doc_text">
<p>This intrinsic makes it possible to excise one parameter, marked with
- the <tt>nest</tt> attribute, from a function. The result is a callable
+ the <a href="#nest"><tt>nest</tt></a> attribute, from a function.
+ The result is a callable
function pointer lacking the nest parameter - the caller does not need to
provide a value for it. Instead, the value to use is stored in advance in a
"trampoline", a block of memory usually allocated on the stack, which also
pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as
follows:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
%tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
- %p = call i8* @llvm.init.trampoline( i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval )
+ %p = call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval)
%fp = bitcast i8* %p to i32 (i32, i32)*
</pre>
-</div>
-<p>The call <tt>%val = call i32 %fp( i32 %x, i32 %y )</tt> is then equivalent
- to <tt>%val = call i32 %f( i8* %nval, i32 %x, i32 %y )</tt>.</p>
+<p>The call <tt>%val = call i32 %fp(i32 %x, i32 %y)</tt> is then equivalent
+ to <tt>%val = call i32 %f(i8* %nval, i32 %x, i32 %y)</tt>.</p>
</div>
<div class="doc_text">
<h5>Syntax:</h5>
<pre>
- declare void @llvm.memory.barrier( i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, i1 <device> )
+ declare void @llvm.memory.barrier(i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, i1 <device>)
</pre>
<h5>Overview:</h5>
<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>
<h5>Example:</h5>
<pre>
-%ptr = malloc i32
+%mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr = bitcast i8* %mallocP to i32*
store i32 4, %ptr
%result1 = load i32* %ptr <i>; yields {i32}:result1 = 4</i>
- call void @llvm.memory.barrier( i1 false, i1 true, i1 false, i1 false )
+ call void @llvm.memory.barrier(i1 false, i1 true, i1 false, i1 false)
<i>; guarantee the above finishes</i>
store i32 8, %ptr <i>; before this begins</i>
</pre>
support all bit widths however.</p>
<pre>
- declare i8 @llvm.atomic.cmp.swap.i8.p0i8( i8* <ptr>, i8 <cmp>, i8 <val> )
- declare i16 @llvm.atomic.cmp.swap.i16.p0i16( i16* <ptr>, i16 <cmp>, i16 <val> )
- declare i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* <ptr>, i32 <cmp>, i32 <val> )
- declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, i64 <val> )
+ declare i8 @llvm.atomic.cmp.swap.i8.p0i8(i8* <ptr>, i8 <cmp>, i8 <val>)
+ declare i16 @llvm.atomic.cmp.swap.i16.p0i16(i16* <ptr>, i16 <cmp>, i16 <val>)
+ declare i32 @llvm.atomic.cmp.swap.i32.p0i32(i32* <ptr>, i32 <cmp>, i32 <val>)
+ declare i64 @llvm.atomic.cmp.swap.i64.p0i64(i64* <ptr>, i64 <cmp>, i64 <val>)
</pre>
<h5>Overview:</h5>
<h5>Examples:</h5>
<pre>
-%ptr = malloc i32
+%mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr = bitcast i8* %mallocP to i32*
store i32 4, %ptr
%val1 = add i32 4, 4
-%result1 = call i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* %ptr, i32 4, %val1 )
+%result1 = call i32 @llvm.atomic.cmp.swap.i32.p0i32(i32* %ptr, i32 4, %val1)
<i>; yields {i32}:result1 = 4</i>
%stored1 = icmp eq i32 %result1, 4 <i>; yields {i1}:stored1 = true</i>
%memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 8</i>
%val2 = add i32 1, 1
-%result2 = call i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* %ptr, i32 5, %val2 )
+%result2 = call i32 @llvm.atomic.cmp.swap.i32.p0i32(i32* %ptr, i32 5, %val2)
<i>; yields {i32}:result2 = 8</i>
%stored2 = icmp eq i32 %result2, 5 <i>; yields {i1}:stored2 = false</i>
integer bit width. Not all targets support all bit widths however.</p>
<pre>
- declare i8 @llvm.atomic.swap.i8.p0i8( i8* <ptr>, i8 <val> )
- declare i16 @llvm.atomic.swap.i16.p0i16( i16* <ptr>, i16 <val> )
- declare i32 @llvm.atomic.swap.i32.p0i32( i32* <ptr>, i32 <val> )
- declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> )
+ declare i8 @llvm.atomic.swap.i8.p0i8(i8* <ptr>, i8 <val>)
+ declare i16 @llvm.atomic.swap.i16.p0i16(i16* <ptr>, i16 <val>)
+ declare i32 @llvm.atomic.swap.i32.p0i32(i32* <ptr>, i32 <val>)
+ declare i64 @llvm.atomic.swap.i64.p0i64(i64* <ptr>, i64 <val>)
</pre>
<h5>Overview:</h5>
<h5>Examples:</h5>
<pre>
-%ptr = malloc i32
+%mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr = bitcast i8* %mallocP to i32*
store i32 4, %ptr
%val1 = add i32 4, 4
-%result1 = call i32 @llvm.atomic.swap.i32.p0i32( i32* %ptr, i32 %val1 )
+%result1 = call i32 @llvm.atomic.swap.i32.p0i32(i32* %ptr, i32 %val1)
<i>; yields {i32}:result1 = 4</i>
%stored1 = icmp eq i32 %result1, 4 <i>; yields {i1}:stored1 = true</i>
%memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 8</i>
%val2 = add i32 1, 1
-%result2 = call i32 @llvm.atomic.swap.i32.p0i32( i32* %ptr, i32 %val2 )
+%result2 = call i32 @llvm.atomic.swap.i32.p0i32(i32* %ptr, i32 %val2)
<i>; yields {i32}:result2 = 8</i>
%stored2 = icmp eq i32 %result2, 8 <i>; yields {i1}:stored2 = true</i>
any integer bit width. Not all targets support all bit widths however.</p>
<pre>
- declare i8 @llvm.atomic.load.add.i8..p0i8( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.add.i16..p0i16( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.add.i32..p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.add.i8.p0i8(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.add.i16.p0i16(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.add.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.add.i64.p0i64(i64* <ptr>, i64 <delta>)
</pre>
<h5>Overview:</h5>
<h5>Examples:</h5>
<pre>
-%ptr = malloc i32
- store i32 4, %ptr
-%result1 = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 4 )
+%mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr = bitcast i8* %mallocP to i32*
+ store i32 4, %ptr
+%result1 = call i32 @llvm.atomic.load.add.i32.p0i32(i32* %ptr, i32 4)
<i>; yields {i32}:result1 = 4</i>
-%result2 = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 2 )
+%result2 = call i32 @llvm.atomic.load.add.i32.p0i32(i32* %ptr, i32 2)
<i>; yields {i32}:result2 = 8</i>
-%result3 = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 5 )
+%result3 = call i32 @llvm.atomic.load.add.i32.p0i32(i32* %ptr, i32 5)
<i>; yields {i32}:result3 = 10</i>
%memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 15</i>
</pre>
support all bit widths however.</p>
<pre>
- declare i8 @llvm.atomic.load.sub.i8.p0i32( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.sub.i16.p0i32( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.sub.i32.p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.sub.i8.p0i32(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.sub.i16.p0i32(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.sub.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.sub.i64.p0i32(i64* <ptr>, i64 <delta>)
</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>
<h5>Examples:</h5>
<pre>
-%ptr = malloc i32
- store i32 8, %ptr
-%result1 = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 4 )
+%mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr = bitcast i8* %mallocP to i32*
+ store i32 8, %ptr
+%result1 = call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %ptr, i32 4)
<i>; yields {i32}:result1 = 8</i>
-%result2 = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 2 )
+%result2 = call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %ptr, i32 2)
<i>; yields {i32}:result2 = 4</i>
-%result3 = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 5 )
+%result3 = call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %ptr, i32 5)
<i>; yields {i32}:result3 = 2</i>
%memval1 = load i32* %ptr <i>; yields {i32}:memval1 = -3</i>
</pre>
widths however.</p>
<pre>
- declare i8 @llvm.atomic.load.and.i8.p0i8( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.and.i16.p0i16( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.and.i32.p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.and.i64.p0i64( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.and.i8.p0i8(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.and.i16.p0i16(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.and.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.and.i64.p0i64(i64* <ptr>, i64 <delta>)
</pre>
<pre>
- declare i8 @llvm.atomic.load.or.i8.p0i8( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.or.i16.p0i16( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.or.i32.p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.or.i64.p0i64( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.or.i8.p0i8(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.or.i16.p0i16(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.or.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.or.i64.p0i64(i64* <ptr>, i64 <delta>)
</pre>
<pre>
- declare i8 @llvm.atomic.load.nand.i8.p0i32( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.nand.i16.p0i32( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.nand.i32.p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.nand.i64.p0i32( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.nand.i8.p0i32(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.nand.i16.p0i32(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.nand.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.nand.i64.p0i32(i64* <ptr>, i64 <delta>)
</pre>
<pre>
- declare i8 @llvm.atomic.load.xor.i8.p0i32( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.xor.i16.p0i32( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.xor.i32.p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.xor.i8.p0i32(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.xor.i16.p0i32(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.xor.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.xor.i64.p0i32(i64* <ptr>, i64 <delta>)
</pre>
<h5>Overview:</h5>
<h5>Examples:</h5>
<pre>
-%ptr = malloc i32
- store i32 0x0F0F, %ptr
-%result0 = call i32 @llvm.atomic.load.nand.i32.p0i32( i32* %ptr, i32 0xFF )
+%mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr = bitcast i8* %mallocP to i32*
+ store i32 0x0F0F, %ptr
+%result0 = call i32 @llvm.atomic.load.nand.i32.p0i32(i32* %ptr, i32 0xFF)
<i>; yields {i32}:result0 = 0x0F0F</i>
-%result1 = call i32 @llvm.atomic.load.and.i32.p0i32( i32* %ptr, i32 0xFF )
+%result1 = call i32 @llvm.atomic.load.and.i32.p0i32(i32* %ptr, i32 0xFF)
<i>; yields {i32}:result1 = 0xFFFFFFF0</i>
-%result2 = call i32 @llvm.atomic.load.or.i32.p0i32( i32* %ptr, i32 0F )
+%result2 = call i32 @llvm.atomic.load.or.i32.p0i32(i32* %ptr, i32 0F)
<i>; yields {i32}:result2 = 0xF0</i>
-%result3 = call i32 @llvm.atomic.load.xor.i32.p0i32( i32* %ptr, i32 0F )
+%result3 = call i32 @llvm.atomic.load.xor.i32.p0i32(i32* %ptr, i32 0F)
<i>; yields {i32}:result3 = FF</i>
%memval1 = load i32* %ptr <i>; yields {i32}:memval1 = F0</i>
</pre>
address spaces. Not all targets support all bit widths however.</p>
<pre>
- declare i8 @llvm.atomic.load.max.i8.p0i8( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.max.i16.p0i16( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.max.i32.p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.max.i64.p0i64( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.max.i8.p0i8(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.max.i16.p0i16(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.max.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.max.i64.p0i64(i64* <ptr>, i64 <delta>)
</pre>
<pre>
- declare i8 @llvm.atomic.load.min.i8.p0i8( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.min.i16.p0i16( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.min.i32..p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.min.i64..p0i64( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.min.i8.p0i8(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.min.i16.p0i16(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.min.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.min.i64.p0i64(i64* <ptr>, i64 <delta>)
</pre>
<pre>
- declare i8 @llvm.atomic.load.umax.i8.p0i8( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.umax.i16.p0i16( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.umax.i32.p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.umax.i64.p0i64( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.umax.i8.p0i8(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.umax.i16.p0i16(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.umax.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.umax.i64.p0i64(i64* <ptr>, i64 <delta>)
</pre>
<pre>
- declare i8 @llvm.atomic.load.umin.i8..p0i8( i8* <ptr>, i8 <delta> )
- declare i16 @llvm.atomic.load.umin.i16.p0i16( i16* <ptr>, i16 <delta> )
- declare i32 @llvm.atomic.load.umin.i32..p0i32( i32* <ptr>, i32 <delta> )
- declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta> )
+ declare i8 @llvm.atomic.load.umin.i8.p0i8(i8* <ptr>, i8 <delta>)
+ declare i16 @llvm.atomic.load.umin.i16.p0i16(i16* <ptr>, i16 <delta>)
+ declare i32 @llvm.atomic.load.umin.i32.p0i32(i32* <ptr>, i32 <delta>)
+ declare i64 @llvm.atomic.load.umin.i64.p0i64(i64* <ptr>, i64 <delta>)
</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>
<h5>Examples:</h5>
<pre>
-%ptr = malloc i32
- store i32 7, %ptr
-%result0 = call i32 @llvm.atomic.load.min.i32.p0i32( i32* %ptr, i32 -2 )
+%mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr = bitcast i8* %mallocP to i32*
+ store i32 7, %ptr
+%result0 = call i32 @llvm.atomic.load.min.i32.p0i32(i32* %ptr, i32 -2)
<i>; yields {i32}:result0 = 7</i>
-%result1 = call i32 @llvm.atomic.load.max.i32.p0i32( i32* %ptr, i32 8 )
+%result1 = call i32 @llvm.atomic.load.max.i32.p0i32(i32* %ptr, i32 8)
<i>; yields {i32}:result1 = -2</i>
-%result2 = call i32 @llvm.atomic.load.umin.i32.p0i32( i32* %ptr, i32 10 )
+%result2 = call i32 @llvm.atomic.load.umin.i32.p0i32(i32* %ptr, i32 10)
<i>; yields {i32}:result2 = 8</i>
-%result3 = call i32 @llvm.atomic.load.umax.i32.p0i32( i32* %ptr, i32 30 )
+%result3 = call i32 @llvm.atomic.load.umax.i32.p0i32(i32* %ptr, i32 30)
<i>; yields {i32}:result3 = 8</i>
%memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 30</i>
</pre>
</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="int_memorymarkers">Memory Use Markers</a>
+</div>
+
+<div class="doc_text">
+
+<p>This class of intrinsics exists to information about the lifetime of memory
+ objects and ranges where variables are immutable.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory
+ object's lifetime.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a constant integer representing the size of the
+ object, or -1 if it is variable sized. The second argument is a pointer to
+ the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that before this point in the code, the value of the
+ memory pointed to by <tt>ptr</tt> is dead. This means that it is known to
+ never be used and has an undefined value. A load from the pointer that
+ precedes this intrinsic can be replaced with
+ <tt>'<a href="#undefvalues">undef</a>'</tt>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory
+ object's lifetime.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a constant integer representing the size of the
+ object, or -1 if it is variable sized. The second argument is a pointer to
+ the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that after this point in the code, the value of the
+ memory pointed to by <tt>ptr</tt> is dead. This means that it is known to
+ never be used and has an undefined value. Any stores into the memory object
+ following this intrinsic may be removed as dead.
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of
+ a memory object will not change.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a constant integer representing the size of the
+ object, or -1 if it is variable sized. The second argument is a pointer to
+ the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses
+ the return value, the referenced memory location is constant and
+ unchanging.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of
+ a memory object are mutable.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic.
+ The second argument is a constant integer representing the size of the
+ object, or -1 if it is variable sized and the third argument is a pointer
+ to the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that the memory is mutable again.</p>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="int_general">General Intrinsics</a>
<h5>Syntax:</h5>
<pre>
- declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int> )
+ declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
</pre>
<h5>Overview:</h5>
any integer bit width.</p>
<pre>
- declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int> )
- declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int> )
- declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int> )
- declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int> )
- declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int> )
+ declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>)
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- declare void @llvm.stackprotector( i8* <guard>, i8** <slot> )
+ declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
</pre>
<h5>Overview:</h5>
the <tt>AllocaInst</tt> stack slot to be before local variables on the
stack. This is to ensure that if a local variable on the stack is
overwritten, it will destroy the value of the guard. When the function exits,
- the guard on the stack is checked against the original guard. If they're
+ the guard on the stack is checked against the original guard. If they are
different, then the program aborts by calling the <tt>__stack_chk_fail()</tt>
function.</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 determine at compile time whether a) an operation (like
+ memcpy) will overflow a buffer that corresponds to an object, or b) 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