LangRef.html

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

<div class="doc_text">

<h5>Syntax:</h5>

<pre>
  call sbyte* (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>
  call void (sbyte*, sbyte**)* %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>
  call 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 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>
  call 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 that of the obvious
source-language caller.
</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>
  call &lt;integer type&gt; (&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>
  call &lt;result&gt; (&lt;ty&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>
  call void (&lt;ty1&gt;, &lt;ty2&gt;*)* %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>
  call void (sbyte*, sbyte*, uint, uint)* %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>
</div>

<div class="doc_text">

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

<h5>Overview:</h5>

<p>
The '<tt>llvm.memmove</tt>' intrinsic moves a block of memory from the source
location to the destination location. It is similar to the '<tt>llvm.memcpy</tt>' 
intrinsic but allows the two memory locations to overlap.
</p>

<p>
Note that, unlike the standard libc function, the <tt>llvm.memmove</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.memmove</tt>' intrinsic copies a block of memory from the source
location to the destination location, which may 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_memset">'<tt>llvm.memset</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  call void (sbyte*, ubyte, uint, uint)* %llvm.memset(sbyte* &lt;dest&gt;, ubyte &lt;val&gt;,
                                                      uint &lt;len&gt;, uint &lt;align&gt;)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.memset</tt>' intrinsic fills a block of memory with a particular
byte value.
</p>

<p>
Note that, unlike the standard libc function, the <tt>llvm.memset</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 to fill, the second is the
byte value to fill it with, the third argument is an (arbitrarily sized) integer
argument specifying the number of bytes to fill, and the fourth argument is the
known alignment of destination location.
</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 the destination pointer is aligned to that boundary.
</p>

<h5>Semantics:</h5>

<p>
The '<tt>llvm.memset</tt>' intrinsic fills "len" bytes of memory starting at the
destination location.  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_isnan">'<tt>llvm.isnan</tt>' Intrinsic</a>
</div>

<div class="doc_text">

<h5>Syntax:</h5>
<pre>
  call bool (&lt;float or double&gt;)* %llvm.isnan(&lt;float or double&gt; Val)
</pre>

<h5>Overview:</h5>

<p>
The '<tt>llvm.isnan</tt>' intrinsic returns true if the specific floating point
value is a NAN.
</p>

<h5>Arguments:</h5>

<p>
The argument is a floating point number.
</p>

<h5>Semantics:</h5>

<p>
If the argument is a SNAN or QNAN, it returns true, otherwise false.
</p>
</div>




<!-- ======================================================================= -->
<div class="doc_subsection">
  <a name="int_debugger">Debugger Intrinsics</a>
</div>

<div class="doc_text">
<p>
The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
are described in the <a
href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
Debugging</a> document.
</p>
</div>


<!-- *********************************************************************** -->
<hr>
<address>
  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
  src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
  <a href="http://validator.w3.org/check/referer"><img
  src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>

  <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
  <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
  Last modified: $Date$
</address>
</body>
</html>