</li>
<li><a href="#int_debugger">Debugger intrinsics</a></li>
<li><a href="#int_eh">Exception Handling intrinsics</a></li>
- <li><a href="#int_trampoline">Trampoline Intrinsic</a>
+ <li><a href="#int_trampoline">Trampoline Intrinsics</a>
<ol>
<li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
+ <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</a></li>
</ol>
</li>
<li><a href="#int_atomics">Atomic intrinsics</a>
ways to create them, and we define LLVM IR's behavior in their presence. This
model is inspired by the C++0x memory model.</p>
+<p>For a more informal introduction to this model, see the
+<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.
+
<p>We define a <i>happens-before</i> partial order as the least partial order
that</p>
<ul>
<p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows:
<ul>
- <li>If there is no write to the same byte that happens before
+ <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile
+ is supposed to give guarantees which can support
+ <code>sig_atomic_t</code> in C/C++, and may be used for accesses to
+ addresses which do not behave like normal memory. It does not generally
+ provide cross-thread synchronization.)
+ <li>Otherwise, if there is no write to the same byte that happens before
<var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns
<tt>undef</tt> for that byte.
<li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write,
that determines which other atomic instructions on the same address they
<i>synchronize with</i>. These semantics are borrowed from Java and C++0x,
but are somewhat more colloquial. If these descriptions aren't precise enough,
-check those specs. <a href="#i_fence"><code>fence</code></a> instructions
+check those specs (see spec references in the
+<a href="Atomic.html#introduction">atomics guide</a>).
+<a href="#i_fence"><code>fence</code></a> instructions
treat these orderings somewhat differently since they don't take an address.
See that instruction's documentation for details.</p>
+<p>For a simpler introduction to the ordering constraints, see the
+<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p>
+
<dl>
<dt><code>unordered</code></dt>
<dd>The set of values that can be read is governed by the happens-before
<code>monotonic</code> (or stronger) operations on the same address. If an
address is written <code>monotonic</code>ally by one thread, and other threads
<code>monotonic</code>ally read that address repeatedly, the other threads must
-eventually see the write. This is intended to model C++'s relaxed atomic
-variables.</dd>
+eventually see the write. This corresponds to the C++0x/C1x
+<code>memory_order_relaxed</code>.</dd>
<dt><code>acquire</code></dt>
-<dd>In addition to the guarantees of <code>monotonic</code>, if this operation
-reads a value written by a <code>release</code> atomic operation, it
-<i>synchronizes-with</i> that operation.</dd>
-<dt><code>release</code></dt>
<dd>In addition to the guarantees of <code>monotonic</code>,
-a <i>synchronizes-with</i> edge may be formed by an <code>acquire</code>
-operation.</dd>
+a <i>synchronizes-with</i> edge may be formed with a <code>release</code>
+operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd>
+<dt><code>release</code></dt>
+<dd>In addition to the guarantees of <code>monotonic</code>, if this operation
+writes a value which is subsequently read by an <code>acquire</code> operation,
+it <i>synchronizes-with</i> that operation. (This isn't a complete
+description; see the C++0x definition of a release sequence.) This corresponds
+to the C++0x/C1x <code>memory_order_release</code>.</dd>
<dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an
-<code>acquire</code> and <code>release</code> operation on its address.</dd>
+<code>acquire</code> and <code>release</code> operation on its address.
+This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd>
<dt><code>seq_cst</code> (sequentially consistent)</dt><dd>
<dd>In addition to the guarantees of <code>acq_rel</code>
(<code>acquire</code> for an operation which only reads, <code>release</code>
sequentially-consistent operations on all addresses, which is consistent with
the <i>happens-before</i> partial order and with the modification orders of
all the affected addresses. Each sequentially-consistent read sees the last
-preceding write to the same address in this global order. This is intended
-to model C++'s sequentially-consistent atomic variables and Java's volatile
-shared variables.</dd>
+preceding write to the same address in this global order. This corresponds
+to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd>
</dl>
<p id="singlethread">If an atomic operation is marked <code>singlethread</code>,
<p>Structures may optionally be "packed" structures, which indicate that the
alignment of the struct is one byte, and that there is no padding between
- the elements. In non-packed structs, padding between field types is defined
- by the target data string to match the underlying processor.</p>
-
-<p>Structures can either be "anonymous" or "named". An anonymous structure is
- defined inline with other types (e.g. <tt>{i32, i32}*</tt>) and a named types
- are always defined at the top level with a name. Anonmyous types are uniqued
- by their contents and can never be recursive since there is no way to write
- one. Named types can be recursive.
+ the elements. In non-packed structs, padding between field types is inserted
+ as defined by the TargetData string in the module, which is required to match
+ what the underlying processor expects.</p>
+
+<p>Structures can either be "literal" or "identified". A literal structure is
+ defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified
+ types are always defined at the top level with a name. Literal types are
+ uniqued by their contents and can never be recursive or opaque since there is
+ no way to write one. Identified types can be recursive, can be opaqued, and are
+ never uniqued.
</p>
<h5>Syntax:</h5>
<pre>
- %T1 = type { <type list> } <i>; Named normal struct type</i>
- %T2 = type <{ <type list> }> <i>; Named packed struct type</i>
+ %T1 = type { <type list> } <i>; Identified normal struct type</i>
+ %T2 = type <{ <type list> }> <i>; Identified packed struct type</i>
</pre>
<h5>Examples:</h5>
<h5>Syntax:</h5>
<pre>
- <result> = [volatile] load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
- <result> = atomic [volatile] load <ty>* <pointer> [singlethread] <ordering>, align <alignment>
+ <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
!<index> = !{ i32 1 }
</pre>
<h5>Syntax:</h5>
<pre>
- [volatile] store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
- atomic [volatile] store <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> <i>; yields {void}</i>
+ store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
+ store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> <i>; yields {void}</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- [volatile] cmpxchg <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i>
+ cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
- [volatile] atomicrmw <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> <i>; yields {ty}</i>
+ atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> <i>; yields {ty}</i>
</pre>
<h5>Overview:</h5>
When indexing into a (optionally packed) structure, only <tt>i32</tt>
integer <b>constants</b> are allowed. When indexing into an array, pointer
or vector, integers of any width are allowed, and they are not required to be
- constant.</p>
+ constant. These integers are treated as signed values where relevant.</p>
<p>For example, let's consider a C code fragment and how it gets compiled to
LLVM:</p>
base pointer is not an <i>in bounds</i> address of an allocated object,
or if any of the addresses that would be formed by successive addition of
the offsets implied by the indices to the base address with infinitely
- precise arithmetic are not an <i>in bounds</i> address of that allocated
- object. The <i>in bounds</i> addresses for an allocated object are all
- the addresses that point into the object, plus the address one byte past
- the end.</p>
+ precise signed arithmetic are not an <i>in bounds</i> address of that
+ allocated object. The <i>in bounds</i> addresses for an allocated object
+ are all the addresses that point into the object, plus the address one
+ byte past the end.</p>
<p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
- the base address with silently-wrapping two's complement arithmetic, and
- the result value of the <tt>getelementptr</tt> may be outside the object
- pointed to by the base pointer. The result value may not necessarily be
- used to access memory though, even if it happens to point into allocated
- storage. See the <a href="#pointeraliasing">Pointer Aliasing Rules</a>
- section for more information.</p>
+ the base address with silently-wrapping two's complement arithmetic. If the
+ offsets have a different width from the pointer, they are sign-extended or
+ truncated to the width of the pointer. The result value of the
+ <tt>getelementptr</tt> may be outside the object pointed to by the base
+ pointer. The result value may not necessarily be used to access memory
+ though, even if it happens to point into allocated storage. See the
+ <a href="#pointeraliasing">Pointer Aliasing Rules</a> section for more
+ information.</p>
<p>The getelementptr instruction is often confusing. For some more insight into
how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
<resultval> = landingpad <somety> personality <type> <pers_fn> cleanup <clause>*
<clause> := catch <type> <value>
- <clause> := filter <type> <value> {, <type> <value>}*
+ <clause> := filter <array constant type> <array constant>
</pre>
<h5>Overview:</h5>
<tt>cleanup</tt> flag indicates that the landing pad block is a cleanup.</p>
<p>A <tt>clause</tt> begins with the clause type — <tt>catch</tt>
- or <tt>filter</tt> — and contains a list of global variables
- representing the "types" that may be caught or filtered respectively. The
- '<tt>landingpad</tt>' instruction must contain <em>at least</em>
+ or <tt>filter</tt> — and contains the global variable representing the
+ "type" that may be caught or filtered respectively. Unlike the
+ <tt>catch</tt> clause, the <tt>filter</tt> clause takes an array constant as
+ its argument. Use "<tt>[0 x i8**] undef</tt>" for a filter which cannot
+ throw. The '<tt>landingpad</tt>' instruction must contain <em>at least</em>
one <tt>clause</tt> or the <tt>cleanup</tt> flag.</p>
<h5>Semantics:</h5>
catch i8** @_ZTIi
;; A landing pad that is a cleanup.
%res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
- cleanup
+ cleanup
;; A landing pad which can catch an integer and can only throw a double.
%res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
catch i8** @_ZTIi
- filter i8** @_ZTId
+ filter [1 x i8**] [@_ZTId]
</pre>
</div>
<!-- ======================================================================= -->
<h3>
- <a name="int_trampoline">Trampoline Intrinsic</a>
+ <a name="int_trampoline">Trampoline Intrinsics</a>
</h3>
<div>
-<p>This intrinsic makes it possible to excise one parameter, marked with
+<p>These intrinsics make it possible to excise one parameter, marked with
the <a href="#nest"><tt>nest</tt></a> attribute, from a function.
The result is a callable
function pointer lacking the nest parameter - the caller does not need to
<pre class="doc_code">
%tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
%tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
- %p = call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval)
+ call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
+ %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
%fp = bitcast i8* %p to i32 (i32, i32)*
</pre>
<h5>Syntax:</h5>
<pre>
- declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
+ declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
</pre>
<h5>Overview:</h5>
-<p>This fills the memory pointed to by <tt>tramp</tt> with code and returns a
- function pointer suitable for executing it.</p>
+<p>This fills the memory pointed to by <tt>tramp</tt> with executable code,
+ turning it into a trampoline.</p>
<h5>Arguments:</h5>
<p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all
<h5>Semantics:</h5>
<p>The block of memory pointed to by <tt>tramp</tt> is filled with target
- dependent code, turning it into a function. A pointer to this function is
- returned, but needs to be bitcast to an <a href="#int_trampoline">appropriate
- function pointer type</a> before being called. The new function's signature
- is the same as that of <tt>func</tt> with any arguments marked with
- the <tt>nest</tt> attribute removed. At most one such <tt>nest</tt> argument
- is allowed, and it must be of pointer type. Calling the new function is
- equivalent to calling <tt>func</tt> with the same argument list, but
- with <tt>nval</tt> used for the missing <tt>nest</tt> argument. If, after
- calling <tt>llvm.init.trampoline</tt>, the memory pointed to
- by <tt>tramp</tt> is modified, then the effect of any later call to the
- returned function pointer is undefined.</p>
+ dependent code, turning it into a function. Then <tt>tramp</tt> needs to be
+ passed to <a href="#int_at">llvm.adjust.trampoline</a> to get a pointer
+ which can be <a href="#int_trampoline">bitcast (to a new function) and
+ called</a>. The new function's signature is the same as that of
+ <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute
+ removed. At most one such <tt>nest</tt> argument is allowed, and it must be of
+ pointer type. Calling the new function is equivalent to calling <tt>func</tt>
+ with the same argument list, but with <tt>nval</tt> used for the missing
+ <tt>nest</tt> argument. If, after calling <tt>llvm.init.trampoline</tt>, the
+ memory pointed to by <tt>tramp</tt> is modified, then the effect of any later call
+ to the returned function pointer is undefined.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="int_at">
+ '<tt>llvm.adjust.trampoline</tt>' Intrinsic
+ </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+ declare i8* @llvm.adjust.trampoline(i8* <tramp>)
+</pre>
+
+<h5>Overview:</h5>
+<p>This performs any required machine-specific adjustment to the address of a
+ trampoline (passed as <tt>tramp</tt>).</p>
+
+<h5>Arguments:</h5>
+<p><tt>tramp</tt> must point to a block of memory which already has trampoline code
+ filled in by a previous call to <a href="#int_it"><tt>llvm.init.trampoline</tt>
+ </a>.</p>
+
+<h5>Semantics:</h5>
+<p>On some architectures the address of the code to be executed needs to be
+ different to the address where the trampoline is actually stored. This
+ intrinsic returns the executable address corresponding to <tt>tramp</tt>
+ after performing the required machine specific adjustments.
+ The pointer returned can then be <a href="#int_trampoline"> bitcast and
+ executed</a>.
+</p>
</div>
<h5>Semantics:</h5>
<p>This intrinsic allows annotation of local variables with arbitrary strings.
This can be useful for special purpose optimizations that want to look for
- these annotations. These have no other defined use, they are ignored by code
+ these annotations. These have no other defined use; they are ignored by code
generation and optimization.</p>
</div>
<h5>Semantics:</h5>
<p>This intrinsic allows annotations to be put on arbitrary expressions with
arbitrary strings. This can be useful for special purpose optimizations that
- want to look for these annotations. These have no other defined use, they
+ want to look for these annotations. These have no other defined use; they
are ignored by code generation and optimization.</p>
</div>
projects / oota-llvm.git / blobdiff