<li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
<li><a href="#datalayout">Data Layout</a></li>
<li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
+ <li><a href="#volatile">Volatile Memory Accesses</a></li>
</ol>
</li>
<li><a href="#typesystem">Type System</a>
<p>LLVM allows an explicit section to be specified for globals. If the target
supports it, it will emit globals to the section specified.</p>
-<p>An explicit alignment may be specified for a global. If not present, or if
- the alignment is set to zero, the alignment of the global is set by the
- target to whatever it feels convenient. If an explicit alignment is
- specified, the global is forced to have at least that much alignment. All
- alignments must be a power of 2.</p>
+<p>An explicit alignment may be specified for a global, which must be a power
+ of 2. If not present, or if the alignment is set to zero, the alignment of
+ the global is set by the target to whatever it feels convenient. If an
+ explicit alignment is specified, the global is forced to have exactly that
+ alignment. Targets and optimizers are not allowed to over-align the global
+ if the global has an assigned section. In this case, the extra alignment
+ could be observable: for example, code could assume that the globals are
+ densely packed in their section and try to iterate over them as an array,
+ alignment padding would break this iteration.</p>
<p>For example, the following defines a global in a numbered address space with
an initializer, section, and alignment:</p>
</dl>
<p>When constructing the data layout for a given target, LLVM starts with a
- default set of specifications which are then (possibly) overriden by the
+ default set of specifications which are then (possibly) overridden by the
specifications in the <tt>datalayout</tt> keyword. The default specifications
are given in this list:</p>
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="volatile">Volatile Memory Accesses</a>
+</div>
+
+<div class="doc_text">
+
+<p>Certain memory accesses, such as <a href="#i_load"><tt>load</tt></a>s, <a
+href="#i_store"><tt>store</tt></a>s, and <a
+href="#int_memcpy"><tt>llvm.memcpy</tt></a>s may be marked <tt>volatile</tt>.
+The optimizers must not change the number of volatile operations or change their
+order of execution relative to other volatile operations. The optimizers
+<i>may</i> change the order of volatile operations relative to non-volatile
+operations. This is not Java's "volatile" and has no cross-thread
+synchronization behavior.</p>
+
+</div>
+
<!-- *********************************************************************** -->
<div class="doc_section"> <a name="typesystem">Type System</a> </div>
<!-- *********************************************************************** -->
<div class="doc_subsection"><a name="trapvalues">Trap Values</a></div>
<div class="doc_text">
-<p>Trap values are similar to <a href="undefvalues">undef values</a>, however
+<p>Trap values are similar to <a href="#undefvalues">undef values</a>, however
instead of representing an unspecified bit pattern, they represent the
fact that an instruction or constant expression which cannot evoke side
effects has nevertheless detected a condition which results in undefined
- behavior.<p>
+ behavior.</p>
+
+<p>There is currently no way of representing a trap value in the IR; they
+ only exist when produced by operations such as
+ <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p>
-<p>Any non-void instruction or constant expression other than a non-intrinsic
- call, invoke, or phi with a trap operand has trap as its result value.
- Any instruction with a trap operand which may have side effects emits
- those side effects as if it had an undef operand instead.</p>
+<p>Trap value behavior is defined in terms of value <i>dependence</i>:</p>
-<p>For example, an <a href="#i_and"><tt>and</tt></a> of a trap value with
- zero still has a trap value result. Using that value as an index in a
- <a href="#i_getelementptr"><tt>getelementptr</tt></a> yields a trap
- result. Using that result as the address of a
- <a href="#i_store"><tt>store</tt></a> produces undefined behavior.</p>
+<p>
+<ul>
+<li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
+ their operands.</li>
-<p>There is currently no way of representing a trap constant in the IR; they
- only exist when produced by certain instructions, such as an
- <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag
- set, when overflow occurs.</p>
+<li><a href="#i_phi"><tt>Phi</tt></a> nodes depend on the operand corresponding
+ to their dynamic predecessor basic block.</li>
+
+<li>Function arguments depend on the corresponding actual argument values in
+ the dynamic callers of their functions.</li>
+
+<li><a href="#i_call"><tt>Call</tt></a> instructions depend on the
+ <a href="#i_ret"><tt>ret</tt></a> instructions that dynamically transfer
+ control back to them.</li>
+
+<li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the
+ <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_unwind"><tt>unwind</tt></a>,
+ or exception-throwing call instructions that dynamically transfer control
+ back to them.</li>
+
+<li>Non-volatile loads and stores depend on the most recent stores to all of the
+ referenced memory addresses, following the order in the IR
+ (including loads and stores implied by intrinsics such as
+ <a href="#int_memcpy"><tt>@llvm.memcpy</tt></a>.)</li>
+
+<!-- TODO: In the case of multiple threads, this only applies if the store
+ "happens-before" the load or store. -->
+
+<!-- TODO: floating-point exception state -->
+
+<li>An instruction with externally visible side effects depends on the most
+ recent preceding instruction with externally visible side effects, following
+ the order in the IR. (This includes volatile loads and stores.)</li>
+
+<li>An instruction <i>control-depends</i> on a
+ <a href="#terminators">terminator instruction</a>
+ if the terminator instruction has multiple successors and the instruction
+ is always executed when control transfers to one of the successors, and
+ may not be executed when control is transfered to another.</li>
+
+<li>Dependence is transitive.</li>
+
+</ul>
+</p>
+
+<p>Whenever a trap value is generated, all values which depend on it evaluate
+ to trap. If they have side effects, the evoke their side effects as if each
+ operand with a trap value were undef. If they have externally-visible side
+ effects, the behavior is undefined.</p>
+
+<p>Here are some examples:</p>
+
+<div class="doc_code">
+<pre>
+entry:
+ %trap = sub nuw i32 0, 1 ; Results in a trap value.
+ %still_trap = and i32 %trap, 0 ; Whereas (and i32 undef, 0) would return 0.
+ %trap_yet_again = getelementptr i32* @h, i32 %still_trap
+ store i32 0, i32* %trap_yet_again ; undefined behavior
+
+ store i32 %trap, i32* @g ; Trap value conceptually stored to memory.
+ %trap2 = load i32* @g ; Returns a trap value, not just undef.
+
+ volatile store i32 %trap, i32* @g ; External observation; undefined behavior.
+
+ %narrowaddr = bitcast i32* @g to i16*
+ %wideaddr = bitcast i32* @g to i64*
+ %trap3 = load 16* %narrowaddr ; Returns a trap value.
+ %trap4 = load i64* %widaddr ; Returns a trap value.
+
+ %cmp = icmp i32 slt %trap, 0 ; Returns a trap value.
+ %br i1 %cmp, %true, %end ; Branch to either destination.
+
+true:
+ volatile store i32 0, i32* @g ; This is control-dependent on %cmp, so
+ ; it has undefined behavior.
+ br label %end
+
+end:
+ %p = phi i32 [ 0, %entry ], [ 1, %true ]
+ ; Both edges into this PHI are
+ ; control-dependent on %cmp, so this
+ ; always results in a trap value.
+
+ volatile store i32 0, i32* @g ; %end is control-equivalent to %entry
+ ; so this is defined (ignoring earlier
+ ; undefined behavior in this example).
+</pre>
+</div>
</div>
attached to it that contains a constant integer. If present, the code
generator will use the integer as the location cookie value when report
errors through the LLVMContext error reporting mechanisms. This allows a
- front-end to corrolate backend errors that occur with inline asm back to the
+ front-end to correlate backend errors that occur with inline asm back to the
source code that produced it. For example:</p>
<div class="doc_code">
</div>
<div class="doc_text">
-
-<p>TODO: Describe this.</p>
+<pre>
+%0 = type { i32, void ()* }
+@llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
+</pre>
+<p>The <tt>@llvm.global_ctors</tt> array contains a list of constructor functions and associated priorities. The functions referenced by this array will be called in ascending order of priority (i.e. lowest first) when the module is loaded. The order of functions with the same priority is not defined.
+</p>
</div>
</div>
<div class="doc_text">
+<pre>
+%0 = type { i32, void ()* }
+@llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
+</pre>
-<p>TODO: Describe this.</p>
+<p>The <tt>@llvm.global_dtors</tt> array contains a list of destructor functions and associated priorities. The functions referenced by this array will be called in descending order of priority (i.e. highest first) when the module is loaded. The order of functions with the same priority is not defined.
+</p>
</div>
from which to load. The pointer must point to
a <a href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the
- number or order of execution of this <tt>load</tt> with other
- volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
- instructions.</p>
+ number or order of execution of this <tt>load</tt> with other <a
+ href="#volatile">volatile operations</a>.</p>
<p>The optional constant <tt>align</tt> argument specifies the alignment of the
operation (that is, the alignment of the memory address). A value of 0 or an
and an address at which to store it. The type of the
'<tt><pointer></tt>' operand must be a pointer to
the <a href="#t_firstclass">first class</a> type of the
- '<tt><value></tt>' 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>
+ '<tt><value></tt>' 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 <a
+ href="#volatile">volatile operations</a>.</p>
<p>The optional constant "align" argument specifies the alignment of the
operation (that is, the alignment of the memory address). A value of 0 or an
then the caller guarantees that both the source and destination pointers are
aligned to that boundary.</p>
-<p>Volatile accesses should not be deleted if dead, but the access behavior is
- not very cleanly specified and it is unwise to depend on it.</p>
+<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+ <tt>llvm.memcpy</tt> call is a <a href="#volatile">volatile operation</a>.
+ The detailed access behavior is not very cleanly specified and it is unwise
+ to depend on it.</p>
<h5>Semantics:</h5>
then the caller guarantees that the source and destination pointers are
aligned to that boundary.</p>
-<p>Volatile accesses should not be deleted if dead, but the access behavior is
- not very cleanly specified and it is unwise to depend on it.</p>
+<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+ <tt>llvm.memmove</tt> call is a <a href="#volatile">volatile operation</a>.
+ The detailed access behavior is not very cleanly specified and it is unwise
+ to depend on it.</p>
<h5>Semantics:</h5>
then the caller guarantees that the destination pointer is aligned to that
boundary.</p>
-<p>Volatile accesses should not be deleted if dead, but the access behavior is
- not very cleanly specified and it is unwise to depend on it.</p>
+<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+ <tt>llvm.memset</tt> call is a <a href="#volatile">volatile operation</a>.
+ The detailed access behavior is not very cleanly specified and it is unwise
+ to depend on it.</p>
<h5>Semantics:</h5>
<p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting
projects / oota-llvm.git / blobdiff