<meta name="author" content="Chris Lattner">
<meta name="description"
content="LLVM Assembly Language Reference Manual.">
- <link rel="stylesheet" href="llvm.css" type="text/css">
+ <link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
<li><a href="#complexconstants">Complex Constants</a></li>
<li><a href="#globalconstants">Global Variable and Function Addresses</a></li>
<li><a href="#undefvalues">Undefined Values</a></li>
- <li><a href="#trapvalues">Trap Values</a></li>
+ <li><a href="#poisonvalues">Poison Values</a></li>
<li><a href="#blockaddress">Addresses of Basic Blocks</a></li>
<li><a href="#constantexprs">Constant Expressions</a></li>
</ol>
<li><a href="#metadata">Metadata Nodes and Metadata Strings</a>
<ol>
<li><a href="#tbaa">'<tt>tbaa</tt>' Metadata</a></li>
- <li><a href="#fpaccuracy">'<tt>fpaccuracy</tt>' Metadata</a></li>
+ <li><a href="#fpmath">'<tt>fpmath</tt>' Metadata</a></li>
+ <li><a href="#range">'<tt>range</tt>' Metadata</a></li>
</ol>
</li>
</ol>
</li>
+ <li><a href="#module_flags">Module Flags Metadata</a>
+ <ol>
+ <li><a href="#objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a></li>
+ </ol>
+ </li>
<li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
<ol>
<li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li>
<li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
<li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li>
<li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
- <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li>
<li><a href="#i_resume">'<tt>resume</tt>' Instruction</a></li>
<li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
</ol>
<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>
+ <li><a href="#int_fabs">'<tt>llvm.fabs.*</tt>' Intrinsic</a></li>
</ol>
</li>
<li><a href="#int_manip">Bit Manipulation Intrinsics</a>
<li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
</ol>
</li>
+ <li><a href="#spec_arithmetic">Specialised Arithmetic Intrinsics</a>
+ <ol>
+ <li><a href="#fmuladd">'<tt>llvm.fmuladd</tt> Intrinsic</a></li>
+ </ol>
+ </li>
<li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a>
<ol>
<li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li>
'<tt>llvm.annotation.*</tt>' Intrinsic</a></li>
<li><a href="#int_trap">
'<tt>llvm.trap</tt>' Intrinsic</a></li>
+ <li><a href="#int_debugtrap">
+ '<tt>llvm.debugtrap</tt>' Intrinsic</a></li>
<li><a href="#int_stackprotector">
'<tt>llvm.stackprotector</tt>' Intrinsic</a></li>
<li><a href="#int_objectsize">
<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,
- and symbol table entries. Modules may be combined together with the LLVM
- linker, which merges function (and global variable) definitions, resolves
- forward declarations, and merges symbol table entries. Here is an example of
- the "hello world" module:</p>
+<p>LLVM programs are composed of <tt>Module</tt>s, each of which is a
+ translation unit of the input programs. Each module consists of functions,
+ global variables, and symbol table entries. Modules may be combined together
+ with the LLVM linker, which merges function (and global variable)
+ definitions, resolves forward declarations, and merges symbol table
+ entries. Here is an example of the "hello world" module:</p>
<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>
+<a href="#identifiers">@.str</a> = <a href="#linkage_private">private</a> <a href="#globalvars">unnamed_addr</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00"
<i>; External declaration of the puts function</i>
-<a href="#functionstructure">declare</a> i32 @puts(i8*) <i>; i32 (i8*)* </i>
+<a href="#functionstructure">declare</a> i32 @puts(i8* <a href="#nocapture">nocapture</a>) <a href="#fnattrs">nounwind</a>
<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>
+ %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.str, i64 0, i64 0
<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_call">call</a> i32 @puts(i8* %cast210)
<a href="#i_ret">ret</a> i32 0
}
<i>; Named metadata</i>
-!1 = metadata !{i32 41}
+!1 = metadata !{i32 42}
!foo = !{!1, null}
</pre>
<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,
+ "<tt>.str</tt>", an external declaration of the "<tt>puts</tt>" function,
a <a href="#functionstructure">function definition</a> for
"<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a>
- "<tt>foo"</tt>.</p>
+ "<tt>foo</tt>".</p>
-<p>In general, a module is made up of a list of global values, where both
- functions and global variables are global values. Global values are
+<p>In general, a module is made up of a list of global values (where both
+ functions and global variables are global values). Global values are
represented by a pointer to a memory location (in this case, a pointer to an
array of char, and a pointer to a function), and have one of the
following <a href="#linkage">linkage types</a>.</p>
<p>Global variables define regions of memory allocated at compilation time
instead of run-time. Global variables may optionally be initialized, may
have an explicit section to be placed in, and may have an optional explicit
- alignment specified. A variable may be defined as "thread_local", which
+ alignment specified.</p>
+
+<p>A variable may be defined as <tt>thread_local</tt>, which
means that it will not be shared by threads (each thread will have a
- separated copy of the variable). A variable may be defined as a global
+ separated copy of the variable). Not all targets support thread-local
+ variables. Optionally, a TLS model may be specified:</p>
+
+<dl>
+ <dt><b><tt>localdynamic</tt></b>:</dt>
+ <dd>For variables that are only used within the current shared library.</dd>
+
+ <dt><b><tt>initialexec</tt></b>:</dt>
+ <dd>For variables in modules that will not be loaded dynamically.</dd>
+
+ <dt><b><tt>localexec</tt></b>:</dt>
+ <dd>For variables defined in the executable and only used within it.</dd>
+</dl>
+
+<p>The models correspond to the ELF TLS models; see
+ <a href="http://people.redhat.com/drepper/tls.pdf">ELF
+ Handling For Thread-Local Storage</a> for more information on under which
+ circumstances the different models may be used. The target may choose a
+ different TLS model if the specified model is not supported, or if a better
+ choice of model can be made.</p>
+
+<p>A variable may be defined as a global
"constant," which indicates that the contents of the variable
will <b>never</b> be modified (enabling better optimization, allowing the
global data to be placed in the read-only section of an executable, etc).
@G = addrspace(5) constant float 1.0, section "foo", align 4
</pre>
+<p>The following example defines a thread-local global with
+ the <tt>initialexec</tt> TLS model:</p>
+
+<pre class="doc_code">
+@G = thread_local(initialexec) global i32 0, align 4
+</pre>
+
</div>
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
+ modify the value in the caller. This attribute is only valid on LLVM
pointer arguments. It is generally used to pass structs and arrays by
value, but is also valid on pointers to scalars. The copy is considered
to belong to the caller not the callee (for example,
</pre>
<dl>
+ <dt><tt><b>address_safety</b></tt></dt>
+ <dd>This attribute indicates that the address safety analysis
+ is enabled for this function. </dd>
+
<dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt>
<dd>This attribute indicates that, when emitting the prologue and epilogue,
the backend should forcibly align the stack pointer. Specify the
It does not write through any pointer arguments
(including <tt><a href="#byval">byval</a></tt> arguments) and never
changes any state visible to callers. This means that it cannot unwind
- exceptions by calling the <tt>C++</tt> exception throwing methods, but
- could use the <tt>unwind</tt> instruction.</dd>
+ exceptions by calling the <tt>C++</tt> exception throwing methods.</dd>
<dt><tt><b><a name="readonly">readonly</a></b></tt></dt>
<dd>This attribute indicates that the function does not write through any
and read state that may be set in the caller. A readonly function always
returns the same value (or unwinds an exception identically) when called
with the same set of arguments and global state. It cannot unwind an
- exception by calling the <tt>C++</tt> exception throwing methods, but may
- use the <tt>unwind</tt> instruction.</dd>
+ exception by calling the <tt>C++</tt> exception throwing methods.</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>
<dt><tt><b><a name="ssp">ssp</a></b></tt></dt>
<dd>This attribute indicates that the function should emit a stack smashing
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>
<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="Atomics.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>
</tr>
<tr>
<td><a href="#t_floating">floating point</a></td>
- <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td>
+ <td><tt>half, float, double, x86_fp80, fp128, ppc_fp128</tt></td>
</tr>
<tr>
<td><a name="t_firstclass">first class</a></td>
<table>
<tbody>
<tr><th>Type</th><th>Description</th></tr>
+ <tr><td><tt>half</tt></td><td>16-bit floating point value</td></tr>
<tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
<tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
<tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr>
<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>, and <a href="#t_vector">vectors</a> are
- aggregate types.</p>
+ member types. <a href="#t_array">Arrays</a> and
+ <a href="#t_struct">structs</a> are aggregate types.
+ <a href="#t_vector">Vectors</a> are not considered to be aggregate types.</p>
</div>
represented in their IEEE hexadecimal format so that assembly and disassembly
do not cause any bits to change in the constants.</p>
-<p>When using the hexadecimal form, constants of types float and double are
+<p>When using the hexadecimal form, constants of types half, float, and double are
represented using the 16-digit form shown above (which matches the IEEE754
- representation for double); float values must, however, be exactly
- representable as IEE754 single precision. Hexadecimal format is always used
+ representation for double); half and float values must, however, be exactly
+ representable as IEE754 half and single precision, respectively.
+ Hexadecimal format is always used
for long double, and there are three forms of long double. The 80-bit format
used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits.
The 128-bit format used by PowerPC (two adjacent doubles) is represented
by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit format
is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no
currently supported target uses this format. Long doubles will only work if
- they match the long double format on your target. All hexadecimal formats
- are big-endian (sign bit at the left).</p>
+ they match the long double format on your target. The IEEE 16-bit format
+ (half precision) is represented by <tt>0xH</tt> followed by 4 hexadecimal
+ digits. All hexadecimal formats are big-endian (sign bit at the left).</p>
<p>There are no constants of type x86mmx.</p>
</div>
<!-- ======================================================================= -->
<h3>
- <a name="trapvalues">Trap Values</a>
+ <a name="poisonvalues">Poison 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
- fact that an instruction or constant expression which cannot evoke side
- effects has nevertheless detected a condition which results in undefined
- behavior.</p>
+<p>Poison values are similar to <a href="#undefvalues">undef values</a>, however
+ they also represent the fact that an instruction or constant expression which
+ cannot evoke side effects has nevertheless detected a condition which results
+ in undefined behavior.</p>
-<p>There is currently no way of representing a trap value in the IR; they
+<p>There is currently no way of representing a poison value in the IR; they
only exist when produced by operations such as
<a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p>
-<p>Trap value behavior is defined in terms of value <i>dependence</i>:</p>
+<p>Poison value behavior is defined in terms of value <i>dependence</i>:</p>
<ul>
<li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
control back to them.</li>
<li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the
- <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_unwind"><tt>unwind</tt></a>,
+ <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_resume"><tt>resume</tt></a>,
or exception-throwing call instructions that dynamically transfer control
back to them.</li>
</ul>
-<p>Whenever a trap value is generated, all values which depend on it evaluate
- 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>Poison Values have the same behavior as <a href="#undefvalues">undef values</a>,
+ with the additional affect that any instruction which has a <i>dependence</i>
+ on a poison value has undefined behavior.</p>
<p>Here are some examples:</p>
<pre class="doc_code">
entry:
- %trap = sub nuw i32 0, 1 ; Results in a trap value.
- %still_trap = and i32 %trap, 0 ; Whereas (and i32 undef, 0) would return 0.
- %trap_yet_again = getelementptr i32* @h, i32 %still_trap
- store i32 0, i32* %trap_yet_again ; undefined behavior
+ %poison = sub nuw i32 0, 1 ; Results in a poison value.
+ %still_poison = and i32 %poison, 0 ; 0, but also poison.
+ %poison_yet_again = getelementptr i32* @h, i32 %still_poison
+ store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned
- store i32 %trap, i32* @g ; Trap value conceptually stored to memory.
- %trap2 = load i32* @g ; Returns a trap value, not just undef.
+ store i32 %poison, i32* @g ; Poison value stored to memory.
+ %poison2 = load i32* @g ; Poison value loaded back from memory.
- store volatile i32 %trap, i32* @g ; External observation; undefined behavior.
+ store volatile i32 %poison, i32* @g ; External observation; undefined behavior.
%narrowaddr = bitcast i32* @g to i16*
%wideaddr = bitcast i32* @g to i64*
- %trap3 = load i16* %narrowaddr ; Returns a trap value.
- %trap4 = load i64* %wideaddr ; Returns a trap value.
+ %poison3 = load i16* %narrowaddr ; Returns a poison value.
+ %poison4 = load i64* %wideaddr ; Returns a poison value.
- %cmp = icmp slt i32 %trap, 0 ; Returns a trap value.
- br i1 %cmp, label %true, label %end ; Branch to either destination.
+ %cmp = icmp slt i32 %poison, 0 ; Returns a poison value.
+ br i1 %cmp, label %true, label %end ; Branch to either destination.
true:
- store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so
- ; it has undefined behavior.
+ store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so
+ ; it has undefined behavior.
br label %end
end:
%p = phi i32 [ 0, %entry ], [ 1, %true ]
- ; Both edges into this PHI are
- ; control-dependent on %cmp, so this
- ; always results in a trap value.
+ ; Both edges into this PHI are
+ ; control-dependent on %cmp, so this
+ ; always results in a poison value.
- store volatile 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.
+ store volatile 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.
+ ; The same branch again, but this time the
+ ; true block doesn't have side effects.
second_true:
; No side effects!
ret void
second_end:
- store volatile 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).
+ store volatile 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 (ignoring earlier undefined
+ ; behavior in this example).
</pre>
</div>
<!-- _______________________________________________________________________ -->
<h4>
- <a name="fpaccuracy">'<tt>fpaccuracy</tt>' Metadata</a>
+ <a name="fpmath">'<tt>fpmath</tt>' Metadata</a>
</h4>
<div>
-<p><tt>fpaccuracy</tt> metadata may be attached to any instruction of floating
- point type. It expresses the maximum relative error of the result of
- that instruction, in ULPs. ULP is defined as follows:</p>
+<p><tt>fpmath</tt> metadata may be attached to any instruction of floating point
+ type. It can be used to express the maximum acceptable error in the result of
+ that instruction, in ULPs, thus potentially allowing the compiler to use a
+ more efficient but less accurate method of computing it. ULP is defined as
+ follows:</p>
<blockquote>
</blockquote>
-<p>The maximum relative error may be any rational number. The metadata node
- shall consist of a pair of unsigned integers respectively representing
- the numerator and denominator. For example, 2.5 ULP:</p>
+<p>The metadata node shall consist of a single positive floating point number
+ representing the maximum relative error, for example:</p>
<div class="doc_code">
<pre>
-!0 = metadata !{ i32 5, i32 2 }
+!0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
</pre>
</div>
</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="range">'<tt>range</tt>' Metadata</a>
+</h4>
+
+<div>
+<p><tt>range</tt> metadata may be attached only to loads of integer types. It
+ expresses the possible ranges the loaded value is in. The ranges are
+ represented with a flattened list of integers. The loaded value is known to
+ be in the union of the ranges defined by each consecutive pair. Each pair
+ has the following properties:</p>
+<ul>
+ <li>The type must match the type loaded by the instruction.</li>
+ <li>The pair <tt>a,b</tt> represents the range <tt>[a,b)</tt>.</li>
+ <li>Both <tt>a</tt> and <tt>b</tt> are constants.</li>
+ <li>The range is allowed to wrap.</li>
+ <li>The range should not represent the full or empty set. That is,
+ <tt>a!=b</tt>. </li>
+</ul>
+<p> In addition, the pairs must be in signed order of the lower bound and
+ they must be non-contiguous.</p>
+
+<p>Examples:</p>
+<div class="doc_code">
+<pre>
+ %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
+ %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
+ %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
+ %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5
+...
+!0 = metadata !{ i8 0, i8 2 }
+!1 = metadata !{ i8 255, i8 2 }
+!2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
+!3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
+</pre>
+</div>
+</div>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="module_flags">Module Flags Metadata</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Information about the module as a whole is difficult to convey to LLVM's
+ subsystems. The LLVM IR isn't sufficient to transmit this
+ information. The <tt>llvm.module.flags</tt> named metadata exists in order to
+ facilitate this. These flags are in the form of key / value pairs —
+ much like a dictionary — making it easy for any subsystem who cares
+ about a flag to look it up.</p>
+
+<p>The <tt>llvm.module.flags</tt> metadata contains a list of metadata
+ triplets. Each triplet has the following form:</p>
+
+<ul>
+ <li>The first element is a <i>behavior</i> flag, which specifies the behavior
+ when two (or more) modules are merged together, and it encounters two (or
+ more) metadata with the same ID. The supported behaviors are described
+ below.</li>
+
+ <li>The second element is a metadata string that is a unique ID for the
+ metadata. How each ID is interpreted is documented below.</li>
+
+ <li>The third element is the value of the flag.</li>
+</ul>
+
+<p>When two (or more) modules are merged together, the resulting
+ <tt>llvm.module.flags</tt> metadata is the union of the
+ modules' <tt>llvm.module.flags</tt> metadata. The only exception being a flag
+ with the <i>Override</i> behavior, which may override another flag's value
+ (see below).</p>
+
+<p>The following behaviors are supported:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+ <tbody>
+ <tr>
+ <th>Value</th>
+ <th>Behavior</th>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td align="left">
+ <dl>
+ <dt><b>Error</b></dt>
+ <dd>Emits an error if two values disagree. It is an error to have an ID
+ with both an Error and a Warning behavior.</dd>
+ </dl>
+ </td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td align="left">
+ <dl>
+ <dt><b>Warning</b></dt>
+ <dd>Emits a warning if two values disagree.</dd>
+ </dl>
+ </td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td align="left">
+ <dl>
+ <dt><b>Require</b></dt>
+ <dd>Emits an error when the specified value is not present or doesn't
+ have the specified value. It is an error for two (or more)
+ <tt>llvm.module.flags</tt> with the same ID to have the Require
+ behavior but different values. There may be multiple Require flags
+ per ID.</dd>
+ </dl>
+ </td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td align="left">
+ <dl>
+ <dt><b>Override</b></dt>
+ <dd>Uses the specified value if the two values disagree. It is an
+ error for two (or more) <tt>llvm.module.flags</tt> with the same
+ ID to have the Override behavior but different values.</dd>
+ </dl>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>An example of module flags:</p>
+
+<pre class="doc_code">
+!0 = metadata !{ i32 1, metadata !"foo", i32 1 }
+!1 = metadata !{ i32 4, metadata !"bar", i32 37 }
+!2 = metadata !{ i32 2, metadata !"qux", i32 42 }
+!3 = metadata !{ i32 3, metadata !"qux",
+ metadata !{
+ metadata !"foo", i32 1
+ }
+}
+!llvm.module.flags = !{ !0, !1, !2, !3 }
+</pre>
+
+<ul>
+ <li><p>Metadata <tt>!0</tt> has the ID <tt>!"foo"</tt> and the value '1'. The
+ behavior if two or more <tt>!"foo"</tt> flags are seen is to emit an
+ error if their values are not equal.</p></li>
+
+ <li><p>Metadata <tt>!1</tt> has the ID <tt>!"bar"</tt> and the value '37'. The
+ behavior if two or more <tt>!"bar"</tt> flags are seen is to use the
+ value '37' if their values are not equal.</p></li>
+
+ <li><p>Metadata <tt>!2</tt> has the ID <tt>!"qux"</tt> and the value '42'. The
+ behavior if two or more <tt>!"qux"</tt> flags are seen is to emit a
+ warning if their values are not equal.</p></li>
+
+ <li><p>Metadata <tt>!3</tt> has the ID <tt>!"qux"</tt> and the value:</p>
+
+<pre class="doc_code">
+metadata !{ metadata !"foo", i32 1 }
+</pre>
+
+ <p>The behavior is to emit an error if the <tt>llvm.module.flags</tt> does
+ not contain a flag with the ID <tt>!"foo"</tt> that has the value
+ '1'. If two or more <tt>!"qux"</tt> flags exist, then they must have
+ the same value or an error will be issued.</p></li>
+</ul>
+
+
+<!-- ======================================================================= -->
+<h3>
+<a name="objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a>
+</h3>
+
+<div>
+
+<p>On the Mach-O platform, Objective-C stores metadata about garbage collection
+ in a special section called "image info". The metadata consists of a version
+ number and a bitmask specifying what types of garbage collection are
+ supported (if any) by the file. If two or more modules are linked together
+ their garbage collection metadata needs to be merged rather than appended
+ together.</p>
+
+<p>The Objective-C garbage collection module flags metadata consists of the
+ following key-value pairs:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+ <col width="30%">
+ <tbody>
+ <tr>
+ <th>Key</th>
+ <th>Value</th>
+ </tr>
+ <tr>
+ <td><tt>Objective-C Version</tt></td>
+ <td align="left"><b>[Required]</b> — The Objective-C ABI
+ version. Valid values are 1 and 2.</td>
+ </tr>
+ <tr>
+ <td><tt>Objective-C Image Info Version</tt></td>
+ <td align="left"><b>[Required]</b> — The version of the image info
+ section. Currently always 0.</td>
+ </tr>
+ <tr>
+ <td><tt>Objective-C Image Info Section</tt></td>
+ <td align="left"><b>[Required]</b> — The section to place the
+ metadata. Valid values are <tt>"__OBJC, __image_info, regular"</tt> for
+ Objective-C ABI version 1, and <tt>"__DATA,__objc_imageinfo, regular,
+ no_dead_strip"</tt> for Objective-C ABI version 2.</td>
+ </tr>
+ <tr>
+ <td><tt>Objective-C Garbage Collection</tt></td>
+ <td align="left"><b>[Required]</b> — Specifies whether garbage
+ collection is supported or not. Valid values are 0, for no garbage
+ collection, and 2, for garbage collection supported.</td>
+ </tr>
+ <tr>
+ <td><tt>Objective-C GC Only</tt></td>
+ <td align="left"><b>[Optional]</b> — Specifies that only garbage
+ collection is supported. If present, its value must be 6. This flag
+ requires that the <tt>Objective-C Garbage Collection</tt> flag have the
+ value 2.</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>Some important flag interactions:</p>
+
+<ul>
+ <li>If a module with <tt>Objective-C Garbage Collection</tt> set to 0 is
+ merged with a module with <tt>Objective-C Garbage Collection</tt> set to
+ 2, then the resulting module has the <tt>Objective-C Garbage
+ Collection</tt> flag set to 0.</li>
+
+ <li>A module with <tt>Objective-C Garbage Collection</tt> set to 0 cannot be
+ merged with a module with <tt>Objective-C GC Only</tt> set to 6.</li>
+</ul>
+
</div>
</div>
'<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>
'<tt>normal</tt>' label or the '<tt>exception</tt>' label. If the callee
function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction,
control flow will return to the "normal" label. If the callee (or any
- indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>"
- instruction, control is interrupted and continued at the dynamically nearest
- "exception" label.</p>
+ indirect callees) returns via the "<a href="#i_resume"><tt>resume</tt></a>"
+ instruction or other exception handling mechanism, 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
+ the information 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
<li>'<tt>normal label</tt>': the label reached when the called function
executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
- <li>'<tt>exception label</tt>': the label reached when a callee returns with
- the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
+ <li>'<tt>exception label</tt>': the label reached when a callee returns via
+ the <a href="#i_resume"><tt>resume</tt></a> instruction or other exception
+ handling mechanism.</li>
<li>The optional <a href="#fnattrs">function attributes</a> list. Only
'<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
block to the "normal" label. If the callee unwinds then no return value is
available.</p>
-<p>Note that the code generator does not yet completely support unwind, and
-that the invoke/unwind semantics are likely to change in future versions.</p>
-
<h5>Example:</h5>
<pre>
%retval = invoke i32 @Test(i32 15) to label %Continue
unwind label %TestCleanup <i>; {i32}:retval set</i>
</pre>
-</div>
-
-<!-- _______________________________________________________________________ -->
-
-<h4>
- <a name="i_unwind">'<tt>unwind</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- unwind
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
- at the first callee in the dynamic call stack which used
- an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call.
- This is primarily used to implement exception handling.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>unwind</tt>' instruction causes execution of the current function to
- immediately halt. The dynamic call stack is then searched for the
- first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack.
- Once found, execution continues at the "exceptional" destination block
- specified by the <tt>invoke</tt> instruction. If there is no <tt>invoke</tt>
- instruction in the dynamic call chain, undefined behavior results.</p>
-
-<p>Note that the code generator does not yet completely support unwind, and
-that the invoke/unwind semantics are likely to change in future versions.</p>
-
</div>
<!-- _______________________________________________________________________ -->
<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
<tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
- is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
+ is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
respectively, occurs.</p>
<h5>Example:</h5>
<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
<tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
- is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
+ is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
respectively, occurs.</p>
<h5>Example:</h5>
<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
<tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
- is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
+ is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
respectively, occurs.</p>
<h5>Example:</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
+ <tt>udiv</tt> is a <a href="#poisonvalues">poison value</a> if %op1 is not a
multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p>
a 32-bit division of -2147483648 by -1.</p>
<p>If the <tt>exact</tt> keyword is present, the result value of the
- <tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would
+ <tt>sdiv</tt> is a <a href="#poisonvalues">poison value</a> if the result would
be rounded.</p>
<h5>Example:</h5>
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
+ <a href="#poisonvalues">poison 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
+ <a href="#poisonvalues">poison 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>
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
+ <tt>lshr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits
shifted out are non-zero.</p>
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
+ <tt>ashr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits
shifted out are non-zero.</p>
<h5>Example:</h5>
<table border="1" cellspacing="0" cellpadding="4">
<tbody>
<tr>
- <td>In0</td>
- <td>In1</td>
- <td>Out</td>
+ <th>In0</th>
+ <th>In1</th>
+ <th>Out</th>
</tr>
<tr>
<td>0</td>
<table border="1" cellspacing="0" cellpadding="4">
<tbody>
<tr>
- <td>In0</td>
- <td>In1</td>
- <td>Out</td>
+ <th>In0</th>
+ <th>In1</th>
+ <th>Out</th>
</tr>
<tr>
<td>0</td>
<table border="1" cellspacing="0" cellpadding="4">
<tbody>
<tr>
- <td>In0</td>
- <td>In1</td>
- <td>Out</td>
+ <th>In0</th>
+ <th>In1</th>
+ <th>Out</th>
</tr>
<tr>
<td>0</td>
<h5>Arguments:</h5>
<p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
- with types that match each other. The third argument is a shuffle mask whose
+ with the same type. The third argument is a shuffle mask whose
element type is always 'i32'. The result of the instruction is a vector
whose length is the same as the shuffle mask and whose element type is the
same as the element type of the first two operands.</p>
'<tt>alloca</tt>' instruction is commonly used to represent automatic
variables that must have an address available. When the function returns
(either with the <tt><a href="#i_ret">ret</a></tt>
- or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is
- reclaimed. Allocating zero bytes is legal, but the result is undefined.</p>
+ or <tt><a href="#i_resume">resume</a></tt> instructions), the memory is
+ reclaimed. Allocating zero bytes is legal, but the result is undefined.
+ The order in which memory is allocated (ie., which way the stack grows) is
+ not specified.</p>
+
+<p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
- <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>]
<result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
!<index> = !{ i32 1 }
</pre>
The code generator may select special instructions to save cache bandwidth,
such as the <tt>MOVNT</tt> instruction on x86.</p>
+<p>The optional <tt>!invariant.load</tt> metadata must reference a single
+ metatadata name <index> corresponding to a metadata node with no
+ entries. The existence of the <tt>!invariant.load</tt> metatadata on the
+ instruction tells the optimizer and code generator that this load address
+ points to memory which does not change value during program execution.
+ The optimizer may then move this load around, for example, by hoisting it
+ out of loops using loop invariant code motion.</p>
+
<h5>Semantics:</h5>
<p>The location of memory pointed to is loaded. If the value being loaded is of
scalar type then the number of bytes read does not exceed the minimum number
<h5>Syntax:</h5>
<pre>
- store [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>
+ 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>
<h5>Syntax:</h5>
<pre>
- cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i>
+ cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i>
</pre>
<h5>Overview:</h5>
<h5>Example:</h5>
<pre>
entry:
- %orig = atomic <a href="#i_load">load</a> i32* %ptr unordered <i>; yields {i32}</i>
+ %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>
+ %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
}
</pre>
-<p>The LLVM code generated by the GCC frontend is:</p>
+<p>The LLVM code generated by Clang is:</p>
<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 }
+%struct.RT = <a href="#namedtypes">type</a> { i8, [10 x [20 x i32]], i8 }
+%struct.ST = <a href="#namedtypes">type</a> { i32, double, %struct.RT }
-define i32* @foo(%ST* %s) {
+define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp {
entry:
- %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
- ret i32* %reg
+ %arrayidx = getelementptr inbounds %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13
+ ret i32* %arrayidx
}
</pre>
<h5>Semantics:</h5>
-<p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
- type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT
- }</tt>' type, a structure. The second index indexes into the third element
- of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]],
- i8 }</tt>' type, another structure. The third index indexes into the second
- element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an
- array. The two dimensions of the array are subscripted into, yielding an
- '<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a
- pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p>
+<p>In the example above, the first index is indexing into the
+ '<tt>%struct.ST*</tt>' type, which is a pointer, yielding a
+ '<tt>%struct.ST</tt>' = '<tt>{ i32, double, %struct.RT }</tt>' type, a
+ structure. The second index indexes into the third element of the structure,
+ yielding a '<tt>%struct.RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], i8 }</tt>'
+ type, another structure. The third index indexes into the second element of
+ the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an array. The
+ two dimensions of the array are subscripted into, yielding an '<tt>i32</tt>'
+ type. The '<tt>getelementptr</tt>' instruction returns a pointer to this
+ element, thus computing a value of '<tt>i32*</tt>' type.</p>
<p>Note that it is perfectly legal to index partially through a structure,
returning a pointer to an inner element. Because of this, the LLVM code for
the given testcase is equivalent to:</p>
-<pre>
- define i32* @foo(%ST* %s) {
- %t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i>
- %t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i>
- %t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i>
- %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i>
- %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i>
- ret i32* %t5
- }
+<pre class="doc_code">
+define i32* @foo(%struct.ST* %s) {
+ %t1 = getelementptr %struct.ST* %s, i32 1 <i>; yields %struct.ST*:%t1</i>
+ %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2 <i>; yields %struct.RT*:%t2</i>
+ %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i>
+ %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i>
+ %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i>
+ ret i32* %t5
+}
</pre>
<p>If the <tt>inbounds</tt> keyword is present, the result value of the
- <tt>getelementptr</tt> is a <a href="#trapvalues">trap value</a> if the
+ <tt>getelementptr</tt> is a <a href="#poisonvalues">poison value</a> if the
base pointer is not an <i>in bounds</i> address of an allocated object,
or if any of the addresses that would be formed by successive addition of
the offsets implied by the indices to the base address with infinitely
%X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i>
</pre>
-<p>Note that the code generator does not yet support conditions
- with vector type.</p>
-
</div>
<!-- _______________________________________________________________________ -->
<h5>Syntax:</h5>
<pre>
- <resultval> = landingpad <somety> personality <type> <pers_fn> <clause>+
- <resultval> = landingpad <somety> personality <type> <pers_fn> cleanup <clause>*
+ <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+
+ <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>*
<clause> := catch <type> <value>
<clause> := filter <array constant type> <array constant>
<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>
+ type <tt>resultty</tt>.</p>
<h5>Arguments:</h5>
<p>This instruction takes a <tt>pers_fn</tt> value. This is the personality
<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>
+ clauses from the calling function are appended to the list of clauses.
+ When the call stack is being unwound due to an exception being thrown, the
+ exception is compared against each <tt>clause</tt> in turn. If it doesn't
+ match any of the clauses, and the <tt>cleanup</tt> flag is not set, then
+ unwinding continues further up the call stack.</p>
<p>The <tt>landingpad</tt> instruction has several restrictions:</p>
</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="int_fabs">'<tt>llvm.fabs.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.fabs</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.</p>
+
+<pre>
+ declare float @llvm.fabs.f32(float %Val)
+ declare double @llvm.fabs.f64(double %Val)
+ declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val)
+ declare fp128 @llvm.fabs.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.fabs.*</tt>' intrinsics return the absolute value of
+ the operand.</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>fabs</tt> functions
+ would, and handles error conditions in the same way.</p>
+
+</div>
+
</div>
<!-- ======================================================================= -->
targets support all bit widths or vector types, however.</p>
<pre>
- declare i8 @llvm.ctlz.i8 (i8 <src>)
- declare i16 @llvm.ctlz.i16(i16 <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)
+ declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>)
+ declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>)
+ declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>)
+ declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>)
+ declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
+ declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
</pre>
<h5>Overview:</h5>
leading zeros in a variable.</p>
<h5>Arguments:</h5>
-<p>The only argument is the value to be counted. The argument may be of any
- integer type, or any vector type with integer element type.
- The return type must match the argument type.</p>
+<p>The first argument is the value to be counted. This argument may be of any
+ integer type, or a vectory with integer element type. The return type
+ must match the first argument type.</p>
+
+<p>The second argument must be a constant and is a flag to indicate whether the
+ intrinsic should ensure that a zero as the first argument produces a defined
+ result. Historically some architectures did not provide a defined result for
+ zero values as efficiently, and many algorithms are now predicated on
+ avoiding zero-value inputs.</p>
<h5>Semantics:</h5>
<p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant)
- 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>
+ zeros in a variable, or within each element of the vector.
+ If <tt>src == 0</tt> then the result is the size in bits of the type of
+ <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise.
+ For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p>
</div>
support all bit widths or vector types, however.</p>
<pre>
- declare i8 @llvm.cttz.i8 (i8 <src>)
- declare i16 @llvm.cttz.i16(i16 <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>)
+ declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>)
+ declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>)
+ declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>)
+ declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>)
+ declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
+ declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
</pre>
<h5>Overview:</h5>
trailing zeros.</p>
<h5>Arguments:</h5>
-<p>The only argument is the value to be counted. The argument may be of any
- integer type, or a vectory with integer element type.. The return type
- must match the argument type.</p>
+<p>The first argument is the value to be counted. This argument may be of any
+ integer type, or a vectory with integer element type. The return type
+ must match the first argument type.</p>
+
+<p>The second argument must be a constant and is a flag to indicate whether the
+ intrinsic should ensure that a zero as the first argument produces a defined
+ result. Historically some architectures did not provide a defined result for
+ zero values as efficiently, and many algorithms are now predicated on
+ avoiding zero-value inputs.</p>
<h5>Semantics:</h5>
<p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant)
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>
+ If <tt>src == 0</tt> then the result is the size in bits of the type of
+ <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise.
+ For example, <tt>llvm.cttz(2) = 1</tt>.</p>
</div>
</div>
+<!-- ======================================================================= -->
+<h3>
+ <a name="spec_arithmetic">Specialised Arithmetic Intrinsics</a>
+</h3>
+
+<!-- _______________________________________________________________________ -->
+
+<h4>
+ <a name="fmuladd">'<tt>llvm.fmuladd.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
+ declare double @llvm.fmuladd.f64(double %a, double %b, double %c)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.fmuladd.*</tt>' intrinsic functions represent multiply-add
+expressions that can be fused if the code generator determines that the fused
+expression would be legal and efficient.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>llvm.fmuladd.*</tt>' intrinsics each take three arguments: two
+multiplicands, a and b, and an addend c.</p>
+
+<h5>Semantics:</h5>
+<p>The expression:</p>
+<pre>
+ %0 = call float @llvm.fmuladd.f32(%a, %b, %c)
+</pre>
+<p>is equivalent to the expression a * b + c, except that rounding will not be
+performed between the multiplication and addition steps if the code generator
+fuses the operations. Fusion is not guaranteed, even if the target platform
+supports it. If a fused multiply-add is required the corresponding llvm.fma.*
+intrinsic function should be used instead.</p>
+
+<h5>Examples:</h5>
+<pre>
+ %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields {float}:r2 = (a * b) + c
+</pre>
+
+</div>
+
<!-- ======================================================================= -->
<h3>
<a name="int_fp16">Half Precision Floating Point Intrinsics</a>
<div>
-<p>Half precision floating point is a storage-only format. This means that it is
+<p>For most target platforms, half precision floating point is a storage-only
+ format. This means that it is
a dense encoding (in memory) but does not support computation in the
format.</p>
<h5>Syntax:</h5>
<pre>
- declare void @llvm.trap()
+ declare void @llvm.trap() noreturn nounwind
</pre>
<h5>Overview:</h5>
<p>None.</p>
<h5>Semantics:</h5>
-<p>This intrinsics is lowered to the target dependent trap instruction. If the
+<p>This intrinsic is lowered to the target dependent trap instruction. If the
target does not have a trap instruction, this intrinsic will be lowered to
- the call of the <tt>abort()</tt> function.</p>
+ a call of the <tt>abort()</tt> function.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="int_debugtrap">'<tt>llvm.debugtrap</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ declare void @llvm.debugtrap() nounwind
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.debugtrap</tt>' intrinsic.</p>
+
+<h5>Arguments:</h5>
+<p>None.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic is lowered to code which is intended to cause an execution
+ trap with the intention of requesting the attention of a debugger.</p>
</div>
<h5>Syntax:</h5>
<pre>
- declare i32 @llvm.objectsize.i32(i8* <object>, i1 <type>)
- declare i64 @llvm.objectsize.i64(i8* <object>, i1 <type>)
+ declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>)
+ declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>)
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
<p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments. The first
argument is a pointer to or into the <tt>object</tt>. The second argument
- is a boolean 0 or 1. This argument determines whether you want the
- maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or
- 1, variables are not allowed.</p>
+ is a boolean and determines whether <tt>llvm.objectsize</tt> returns 0 (if
+ true) or -1 (if false) when the object size is unknown.
+ The second argument only accepts constants.</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>
+<p>The <tt>llvm.objectsize</tt> intrinsic is lowered to a constant representing
+ the size of the object concerned. If the size cannot be determined at compile
+ time, <tt>llvm.objectsize</tt> returns <tt>i32/i64 -1 or 0</tt>
+ (depending on the <tt>min</tt> argument).</p>
</div>
<!-- _______________________________________________________________________ -->
projects / oota-llvm.git / blobdiff