<ol>
<li><a href="#modulestructure">Module Structure</a></li>
<li><a href="#linkage">Linkage Types</a></li>
+ <li><a href="#callingconv">Calling Conventions</a></li>
<li><a href="#globalvars">Global Variables</a></li>
<li><a href="#functionstructure">Function Structure</a></li>
</ol>
<li><a href="#t_pointer">Pointer Type</a></li>
<li><a href="#t_struct">Structure Type</a></li>
<li><a href="#t_packed">Packed Type</a></li>
+ <li><a href="#t_opaque">Opaque Type</a></li>
</ol>
</li>
</ol>
</li>
<li><a href="#constants">Constants</a>
+ <ol>
+ <li><a href="#simpleconstants">Simple Constants</a>
+ <li><a href="#aggregateconstants">Aggregate Constants</a>
+ <li><a href="#globalconstants">Global Variable and Function Addresses</a>
+ <li><a href="#undefvalues">Undefined Values</a>
+ <li><a href="#constantexprs">Constant Expressions</a>
+ </ol>
</li>
<li><a href="#instref">Instruction Reference</a>
<ol>
<li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a></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_vanext">'<tt>vanext</tt>' Instruction</a></li>
<li><a href="#i_vaarg">'<tt>vaarg</tt>' Instruction</a></li>
</ol>
</li>
<ol>
<li><a href="#i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
<li><a href="#i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li>
+ <li><a href="#i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
+ <li><a href="#i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
</ol>
</li>
<li><a href="#int_os">Operating System Intrinsics</a>
<li><a href="#i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a></li>
<li><a href="#i_memset">'<tt>llvm.memset</tt>' Intrinsic</a></li>
<li><a href="#i_isunordered">'<tt>llvm.isunordered</tt>' Intrinsic</a></li>
+ <li><a href="#i_sqrt">'<tt>llvm.sqrt</tt>' Intrinsic</a></li>
+
+ </ol>
+ </li>
+ <li><a href="#int_count">Bit counting Intrinsics</a>
+ <ol>
+ <li><a href="#int_ctpop">'<tt>llvm.ctpop</tt>' Intrinsic </a></li>
+ <li><a href="#int_ctlz">'<tt>llvm.ctlz</tt>' Intrinsic </a></li>
+ <li><a href="#int_cttz">'<tt>llvm.cttz</tt>' Intrinsic </a></li>
</ol>
</li>
<li><a href="#int_debugger">Debugger intrinsics</a></li>
of LLVM are all equivalent. This document describes the human readable
representation and notation.</p>
-<p>The LLVM representation aims to be a light-weight and low-level
+<p>The LLVM representation aims to be light-weight and low-level
while being expressive, typed, and extensible at the same time. It
aims to be a "universal IR" of sorts, by being at a low enough level
that high-level ideas may be cleanly mapped to it (similar to how
<p>...because the definition of <tt>%x</tt> does not dominate all of
its uses. The LLVM infrastructure provides a verification pass that may
be used to verify that an LLVM module is well formed. This pass is
-automatically run by the parser after parsing input assembly, and by
+automatically run by the parser after parsing input assembly and by
the optimizer before it outputs bytecode. The violations pointed out
by the verifier pass indicate bugs in transformation passes or input to
the parser.</p>
purposes:</p>
<ol>
- <li>Numeric constants are represented as you would expect: 12, -3 123.421,
- etc. Floating point constants have an optional hexadecimal notation.</li>
-
<li>Named values are represented as a string of characters with a '%' prefix.
For example, %foo, %DivisionByZero, %a.really.long.identifier. The actual
regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
<li>Unnamed values are represented as an unsigned numeric value with a '%'
prefix. For example, %12, %2, %44.</li>
+ <li>Constants, which are described in a <a href="#constants">section about
+ constants</a>, below.</li>
</ol>
<p>LLVM requires that values start with a '%' sign for two reasons: Compilers
</ol>
-<p>...and it also show a convention that we follow in this document. When
+<p>...and it also shows a convention that we follow in this document. When
demonstrating instructions, we will follow an instruction with a comment that
defines the type and name of value produced. Comments are shown in italic
text.</p>
-<p>The one non-intuitive notation for constants is the optional hexidecimal form
-of floating point constants. For example, the form '<tt>double
-0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
-4.5e+15</tt>' which is also supported by the parser. The only time hexadecimal
-floating point constants are useful (and the only time that they are generated
-by the disassembler) is when an FP constant has to be emitted that is not
-representable as a decimal floating point number exactly. For example, NaN's,
-infinities, and other special cases are represented in their IEEE hexadecimal
-format so that assembly and disassembly do not cause any bits to change in the
-constants.</p>
</div>
<!-- *********************************************************************** -->
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="callingconv">Calling Conventions</a>
+</div>
+
+<div class="doc_text">
+
+<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 convention
+specified for the call. The calling convention of any pair of dynamic
+caller/callee must match, or the behavior of the program is undefined. The
+following calling conventions are supported by LLVM, and more may be added in
+the future:</p>
+
+<dl>
+ <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
+
+ <dd>This calling convention (the default if no other calling convention is
+ specified) matches the target C calling conventions. This calling convention
+ supports varargs function calls and tolerates some mismatch in the declared
+ prototype and implemented declaration of the function (as does normal C).
+ </dd>
+
+ <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
+
+ <dd>This calling convention attempts to make calls as fast as possible
+ (e.g. by passing things in registers). This calling convention allows the
+ target to use whatever tricks it wants to produce fast code for the target,
+ without having to conform to an externally specified ABI. Implementations of
+ this convention should allow arbitrary tail call optimization to be supported.
+ This calling convention does not support varargs and requires the prototype of
+ all callees to exactly match the prototype of the function definition.
+ </dd>
+
+ <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
+
+ <dd>This calling convention attempts to make code in the caller as efficient
+ as possible under the assumption that the call is not commonly executed. As
+ such, these calls often preserve all registers so that the call does not break
+ any live ranges in the caller side. This calling convention does not support
+ varargs and requires the prototype of all callees to exactly match the
+ prototype of the function definition.
+ </dd>
+
+ <dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt>
+
+ <dd>Any calling convention may be specified by number, allowing
+ target-specific calling conventions to be used. Target specific calling
+ conventions start at 64.
+ </dd>
+</dl>
+
+<p>More calling conventions can be added/defined on an as-needed basis, to
+support pascal conventions or any other well-known target-independent
+convention.</p>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="globalvars">Global Variables</a>
<div class="doc_text">
-<p>Global variables define regions of memory allocated at compilation
-time instead of run-time. Global variables may optionally be
-initialized. A variable may be defined as a global "constant", which
-indicates that the contents of the variable will never be modified
-(enabling better optimization, allowing the global data to be placed in the
-read-only section of an executable, etc).</p>
+<p>Global variables define regions of memory allocated at compilation time
+instead of run-time. Global variables may optionally be initialized. 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). Note that variables that need runtime initialization
+cannot be marked "constant", as there is a store to the variable.</p>
+
+<p>
+LLVM explicitly allows <em>declarations</em> of global variables to be marked
+constant, even if the final definition of the global is not. This capability
+can be used to enable slightly better optimization of the program, but requires
+the language definition to guarantee that optimizations based on the
+'constantness' are valid for the translation units that do not include the
+definition.
+</p>
<p>As SSA values, global variables define pointer values that are in
scope (i.e. they dominate) all basic blocks in the program. Global
<div class="doc_text">
-<p>LLVM function definitions are composed of a (possibly empty) argument list,
-an opening curly brace, a list of basic blocks, and a closing curly brace. LLVM
-function declarations are defined with the "<tt>declare</tt>" keyword, a
-function name, and a function signature.</p>
+<p>LLVM function definitions consist of an optional <a href="#linkage">linkage
+type</a>, an optional <a href="#callingconv">calling convention</a>, a return
+type, a function name, a (possibly empty) argument list, an opening curly brace,
+a list of basic blocks, and a closing curly brace. LLVM function declarations
+are defined with the "<tt>declare</tt>" keyword, an optional <a
+href="#callingconv">calling convention</a>, a return type, a function name, and
+a possibly empty list of arguments.</p>
<p>A function definition contains a list of basic blocks, forming the CFG for
the function. Each basic block may optionally start with a label (giving the
with a <a href="#terminators">terminator</a> instruction (such as a branch or
function return).</p>
-<p>The first basic block in program is special in two ways: it is immediately
+<p>The first basic block in a program is special in two ways: it is immediately
executed on entrance to the function, and it is not allowed to have predecessor
basic blocks (i.e. there can not be any branches to the entry block of a
function). Because the block can have no predecessors, it also cannot have any
<p>LLVM functions are identified by their name and type signature. Hence, two
functions with the same name but different parameter lists or return values are
-considered different functions, and LLVM will resolves references to each
+considered different functions, and LLVM will resolve references to each
appropriately.</p>
</div>
<div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
<div class="doc_text">
<p>The primitive types are the fundamental building blocks of the LLVM
-system. The current set of primitive types are as follows:</p>
+system. The current set of primitive types is as follows:</p>
<table class="layout">
<tr class="layout">
<tbody>
<tr><th>Type</th><th>Description</th></tr>
<tr><td><tt>void</tt></td><td>No value</td></tr>
- <tr><td><tt>ubyte</tt></td><td>Unsigned 8 bit value</td></tr>
- <tr><td><tt>ushort</tt></td><td>Unsigned 16 bit value</td></tr>
- <tr><td><tt>uint</tt></td><td>Unsigned 32 bit value</td></tr>
- <tr><td><tt>ulong</tt></td><td>Unsigned 64 bit value</td></tr>
- <tr><td><tt>float</tt></td><td>32 bit floating point value</td></tr>
+ <tr><td><tt>ubyte</tt></td><td>Unsigned 8-bit value</td></tr>
+ <tr><td><tt>ushort</tt></td><td>Unsigned 16-bit value</td></tr>
+ <tr><td><tt>uint</tt></td><td>Unsigned 32-bit value</td></tr>
+ <tr><td><tt>ulong</tt></td><td>Unsigned 64-bit value</td></tr>
+ <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
<tr><td><tt>label</tt></td><td>Branch destination</td></tr>
</tbody>
</table>
<tbody>
<tr><th>Type</th><th>Description</th></tr>
<tr><td><tt>bool</tt></td><td>True or False value</td></tr>
- <tr><td><tt>sbyte</tt></td><td>Signed 8 bit value</td></tr>
- <tr><td><tt>short</tt></td><td>Signed 16 bit value</td></tr>
- <tr><td><tt>int</tt></td><td>Signed 32 bit value</td></tr>
- <tr><td><tt>long</tt></td><td>Signed 64 bit value</td></tr>
- <tr><td><tt>double</tt></td><td>64 bit floating point value</td></tr>
+ <tr><td><tt>sbyte</tt></td><td>Signed 8-bit value</td></tr>
+ <tr><td><tt>short</tt></td><td>Signed 16-bit value</td></tr>
+ <tr><td><tt>int</tt></td><td>Signed 32-bit value</td></tr>
+ <tr><td><tt>long</tt></td><td>Signed 64-bit value</td></tr>
+ <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
</tbody>
</table>
</td>
instructions. This means that all structures and arrays must be
manipulated either by pointer or by component.</p>
</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
+
<div class="doc_text">
+
<p>The real power in LLVM comes from the derived types in the system.
This is what allows a programmer to represent arrays, functions,
pointers, and other useful types. Note that these derived types may be
recursive: For example, it is possible to have a two dimensional array.</p>
+
</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
+
<div class="doc_text">
+
<h5>Overview:</h5>
+
<p>The array type is a very simple derived type that arranges elements
sequentially in memory. The array type requires a size (number of
elements) and an underlying data type.</p>
+
<h5>Syntax:</h5>
-<pre> [<# elements> x <elementtype>]<br></pre>
-<p>The number of elements is a constant integer value, elementtype may
+
+<pre>
+ [<# elements> x <elementtype>]
+</pre>
+
+<p>The number of elements is a constant integer value; elementtype may
be any type with a size.</p>
+
<h5>Examples:</h5>
<table class="layout">
<tr class="layout">
<tt>[2 x [3 x [4 x uint]]]</tt><br/>
</td>
<td class="left">
- 3x4 array integer values.<br/>
+ 3x4 array of integer values.<br/>
12x10 array of single precision floating point values.<br/>
2x3x4 array of unsigned integer values.<br/>
</td>
</tr>
</table>
+
+<p>Note that 'variable sized arrays' can be implemented in LLVM With a zero
+length array. Normally accesses past the end of an array are undefined in
+LLVM (e.g. it is illegal to access the 5th element of a 3 element array).
+As a special case, however, zero length arrays are recognized to be variable
+length. This allows implementation of 'pascal style arrays' with the LLVM
+type "{ int, [0 x float]}", for example.</p>
+
</div>
<!-- _______________________________________________________________________ -->
A <a href="#t_pointer">pointer</a> to <a href="#t_array">array</a> of
four <tt>int</tt> values<br/>
A <a href="#t_pointer">pointer</a> to a <a
- href="#t_function">function</a> that takes an <tt>int</tt>, returning an
+ href="#t_function">function</a> that takes an <tt>int*</tt>, returning an
<tt>int</tt>.<br/>
</td>
</tr>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="t_packed">Packed Type</a> </div>
<div class="doc_text">
+
<h5>Overview:</h5>
+
<p>A packed type is a simple derived type that represents a vector
of elements. Packed types are used when multiple primitive data
are operated in parallel using a single instruction (SIMD).
A packed type requires a size (number of
elements) and an underlying primitive data type. Packed types are
considered <a href="#t_firstclass">first class</a>.</p>
+
<h5>Syntax:</h5>
-<pre> < <# elements> x <elementtype> ><br></pre>
-<p>The number of elements is a constant integer value, elementtype may
+
+<pre>
+ < <# elements> x <elementtype> >
+</pre>
+
+<p>The number of elements is a constant integer value; elementtype may
be any integral or floating point type.</p>
+
<h5>Examples:</h5>
+
<table class="layout">
<tr class="layout">
<td class="left">
</table>
</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 foward 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.<br/>
+ </td>
+ </tr>
+</table>
+</div>
+
+
+<!-- *********************************************************************** -->
+<div class="doc_section"> <a name="constants">Constants</a> </div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<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>
+
+<div class="doc_text">
+
+<dl>
+ <dt><b>Boolean constants</b></dt>
+
+ <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
+ constants of the <tt><a href="#t_primitive">bool</a></tt> type.
+ </dd>
+
+ <dt><b>Integer constants</b></dt>
+
+ <dd>Standard integers (such as '4') are constants of the <a
+ href="#t_integer">integer</a> type. Negative numbers may be used with signed
+ integer types.
+ </dd>
+
+ <dt><b>Floating point constants</b></dt>
+
+ <dd>Floating point constants use standard decimal notation (e.g. 123.421),
+ exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
+ notation (see below). Floating point constants must have a <a
+ href="#t_floating">floating point</a> type. </dd>
+
+ <dt><b>Null pointer constants</b></dt>
+
+ <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
+ and must be of <a href="#t_pointer">pointer type</a>.</dd>
+
+</dl>
+
+<p>The one non-intuitive notation for constants is the optional hexadecimal form
+of floating point constants. For example, the form '<tt>double
+0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
+4.5e+15</tt>'. The only time hexadecimal floating point constants are required
+(and the only time that they are generated by the disassembler) is when a
+floating point constant must be emitted but it cannot be represented as a
+decimal floating point number. For example, NaN's, infinities, and other
+special values are represented in their IEEE hexadecimal format so that
+assembly and disassembly do not cause any bits to change in the constants.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="aggregateconstants">Aggregate Constants</a>
+</div>
+
+<div class="doc_text">
+<p>Aggregate constants arise from aggregation of simple constants
+and smaller aggregate constants.</p>
+
+<dl>
+ <dt><b>Structure constants</b></dt>
+
+ <dd>Structure constants are represented with notation similar to structure
+ type definitions (a comma separated list of elements, surrounded by braces
+ (<tt>{}</tt>)). For example: "<tt>{ int 4, float 17.0, int* %G }</tt>",
+ where "<tt>%G</tt>" is declared as "<tt>%G = external global int</tt>". Structure constants
+ must have <a href="#t_struct">structure type</a>, and the number and
+ types of elements must match those specified by the type.
+ </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 brackets
+ (<tt>[]</tt>)). For example: "<tt>[ int 42, int 11, int 74 ]</tt>". Array
+ constants must have <a href="#t_array">array type</a>, and the number and
+ types of elements must match those specified by the type.
+ </dd>
+
+ <dt><b>Packed constants</b></dt>
+
+ <dd>Packed constants are represented with notation similar to packed type
+ definitions (a comma separated list of elements, surrounded by
+ less-than/greater-than's (<tt><></tt>)). For example: "<tt>< int 42,
+ int 11, int 74, int 100 ></tt>". Packed constants must have <a
+ href="#t_packed">packed type</a>, and the number and types of elements must
+ match those specified by the type.
+ </dd>
+
+ <dt><b>Zero initialization</b></dt>
+
+ <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
+ value to zero of <em>any</em> type, including scalar and aggregate types.
+ This is often used to avoid having to print large zero initializers (e.g. for
+ large arrays), and is always exactly equivalent to using explicit zero
+ initializers.
+ </dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="globalconstants">Global Variable and Function Addresses</a>
+</div>
+
+<div class="doc_text">
+
+<p>The addresses of <a href="#globalvars">global variables</a> and <a
+href="#functionstructure">functions</a> are always implicitly valid (link-time)
+constants. These constants are explicitly referenced when the <a
+href="#identifiers">identifier for the global</a> is used and always have <a
+href="#t_pointer">pointer</a> type. For example, the following is a legal LLVM
+file:</p>
+
+<pre>
+ %X = global int 17
+ %Y = global int 42
+ %Z = global [2 x int*] [ int* %X, int* %Y ]
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
+<div class="doc_text">
+ <p>The string '<tt>undef</tt>' is recognized as a type-less constant that has
+ no specific value. Undefined values may be of any type and be used anywhere
+ a constant is permitted.</p>
+
+ <p>Undefined values indicate to the compiler that the program is well defined
+ no matter what value is used, giving the compiler more freedom to optimize.
+ </p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
+</div>
+
+<div class="doc_text">
+
+<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>
+
+<dl>
+ <dt><b><tt>cast ( CST to TYPE )</tt></b></dt>
+
+ <dd>Cast a constant to another type.</dd>
+
+ <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
+
+ <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
+ constants. As with the <a href="#i_getelementptr">getelementptr</a>
+ instruction, the index list may have zero or more indexes, which are required
+ to make sense for the type of "CSTPTR".</dd>
+
+ <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt>
+
+ <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
+ be any of the <a href="#binaryops">binary</a> or <a href="#bitwiseops">bitwise
+ binary</a> operations. The constraints on operands are the same as those for
+ the corresponding instruction (e.g. no bitwise operations on floating point
+ values are allowed).</dd>
+</dl>
+</div>
<!-- *********************************************************************** -->
<div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
<!-- *********************************************************************** -->
+
<div class="doc_text">
+
<p>The LLVM instruction set consists of several different
classifications of instructions: <a href="#terminators">terminator
-instructions</a>, <a href="#binaryops">binary instructions</a>, <a
+instructions</a>, <a href="#binaryops">binary instructions</a>,
+<a href="#bitwiseops">bitwise binary instructions</a>, <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>
+
<div class="doc_text">
+
<p>As mentioned <a href="#functionstructure">previously</a>, every
basic block in a program ends with a "Terminator" instruction, which
indicates which block should be executed after the current block is
finished. These terminator instructions typically yield a '<tt>void</tt>'
value: they produce control flow, not values (the one exception being
the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
-<p>There are
five different terminator instructions: the '<a
+<p>There are
six 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_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>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
Instruction</a> </div>
</pre>
<h5>Overview:</h5>
<p>The '<tt>ret</tt>' instruction is used to return control flow (and a
-value) from a function, back to the caller.</p>
+value) from a function back to the caller.</p>
<p>There are two forms of the '<tt>ret</tt>' instruction: one that
returns a value and then causes control flow, and one that just causes
control flow to occur.</p>
href="#i_call"><tt>call</tt></a>" instruction, execution continues at
the instruction after the call. If the caller was an "<a
href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues
-at the beginning "normal" of the destination block. If the instruction
+at the beginning of the "normal" destination block. If the instruction
returns a value, that value shall set the call or invoke instruction's
return value.</p>
<h5>Example:</h5>
uint 2, label %ontwo ]
</pre>
</div>
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_invoke">'<tt>invoke</tt>'
-Instruction</a> </div>
+<div class="doc_subsubsection">
+ <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
+</div>
+
<div class="doc_text">
+
<h5>Syntax:</h5>
-<pre> <result> = invoke <ptr to function ty> %<function ptr val>(<function args>)<br> to label <normal label> except label <exception label><br></pre>
+
+<pre>
+ <result> = invoke [<a href="#callingconv">cconv</a>] <ptr to function ty> %<function ptr val>(<function args>)
+ to label <normal label> except label <exception label>
+</pre>
+
<h5>Overview:</h5>
-<p>The '<tt>invoke</tt>' instruction causes control to transfer to a
-specified function, with the possibility of control flow transfer to
-either the '<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'<tt>label</tt>.
-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 "except" label.</p>
+
+<p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
+function, with the possibility of control flow transfer to either the
+'<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>
+
<h5>Arguments:</h5>
+
<p>This instruction requires several arguments:</p>
+
<ol>
- <li>'<tt>ptr to function ty</tt>': shall be the signature of the
-pointer to function value being invoked. In most cases, this is a
-direct function invocation, but indirect <tt>invoke</tt>s are just as
-possible, branching off an arbitrary pointer to function value. </li>
- <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer
-to a function to be invoked. </li>
- <li>'<tt>function args</tt>': argument list whose types match the
-function signature argument types. If the function signature indicates
-the function accepts a variable number of arguments, the extra
-arguments can be specified. </li>
- <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>
+ The optional "cconv" marker indicates which <a href="callingconv">calling
+ convention</a> the call should use. If none is specified, the call defaults
+ to using C calling conventions.
+ </li>
+ <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
+ function value being invoked. In most cases, this is a direct function
+ invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
+ an arbitrary pointer to function value.
+ </li>
+
+ <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
+ function to be invoked. </li>
+
+ <li>'<tt>function args</tt>': argument list whose types match the function
+ signature argument types. If the function signature indicates the function
+ accepts a variable number of arguments, the extra arguments can be
+ specified. </li>
+
+ <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>
+
</ol>
+
<h5>Semantics:</h5>
+
<p>This instruction is designed to operate as a standard '<tt><a
- href="#i_call">call</a></tt>' instruction in most regards. The
-primary difference is that it establishes an association with a label,
-which is used by the runtime library to unwind the stack.</p>
-<p>This instruction is used in languages with destructors to ensure
-that proper cleanup is performed in the case of either a <tt>longjmp</tt>
-or a thrown exception. Additionally, this is important for
-implementation of '<tt>catch</tt>' clauses in high-level languages that
-support them.</p>
+href="#i_call">call</a></tt>' instruction in most regards. The primary
+difference is that it establishes an association with a label, which is used by
+the runtime library to unwind the stack.</p>
+
+<p>This instruction is used in languages with destructors to ensure that proper
+cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
+exception. Additionally, this is important for implementation of
+'<tt>catch</tt>' clauses in high-level languages that support them.</p>
+
<h5>Example:</h5>
-<pre> %retval = invoke int %Test(int 15)<br> to label %Continue<br> except label %TestCleanup <i>; {int}:retval set</i>
+<pre>
+ %retval = invoke int %Test(int 15) to label %Continue
+ except label %TestCleanup <i>; {int}:retval set</i>
+ %retval = invoke <a href="#callingconv">coldcc</a> int %Test(int 15) to label %Continue
+ except label %TestCleanup <i>; {int}:retval set</i>
</pre>
</div>
<div class="doc_text">
<p>Binary operators are used to do most of the computation in a
program. They require two operands, execute an operation on them, and
-produce a single value. Although, that single value might represent
+produce a single value. The operands might represent
multiple data, as is the case with the <a href="#t_packed">packed</a> data type.
The result value of a binary operator is not
necessarily the same type as its operands.</p>
<div class="doc_text">
<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 strength reduced from other
+instructions and can commonly be strength reduced from other
instructions. They require two operands, execute an operation on them,
and produce a single value. The resulting value of the bitwise binary
operators is always the same type as its first operand.</p>
<p>A key design point of an SSA-based representation is how it
represents memory. In LLVM, no memory locations are in SSA form, which
makes things very simple. This section describes how to read, write,
-allocate and free memory in LLVM.</p>
+allocate, and free memory in LLVM.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_malloc">'<tt>malloc</tt>'
</pre>
<h5>Overview:</h5>
<p>The '<tt>free</tt>' instruction returns memory back to the unused
-memory heap, to be reallocated in the future.</p>
+memory heap to be reallocated in the future.</p>
<p> </p>
<h5>Arguments:</h5>
<p>'<tt>value</tt>' shall be a pointer value that points to a value
that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
instruction.</p>
<h5>Semantics:</h5>
-<p>Access to the memory pointed to by the pointer is not longer defined
+<p>Access to the memory pointed to by the pointer is no longer defined
after this instruction executes.</p>
<h5>Example:</h5>
<pre> %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
stack frame of the procedure that is live until the current function
returns to its caller.</p>
<h5>Arguments:</h5>
-<p>The the '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
+<p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
bytes of memory on the runtime stack, returning a pointer of the
appropriate type to the program. The second form of the instruction is
a shorter version of the first that defaults to allocating one element.</p>
<p>'<tt>type</tt>' may be any sized type.</p>
<h5>Semantics:</h5>
-<p>Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d
+<p>Memory is allocated; a pointer is returned. '<tt>alloca</tt>'d
memory is automatically released when the function returns. The '<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_invoke">invoke</a></tt>
+ href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
instructions), the memory is reclaimed.</p>
<h5>Example:</h5>
<pre> %ptr = alloca int <i>; yields {int*}:ptr</i>
<p>There are two arguments to the '<tt>store</tt>' instruction: a value
to store and an address to store it into. The type of the '<tt><pointer></tt>'
operand must be a pointer to the type of the '<tt><value></tt>'
-operand. If the <tt>store</tt> is marked as <tt>volatile</tt> then the
+operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the
optimizer is not allowed to modify the number or order of execution of
this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
href="#i_store">store</a></tt> instructions.</p>
elements of the aggregate object to index to. The actual types of the arguments
provided depend on the type of the first pointer argument. The
'<tt>getelementptr</tt>' instruction is used to index down through the type
-levels of a structure. When indexing into a structure, only <tt>uint</tt>
-integer constants are allowed. When indexing into an array or pointer
+levels of a structure or to a specific index in an array. When indexing into a
+structure, only <tt>uint</tt>
+integer constants are allowed. When indexing into an array or pointer,
<tt>int</tt> and <tt>long</tt> indexes are allowed of any sign.</p>
<p>For example, let's consider a C code fragment and how it gets
<h5>Semantics:</h5>
<p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
-on the pointer type that is being index into. <a href="#t_pointer">Pointer</a>
+on the pointer type that is being index
ed into. <a href="#t_pointer">Pointer</a>
and <a href="#t_array">array</a> types require <tt>uint</tt>, <tt>int</tt>,
<tt>ulong</tt>, or <tt>long</tt> values, and <a href="#t_struct">structure</a>
types require <tt>uint</tt> <b>constants</b>.</p>
sbyte }</tt>' type, another structure. The third index indexes into the second
element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
array. The two dimensions of the array are subscripted into, yielding an
-'<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction return a pointer
+'<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer
to this element, thus computing a value of '<tt>int*</tt>' type.</p>
<p>Note that it is perfectly legal to index partially through a
the LLVM code for the given testcase is equivalent to:</p>
<pre>
- int* "foo"(%ST* %s) {
+ int* %foo(%ST* %s) {
%t1 = getelementptr %ST* %s, int 1 <i>; yields %ST*:%t1</i>
%t2 = getelementptr %ST* %t1, int 0, uint 2 <i>; yields %RT*:%t2</i>
%t3 = getelementptr %RT* %t2, int 0, uint 1 <i>; yields [10 x [20 x int]]*:%t3</i>
ret int* %t5
}
</pre>
+
+<p>Note that it is undefined to access an array out of bounds: array and
+pointer indexes must always be within the defined bounds of the array type.
+The one exception for this rules is zero length arrays. These arrays are
+defined to be accessible as variable length arrays, which requires access
+beyond the zero'th element.</p>
+
<h5>Example:</h5>
+
<pre>
<i>; yields [12 x ubyte]*:aptr</i>
%aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1
<p>
If the boolean condition evaluates to true, the instruction returns the first
-value argument, otherwise it returns the second value argument.
+value argument; otherwise, it returns the second value argument.
</p>
<h5>Example:</h5>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_call">'<tt>call</tt>'
-Instruction</a> </div>
+<div class="doc_subsubsection">
+ <a name="i_call">'<tt>call</tt>' Instruction</a>
+</div>
+
<div class="doc_text">
+
<h5>Syntax:</h5>
-<pre> <result> = call <ty>* <fnptrval>(<param list>)<br></pre>
+<pre>
+ <result> = [tail] call [<a href="#callingconv">cconv</a>] <ty>* <fnptrval>(<param list>)
+</pre>
+
<h5>Overview:</h5>
+
<p>The '<tt>call</tt>' instruction represents a simple function call.</p>
+
<h5>Arguments:</h5>
+
<p>This instruction requires several arguments:</p>
+
<ol>
<li>
- <p>'<tt>ty</tt>': shall be the signature of the pointer to function
-value being invoked. The argument types must match the types implied
-by this signature.</p>
+ <p>The optional "tail" marker indicates whether the callee function accesses
+ any allocas or varargs in the caller. If the "tail" marker is present, the
+ function call is eligible for tail call optimization. Note that calls may
+ be marked "tail" even if they do not occur before a <a
+ href="#i_ret"><tt>ret</tt></a> instruction.
</li>
<li>
- <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a
-function to be invoked. In most cases, this is a direct function
-invocation, but indirect <tt>call</tt>s are just as possible,
-calling an arbitrary pointer to function values.</p>
+ <p>The optional "cconv" marker indicates which <a href="callingconv">calling
+ convention</a> the call should use. If none is specified, the call defaults
+ to using C calling conventions.
+ </li>
+ <li>
+ <p>'<tt>ty</tt>': shall be the signature of the pointer to function value
+ being invoked. The argument types must match the types implied by this
+ signature. This type can be omitted if the function is not varargs and
+ if the function type does not return a pointer to a function.</p>
+ </li>
+ <li>
+ <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
+ be invoked. In most cases, this is a direct function invocation, but
+ indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
+ to function value.</p>
</li>
<li>
<p>'<tt>function args</tt>': argument list whose types match the
-function signature argument types. If the function signature
-indicates the function accepts a variable number of arguments, the
-extra arguments can be specified.</p>
+ function signature argument types. All arguments must be of
+ <a href="#t_firstclass">first class</a> type. If the function signature
+ indicates the function accepts a variable number of arguments, the extra
+ arguments can be specified.</p>
</li>
</ol>
+
<h5>Semantics:</h5>
+
<p>The '<tt>call</tt>' instruction is used to cause control flow to
transfer to a specified function, with its incoming arguments bound to
the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
instruction after the function call, and the return value of the
function is bound to the result argument. This is a simpler case of
the <a href="#i_invoke">invoke</a> instruction.</p>
-<h5>Example:</h5>
-<pre> %retval = call int %test(int %argc)<br> call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);<br></pre>
-</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_vanext">'<tt>vanext</tt>' Instruction</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Syntax:</h5>
+<h5>Example:</h5>
<pre>
- <resultarglist> = vanext <va_list> <arglist>, <argty>
+ %retval = call int %test(int %argc)
+ call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
+ %X = tail call int %foo()
+ %Y = tail call <a href="#callingconv">fastcc</a> int %foo()
</pre>
-<h5>Overview:</h5>
-
-<p>The '<tt>vanext</tt>' instruction is used to access arguments passed
-through the "variable argument" area of a function call. It is used to
-implement the <tt>va_arg</tt> macro in C.</p>
-
-<h5>Arguments:</h5>
-
-<p>This instruction takes a <tt>va_list</tt> value and the type of the
-argument. It returns another <tt>va_list</tt>. The actual type of
-<tt>va_list</tt> may be defined differently for different targets. Most targets
-use a <tt>va_list</tt> type of <tt>sbyte*</tt> or some other pointer type.</p>
-
-<h5>Semantics:</h5>
-
-<p>The '<tt>vanext</tt>' instruction advances the specified <tt>va_list</tt>
-past an argument of the specified type. In conjunction with the <a
- href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement
-the <tt>va_arg</tt> macro available in C. For more information, see
-the variable argument handling <a href="#int_varargs">Intrinsic
-Functions</a>.</p>
-
-<p>It is legal for this instruction to be called in a function which
-does not take a variable number of arguments, for example, the <tt>vfprintf</tt>
-function.</p>
-
-<p><tt>vanext</tt> is an LLVM instruction instead of an <a
-href="#intrinsics">intrinsic function</a> because it takes a type as an
-argument. The type refers to the current argument in the <tt>va_list</tt>, it
-tells the compiler how far on the stack it needs to advance to find the next
-argument</p>
-
-<h5>Example:</h5>
-
-<p>See the <a href="#int_varargs">variable argument processing</a>
-section.</p>
-
</div>
<!-- _______________________________________________________________________ -->
<h5>Syntax:</h5>
<pre>
- <resultval> = vaarg <va_list> <arglist>, <argty>
+ <resultval> = va_arg <va_list*> <arglist>, <argty>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>vaarg</tt>' instruction is used to access arguments passed through
+<p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
the "variable argument" area of a function call. It is used to implement the
<tt>va_arg</tt> macro in C.</p>
<h5>Arguments:</h5>
-<p>This instruction takes a <tt>va_list</tt> value and the type of the
-argument. It returns a value of the specified argument type. Again, the actual
-type of <tt>va_list</tt> is target specific.</p>
+<p>This instruction takes a <tt>va_list*</tt> value and the type of
+the argument. It returns a value of the specified argument type and
+increments the <tt>va_list</tt> to poin to the next argument. Again, the
+actual type of <tt>va_list</tt> is target specific.</p>
<h5>Semantics:</h5>
-<p>The '<tt>vaarg</tt>' instruction loads an argument of the specified type from
-the specified <tt>va_list</tt>. In conjunction with the <a
-href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to implement the
-<tt>va_arg</tt> macro available in C. For more information, see the variable
-argument handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
+<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified
+type from the specified <tt>va_list</tt> and causes the
+<tt>va_list</tt> to point to the next argument. For more information,
+see the variable argument handling <a href="#int_varargs">Intrinsic
+Functions</a>.</p>
<p>It is legal for this instruction to be called in a function which does not
take a variable number of arguments, for example, the <tt>vfprintf</tt>
function.</p>
-<p><tt>vaarg</tt> is an LLVM instruction instead of an <a
-href="#intrinsics">intrinsic function</a> because it takes an type as an
+<p><tt>va
_arg</tt> is an LLVM instruction instead of an <a
+href="#intrinsics">intrinsic function</a> because it takes a type as an
argument.</p>
<h5>Example:</h5>
<div class="doc_text">
<p>LLVM supports the notion of an "intrinsic function". These functions have
-well known names and semantics, and are required to follow certain
+well known names and semantics and are required to follow certain
restrictions. Overall, these instructions represent an extension mechanism for
the LLVM language that does not require changing all of the transformations in
LLVM to add to the language (or the bytecode reader/writer, the parser,
etc...).</p>
-<p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
-prefix is reserved in LLVM for intrinsic names, thus functions may not be named
+<p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
+prefix is reserved in LLVM for intrinsic names; thus, functions may not be named
this. Intrinsic functions must always be external functions: you cannot define
the body of intrinsic functions. Intrinsic functions may only be used in call
or invoke instructions: it is illegal to take the address of an intrinsic
language, it is required that they all be documented here if any are added.</p>
-<p>
-Adding an intrinsic to LLVM is straight-forward if it is possible to express the
-concept in LLVM directly (ie, code generator support is not _required_). To do
-this, extend the default implementation of the IntrinsicLowering class to handle
-the intrinsic. Code generators use this class to lower intrinsics they do not
-understand to raw LLVM instructions that they do.
+<p>To learn how to add an intrinsic function, please see the <a
+href="ExtendingLLVM.html">Extending LLVM Guide</a>.
</p>
</div>
<pre>
int %test(int %X, ...) {
; Initialize variable argument processing
- %ap = call sbyte* %<a href="#i_va_start">llvm.va_start</a>()
+ %ap = alloca sbyte*
+ call void %<a href="#i_va_start">llvm.va_start</a>(sbyte** %ap)
; Read a single integer argument
- %tmp = vaarg sbyte* %ap, int
-
- ; Advance to the next argument
- %ap2 = vanext sbyte* %ap, int
+ %tmp = va_arg sbyte** %ap, int
; Demonstrate usage of llvm.va_copy and llvm.va_end
- %aq = call sbyte* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
- call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
+ %aq = alloca sbyte*
+ call void %<a href="#i_va_copy">llvm.va_copy</a>(sbyte** %aq, sbyte** %ap)
+ call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %aq)
; Stop processing of arguments.
- call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
+ call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %ap)
ret int %tmp
}
</pre>
<div class="doc_text">
<h5>Syntax:</h5>
-<pre> call <va_list> ()* %llvm.va_start()<br></pre>
+<pre> declare void %llvm.va_start(<va_list>* <arglist>)<br></pre>
<h5>Overview:</h5>
-<p>The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt><arglist></tt>
-for subsequent use by the variable argument intrinsics.</p>
+<P>The '<tt>llvm.va_start</tt>' intrinsic initializes
+<tt>*<arglist></tt> for subsequent use by <tt><a
+href="#i_va_arg">va_arg</a></tt>.</p>
+
+<h5>Arguments:</h5>
+
+<P>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
+
<h5>Semantics:</h5>
-<p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
-macro available in C. In a target-dependent way, it initializes and
-returns a <tt>va_list</tt> element, so that the next <tt>vaarg</tt>
-will produce the first variable argument passed to the function. Unlike
-the C <tt>va_start</tt> macro, this intrinsic does not need to know the
+
+<P>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
+macro available in C. In a target-dependent way, it initializes the
+<tt>va_list</tt> element the argument points to, so that the next call to
+<tt>va_arg</tt> will produce the first variable argument passed to the function.
+Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
last argument of the function, the compiler can figure that out.</p>
-<p>Note that this intrinsic function is only legal to be called from
-within the body of a variable argument function.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_text">
<h5>Syntax:</h5>
-<pre> call void (<va_list>)* %llvm.va_end(<va_list> <arglist>)<br></pre>
+<pre> declare void %llvm.va_end(<va_list*> <arglist>)<br></pre>
<h5>Overview:</h5>
<p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt><arglist></tt>
which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
<h5>Syntax:</h5>
<pre>
- call <va_list> (<va_list>)* %llvm.va_copy(<va_list> <destarglist>)
+ declare void %llvm.va_copy(<va_list>* <destarglist>,
+ <va_list>* <srcarglist>)
</pre>
<h5>Overview:</h5>
-<p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
-from the source argument list to the destination argument list.</p>
+<p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
+the source argument list to the destination argument list.</p>
<h5>Arguments:</h5>
-<p>The argument is the <tt>va_list</tt> to copy.</p>
+<p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
+The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p>
+
<h5>Semantics:</h5>
-<p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
-macro available in C. In a target-dependent way, it copies the source
-<tt>va_list</tt> element into the returned list. This intrinsic is necessary
-because the <tt><a href="#i_va_start">llvm.va_start</a></tt> intrinsic may be
+<p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
+available in C. In a target-dependent way, it copies the source
+<tt>va_list</tt> element into the destination list. This intrinsic is necessary
+because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
arbitrarily complex and require memory allocation, for example.</p>
</div>
<h5>Syntax:</h5>
<pre>
- call void (<ty>**, <ty2>*)* %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)
+ declare void %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)
</pre>
<h5>Overview:</h5>
-<p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existance of a GC root to
+<p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
the code generator, and allows some metadata to be associated with it.</p>
<h5>Arguments:</h5>
<h5>Syntax:</h5>
<pre>
- call sbyte* (sbyte**)* %llvm.gcread(sbyte** %Ptr)
+ declare sbyte* %llvm.gcread(sbyte** %Ptr)
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- call void (sbyte*, sbyte**)* %llvm.gcwrite(sbyte* %P1, sbyte** %P2)
+ declare void %llvm.gcwrite(sbyte* %P1, sbyte** %P2)
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- call void* ()* %llvm.returnaddress(uint <level>)
+ declare void* %llvm.returnaddress(uint <level>)
</pre>
<h5>Overview:</h5>
<p>
Note that calling this intrinsic does not prevent function inlining or other
-aggressive transformations, so the value returned may not that of the obvious
+aggressive transformations, so the value returned may not be that of the obvious
source-language caller.
</p>
</div>
<h5>Syntax:</h5>
<pre>
- call void* ()* %llvm.frameaddress(uint <level>)
+ declare void* %llvm.frameaddress(uint <level>)
</pre>
<h5>Overview:</h5>
<p>
Note that calling this intrinsic does not prevent function inlining or other
-aggressive transformations, so the value returned may not that of the obvious
+aggressive transformations, so the value returned may not be that of the obvious
source-language caller.
</p>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare void %llvm.prefetch(sbyte * <address>,
+ uint <rw>, uint <locality>)
+</pre>
+
+<h5>Overview:</h5>
+
+
+<p>
+The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert
+a prefetch instruction if supported; otherwise, it is a noop. Prefetches have
+no
+effect on the behavior of the program but can change its performance
+characteristics.
+</p>
+
+<h5>Arguments:</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>
+
+<h5>Semantics:</h5>
+
+<p>
+This intrinsic does not modify the behavior of the program. In particular,
+prefetches cannot trap and do not produce a value. On targets that support this
+intrinsic, the prefetch can provide hints to the processor cache for better
+performance.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare void %llvm.pcmarker( uint <id> )
+</pre>
+
+<h5>Overview:</h5>
+
+
+<p>
+The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter
+(PC) in a region of
+code to simulators and other tools. The method is target specific, but it is
+expected that the marker will use exported symbols to transmit the PC of the marker.
+The marker makes no guaranties that it will remain with any specific instruction
+after optimizations. It is possible that the presense of a marker will inhibit
+optimizations. The intended use is to be inserted after optmizations to allow
+correlations of simulation runs.
+</p>
+
+<h5>Arguments:</h5>
+
+<p>
+<tt>id</tt> is a numerical id identifying the marker.
+</p>
+
+<h5>Semantics:</h5>
+
+<p>
+This intrinsic does not modify the behavior of the program. Backends that do not
+support this intrinisic may ignore it.
+</p>
+
+</div>
+
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="int_os">Operating System Intrinsics</a>
<h5>Syntax:</h5>
<pre>
- call <integer type> (<integer type>)* %llvm.readport (<integer type> <address>)
+ declare <integer type> %llvm.readport (<integer type> <address>)
</pre>
<h5>Overview:</h5>
specified by <i>address</i> and returns the value. The address and return
value must be integers, but the size is dependent upon the platform upon which
the program is code generated. For example, on x86, the address must be an
-unsigned 16 bit value, and the return value must be 8, 16, or 32 bits.
+unsigned 16-bit value, and the return value must be 8, 16, or 32 bits.
</p>
</div>
<h5>Syntax:</h5>
<pre>
- call void (<integer type>, <integer type>)* %llvm.writeport (<integer type> <value>, <integer type> <address>)
+ call void (<integer type>, <integer type>)*
+ %llvm.writeport (<integer type> <value>,
+ <integer type> <address>)
</pre>
<h5>Overview:</h5>
The '<tt>llvm.writeport</tt>' intrinsic writes <i>value</i> to the I/O port
specified by <i>address</i>. The address and value must be integers, but the
size is dependent upon the platform upon which the program is code generated.
-For example, on x86, the address must be an unsigned 16 bit value, and the
+For example, on x86, the address must be an unsigned 16-bit value, and the
value written must be 8, 16, or 32 bits in length.
</p>
<h5>Syntax:</h5>
<pre>
- call <result> (<ty>*)* %llvm.readio (<ty> * <pointer>)
+ declare <result> %llvm.readio (<ty> * <pointer>)
</pre>
<h5>Overview:</h5>
location specified by <i>pointer</i> and returns the value. The argument must
be a pointer, and the return value must be a
<a href="#t_firstclass">first class</a> type. However, certain architectures
-may not support I/O on all first class types. For example, 32 bit processors
+may not support I/O on all first class types. For example, 32-bit processors
may only support I/O on data types that are 32 bits or less.
</p>
<h5>Syntax:</h5>
<pre>
- call void (<ty1>, <ty2>*)* %llvm.writeio (<ty1> <value>, <ty2> * <pointer>)
+ declare void %llvm.writeio (<ty1> <value>, <ty2> * <pointer>)
</pre>
<h5>Overview:</h5>
The '<tt>llvm.writeio</tt>' intrinsic writes <i>value</i> to the memory mapped
I/O address specified by <i>pointer</i>. The value must be a
<a href="#t_firstclass">first class</a> type. However, certain architectures
-may not support I/O on all first class types. For example, 32 bit processors
+may not support I/O on all first class types. For example, 32-bit processors
may only support I/O on data types that are 32 bits or less.
</p>
<h5>Syntax:</h5>
<pre>
- call void (sbyte*, sbyte*, uint, uint)* %llvm.memcpy(sbyte* <dest>, sbyte* <src>,
- uint <len>, uint <align>)
+ declare void %llvm.memcpy(sbyte* <dest>, sbyte* <src>,
+ uint <len>, uint <align>)
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- call void (sbyte*, sbyte*, uint, uint)* %llvm.memmove(sbyte* <dest>, sbyte* <src>,
- uint <len>, uint <align>)
+ declare void %llvm.memmove(sbyte* <dest>, sbyte* <src>,
+ uint <len>, uint <align>)
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- call void (sbyte*, ubyte, uint, uint)* %llvm.memset(sbyte* <dest>, ubyte <val>,
- uint <len>, uint <align>)
+ declare void %llvm.memset(sbyte* <dest>, ubyte <val>,
+ uint <len>, uint <align>)
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- call bool (<float or double>, <float or double>)* %llvm.isunordered(<float or double> Val1,
- <float or double> Val2)
+ declare bool %llvm.isunordered(<float or double> Val1, <float or double> Val2)
</pre>
<h5>Overview:</h5>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="i_sqrt">'<tt>llvm.sqrt</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare <float or double> %llvm.sqrt(<float or double> Val)
+</pre>
+<h5>Overview:</h5>
+
+<p>
+The '<tt>llvm.sqrt</tt>' intrinsic returns the sqrt of the specified operand,
+returning the same value as the libm '<tt>sqrt</tt>' function would. Unlike
+<tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for
+negative numbers (which allows for better optimization).
+</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 sqrt of the specified operand if it is a positive
+floating point number.
+</p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="int_count">Bit Counting Intrinsics</a>
+</div>
+
+<div class="doc_text">
+<p>
+LLVM provides intrinsics for a few important bit counting operations.
+These allow efficient code generation for some algorithms.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_ctpop">'<tt>llvm.ctpop</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare int %llvm.ctpop(int <src>)
+
+</pre>
+
+<h5>Overview:</h5>
+
+<p>
+The '<tt>llvm.ctpop</tt>' intrinsic counts the number of ones 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. 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>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_ctlz">'<tt>llvm.ctlz</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare int %llvm.ctlz(int <src>)
+
+</pre>
+
+<h5>Overview:</h5>
+
+<p>
+The '<tt>llvm.ctlz</tt>' intrinsic counts the number of 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. 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 the type
+of src. For example, <tt>llvm.cttz(int 2) = 30</tt>.
+</p>
+</div>
+
+
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="int_cttz">'<tt>llvm.cttz</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+ declare int %llvm.cttz(int <src>)
+
+</pre>
+
+<h5>Overview:</h5>
+
+<p>
+The '<tt>llvm.cttz</tt>' intrinsic counts the number of trailing zeros.
+</p>
+
+<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>
+
+<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 the type
+of src. For example, <tt>llvm.cttz(2) = 1</tt>.
+</p>
+</div>
<!-- ======================================================================= -->
<div class="doc_subsection">
projects / oota-llvm.git / blobdiff