<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>
<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_cttz">'<tt>llvm.cttz</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>
<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>
<!-- _______________________________________________________________________ -->
< <# elements> x <elementtype> >
</pre>
-<p>The number of elements is a constant integer value, elementtype may
+<p>The number of elements is a constant integer value; elementtype may
be any integral or floating point type.</p>
<h5>Examples:</h5>
<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. Floating point constants have an optional hexadecimal
notation (see below). Floating point constants must have a <a
href="#t_floating">floating point</a> type. </dd>
<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
+ 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
<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
+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>
<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>
</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>
<ol>
<li>
- <p>The optional "cconv" marker indicates which <a href="callingconv">calling
+ 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>
</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
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
<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 indexed 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
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>
<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>
+ 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 values.</p>
+ to function value.</p>
</li>
<li>
<p>'<tt>function args</tt>': argument list whose types match the
</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_vanext">'<tt>vanext</tt>' Instruction</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Syntax:</h5>
-
-<pre>
- <resultarglist> = vanext <va_list> <arglist>, <argty>
-</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>
-
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="i_vaarg">'<tt>vaarg</tt>' Instruction</a>
<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>To learn how to add an intrinsics, please see the <a
+<p>To learn how to add an intrinsic function, please see the <a
href="ExtendingLLVM.html">Extending LLVM Guide</a>.
</p>
<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> declare <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> declare void %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>
- declare <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>
<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
+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>
<p>
-The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a PC in a region of
+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
-corrolations of simulation runs.
+correlations of simulation runs.
</p>
<h5>Arguments:</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 class="doc_subsubsection">
- <a name="int_cttz">'<tt>llvm.cttz</tt>' Intrinsic</a>
+ <a name="int_ctlz">'<tt>llvm.ctlz</tt>' Intrinsic</a>
</div>
<div class="doc_text">
<h5>Syntax:</h5>
<pre>
- declare int %llvm.cttz(int <src>)
+ declare int %llvm.ctlz(int <src>)
</pre>
<h5>Overview:</h5>
<p>
-The '<tt>llvm.cttz</tt>' intrinsic counts the number of trailing zeros.
+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.
+integer type. The return type must match the argument type.
</p>
<h5>Semantics:</h5>
<p>
-The '<tt>llvm.cttz</tt>' intrinsic counts the trailing zeros in a variable. If
-the src == 0 then the result is the size in bits of the type of src.
+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_ctlz">'<tt>llvm.ctlz</tt>' Intrinsic</a>
+ <a name="int_cttz">'<tt>llvm.cttz</tt>' Intrinsic</a>
</div>
<div class="doc_text">
<h5>Syntax:</h5>
<pre>
- declare int %llvm.ctlz(int <src>)
+ declare int %llvm.cttz(int <src>)
</pre>
<h5>Overview:</h5>
<p>
-The '<tt>llvm.ctlz</tt>' intrinsic counts the number of leading zeros in a
-variable.
+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.
+integer type. The return type must match the argument type.
</p>
<h5>Semantics:</h5>
<p>
-The '<tt>llvm.ctlz</tt>' intrinsic counts the leading zeros in a variable. If
-the src == 0 then the result is the size in bits of the type of src.
+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">
<a name="int_debugger">Debugger Intrinsics</a>