LangRef.html

<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
</pre>

</div>
<!-- ======================================================================= -->
<div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
<div class="doc_text">
<p>The instructions in this category are the "miscellaneous"
instructions, which defy better classification.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
Instruction</a> </div>
<div class="doc_text">
<h5>Syntax:</h5>
<pre>  &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...<br></pre>
<h5>Overview:</h5>
<p>The '<tt>phi</tt>' instruction is used to implement the &#966; node in
the SSA graph representing the function.</p>
<h5>Arguments:</h5>
<p>The type of the incoming values are specified with the first type
field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
as arguments, with one pair for each predecessor basic block of the
current block.  Only values of <a href="#t_firstclass">first class</a>
type may be used as the value arguments to the PHI node.  Only labels
may be used as the label arguments.</p>
<p>There must be no non-phi instructions between the start of a basic
block and the PHI instructions: i.e. PHI instructions must be first in
a basic block.</p>
<h5>Semantics:</h5>
<p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
value specified by the parameter, depending on which basic block we
came from in the last <a href="#terminators">terminator</a> instruction.</p>
<h5>Example:</h5>
<pre>Loop:       ; Infinite loop that counts from 0 on up...<br>  %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]<br>  %nextindvar = add uint %indvar, 1<br>  br label %Loop<br></pre>
</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
   <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  &lt;result&gt; = cast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
</pre>

<h5>Overview:</h5>

<p>
The '<tt>cast</tt>' instruction is used as the primitive means to convert
integers to floating point, change data type sizes, and break type safety (by
casting pointers).
</p>


<h5>Arguments:</h5>

<p>
The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
class value, and a type to cast it to, which must also be a <a
href="#t_firstclass">first class</a> type.
</p>

<h5>Semantics:</h5>

<p>
This instruction follows the C rules for explicit casts when determining how the
data being cast must change to fit in its new container.
</p>

<p>
When casting to bool, any value that would be considered true in the context of
a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
all else are '<tt>false</tt>'.
</p>

<p>
When extending an integral value from a type of one signness to another (for
example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
<b>source</b> value is signed, and zero-extended if the source value is
unsigned. <tt>bool</tt> values are always zero extended into either zero or
one.
</p>

<h5>Example:</h5>

<pre>
  %X = cast int 257 to ubyte              <i>; yields ubyte:1</i>
  %Y = cast int 123 to bool               <i>; yields bool:true</i>
</pre>
</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
   <a name="i_select">'<tt>select</tt>' Instruction</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  &lt;result&gt; = select bool &lt;cond&gt;, &lt;ty&gt; &lt;val1&gt;, &lt;ty&gt; &lt;val2&gt;             <i>; yields ty</i>
</pre>

<h5>Overview:</h5>

<p>
The '<tt>select</tt>' instruction is used to choose one value based on a
condition, without branching.
</p>


<h5>Arguments:</h5>

<p>
The '<tt>select</tt>' instruction requires a boolean value indicating the condition, and two values of the same <a href="#t_firstclass">first class</a> type.
</p>

<h5>Semantics:</h5>

<p>
If the boolean condition evaluates to true, the instruction returns the first
value argument; otherwise, it returns the second value argument.
</p>

<h5>Example:</h5>

<pre>
  %X = select bool true, ubyte 17, ubyte 42          <i>; yields ubyte:17</i>
</pre>
</div>





<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_call">'<tt>call</tt>' Instruction</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  &lt;result&gt; = [tail] call [<a href="#callingconv">cconv</a>] &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
</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>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>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. 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 in the called function, control flow continues with the
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)
  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>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_vaarg">'<tt>vaarg</tt>' Instruction</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  &lt;resultval&gt; = va_arg &lt;va_list*&gt; &lt;arglist&gt;, &lt;argty&gt;
</pre>

<h5>Overview:</h5>

<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 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>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>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>

<p>See the <a href="#int_varargs">variable argument processing</a> section.</p>

</div>

<!-- *********************************************************************** -->
<div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
<!-- *********************************************************************** -->

<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
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
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
function.  Additionally, because intrinsic functions are part of the LLVM
language, it is required that they all be documented here if any are added.</p>


<p>To learn how to add an intrinsic function, please see the <a
href="ExtendingLLVM.html">Extending LLVM Guide</a>.
</p>

</div>

<!-- ======================================================================= -->
<div class="doc_subsection">
  <a name="int_varargs">Variable Argument Handling Intrinsics</a>
</div>

<div class="doc_text">

<p>Variable argument support is defined in LLVM with the <a
 href="#i_vanext"><tt>vanext</tt></a> instruction and these three
intrinsic functions.  These functions are related to the similarly
named macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.</p>

<p>All of these functions operate on arguments that use a
target-specific value type "<tt>va_list</tt>".  The LLVM assembly
language reference manual does not define what this type is, so all
transformations should be prepared to handle intrinsics with any type
used.</p>

<p>This example shows how the <a href="#i_vanext"><tt>vanext</tt></a>
instruction and the variable argument handling intrinsic functions are
used.</p>

<pre>
int %test(int %X, ...) {
  ; Initialize variable argument processing
  %ap = alloca sbyte*
  call void %<a href="#i_va_start">llvm.va_start</a>(sbyte** %ap)

  ; Read a single integer argument
  %tmp = va_arg sbyte** %ap, int

  ; Demonstrate usage of llvm.va_copy and llvm.va_end
  %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** %ap)
  ret int %tmp
}
</pre>
</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
</div>


<div class="doc_text">
<h5>Syntax:</h5>
<pre>  declare void %llvm.va_start(&lt;va_list&gt;* &lt;arglist&gt;)<br></pre>
<h5>Overview:</h5>
<P>The '<tt>llvm.va_start</tt>' intrinsic initializes
<tt>*&lt;arglist&gt;</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 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>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
 <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
</div>

<div class="doc_text">
<h5>Syntax:</h5>
<pre>  declare void %llvm.va_end(&lt;va_list*&gt; &lt;arglist&gt;)<br></pre>
<h5>Overview:</h5>
<p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt>
which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
<h5>Arguments:</h5>
<p>The argument is a <tt>va_list</tt> to destroy.</p>
<h5>Semantics:</h5>
<p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
macro available in C.  In a target-dependent way, it destroys the <tt>va_list</tt>.
Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
 href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
with calls to <tt>llvm.va_end</tt>.</p>
</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  declare void %llvm.va_copy(&lt;va_list&gt;* &lt;destarglist&gt;,
                                          &lt;va_list&gt;* &lt;srcarglist&gt;)
</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>

<h5>Arguments:</h5>

<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 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>

<!-- ======================================================================= -->
<div class="doc_subsection">
  <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
</div>

<div class="doc_text">

<p>
LLVM support for <a href="GarbageCollection.html">Accurate Garbage
Collection</a> requires the implementation and generation of these intrinsics.
These intrinsics allow identification of <a href="#i_gcroot">GC roots on the
stack</a>, as well as garbage collector implementations that require <a
href="#i_gcread">read</a> and <a href="#i_gcwrite">write</a> barriers.
Front-ends for type-safe garbage collected languages should generate these
intrinsics to make use of the LLVM garbage collectors.  For more details, see <a
href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
</p>
</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  declare void %llvm.gcroot(&lt;ty&gt;** %ptrloc, &lt;ty2&gt;* %metadata)
</pre>

<h5>Overview:</h5>

<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>

<p>The first argument specifies the address of a stack object that contains the
root pointer.  The second pointer (which must be either a constant or a global
value address) contains the meta-data to be associated with the root.</p>

<h5>Semantics:</h5>

<p>At runtime, a call to this intrinsics stores a null pointer into the "ptrloc"
location.  At compile-time, the code generator generates information to allow
the runtime to find the pointer at GC safe points.
</p>

</div>


<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  declare sbyte* %llvm.gcread(sbyte** %Ptr)
</pre>

<h5>Overview:</h5>

<p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
locations, allowing garbage collector implementations that require read
barriers.</p>

<h5>Arguments:</h5>

<p>The argument is the address to read from, which should be an address
allocated from the garbage collector.</p>

<h5>Semantics:</h5>

<p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
instruction, but may be replaced with substantially more complex code by the
garbage collector runtime, as needed.</p>

</div>


<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  declare void %llvm.gcwrite(sbyte* %P1, sbyte** %P2)
</pre>

<h5>Overview:</h5>

<p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
locations, allowing garbage collector implementations that require write
barriers (such as generational or reference counting collectors).</p>

<h5>Arguments:</h5>

<p>The first argument is the reference to store, and the second is the heap
location to store to.</p>

<h5>Semantics:</h5>

<p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
instruction, but may be replaced with substantially more complex code by the
garbage collector runtime, as needed.</p>

</div>



<!-- ======================================================================= -->
<div class="doc_subsection">
  <a name="int_codegen">Code Generator Intrinsics</a>
</div>

<div class="doc_text">
<p>
These intrinsics are provided by LLVM to expose special features that may only
be implemented with code generator support.
</p>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  declare void* %llvm.returnaddress(uint &lt;level&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.returnaddress</tt>' intrinsic returns a target-specific value
indicating the return address of the current function or one of its callers.
</p>

<h5>Arguments:</h5>

<p>
The argument to this intrinsic indicates which function to return the address
for.  Zero indicates the calling function, one indicates its caller, etc.  The
argument is <b>required</b> to be a constant integer value.
</p>

<h5>Semantics:</h5>

<p>
The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
the return address of the specified call frame, or zero if it cannot be
identified.  The value returned by this intrinsic is likely to be incorrect or 0
for arguments other than zero, so it should only be used for debugging purposes.
</p>

<p>
Note that calling this intrinsic does not prevent function inlining or other
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_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  declare void* %llvm.frameaddress(uint &lt;level&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.frameaddress</tt>' intrinsic returns the target-specific frame
pointer value for the specified stack frame.
</p>

<h5>Arguments:</h5>

<p>
The argument to this intrinsic indicates which function to return the frame
pointer for.  Zero indicates the calling function, one indicates its caller,
etc.  The argument is <b>required</b> to be a constant integer value.
</p>

<h5>Semantics:</h5>

<p>
The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
the frame address of the specified call frame, or zero if it cannot be
identified.  The value returned by this intrinsic is likely to be incorrect or 0
for arguments other than zero, so it should only be used for debugging purposes.
</p>

<p>
Note that calling this intrinsic does not prevent function inlining or other
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 * &lt;address&gt;,
                                uint &lt;rw&gt;, uint &lt;locality&gt;)
</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 &lt;id&gt; )
</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>
</div>

<div class="doc_text">
<p>
These intrinsics are provided by LLVM to support the implementation of
operating system level code.
</p>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_readport">'<tt>llvm.readport</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  declare &lt;integer type&gt; %llvm.readport (&lt;integer type&gt; &lt;address&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.readport</tt>' intrinsic reads data from the specified hardware
I/O port.
</p>

<h5>Arguments:</h5>

<p>
The argument to this intrinsic indicates the hardware I/O address from which
to read the data.  The address is in the hardware I/O address namespace (as
opposed to being a memory location for memory mapped I/O).
</p>

<h5>Semantics:</h5>

<p>
The '<tt>llvm.readport</tt>' intrinsic reads data from the hardware I/O port
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.
</p>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_writeport">'<tt>llvm.writeport</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  call void (&lt;integer type&gt;, &lt;integer type&gt;)*
            %llvm.writeport (&lt;integer type&gt; &lt;value&gt;,
                             &lt;integer type&gt; &lt;address&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.writeport</tt>' intrinsic writes data to the specified hardware
I/O port.
</p>

<h5>Arguments:</h5>

<p>
The first argument is the value to write to the I/O port.
</p>

<p>
The second argument indicates the hardware I/O address to which data should be
written.  The address is in the hardware I/O address namespace (as opposed to
being a memory location for memory mapped I/O).
</p>

<h5>Semantics:</h5>

<p>
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
value written must be 8, 16, or 32 bits in length.
</p>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_readio">'<tt>llvm.readio</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  declare &lt;result&gt; %llvm.readio (&lt;ty&gt; * &lt;pointer&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
address.
</p>

<h5>Arguments:</h5>

<p>
The argument to this intrinsic is a pointer indicating the memory address from
which to read the data.  The data must be a
<a href="#t_firstclass">first class</a> type.
</p>

<h5>Semantics:</h5>

<p>
The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
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 only support I/O on data types that are 32 bits or less.
</p>

<p>
This intrinsic enforces an in-order memory model for llvm.readio and
llvm.writeio calls on machines that use dynamic scheduling.  Dynamically
scheduled processors may execute loads and stores out of order, re-ordering at
run time accesses to memory mapped I/O registers.  Using these intrinsics
ensures that accesses to memory mapped I/O registers occur in program order.
</p>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_writeio">'<tt>llvm.writeio</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  declare void %llvm.writeio (&lt;ty1&gt; &lt;value&gt;, &lt;ty2&gt; * &lt;pointer&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.writeio</tt>' intrinsic writes data to the specified memory
mapped I/O address.
</p>

<h5>Arguments:</h5>

<p>
The first argument is the value to write to the memory mapped I/O location.
The second argument is a pointer indicating the memory address to which the
data should be written.
</p>

<h5>Semantics:</h5>

<p>
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 only support I/O on data types that are 32 bits or less.
</p>

<p>
This intrinsic enforces an in-order memory model for llvm.readio and
llvm.writeio calls on machines that use dynamic scheduling.  Dynamically
scheduled processors may execute loads and stores out of order, re-ordering at
run time accesses to memory mapped I/O registers.  Using these intrinsics
ensures that accesses to memory mapped I/O registers occur in program order.
</p>

</div>

<!-- ======================================================================= -->
<div class="doc_subsection">
  <a name="int_libc">Standard C Library Intrinsics</a>
</div>

<div class="doc_text">
<p>
LLVM provides intrinsics for a few important standard C library functions.
These intrinsics allow source-language front-ends to pass information about the
alignment of the pointer arguments to the code generator, providing opportunity
for more efficient code generation.
</p>

</div>

<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  declare void %llvm.memcpy(sbyte* &lt;dest&gt;, sbyte* &lt;src&gt;,
                            uint &lt;len&gt;, uint &lt;align&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.memcpy</tt>' intrinsic copies a block of memory from the source
location to the destination location.
</p>

<p>
Note that, unlike the standard libc function, the <tt>llvm.memcpy</tt> intrinsic
does not return a value, and takes an extra alignment argument.
</p>

<h5>Arguments:</h5>

<p>
The first argument is a pointer to the destination, the second is a pointer to
the source.  The third argument is an (arbitrarily sized) integer argument
specifying the number of bytes to copy, and the fourth argument is the alignment
of the source and destination locations.
</p>

<p>
If the call to this intrinisic has an alignment value that is not 0 or 1, then
the caller guarantees that the size of the copy is a multiple of the alignment
and that both the source and destination pointers are aligned to that boundary.
</p>

<h5>Semantics:</h5>

<p>
The '<tt>llvm.memcpy</tt>' intrinsic copies a block of memory from the source
location to the destination location, which are not allowed to overlap.  It
copies "len" bytes of memory over.  If the argument is known to be aligned to
some boundary, this can be specified as the fourth argument, otherwise it should
be set to 0 or 1.
</p>
</div>


<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
  <a name="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>