<body>
-<div class="doc_title"> LLVM Language Reference Manual </div>
+<h1>LLVM Language Reference Manual</h1>
<ol>
<li><a href="#abstract">Abstract</a></li>
<li><a href="#introduction">Introduction</a></li>
<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_externweak">'<tt>extern_weak</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_external">'<tt>external</tt>' Linkage</a></li>
<li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li>
<li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li>
</ol>
<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>
+ <li><a href="#memmodel">Memory Model for Concurrent Operations</a></li>
+ <li><a href="#ordering">Atomic Memory Ordering Constraints</a></li>
</ol>
</li>
<li><a href="#typesystem">Type System</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>
<ol>
<li><a href="#t_array">Array Type</a></li>
<li><a href="#t_struct">Structure Type</a></li>
- <li><a href="#t_pstruct">Packed Structure Type</a></li>
- <li><a href="#t_union">Union Type</a></li>
+ <li><a href="#t_opaque">Opaque Structure Types</a></li>
<li><a href="#t_vector">Vector Type</a></li>
</ol>
</li>
<li><a href="#t_function">Function Type</a></li>
<li><a href="#t_pointer">Pointer Type</a></li>
- <li><a href="#t_opaque">Opaque Type</a></li>
</ol>
</li>
- <li><a href="#t_uprefs">Type Up-references</a></li>
</ol>
</li>
<li><a href="#constants">Constants</a>
<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_resume">'<tt>resume</tt>' Instruction</a></li>
<li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
</ol>
</li>
</li>
<li><a href="#memoryops">Memory Access and Addressing Operations</a>
<ol>
- <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="#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="#i_fence">'<tt>fence</tt>' Instruction</a></li>
+ <li><a href="#i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a></li>
+ <li><a href="#i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a></li>
<li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
</ol>
</li>
<li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
<li><a href="#i_call">'<tt>call</tt>' Instruction</a></li>
<li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a></li>
+ <li><a href="#i_landingpad">'<tt>landingpad</tt>' Instruction</a></li>
</ol>
</li>
</ol>
<li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li>
<li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li>
<li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_log">'<tt>llvm.log.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a></li>
</ol>
</li>
<li><a href="#int_manip">Bit Manipulation Intrinsics</a>
</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_trampoline">Trampoline Intrinsics</a>
<ol>
<li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
+ <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</a></li>
</ol>
</li>
<li><a href="#int_atomics">Atomic intrinsics</a>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="abstract">Abstract </a></div>
+<h2><a name="abstract">Abstract</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This document is a reference manual for the LLVM assembly language. LLVM is
a Static Single Assignment (SSA) based representation that provides type
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="introduction">Introduction</a> </div>
+<h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>The LLVM code representation is designed to be used in three different forms:
as an in-memory compiler IR, as an on-disk bitcode representation (suitable
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>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
+<h4>
+ <a name="wellformed">Well-Formedness</a>
+</h4>
-<div class="doc_text">
+<div>
<p>It is important to note that this document describes 'well formed' LLVM
assembly language. There is a difference between what the parser accepts and
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
</div>
+</div>
+
<!-- Describe the typesetting conventions here. -->
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
+<h2><a name="identifiers">Identifiers</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>LLVM identifiers come in two basic types: global and local. Global
identifiers (functions, global variables) begin with the <tt>'@'</tt>
<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>
+<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>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
+<h2><a name="highlevel">High Level Structure</a></h2>
<!-- *********************************************************************** -->
-
+<div>
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="modulestructure">Module Structure</a>
-</div>
+<h3>
+ <a name="modulestructure">Module Structure</a>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM programs are composed of "Module"s, each of which is a translation unit
of the input programs. Each module consists of functions, global variables,
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>}
+ <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,
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="linkage">Linkage Types</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>All Global Variables and Functions have one of the following types of
linkage:</p>
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
be merged with equivalent globals. These linkage types are otherwise the
same as their non-<tt>odr</tt> versions.</dd>
- <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
+ <dt><tt><b><a name="linkage_external">external</a></b></tt>:</dt>
<dd>If none of the above identifiers are used, the global is externally
visible, meaning that it participates in linkage and can be used to
resolve external symbol references.</dd>
declarations), they are accessible outside of the current module.</p>
<p>It is illegal for a function <i>declaration</i> to have any linkage type
- other than "externally visible", <tt>dllimport</tt>
- or <tt>extern_weak</tt>.</p>
+ other than <tt>external</tt>, <tt>dllimport</tt>
+ or <tt>extern_weak</tt>.</p>
<p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt>
or <tt>weak_odr</tt> linkages.</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="callingconv">Calling Conventions</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
and <a href="#i_invoke">invokes</a> can all have an optional calling
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="visibility">Visibility Styles</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>All Global Variables and Functions have one of the following visibility
styles:</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="namedtypes">Named Types</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM IR allows you to specify name aliases for certain types. This can make
it easier to read the IR and make the IR more condensed (particularly when
recursive types are involved). An example of a name specification is:</p>
-<div class="doc_code">
-<pre>
+<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,
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="globalvars">Global Variables</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Global variables define regions of memory allocated at compilation time
instead of run-time. Global variables may optionally be initialized, may
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>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_subsection">
+<h3>
<a name="functionstructure">Functions</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<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="#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>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="aliasstructure">Aliases</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Aliases act as "second name" for the aliasee value (which can be either
function, global variable, another alias or bitcast of global value). Aliases
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>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="namedmetadatastructure">Named Metadata</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Named metadata is a collection of metadata. <a href="#metadata">Metadata
- nodes</a> (but not metadata strings) and null are the only valid operands for
+ nodes</a> (but not metadata strings) are the only valid operands for
a named metadata.</p>
<h5>Syntax:</h5>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
+; Some unnamed metadata nodes, which are referenced by the named metadata.
+!0 = metadata !{metadata !"zero"}
!1 = metadata !{metadata !"one"}
-!name = !{null, !1}
+!2 = metadata !{metadata !"two"}
+; A named metadata.
+!name = !{!0, !1, !2}
</pre>
-</div>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div>
+<h3>
+ <a name="paramattrs">Parameter Attributes</a>
+</h3>
-<div class="doc_text">
+<div>
<p>The return type and each parameter of a function type may have a set of
<i>parameter attributes</i> associated with them. Parameter attributes are
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>
<dl>
<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><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><b>inreg</b></tt></dt>
<dd>This indicates that this parameter or return value should be treated in a
registers). Use of this attribute is target-specific.</dd>
<dt><tt><b><a name="byval">byval</a></b></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
+ <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>
+ 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
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, thought it is slightly weaker.
+ 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.
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="gc">Garbage Collector Names</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Each function may specify a garbage collector name, which is simply a
string:</p>
-<div class="doc_code">
-<pre>
+<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
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="fnattrs">Function Attributes</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Function attributes are set to communicate additional information about a
function. Function attributes are considered to be part of the function, not
<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 { ... }
</pre>
-</div>
<dl>
<dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt>
function into callers whenever possible, ignoring any active inlining size
threshold for this caller.</dd>
+ <dt><tt><b>nonlazybind</b></tt></dt>
+ <dd>This attribute suppresses lazy symbol binding for the function. This
+ may make calls to the function faster, at the cost of extra program
+ startup time if the function is not called during program startup.</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><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>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><b>noreturn</b></tt></dt>
<dd>This function attribute indicates that the function never returns
unwind or exceptional control flow. If the function does unwind, its
runtime behavior is undefined.</dd>
+ <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
an <tt>ssp</tt> attribute, then the resulting function will have
an <tt>sspreq</tt> attribute.</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><b>noimplicitfloat</b></tt></dt>
- <dd>This attributes disables implicit floating point instructions.</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><a name="uwtable">uwtable</a></b></tt></dt>
+ <dd>This attribute indicates that the ABI being targeted requires that
+ an unwind table entry be produce for this function even if we can
+ show that no exceptions passes by it. This is normally the case for
+ the ELF x86-64 abi, but it can be disabled for some compilation
+ units.</dd>
+
+ <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt>
+ <dd>This attribute indicates that this function can return
+ twice. The C <code>setjmp</code> is an example of such a function.
+ The compiler disables some optimizations (like tail calls) in the caller of
+ these functions.</dd>
</dl>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="moduleasm">Module-Level Inline Assembly</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Modules may contain "module-level inline asm" blocks, which corresponds to
the GCC "file scope inline asm" blocks. These blocks are internally
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
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="datalayout">Data Layout</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>A module may specify a target specific data layout string that specifies how
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
the bits with the least significance have the lowest address
location.</dd>
+ <dt><tt>S<i>size</i></tt></dt>
+ <dd>Specifies the natural alignment of the stack in bits. Alignment promotion
+ of stack variables is limited to the natural stack alignment to avoid
+ dynamic stack realignment. The stack alignment must be a multiple of
+ 8-bits. If omitted, the natural stack alignment defaults to "unspecified",
+ which does not prevent any alignment promotions.</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
<i>preferred</i> alignments. All sizes are in bits. Specifying
implemented in terms of 64 <2 x double>, for example.</li>
</ol>
+<p>The function of the data layout string may not be what you expect. Notably,
+ this is not a specification from the frontend of what alignment the code
+ generator should use.</p>
+
+<p>Instead, if specified, the target data layout is required to match what the
+ ultimate <em>code generator</em> expects. This string is used by the
+ mid-level optimizers to
+ improve code, and this only works if it matches what the ultimate code
+ generator uses. If you would like to generate IR that does not embed this
+ target-specific detail into the IR, then you don't have to specify the
+ string. This will disable some optimizations that require precise layout
+ information, but this also prevents those optimizations from introducing
+ target specificity into the IR.</p>
+
+
+
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="pointeraliasing">Pointer Aliasing Rules</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Any memory access must be done through a pointer value associated
with an address range of the memory access, otherwise the behavior
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="volatile">Volatile Memory Accesses</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<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
</div>
+<!-- ======================================================================= -->
+<h3>
+ <a name="memmodel">Memory Model for Concurrent Operations</a>
+</h3>
+
+<div>
+
+<p>The LLVM IR does not define any way to start parallel threads of execution
+or to register signal handlers. Nonetheless, there are platform-specific
+ways to create them, and we define LLVM IR's behavior in their presence. This
+model is inspired by the C++0x memory model.</p>
+
+<p>For a more informal introduction to this model, see the
+<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.
+
+<p>We define a <i>happens-before</i> partial order as the least partial order
+that</p>
+<ul>
+ <li>Is a superset of single-thread program order, and</li>
+ <li>When a <i>synchronizes-with</i> <tt>b</tt>, includes an edge from
+ <tt>a</tt> to <tt>b</tt>. <i>Synchronizes-with</i> pairs are introduced
+ by platform-specific techniques, like pthread locks, thread
+ creation, thread joining, etc., and by atomic instructions.
+ (See also <a href="#ordering">Atomic Memory Ordering Constraints</a>).
+ </li>
+</ul>
+
+<p>Note that program order does not introduce <i>happens-before</i> edges
+between a thread and signals executing inside that thread.</p>
+
+<p>Every (defined) read operation (load instructions, memcpy, atomic
+loads/read-modify-writes, etc.) <var>R</var> reads a series of bytes written by
+(defined) write operations (store instructions, atomic
+stores/read-modify-writes, memcpy, etc.). For the purposes of this section,
+initialized globals are considered to have a write of the initializer which is
+atomic and happens before any other read or write of the memory in question.
+For each byte of a read <var>R</var>, <var>R<sub>byte</sub></var> may see
+any write to the same byte, except:</p>
+
+<ul>
+ <li>If <var>write<sub>1</sub></var> happens before
+ <var>write<sub>2</sub></var>, and <var>write<sub>2</sub></var> happens
+ before <var>R<sub>byte</sub></var>, then <var>R<sub>byte</sub></var>
+ does not see <var>write<sub>1</sub></var>.
+ <li>If <var>R<sub>byte</sub></var> happens before
+ <var>write<sub>3</sub></var>, then <var>R<sub>byte</sub></var> does not
+ see <var>write<sub>3</sub></var>.
+</ul>
+
+<p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows:
+<ul>
+ <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile
+ is supposed to give guarantees which can support
+ <code>sig_atomic_t</code> in C/C++, and may be used for accesses to
+ addresses which do not behave like normal memory. It does not generally
+ provide cross-thread synchronization.)
+ <li>Otherwise, if there is no write to the same byte that happens before
+ <var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns
+ <tt>undef</tt> for that byte.
+ <li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write,
+ <var>R<sub>byte</sub></var> returns the value written by that
+ write.</li>
+ <li>Otherwise, if <var>R</var> is atomic, and all the writes
+ <var>R<sub>byte</sub></var> may see are atomic, it chooses one of the
+ values written. See the <a href="#ordering">Atomic Memory Ordering
+ Constraints</a> section for additional constraints on how the choice
+ is made.
+ <li>Otherwise <var>R<sub>byte</sub></var> returns <tt>undef</tt>.</li>
+</ul>
+
+<p><var>R</var> returns the value composed of the series of bytes it read.
+This implies that some bytes within the value may be <tt>undef</tt>
+<b>without</b> the entire value being <tt>undef</tt>. Note that this only
+defines the semantics of the operation; it doesn't mean that targets will
+emit more than one instruction to read the series of bytes.</p>
+
+<p>Note that in cases where none of the atomic intrinsics are used, this model
+places only one restriction on IR transformations on top of what is required
+for single-threaded execution: introducing a store to a byte which might not
+otherwise be stored is not allowed in general. (Specifically, in the case
+where another thread might write to and read from an address, introducing a
+store can change a load that may see exactly one write into a load that may
+see multiple writes.)</p>
+
+<!-- FIXME: This model assumes all targets where concurrency is relevant have
+a byte-size store which doesn't affect adjacent bytes. As far as I can tell,
+none of the backends currently in the tree fall into this category; however,
+there might be targets which care. If there are, we want a paragraph
+like the following:
+
+Targets may specify that stores narrower than a certain width are not
+available; on such a target, for the purposes of this model, treat any
+non-atomic write with an alignment or width less than the minimum width
+as if it writes to the relevant surrounding bytes.
+-->
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="ordering">Atomic Memory Ordering Constraints</a>
+</h3>
+
+<div>
+
+<p>Atomic instructions (<a href="#i_cmpxchg"><code>cmpxchg</code></a>,
+<a href="#i_atomicrmw"><code>atomicrmw</code></a>,
+<a href="#i_fence"><code>fence</code></a>,
+<a href="#i_load"><code>atomic load</code></a>, and
+<a href="#i_store"><code>atomic store</code></a>) take an ordering parameter
+that determines which other atomic instructions on the same address they
+<i>synchronize with</i>. These semantics are borrowed from Java and C++0x,
+but are somewhat more colloquial. If these descriptions aren't precise enough,
+check those specs (see spec references in the
+<a href="Atomic.html#introduction">atomics guide</a>).
+<a href="#i_fence"><code>fence</code></a> instructions
+treat these orderings somewhat differently since they don't take an address.
+See that instruction's documentation for details.</p>
+
+<p>For a simpler introduction to the ordering constraints, see the
+<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p>
+
+<dl>
+<dt><code>unordered</code></dt>
+<dd>The set of values that can be read is governed by the happens-before
+partial order. A value cannot be read unless some operation wrote it.
+This is intended to provide a guarantee strong enough to model Java's
+non-volatile shared variables. This ordering cannot be specified for
+read-modify-write operations; it is not strong enough to make them atomic
+in any interesting way.</dd>
+<dt><code>monotonic</code></dt>
+<dd>In addition to the guarantees of <code>unordered</code>, there is a single
+total order for modifications by <code>monotonic</code> operations on each
+address. All modification orders must be compatible with the happens-before
+order. There is no guarantee that the modification orders can be combined to
+a global total order for the whole program (and this often will not be
+possible). The read in an atomic read-modify-write operation
+(<a href="#i_cmpxchg"><code>cmpxchg</code></a> and
+<a href="#i_atomicrmw"><code>atomicrmw</code></a>)
+reads the value in the modification order immediately before the value it
+writes. If one atomic read happens before another atomic read of the same
+address, the later read must see the same value or a later value in the
+address's modification order. This disallows reordering of
+<code>monotonic</code> (or stronger) operations on the same address. If an
+address is written <code>monotonic</code>ally by one thread, and other threads
+<code>monotonic</code>ally read that address repeatedly, the other threads must
+eventually see the write. This corresponds to the C++0x/C1x
+<code>memory_order_relaxed</code>.</dd>
+<dt><code>acquire</code></dt>
+<dd>In addition to the guarantees of <code>monotonic</code>,
+a <i>synchronizes-with</i> edge may be formed with a <code>release</code>
+operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd>
+<dt><code>release</code></dt>
+<dd>In addition to the guarantees of <code>monotonic</code>, if this operation
+writes a value which is subsequently read by an <code>acquire</code> operation,
+it <i>synchronizes-with</i> that operation. (This isn't a complete
+description; see the C++0x definition of a release sequence.) This corresponds
+to the C++0x/C1x <code>memory_order_release</code>.</dd>
+<dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an
+<code>acquire</code> and <code>release</code> operation on its address.
+This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd>
+<dt><code>seq_cst</code> (sequentially consistent)</dt><dd>
+<dd>In addition to the guarantees of <code>acq_rel</code>
+(<code>acquire</code> for an operation which only reads, <code>release</code>
+for an operation which only writes), there is a global total order on all
+sequentially-consistent operations on all addresses, which is consistent with
+the <i>happens-before</i> partial order and with the modification orders of
+all the affected addresses. Each sequentially-consistent read sees the last
+preceding write to the same address in this global order. This corresponds
+to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd>
+</dl>
+
+<p id="singlethread">If an atomic operation is marked <code>singlethread</code>,
+it only <i>synchronizes with</i> or participates in modification and seq_cst
+total orderings with other operations running in the same thread (for example,
+in signal handlers).</p>
+
+</div>
+
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="typesystem">Type System</a> </div>
+<h2><a name="typesystem">Type System</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>The LLVM type system is one of the most important features of the
intermediate representation. Being typed enables a number of optimizations
and transformations that are not feasible to perform on normal three address
code representations.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="t_classifications">Type
-Classifications</a> </div>
+<h3>
+ <a name="t_classifications">Type Classifications</a>
+</h3>
-<div class="doc_text">
+<div>
<p>The types fall into a few useful classifications:</p>
<a href="#t_pointer">pointer</a>,
<a href="#t_vector">vector</a>,
<a href="#t_struct">structure</a>,
- <a href="#t_union">union</a>,
<a href="#t_array">array</a>,
<a href="#t_label">label</a>,
<a href="#t_metadata">metadata</a>.
<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>
<a href="#t_function">function</a>,
<a href="#t_pointer">pointer</a>,
<a href="#t_struct">structure</a>,
- <a href="#t_pstruct">packed structure</a>,
- <a href="#t_union">union</a>,
<a href="#t_vector">vector</a>,
<a href="#t_opaque">opaque</a>.
</td>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
+<h3>
+ <a name="t_primitive">Primitive Types</a>
+</h3>
-<div class="doc_text">
+<div>
<p>The primitive types are the fundamental building blocks of the LLVM
system.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
+<h4>
+ <a name="t_integer">Integer Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>The integer type is a very simple type that simply specifies an arbitrary
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div>
+<h4>
+ <a name="t_floating">Floating Point Types</a>
+</h4>
-<div class="doc_text">
+<div>
<table>
<tbody>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div>
+<h4>
+ <a name="t_x86mmx">X86mmx Type</a>
+</h4>
+
+<div>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="t_void">Void Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>The void type does not represent any value and has no size.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_label">Label Type</a> </div>
+<h4>
+ <a name="t_label">Label Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>The label type represents code labels.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_metadata">Metadata Type</a> </div>
+<h4>
+ <a name="t_metadata">Metadata Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>The metadata type represents embedded metadata. No derived types may be
</div>
+</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
+<h3>
+ <a name="t_derived">Derived Types</a>
+</h3>
-<div class="doc_text">
+<div>
<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
possible to have a two dimensional array, using an array as the element type
of another array.</p>
-
</div>
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_aggregate">Aggregate Types</a> </div>
+<h4>
+ <a name="t_aggregate">Aggregate Types</a>
+</h4>
-<div class="doc_text">
+<div>
<p>Aggregate Types are a subset of derived types that can contain multiple
member types. <a href="#t_array">Arrays</a>,
- <a href="#t_struct">structs</a>, <a href="#t_vector">vectors</a> and
- <a href="#t_union">unions</a> are aggregate types.</p>
-
-</div>
+ <a href="#t_struct">structs</a>, and <a href="#t_vector">vectors</a> are
+ aggregate types.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
+<h4>
+ <a name="t_array">Array Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>The array type is a very simple derived type that arranges elements
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
+<h4>
+ <a name="t_function">Function Type</a>
+</h4>
-<div class="doc_text">
+<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, a struct type, or a union
- type. If the return type is a struct type then all struct elements must be
- of first class types, and the struct must have at least one element.</p>
+ function type is a first class type or a void type.</p>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
+<h4>
+ <a name="t_struct">Structure Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>The structure type is used to represent a collection of data members together
- in memory. The packing of the field types is defined to match the ABI of the
- underlying processor. The elements of a structure may be any type that has a
- size.</p>
+ in memory. The elements of a structure may be any type that has a size.</p>
<p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>'
and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field
Structures in registers are accessed using the
'<tt><a href="#i_extractvalue">extractvalue</a></tt>' and
'<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p>
+
+<p>Structures may optionally be "packed" structures, which indicate that the
+ alignment of the struct is one byte, and that there is no padding between
+ the elements. In non-packed structs, padding between field types is inserted
+ as defined by the TargetData string in the module, which is required to match
+ what the underlying code generator expects.</p>
+
+<p>Structures can either be "literal" or "identified". A literal structure is
+ defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified
+ types are always defined at the top level with a name. Literal types are
+ uniqued by their contents and can never be recursive or opaque since there is
+ no way to write one. Identified types can be recursive, can be opaqued, and are
+ never uniqued.
+</p>
+
<h5>Syntax:</h5>
<pre>
- { <type list> }
+ %T1 = type { <type list> } <i>; Identified normal struct type</i>
+ %T2 = type <{ <type list> }> <i>; Identified packed struct type</i>
</pre>
-
+
<h5>Examples:</h5>
<table class="layout">
<tr class="layout">
<td class="left"><tt>{ i32, i32, i32 }</tt></td>
<td class="left">A triple of three <tt>i32</tt> values</td>
- </tr><tr class="layout">
+ </tr>
+ <tr class="layout">
<td class="left"><tt>{ float, i32 (i32) * }</tt></td>
<td class="left">A pair, where the first element is a <tt>float</tt> and the
second element is a <a href="#t_pointer">pointer</a> to a
<a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
an <tt>i32</tt>.</td>
</tr>
-</table>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_pstruct">Packed Structure Type</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Overview:</h5>
-<p>The packed structure type is used to represent a collection of data members
- together in memory. There is no padding between fields. Further, the
- alignment of a packed structure is 1 byte. The elements of a packed
- structure may be any type that has a size.</p>
-
-<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and
- '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with
- the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
-
-<h5>Syntax:</h5>
-<pre>
- < { <type list> } >
-</pre>
-
-<h5>Examples:</h5>
-<table class="layout">
<tr class="layout">
- <td class="left"><tt>< { i32, i32, i32 } ></tt></td>
- <td class="left">A triple of three <tt>i32</tt> values</td>
- </tr><tr class="layout">
- <td class="left">
-<tt>< { float, i32 (i32)* } ></tt></td>
- <td class="left">A pair, where the first element is a <tt>float</tt> and the
- second element is a <a href="#t_pointer">pointer</a> to a
- <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
- an <tt>i32</tt>.</td>
+ <td class="left"><tt><{ i8, i32 }></tt></td>
+ <td class="left">A packed struct known to be 5 bytes in size.</td>
</tr>
</table>
</div>
-
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_union">Union Type</a> </div>
+<h4>
+ <a name="t_opaque">Opaque Structure Types</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
-<p>A union type describes an object with size and alignment suitable for
- an object of any one of a given set of types (also known as an "untagged"
- union). It is similar in concept and usage to a
- <a href="#t_struct">struct</a>, except that all members of the union
- have an offset of zero. The elements of a union may be any type that has a
- size. Unions must have at least one member - empty unions are not allowed.
- </p>
-
-<p>The size of the union as a whole will be the size of its largest member,
- and the alignment requirements of the union as a whole will be the largest
- alignment requirement of any member.</p>
-
-<p>Union members are accessed using '<tt><a href="#i_load">load</a></tt> and
- '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with
- the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.
- Since all members are at offset zero, the getelementptr instruction does
- not affect the address, only the type of the resulting pointer.</p>
+<p>Opaque structure types are used to represent named structure types that do
+ not have a body specified. This corresponds (for example) to the C notion of
+ a forward declared structure.</p>
<h5>Syntax:</h5>
<pre>
- union { <type list> }
+ %X = type opaque
+ %52 = type opaque
</pre>
<h5>Examples:</h5>
<table class="layout">
<tr class="layout">
- <td class="left"><tt>union { i32, i32*, float }</tt></td>
- <td class="left">A union of three types: an <tt>i32</tt>, a pointer to
- an <tt>i32</tt>, and a <tt>float</tt>.</td>
- </tr><tr class="layout">
- <td class="left">
- <tt>union { float, i32 (i32) * }</tt></td>
- <td class="left">A union, where the first element is a <tt>float</tt> and the
- second element is a <a href="#t_pointer">pointer</a> to a
- <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
- an <tt>i32</tt>.</td>
+ <td class="left"><tt>opaque</tt></td>
+ <td class="left">An opaque type.</td>
</tr>
</table>
</div>
+
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
+<h4>
+ <a name="t_pointer">Pointer Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>The pointer type is used to specify memory locations.
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_vector">Vector Type</a> </div>
+<h4>
+ <a name="t_vector">Vector Type</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Overview:</h5>
<p>A vector type is a simple derived type that represents a vector of elements.
< <# 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">
</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_opaque">Opaque Type</a> </div>
-<div class="doc_text">
-
-<h5>Overview:</h5>
-<p>Opaque types are used to represent unknown types in the system. This
- corresponds (for example) to the C notion of a forward declared structure
- type. In LLVM, opaque types can eventually be resolved to any type (not just
- a structure type).</p>
-
-<h5>Syntax:</h5>
-<pre>
- opaque
-</pre>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>opaque</tt></td>
- <td class="left">An opaque type.</td>
- </tr>
-</table>
-
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="t_uprefs">Type Up-references</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Overview:</h5>
-<p>An "up reference" allows you to refer to a lexically enclosing type without
- requiring it to have a name. For instance, a structure declaration may
- contain a pointer to any of the types it is lexically a member of. Example
- of up references (with their equivalent as named type declarations)
- include:</p>
-
-<pre>
- { \2 * } %x = type { %x* }
- { \2 }* %y = type { %y }*
- \1* %z = type %z*
-</pre>
-
-<p>An up reference is needed by the asmprinter for printing out cyclic types
- when there is no declared name for a type in the cycle. Because the
- asmprinter does not want to print out an infinite type string, it needs a
- syntax to handle recursive types that have no names (all names are optional
- in llvm IR).</p>
-
-<h5>Syntax:</h5>
-<pre>
- \<level>
-</pre>
-
-<p>The level is the count of the lexical type that is being referred to.</p>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>\1*</tt></td>
- <td class="left">Self-referential pointer.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>{ { \3*, i8 }, i32 }</tt></td>
- <td class="left">Recursive structure where the upref refers to the out-most
- structure.</td>
- </tr>
-</table>
-
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="constants">Constants</a> </div>
+<h2><a name="constants">Constants</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>LLVM has several different basic types of constants. This section describes
them all and their syntax.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="simpleconstants">Simple Constants</a></div>
+<h3>
+ <a name="simpleconstants">Simple Constants</a>
+</h3>
-<div class="doc_text">
+<div>
<dl>
<dt><b>Boolean constants</b></dt>
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>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="aggregateconstants"></a> <!-- old anchor -->
<a name="complexconstants">Complex Constants</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Complex constants are a (potentially recursive) combination of simple
constants and smaller complex constants.</p>
the number and types of elements must match those specified by the
type.</dd>
- <dt><b>Union constants</b></dt>
- <dd>Union constants are represented with notation similar to a structure with
- a single element - that is, a single typed element surrounded
- by braces (<tt>{}</tt>)). For example: "<tt>{ i32 4 }</tt>". The
- <a href="#t_union">union type</a> can be initialized with a single-element
- struct as long as the type of the struct element matches the type of
- one of the union members.</dd>
-
<dt><b>Array constants</b></dt>
<dd>Array constants are represented with notation similar to array type
definitions (a comma separated list of elements, surrounded by square
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="globalconstants">Global Variable and Function Addresses</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>The addresses of <a href="#globalvars">global variables</a>
and <a href="#functionstructure">functions</a> are always implicitly valid
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">
+<h3>
+ <a name="undefvalues">Undefined Values</a>
+</h3>
+
+<div>
<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 label or void) and be used
- anywhere a constant is permitted.</p>
+ 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
surprising) transformations that are valid (in pseudo IR):</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = add %X, undef
%B = sub %X, undef
%C = xor %X, undef
%B = undef
%C = undef
</pre>
-</div>
<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>
+ Any output bit can have a zero or one depending on the input bits.</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = or %X, undef
%B = and %X, undef
Safe:
%A = undef
%B = undef
</pre>
-</div>
<p>These logical operations have bits that are not always affected by the input.
-For example, if "%X" has a zero bit, then the output of the 'and' operation will
-always be a zero, no matter what the corresponding bit from the undef is. As
-such, it is unsafe to optimize or assume that the result of the and is undef.
-However, it is safe to assume that all bits of the undef could be 0, and
-optimize the and to 0. Likewise, it is safe to assume that all the bits of
-the undef operand to the or could be set, allowing the or to be folded to
--1.</p>
-
-<div class="doc_code">
-<pre>
+ 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
%B = undef
%C = undef
</pre>
-</div>
-
-<p>This set of examples show that undefined select (and conditional branch)
-conditions can go "either way" but they have to come from one of the two
-operands. In the %A example, if %X and %Y were both known to have a clear low
-bit, then %A would have to have a cleared low bit. However, in the %C example,
-the optimizer is allowed to assume that the undef operand could be the same as
-%Y, allowing the whole select to be eliminated.</p>
+<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>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = xor undef, undef
%B = undef
%E = undef
%F = undef
</pre>
-</div>
-<p>This example points out that two undef operands are not necessarily the same.
-This can be surprising to people (and also matches C semantics) where they
-assume that "X^X" is always zero, even if X is undef. This isn't true for a
-number of reasons, but the short answer is that an undef "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, %A and %C need
-to have the same semantics or the core LLVM "replace all uses with" concept
-would not hold.</p>
+<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>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = fdiv undef, %X
%B = fdiv %X, undef
Safe:
%A = undef
b: unreachable
</pre>
-</div>
<p>These examples show the crucial difference between an <em>undefined
-value</em> and <em>undefined behavior</em>. An undefined value (like undef) is
-allowed to have an arbitrary bit-pattern. This means that the %A operation
-can be constant folded to undef because the undef could be an SNaN, and fdiv is
-not (currently) defined on SNaN's. However, in the second example, we can make
-a more aggressive assumption: because the undef 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: since the undefined operation "can't happen", the optimizer can assume that
-it occurs in dead code.
-</p>
-
-<div class="doc_code">
-<pre>
+ 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>
-</div>
-<p>These examples reiterate the fdiv example: a store "of" an undefined value
-can be assumed to not have any effect: we can assume that the value is
-overwritten with bits that happen to match what was already there. However, a
-store "to" an undefined location could clobber arbitrary memory, therefore, it
-has undefined behavior.</p>
+<p>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">
+<h3>
+ <a name="trapvalues">Trap Values</a>
+</h3>
+
+<div>
<p>Trap values are similar to <a href="#undefvalues">undef values</a>, however
instead of representing an unspecified bit pattern, they represent the
<p>Trap value behavior is defined in terms of value <i>dependence</i>:</p>
-<p>
<ul>
<li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
their operands.</li>
<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>
+ may not be executed when control is transferred to another.</li>
+
+<li>Additionally, an instruction also <i>control-depends</i> on a terminator
+ instruction if the set of instructions it otherwise depends on would be
+ different if the terminator had transferred control to a different
+ successor.</li>
<li>Dependence is transitive.</li>
</ul>
-</p>
<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
+ to trap. If they have side effects, they 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>
-<div class="doc_code">
-<pre>
+<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.
%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.
+ %trap3 = load i16* %narrowaddr ; Returns a trap value.
+ %trap4 = load i64* %wideaddr ; Returns a trap value.
- %cmp = icmp i32 slt %trap, 0 ; Returns a trap value.
- %br i1 %cmp, %true, %end ; Branch to either destination.
+ %cmp = icmp slt i32 %trap, 0 ; Returns a trap value.
+ br i1 %cmp, label %true, label %end ; Branch to either destination.
true:
volatile store i32 0, i32* @g ; This is control-dependent on %cmp, so
; 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
+ volatile store i32 0, i32* @g ; This would depend on the store in %true
+ ; if %cmp is true, or the store in %entry
+ ; otherwise, so this is undefined behavior.
+
+ br i1 %cmp, label %second_true, label %second_end
+ ; The same branch again, but this time the
+ ; true block doesn't have side effects.
+
+second_true:
+ ; No side effects!
+ ret void
+
+second_end:
+ volatile store i32 0, i32* @g ; This time, the instruction always depends
+ ; on the store in %end. Also, it is
+ ; control-equivalent to %end, so this is
+ ; well-defined (again, ignoring earlier
; undefined behavior in this example).
</pre>
-</div>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="blockaddress">Addresses of Basic
- Blocks</a></div>
-<div class="doc_text">
+<h3>
+ <a name="blockaddress">Addresses of Basic Blocks</a>
+</h3>
+
+<div>
<p><b><tt>blockaddress(@function, %block)</tt></b></p>
the address of the entry block is illegal.</p>
<p>This value only has defined behavior when used as an operand to the
- '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction or for comparisons
- against null. Pointer equality tests between labels addresses is undefined
- behavior - though, again, comparison against null is ok, and no label is
- equal to the null pointer. This may also 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>.</p>
+ '<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>
+<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>
+<h3>
+ <a name="constantexprs">Constant Expressions</a>
+</h3>
-<div class="doc_text">
+<div>
<p>Constant expressions are used to allow expressions involving other constants
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>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>
<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>
<dd>Truncate a floating point constant to another floating point type. The
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="othervalues">Other Values</a> </div>
+<h2><a name="othervalues">Other Values</a></h2>
<!-- *********************************************************************** -->
-
+<div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="inlineasm">Inline Assembler Expressions</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM supports inline assembler expressions (as opposed
to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of
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,
contain and should generate its usual stack alignment code in the prologue
if the '<tt>alignstack</tt>' keyword is present:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
call void asm alignstack "eieio", ""()
</pre>
-</div>
<p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come
first.</p>
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">
+<h4>
<a name="inlineasm_md">Inline Asm Metadata</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode
- attached to it that contains a constant integer. If present, the code
- generator will use the integer as the location cookie value when report
+ 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>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
...
!42 = !{ i32 1234567 }
</pre>
-</div>
<p>It is up to the front-end to make sense of the magic numbers it places in the
- IR.</p>
+ 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">
+<!-- ======================================================================= -->
+<h3>
+ <a name="metadata">Metadata Nodes and Metadata Strings</a>
+</h3>
+
+<div>
<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
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.
+ function is using two metadata arguments.</p>
- call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
- </pre>
- </div></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.
+ 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></p>
+<div class="doc_code">
+<pre>
+%indvar.next = add i64 %indvar, 1, !dbg !21
+</pre>
</div>
+</div>
+
+</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="intrinsic_globals">Intrinsic Global Variables</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-
+<div>
<p>LLVM has a number of "magic" global variables that contain data that affect
code generation or other IR semantics. These are documented here. All globals
of this sort should have a section specified as "<tt>llvm.metadata</tt>". This
by LLVM.</p>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a
href="#linkage_appending">appending linkage</a>. This array contains a list of
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
-<a name="intg_compiler_used">The '<tt>llvm.compiler.used</tt>' Global Variable</a>
-</div>
+<h3>
+ <a name="intg_compiler_used">
+ The '<tt>llvm.compiler.used</tt>' Global Variable
+ </a>
+</h3>
-<div class="doc_text">
+<div>
<p>The <tt>@llvm.compiler.used</tt> directive is the same as the
<tt>@llvm.used</tt> directive, except that it only prevents the compiler from
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<pre>
%0 = type { i32, void ()* }
@llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<pre>
%0 = type { i32, void ()* }
@llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
</div>
+</div>
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
+<h2><a name="instref">Instruction Reference</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>The LLVM instruction set consists of several different classifications of
instructions: <a href="#terminators">terminator
<a href="#memoryops">memory instructions</a>, and
<a href="#otherops">other instructions</a>.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="terminators">Terminator
-Instructions</a> </div>
+<h3>
+ <a name="terminators">Terminator Instructions</a>
+</h3>
-<div class="doc_text">
+<div>
<p>As mentioned <a href="#functionstructure">previously</a>, every basic block
in a program ends with a "Terminator" instruction, which indicates which
control flow, not values (the one exception being the
'<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
-<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>
-
-</div>
+<p>The terminator instructions are:
+ '<a href="#i_ret"><tt>ret</tt></a>',
+ '<a href="#i_br"><tt>br</tt></a>',
+ '<a href="#i_switch"><tt>switch</tt></a>',
+ '<a href="#i_indirectbr"><tt>indirectbr</tt></a>',
+ '<a href="#i_invoke"><tt>invoke</tt></a>',
+ '<a href="#i_unwind"><tt>unwind</tt></a>',
+ '<a href="#i_resume"><tt>resume</tt></a>', and
+ '<a href="#i_unreachable"><tt>unreachable</tt></a>'.</p>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_ret">'<tt>ret</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
+<h4>
+ <a name="i_br">'<tt>br</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
- br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i>
+ br i1 <cond>, label <iftrue>, label <iffalse>
+ br label <dest> <i>; Unconditional branch</i>
</pre>
<h5>Overview:</h5>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_switch">'<tt>switch</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
instruction, control is interrupted and continued at the dynamically nearest
"exception" label.</p>
+<p>The '<tt>exception</tt>' label is a
+ <i><a href="ExceptionHandling.html#overview">landing pad</a></i> for the
+ exception. As such, '<tt>exception</tt>' label is required to have the
+ "<a href="#i_landingpad"><tt>landingpad</tt></a>" instruction, which contains
+ the information about about the behavior of the program after unwinding
+ happens, as its first non-PHI instruction. The restrictions on the
+ "<tt>landingpad</tt>" instruction's tightly couples it to the
+ "<tt>invoke</tt>" instruction, so that the important information contained
+ within the "<tt>landingpad</tt>" instruction can't be lost through normal
+ code motion.</p>
+
<h5>Arguments:</h5>
<p>This instruction requires several arguments:</p>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_unwind">'<tt>unwind</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
<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>
+
+ <!-- _______________________________________________________________________ -->
+
+<h4>
+ <a name="i_resume">'<tt>resume</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ resume <type> <value>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>resume</tt>' instruction is a terminator instruction that has no
+ successors.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>resume</tt>' instruction requires one argument, which must have the
+ same type as the result of any '<tt>landingpad</tt>' instruction in the same
+ function.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>resume</tt>' instruction resumes propagation of an existing
+ (in-flight) exception whose unwinding was interrupted with
+ a <a href="#i_landingpad"><tt>landingpad</tt></a> instruction.</p>
+
+<h5>Example:</h5>
+<pre>
+ resume { i8*, i32 } %exn
+</pre>
+
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_unreachable">'<tt>unreachable</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_unreachable">'<tt>unreachable</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
+<h3>
+ <a name="binaryops">Binary Operations</a>
+</h3>
-<div class="doc_text">
+<div>
<p>Binary operators are used to do most of the computation in a program. They
require two operands of the same type, execute an operation on them, and
<p>There are several different binary operators:</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_add">'<tt>add</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_fadd">'<tt>fadd</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_sub">'<tt>sub</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_fsub">'<tt>fsub</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_mul">'<tt>mul</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_fmul">'<tt>fmul</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction
-</a></div>
+<h4>
+ <a name="i_udiv">'<tt>udiv</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<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>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>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction
-</a> </div>
+<h4>
+ <a name="i_sdiv">'<tt>sdiv</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
<p>If the <tt>exact</tt> keyword is present, the result value of the
<tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would
- be rounded or if overflow would occur.</p>
+ be rounded.</p>
<h5>Example:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_fdiv">'<tt>fdiv</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a>
-</div>
+<h4>
+ <a name="i_urem">'<tt>urem</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_srem">'<tt>srem</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
<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">
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_frem">'<tt>frem</tt>' Instruction</a> </div>
+<h4>
+ <a name="i_frem">'<tt>frem</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
-Operations</a> </div>
+<h3>
+ <a name="bitwiseops">Bitwise Binary Operations</a>
+</h3>
-<div class="doc_text">
+<div>
<p>Bitwise binary operators are used to do various forms of bit-twiddling in a
program. They are generally very efficient instructions and can commonly be
same type, execute an operation on them, and produce a single value. The
resulting value is the same type as its operands.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_shl">'<tt>shl</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<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>
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>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_lshr">'<tt>lshr</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<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>
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>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_ashr">'<tt>ashr</tt>'
-Instruction</a> </div>
-<div class="doc_text">
+<h4>
+ <a name="i_ashr">'<tt>ashr</tt>' Instruction</a>
+</h4>
+
+<div>
<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>
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>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_and">'<tt>and</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
+<h4>
+ <a name="i_or">'<tt>or</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_xor">'<tt>xor</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="vectorops">Vector Operations</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM supports several instructions to represent vector operations in a
target-independent manner. These instructions cover the element-access and
will want to use target-specific intrinsics to take full advantage of a
specific target.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="aggregateops">Aggregate Operations</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM supports several instructions for working with
<a href="#t_aggregate">aggregate</a> values.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_extractvalue">'<tt>extractvalue</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
<h5>Arguments:</h5>
<p>The first operand of an '<tt>extractvalue</tt>' instruction is a value
- of <a href="#t_struct">struct</a>, <a href="#t_union">union</a> or
+ 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
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_insertvalue">'<tt>insertvalue</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
- <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx> <i>; yields <aggregate type></i>
+ <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* <i>; yields <aggregate type></i>
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
<p>The first operand of an '<tt>insertvalue</tt>' instruction is a value
- of <a href="#t_struct">struct</a>, <a href="#t_union">union</a> or
+ 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
+ '<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>
- %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>
+ %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>
+ %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0 <i>; yields {i32 1, float %val}</i>
</pre>
</div>
+</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="memoryops">Memory Access and Addressing Operations</a>
-</div>
+</h3>
-<div class="doc_text">
+<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, and allocate
memory in LLVM.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_load">'<tt>load</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
- <result> = load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
- <result> = volatile load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
!<index> = !{ i32 1 }
</pre>
number or order of execution of this <tt>load</tt> with other <a
href="#volatile">volatile operations</a>.</p>
+<p>If the <code>load</code> is marked as <code>atomic</code>, it takes an extra
+ <a href="#ordering">ordering</a> and optional <code>singlethread</code>
+ argument. The <code>release</code> and <code>acq_rel</code> orderings are
+ not valid on <code>load</code> instructions. Atomic loads produce <a
+ href="#memorymodel">defined</a> results when they may see multiple atomic
+ stores. The type of the pointee must be an integer type whose bit width
+ is a power of two greater than or equal to eight and less than or equal
+ to a target-specific size limit. <code>align</code> must be explicitly
+ specified on atomic loads, and the load has undefined behavior if the
+ alignment is not set to a value which is at least the size in bytes of
+ the pointee. <code>!nontemporal</code> does not have any defined semantics
+ for atomic loads.</p>
+
<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 <tt>align</tt> argument means that the operation has the preferential
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
-Instruction</a> </div>
+<h4>
+ <a name="i_store">'<tt>store</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
- 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>
+ store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
+ store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> <i>; yields {void}</i>
</pre>
<h5>Overview:</h5>
order of execution of this <tt>store</tt> with other <a
href="#volatile">volatile operations</a>.</p>
+<p>If the <code>store</code> is marked as <code>atomic</code>, it takes an extra
+ <a href="#ordering">ordering</a> and optional <code>singlethread</code>
+ argument. The <code>acquire</code> and <code>acq_rel</code> orderings aren't
+ valid on <code>store</code> instructions. Atomic loads produce <a
+ href="#memorymodel">defined</a> results when they may see multiple atomic
+ stores. The type of the pointee must be an integer type whose bit width
+ is a power of two greater than or equal to eight and less than or equal
+ to a target-specific size limit. <code>align</code> must be explicitly
+ specified on atomic stores, and the store has undefined behavior if the
+ alignment is not set to a value which is at least the size in bytes of
+ the pointee. <code>!nontemporal</code> does not have any defined semantics
+ for atomic stores.</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
omitted "align" argument means that the operation has the preferential
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
+ 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
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
+<h4>
+<a name="i_fence">'<tt>fence</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ fence [singlethread] <ordering> <i>; yields {void}</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fence</tt>' instruction is used to introduce happens-before edges
+between operations.</p>
+
+<h5>Arguments:</h5> <p>'<code>fence</code>' instructions take an <a
+href="#ordering">ordering</a> argument which defines what
+<i>synchronizes-with</i> edges they add. They can only be given
+<code>acquire</code>, <code>release</code>, <code>acq_rel</code>, and
+<code>seq_cst</code> orderings.</p>
+
+<h5>Semantics:</h5>
+<p>A fence <var>A</var> which has (at least) <code>release</code> ordering
+semantics <i>synchronizes with</i> a fence <var>B</var> with (at least)
+<code>acquire</code> ordering semantics if and only if there exist atomic
+operations <var>X</var> and <var>Y</var>, both operating on some atomic object
+<var>M</var>, such that <var>A</var> is sequenced before <var>X</var>,
+<var>X</var> modifies <var>M</var> (either directly or through some side effect
+of a sequence headed by <var>X</var>), <var>Y</var> is sequenced before
+<var>B</var>, and <var>Y</var> observes <var>M</var>. This provides a
+<i>happens-before</i> dependency between <var>A</var> and <var>B</var>. Rather
+than an explicit <code>fence</code>, one (but not both) of the atomic operations
+<var>X</var> or <var>Y</var> might provide a <code>release</code> or
+<code>acquire</code> (resp.) ordering constraint and still
+<i>synchronize-with</i> the explicit <code>fence</code> and establish the
+<i>happens-before</i> edge.</p>
+
+<p>A <code>fence</code> which has <code>seq_cst</code> ordering, in addition to
+having both <code>acquire</code> and <code>release</code> semantics specified
+above, participates in the global program order of other <code>seq_cst</code>
+operations and/or fences.</p>
+
+<p>The optional "<a href="#singlethread"><code>singlethread</code></a>" argument
+specifies that the fence only synchronizes with other fences in the same
+thread. (This is useful for interacting with signal handlers.)</p>
+
+<h5>Example:</h5>
+<pre>
+ fence acquire <i>; yields {void}</i>
+ fence singlethread seq_cst <i>; yields {void}</i>
+</pre>
+
</div>
-<div class="doc_text">
+<!-- _______________________________________________________________________ -->
+<h4>
+<a name="i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>cmpxchg</tt>' instruction is used to atomically modify memory.
+It loads a value in memory and compares it to a given value. If they are
+equal, it stores a new value into the memory.</p>
+
+<h5>Arguments:</h5>
+<p>There are three arguments to the '<code>cmpxchg</code>' instruction: an
+address to operate on, a value to compare to the value currently be at that
+address, and a new value to place at that address if the compared values are
+equal. The type of '<var><cmp></var>' must be an integer type whose
+bit width is a power of two greater than or equal to eight and less than
+or equal to a target-specific size limit. '<var><cmp></var>' and
+'<var><new></var>' must have the same type, and the type of
+'<var><pointer></var>' must be a pointer to that type. If the
+<code>cmpxchg</code> is marked as <code>volatile</code>, then the
+optimizer is not allowed to modify the number or order of execution
+of this <code>cmpxchg</code> with other <a href="#volatile">volatile
+operations</a>.</p>
+
+<!-- FIXME: Extend allowed types. -->
+
+<p>The <a href="#ordering"><var>ordering</var></a> argument specifies how this
+<code>cmpxchg</code> synchronizes with other atomic operations.</p>
+
+<p>The optional "<code>singlethread</code>" argument declares that the
+<code>cmpxchg</code> is only atomic with respect to code (usually signal
+handlers) running in the same thread as the <code>cmpxchg</code>. Otherwise the
+cmpxchg is atomic with respect to all other code in the system.</p>
+
+<p>The pointer passed into cmpxchg must have alignment greater than or equal to
+the size in memory of the operand.
+
+<h5>Semantics:</h5>
+<p>The contents of memory at the location specified by the
+'<tt><pointer></tt>' operand is read and compared to
+'<tt><cmp></tt>'; if the read value is the equal,
+'<tt><new></tt>' is written. The original value at the location
+is returned.
+
+<p>A successful <code>cmpxchg</code> is a read-modify-write instruction for the
+purpose of identifying <a href="#release_sequence">release sequences</a>. A
+failed <code>cmpxchg</code> is equivalent to an atomic load with an ordering
+parameter determined by dropping any <code>release</code> part of the
+<code>cmpxchg</code>'s ordering.</p>
+
+<!--
+FIXME: Is compare_exchange_weak() necessary? (Consider after we've done
+optimization work on ARM.)
+
+FIXME: Is a weaker ordering constraint on failure helpful in practice?
+-->
+
+<h5>Example:</h5>
+<pre>
+entry:
+ %orig = atomic <a href="#i_load">load</a> i32* %ptr unordered <i>; yields {i32}</i>
+ <a href="#i_br">br</a> label %loop
+
+loop:
+ %cmp = <a href="#i_phi">phi</a> i32 [ %orig, %entry ], [%old, %loop]
+ %squared = <a href="#i_mul">mul</a> i32 %cmp, %cmp
+ %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared <i>; yields {i32}</i>
+ %success = <a href="#i_icmp">icmp</a> eq i32 %cmp, %old
+ <a href="#i_br">br</a> i1 %success, label %done, label %loop
+
+done:
+ ...
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+<a name="i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> <i>; yields {ty}</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>atomicrmw</tt>' instruction is used to atomically modify memory.</p>
+
+<h5>Arguments:</h5>
+<p>There are three arguments to the '<code>atomicrmw</code>' instruction: an
+operation to apply, an address whose value to modify, an argument to the
+operation. The operation must be one of the following keywords:</p>
+<ul>
+ <li>xchg</li>
+ <li>add</li>
+ <li>sub</li>
+ <li>and</li>
+ <li>nand</li>
+ <li>or</li>
+ <li>xor</li>
+ <li>max</li>
+ <li>min</li>
+ <li>umax</li>
+ <li>umin</li>
+</ul>
+
+<p>The type of '<var><value></var>' must be an integer type whose
+bit width is a power of two greater than or equal to eight and less than
+or equal to a target-specific size limit. The type of the
+'<code><pointer></code>' operand must be a pointer to that type.
+If the <code>atomicrmw</code> is marked as <code>volatile</code>, then the
+optimizer is not allowed to modify the number or order of execution of this
+<code>atomicrmw</code> with other <a href="#volatile">volatile
+ operations</a>.</p>
+
+<!-- FIXME: Extend allowed types. -->
+
+<h5>Semantics:</h5>
+<p>The contents of memory at the location specified by the
+'<tt><pointer></tt>' operand are atomically read, modified, and written
+back. The original value at the location is returned. The modification is
+specified by the <var>operation</var> argument:</p>
+
+<ul>
+ <li>xchg: <code>*ptr = val</code></li>
+ <li>add: <code>*ptr = *ptr + val</code></li>
+ <li>sub: <code>*ptr = *ptr - val</code></li>
+ <li>and: <code>*ptr = *ptr & val</code></li>
+ <li>nand: <code>*ptr = ~(*ptr & val)</code></li>
+ <li>or: <code>*ptr = *ptr | val</code></li>
+ <li>xor: <code>*ptr = *ptr ^ val</code></li>
+ <li>max: <code>*ptr = *ptr > val ? *ptr : val</code> (using a signed comparison)</li>
+ <li>min: <code>*ptr = *ptr < val ? *ptr : val</code> (using a signed comparison)</li>
+ <li>umax: <code>*ptr = *ptr > val ? *ptr : val</code> (using an unsigned comparison)</li>
+ <li>umin: <code>*ptr = *ptr < val ? *ptr : val</code> (using an unsigned comparison)</li>
+</ul>
+
+<h5>Example:</h5>
+<pre>
+ %old = atomicrmw add i32* %ptr, i32 1 acquire <i>; yields {i32}</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
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, structs and unions. Note that subsequent types being indexed into
+ 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 (optionally packed) structure or union, only <tt>i32</tt>
+ 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>
+ constant. These integers are treated as signed values where relevant.</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>'
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>
+ precise signed 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>
+ the base address with silently-wrapping two's complement arithmetic. If the
+ offsets have a different width from the pointer, they are sign-extended or
+ truncated to the width of the pointer. 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>
</div>
-<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="convertops">Conversion Operations</a>
</div>
-<div class="doc_text">
+<!-- ======================================================================= -->
+<h3>
+ <a name="convertops">Conversion Operations</a>
+</h3>
+
+<div>
<p>The instructions in this category are the conversion instructions (casting)
which all take a single operand and a type. They perform various bit
conversions on the operand.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
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>
- %Z = 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>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
<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>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
<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>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
<h5>Example:</h5>
<pre>
- %X = fpext float 3.1415 to double <i>; yields double:3.1415</i>
- %Y = fpext float 1.0 to float <i>; yields float:1.0 (no-op)</i>
+ %X = fpext float 3.125 to double <i>; yields double:3.125000e+00</i>
+ %Y = fpext double %X to fp128 <i>; yields fp128:0xL00000000000000004000900000000000</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
+<h3>
+ <a name="otherops">Other Operations</a>
+</h3>
-<div class="doc_text">
+<div>
<p>The instructions in this category are the "miscellaneous" instructions, which
defy better classification.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
-</div>
+<h4>
+ <a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
-</div>
+<h4>
+ <a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_phi">'<tt>phi</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_select">'<tt>select</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_call">'<tt>call</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="i_landingpad">'<tt>landingpad</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ <resultval> = landingpad <somety> personality <type> <pers_fn> <clause>+
+ <resultval> = landingpad <somety> personality <type> <pers_fn> cleanup <clause>*
+
+ <clause> := catch <type> <value>
+ <clause> := filter <array constant type> <array constant>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>landingpad</tt>' instruction is used by
+ <a href="ExceptionHandling.html#overview">LLVM's exception handling
+ system</a> to specify that a basic block is a landing pad — one where
+ the exception lands, and corresponds to the code found in the
+ <i><tt>catch</tt></i> portion of a <i><tt>try/catch</tt></i> sequence. It
+ defines values supplied by the personality function (<tt>pers_fn</tt>) upon
+ re-entry to the function. The <tt>resultval</tt> has the
+ type <tt>somety</tt>.</p>
+
+<h5>Arguments:</h5>
+<p>This instruction takes a <tt>pers_fn</tt> value. This is the personality
+ function associated with the unwinding mechanism. The optional
+ <tt>cleanup</tt> flag indicates that the landing pad block is a cleanup.</p>
+
+<p>A <tt>clause</tt> begins with the clause type — <tt>catch</tt>
+ or <tt>filter</tt> — and contains the global variable representing the
+ "type" that may be caught or filtered respectively. Unlike the
+ <tt>catch</tt> clause, the <tt>filter</tt> clause takes an array constant as
+ its argument. Use "<tt>[0 x i8**] undef</tt>" for a filter which cannot
+ throw. The '<tt>landingpad</tt>' instruction must contain <em>at least</em>
+ one <tt>clause</tt> or the <tt>cleanup</tt> flag.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>landingpad</tt>' instruction defines the values which are set by the
+ personality function (<tt>pers_fn</tt>) upon re-entry to the function, and
+ therefore the "result type" of the <tt>landingpad</tt> instruction. As with
+ calling conventions, how the personality function results are represented in
+ LLVM IR is target specific.</p>
+
+<p>The clauses are applied in order from top to bottom. If two
+ <tt>landingpad</tt> instructions are merged together through inlining, the
+ clauses from the calling function are appended to the list of clauses.</p>
+
+<p>The <tt>landingpad</tt> instruction has several restrictions:</p>
+
+<ul>
+ <li>A landing pad block is a basic block which is the unwind destination of an
+ '<tt>invoke</tt>' instruction.</li>
+ <li>A landing pad block must have a '<tt>landingpad</tt>' instruction as its
+ first non-PHI instruction.</li>
+ <li>There can be only one '<tt>landingpad</tt>' instruction within the landing
+ pad block.</li>
+ <li>A basic block that is not a landing pad block may not include a
+ '<tt>landingpad</tt>' instruction.</li>
+ <li>All '<tt>landingpad</tt>' instructions in a function must have the same
+ personality function.</li>
+</ul>
+
+<h5>Example:</h5>
+<pre>
+ ;; A landing pad which can catch an integer.
+ %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+ catch i8** @_ZTIi
+ ;; A landing pad that is a cleanup.
+ %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+ cleanup
+ ;; A landing pad which can catch an integer and can only throw a double.
+ %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+ catch i8** @_ZTIi
+ filter [1 x i8**] [@_ZTId]
+</pre>
+
+</div>
+
+</div>
+
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
+<h2><a name="intrinsics">Intrinsic Functions</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>LLVM supports the notion of an "intrinsic function". These functions have
well known names and semantics and are required to follow certain
<p>To learn how to add an intrinsic function, please see the
<a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_varargs">Variable Argument Handling Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Variable argument support is defined in LLVM with
the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
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>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_gc">Accurate Garbage Collection Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage
Collection</a> (GC) requires the implementation and generation of these
<p>The garbage collection intrinsics only operate on objects in the generic
address space (address space zero).</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_codegen">Code Generator Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>These intrinsics are provided by LLVM to expose special features that may
only be implemented with code generator support.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
- declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>)
+ declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
</pre>
<h5>Overview:</h5>
<p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the
specifier determining if the fetch should be for a read (0) or write (1),
and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
- locality, to (3) - extremely local keep in cache. The <tt>rw</tt>
- and <tt>locality</tt> arguments must be constant integers.</p>
+ locality, to (3) - extremely local keep in cache. The <tt>cache type</tt>
+ specifies whether the prefetch is performed on the data (1) or instruction (0)
+ cache. The <tt>rw</tt>, <tt>locality</tt> and <tt>cache type</tt> arguments
+ must be constant integers.</p>
<h5>Semantics:</h5>
<p>This intrinsic does not modify the behavior of the program. In particular,
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_libc">Standard C Library Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM provides intrinsics for a few important standard C library functions.
These intrinsics allow source-language front-ends to pass information about
the alignment of the pointer arguments to the code generator, providing
opportunity for more efficient code generation.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit
- width and for different address spaces. 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.p0i8.i32(i8* <dest>, i8 <val>,
particular byte value.</p>
<p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt>
- intrinsic does not return a value, takes extra alignment/volatile arguments,
- and the destination can be in an arbitrary address space.</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 intrinsic has an alignment value that is not 0 or 1,
then the caller guarantees that the destination pointer is aligned to that
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any
</div>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.exp</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.</p>
+
+<pre>
+ declare float @llvm.exp.f32(float %Val)
+ declare double @llvm.exp.f64(double %Val)
+ declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val)
+ declare fp128 @llvm.exp.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.exp.*</tt>' intrinsics perform the exp function.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+ type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>exp</tt> functions
+ would, and handles error conditions in the same way.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="int_log">'<tt>llvm.log.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.log</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.</p>
+
+<pre>
+ declare float @llvm.log.f32(float %Val)
+ declare double @llvm.log.f64(double %Val)
+ declare x86_fp80 @llvm.log.f80(x86_fp80 %Val)
+ declare fp128 @llvm.log.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.log.*</tt>' intrinsics perform the log function.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+ type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>log</tt> functions
+ would, and handles error conditions in the same way.</p>
+
+<h4>
+ <a name="int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.fma</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.</p>
+
+<pre>
+ declare float @llvm.fma.f32(float %a, float %b, float %c)
+ declare double @llvm.fma.f64(double %a, double %b, double %c)
+ declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
+ declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
+ declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.fma.*</tt>' intrinsics perform the fused multiply-add
+ operation.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+ type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>fma</tt> functions
+ would.</p>
+
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_manip">Bit Manipulation Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM provides intrinsics for a few important bit manipulation operations.
These allow efficient code generation for some algorithms.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic function. You can use bswap on any integer
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
- width. Not all targets support all bit widths however.</p>
+ width, or on any vector with integer elements. Not all targets support all
+ bit widths or vector types, however.</p>
<pre>
declare i8 @llvm.ctpop.i8(i8 <src>)
declare i32 @llvm.ctpop.i32(i32 <src>)
declare i64 @llvm.ctpop.i64(i64 <src>)
declare i256 @llvm.ctpop.i256(i256 <src>)
+ declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
<p>The only argument is the value to be counted. The argument may be of any
- integer type. The return type must match the argument type.</p>
+ integer type, or a vector with integer elements.
+ The return type must match the argument type.</p>
<h5>Semantics:</h5>
-<p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.</p>
+<p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable, or within each
+ element of a vector.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any
- integer bit width. Not all targets support all bit widths however.</p>
+ integer bit width, or any vector whose elements are integers. Not all
+ targets support all bit widths or vector types, however.</p>
<pre>
declare i8 @llvm.ctlz.i8 (i8 <src>)
declare i32 @llvm.ctlz.i32(i32 <src>)
declare i64 @llvm.ctlz.i64(i64 <src>)
declare i256 @llvm.ctlz.i256(i256 <src>)
+ declare <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src;gt)
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
<p>The only argument is the value to be counted. The argument may be of any
- integer type. The return type must match the argument type.</p>
+ integer type, or any vector type with integer element type.
+ The return type must match the argument type.</p>
<h5>Semantics:</h5>
<p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant)
- zeros in a variable. If the src == 0 then the result is the size in bits of
+ zeros in a variable, or within each element of the vector if the operation
+ is of vector type. If the src == 0 then the result is the size in bits of
the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any
- integer bit width. Not all targets support all bit widths however.</p>
+ integer bit width, or any vector of integer elements. Not all targets
+ support all bit widths or vector types, however.</p>
<pre>
declare i8 @llvm.cttz.i8 (i8 <src>)
declare i32 @llvm.cttz.i32(i32 <src>)
declare i64 @llvm.cttz.i64(i64 <src>)
declare i256 @llvm.cttz.i256(i256 <src>)
+ declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>)
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
<p>The only argument is the value to be counted. The argument may be of any
- integer type. The return type must match the argument type.</p>
+ integer type, or a vectory with integer element type.. The return type
+ must match the argument type.</p>
<h5>Semantics:</h5>
<p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant)
- zeros in a variable. If the src == 0 then the result is the size in bits of
+ zeros in a variable, or within each element of a vector.
+ If the src == 0 then the result is the size in bits of
the type of src. For example, <tt>llvm.cttz(2) = 1</tt>.</p>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_overflow">Arithmetic with Overflow Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM provides intrinsics for some arithmetic with overflow operations.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics</a>
-</div>
+<h4>
+ <a name="int_sadd_overflow">
+ '<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics</a>
-</div>
+<h4>
+ <a name="int_uadd_overflow">
+ '<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics</a>
-</div>
+<h4>
+ <a name="int_ssub_overflow">
+ '<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt>' Intrinsics</a>
-</div>
+<h4>
+ <a name="int_usub_overflow">
+ '<tt>llvm.usub.with.overflow.*</tt>' Intrinsics
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt>' Intrinsics</a>
-</div>
+<h4>
+ <a name="int_smul_overflow">
+ '<tt>llvm.smul.with.overflow.*</tt>' Intrinsics
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt>' Intrinsics</a>
-</div>
+<h4>
+ <a name="int_umul_overflow">
+ '<tt>llvm.umul.with.overflow.*</tt>' Intrinsics
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_fp16">Half Precision Floating Point Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<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
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>
+<h4>
+ <a name="int_convert_to_fp16">
+ '<tt>llvm.convert.to.fp16</tt>' Intrinsic
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a>
-</div>
+<h4>
+ <a name="int_convert_from_fp16">
+ '<tt>llvm.convert.from.fp16</tt>' Intrinsic
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_debugger">Debugger Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt>
prefix), are described in
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_eh">Exception Handling Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>The LLVM exception handling intrinsics (which all start with
<tt>llvm.eh.</tt> prefix), are described in
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="int_trampoline">Trampoline Intrinsic</a>
-</div>
+<h3>
+ <a name="int_trampoline">Trampoline Intrinsics</a>
+</h3>
-<div class="doc_text">
+<div>
-<p>This intrinsic makes it possible to excise one parameter, marked with
+<p>These intrinsics make it possible to excise one parameter, marked with
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
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)
+ call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
+ %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
%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>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a>
-</div>
+<h4>
+ <a name="int_it">
+ '<tt>llvm.init.trampoline</tt>' Intrinsic
+ </a>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
- declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
+ declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
</pre>
<h5>Overview:</h5>
-<p>This fills the memory pointed to by <tt>tramp</tt> with code and returns a
- function pointer suitable for executing it.</p>
+<p>This fills the memory pointed to by <tt>tramp</tt> with executable code,
+ turning it into a trampoline.</p>
<h5>Arguments:</h5>
<p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all
<h5>Semantics:</h5>
<p>The block of memory pointed to by <tt>tramp</tt> is filled with target
- dependent code, turning it into a function. A pointer to this function is
- returned, but needs to be bitcast to an <a href="#int_trampoline">appropriate
- function pointer type</a> before being called. The new function's signature
- is the same as that of <tt>func</tt> with any arguments marked with
- the <tt>nest</tt> attribute removed. At most one such <tt>nest</tt> argument
- is allowed, and it must be of pointer type. Calling the new function is
- equivalent to calling <tt>func</tt> with the same argument list, but
- with <tt>nval</tt> used for the missing <tt>nest</tt> argument. If, after
- calling <tt>llvm.init.trampoline</tt>, the memory pointed to
- by <tt>tramp</tt> is modified, then the effect of any later call to the
- returned function pointer is undefined.</p>
+ dependent code, turning it into a function. Then <tt>tramp</tt> needs to be
+ passed to <a href="#int_at">llvm.adjust.trampoline</a> to get a pointer
+ which can be <a href="#int_trampoline">bitcast (to a new function) and
+ called</a>. The new function's signature is the same as that of
+ <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute
+ removed. At most one such <tt>nest</tt> argument is allowed, and it must be of
+ pointer type. Calling the new function is equivalent to calling <tt>func</tt>
+ with the same argument list, but with <tt>nval</tt> used for the missing
+ <tt>nest</tt> argument. If, after calling <tt>llvm.init.trampoline</tt>, the
+ memory pointed to by <tt>tramp</tt> is modified, then the effect of any later call
+ to the returned function pointer is undefined.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="int_at">
+ '<tt>llvm.adjust.trampoline</tt>' Intrinsic
+ </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ declare i8* @llvm.adjust.trampoline(i8* <tramp>)
+</pre>
+
+<h5>Overview:</h5>
+<p>This performs any required machine-specific adjustment to the address of a
+ trampoline (passed as <tt>tramp</tt>).</p>
+
+<h5>Arguments:</h5>
+<p><tt>tramp</tt> must point to a block of memory which already has trampoline code
+ filled in by a previous call to <a href="#int_it"><tt>llvm.init.trampoline</tt>
+ </a>.</p>
+
+<h5>Semantics:</h5>
+<p>On some architectures the address of the code to be executed needs to be
+ different to the address where the trampoline is actually stored. This
+ intrinsic returns the executable address corresponding to <tt>tramp</tt>
+ after performing the required machine specific adjustments.
+ The pointer returned can then be <a href="#int_trampoline"> bitcast and
+ executed</a>.
+</p>
+
+</div>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_atomics">Atomic Operations and Synchronization Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>These intrinsic functions expand the "universal IR" of LLVM to represent
hardware constructs for atomic operations and memory synchronization. This
No one model or paradigm should be selected above others unless the hardware
itself ubiquitously does so.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_memory_barrier">'<tt>llvm.memory.barrier</tt>' Intrinsic</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<pre>
declare void @llvm.memory.barrier(i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, i1 <device>)
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, i1 true)
<i>; guarantee the above finishes</i>
store i32 8, %ptr <i>; before this begins</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_atomic_cmp_swap">'<tt>llvm.atomic.cmp.swap.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_atomic_swap">'<tt>llvm.atomic.swap.*</tt>' Intrinsic</a>
-</div>
-<div class="doc_text">
+</h4>
+
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_atomic_load_add">'<tt>llvm.atomic.load.add.*</tt>' Intrinsic</a>
+</h4>
-</div>
-
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_atomic_load_sub">'<tt>llvm.atomic.load.sub.*</tt>' Intrinsic</a>
+</h4>
-</div>
-
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_atomic_load_and">'<tt>llvm.atomic.load.and.*</tt>' Intrinsic</a><br>
- <a name="int_atomic_load_nand">'<tt>llvm.atomic.load.nand.*</tt>' Intrinsic</a><br>
- <a name="int_atomic_load_or">'<tt>llvm.atomic.load.or.*</tt>' Intrinsic</a><br>
- <a name="int_atomic_load_xor">'<tt>llvm.atomic.load.xor.*</tt>' Intrinsic</a><br>
-</div>
-
-<div class="doc_text">
+<h4>
+ <a name="int_atomic_load_and">
+ '<tt>llvm.atomic.load.and.*</tt>' Intrinsic
+ </a>
+ <br>
+ <a name="int_atomic_load_nand">
+ '<tt>llvm.atomic.load.nand.*</tt>' Intrinsic
+ </a>
+ <br>
+ <a name="int_atomic_load_or">
+ '<tt>llvm.atomic.load.or.*</tt>' Intrinsic
+ </a>
+ <br>
+ <a name="int_atomic_load_xor">
+ '<tt>llvm.atomic.load.xor.*</tt>' Intrinsic
+ </a>
+</h4>
+
+<div>
<h5>Syntax:</h5>
<p>These are overloaded intrinsics. You can
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="int_atomic_load_max">'<tt>llvm.atomic.load.max.*</tt>' Intrinsic</a><br>
- <a name="int_atomic_load_min">'<tt>llvm.atomic.load.min.*</tt>' Intrinsic</a><br>
- <a name="int_atomic_load_umax">'<tt>llvm.atomic.load.umax.*</tt>' Intrinsic</a><br>
- <a name="int_atomic_load_umin">'<tt>llvm.atomic.load.umin.*</tt>' Intrinsic</a><br>
-</div>
-
-<div class="doc_text">
+<h4>
+ <a name="int_atomic_load_max">
+ '<tt>llvm.atomic.load.max.*</tt>' Intrinsic
+ </a>
+ <br>
+ <a name="int_atomic_load_min">
+ '<tt>llvm.atomic.load.min.*</tt>' Intrinsic
+ </a>
+ <br>
+ <a name="int_atomic_load_umax">
+ '<tt>llvm.atomic.load.umax.*</tt>' Intrinsic
+ </a>
+ <br>
+ <a name="int_atomic_load_umin">
+ '<tt>llvm.atomic.load.umin.*</tt>' Intrinsic
+ </a>
+</h4>
+
+<div>
<h5>Syntax:</h5>
<p>These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>,
</div>
+</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_memorymarkers">Memory Use Markers</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<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">
+<h4>
<a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
- declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) readonly
+ declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
</pre>
<h5>Overview:</h5>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="int_general">General Intrinsics</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>This class of intrinsics is designed to be generic and has no specific
purpose.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_var_annotation">'<tt>llvm.var.annotation</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
<h5>Semantics:</h5>
<p>This intrinsic allows annotation of local variables with arbitrary strings.
This can be useful for special purpose optimizations that want to look for
- these annotations. These have no other defined use, they are ignored by code
+ these annotations. These have no other defined use; they are ignored by code
generation and optimization.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_annotation">'<tt>llvm.annotation.*</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on
<h5>Semantics:</h5>
<p>This intrinsic allows annotations to be put on arbitrary expressions with
arbitrary strings. This can be useful for special purpose optimizations that
- want to look for these annotations. These have no other defined use, they
+ want to look for these annotations. These have no other defined use; they
are ignored by code generation and optimization.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_trap">'<tt>llvm.trap</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
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">
+<h4>
<a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<h5>Syntax:</h5>
<pre>
</pre>
<h5>Overview:</h5>
-<p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information
- to the optimizers to discover at compile time either a) when an
- operation like memcpy will either overflow a buffer that corresponds to
- an object, or b) to determine that a runtime check for overflow isn't
- necessary. An object in this context means an allocation of a
- specific class, structure, array, or other object.</p>
+<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
+<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
+ 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>
+ 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>
+
+</div>
</div>
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
- <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff