what is considered 'well formed'. For example, the following instruction is
syntactically okay, but not well formed:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%x = <a href="#i_add">add</a> i32 1, %x
</pre>
-</div>
<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
<p>The easy way:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%result = <a href="#i_mul">mul</a> i32 %X, 8
</pre>
-</div>
<p>After strength reduction:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%result = <a href="#i_shl">shl</a> i32 %X, i8 3
</pre>
-</div>
<p>And the hard way:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%0 = <a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i>
%1 = <a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i>
%result = <a href="#i_add">add</a> i32 %1, %1
</pre>
-</div>
<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
lexical features of LLVM:</p>
forward declarations, and merges symbol table entries. Here is an example of
the "hello world" module:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
<i>; Declare the string constant as a global constant.</i>
<a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i>
!1 = metadata !{i32 41}
!foo = !{!1, null}
</pre>
-</div>
<p>This example is made up of a <a href="#globalvars">global variable</a> named
"<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function,
it easier to read the IR and make the IR more condensed (particularly when
recursive types are involved). An example of a name specification is:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%mytype = type { %mytype*, i32 }
</pre>
-</div>
<p>You may give a name to any <a href="#typesystem">type</a> except
"<a href="t_void">void</a>". Type name aliases may be used anywhere a type
<p>For example, the following defines a global in a numbered address space with
an initializer, section, and alignment:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
@G = addrspace(5) constant float 1.0, section "foo", align 4
</pre>
-</div>
</div>
alignments must be a power of 2.</p>
<h5>Syntax:</h5>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
[<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>]
<ResultType> @<FunctionName> ([argument list])
[<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N]
[<a href="#gc">gc</a>] { ... }
</pre>
-</div>
</div>
optional <a href="#visibility">visibility style</a>.</p>
<h5>Syntax:</h5>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
@<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
</pre>
-</div>
</div>
a named metadata.</p>
<h5>Syntax:</h5>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
+; An unnamed metadata node, which is referenced by the named metadata.
!1 = metadata !{metadata !"one"}
+; A named metadata.
!name = !{null, !1}
</pre>
-</div>
</div>
multiple parameter attributes are needed, they are space separated. For
example:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
declare i32 @printf(i8* noalias nocapture, ...)
declare i32 @atoi(i8 zeroext)
declare signext i8 @returns_signed_char()
</pre>
-</div>
<p>Note that any attributes for the function result (<tt>nounwind</tt>,
<tt>readonly</tt>) come immediately after the argument list.</p>
<dt><tt><b><a name="noalias">noalias</a></b></tt></dt>
<dd>This indicates that pointer values
<a href="#pointeraliasing"><i>based</i></a> on the argument or return
- value do not alias pointer values which are not <i>based</i> on it.
+ value do not alias pointer values which are not <i>based</i> on it,
+ ignoring certain "irrelevant" dependencies.
+ For a call to the parent function, dependencies between memory
+ references from before or after the call and from those during the call
+ are "irrelevant" to the <tt>noalias</tt> keyword for the arguments and
+ return value used in that call.
The caller shares the responsibility with the callee for ensuring that
these requirements are met.
For further details, please see the discussion of the NoAlias response in
- <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.</dd>
+ <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.<br>
+<br>
+ Note that this definition of <tt>noalias</tt> is intentionally
+ similar to the definition of <tt>restrict</tt> in C99 for function
+ arguments, though it is slightly weaker.
+<br>
+ For function return values, C99's <tt>restrict</tt> is not meaningful,
+ while LLVM's <tt>noalias</tt> is.
+ </dd>
<dt><tt><b><a name="nocapture">nocapture</a></b></tt></dt>
<dd>This indicates that the callee does not make any copies of the pointer
<p>Each function may specify a garbage collector name, which is simply a
string:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
define void @f() gc "name" { ... }
</pre>
-</div>
<p>The compiler declares the supported values of <i>name</i>. Specifying a
collector which will cause the compiler to alter its output in order to
<p>Function attributes are simple keywords that follow the type specified. If
multiple attributes are needed, they are space separated. For example:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
define void @f() noinline { ... }
define void @f() alwaysinline { ... }
define void @f() alwaysinline optsize { ... }
define void @f() optsize { ... }
</pre>
-</div>
<dl>
<dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt>
this function is desirable (such as the "inline" keyword in C/C++). It
is just a hint; it imposes no requirements on the inliner.</dd>
+ <dt><tt><b>naked</b></tt></dt>
+ <dd>This attribute disables prologue / epilogue emission for the function.
+ This can have very system-specific consequences.</dd>
+
+ <dt><tt><b>noimplicitfloat</b></tt></dt>
+ <dd>This attributes disables implicit floating point instructions.</dd>
+
<dt><tt><b>noinline</b></tt></dt>
<dd>This attribute indicates that the inliner should never inline this
function in any situation. This attribute may not be used together with
the <tt>alwaysinline</tt> attribute.</dd>
- <dt><tt><b>optsize</b></tt></dt>
- <dd>This attribute suggests that optimization passes and code generator passes
- make choices that keep the code size of this function low, and otherwise
- do optimizations specifically to reduce code size.</dd>
+ <dt><tt><b>noredzone</b></tt></dt>
+ <dd>This attribute indicates that the code generator should not use a red
+ zone, even if the target-specific ABI normally permits it.</dd>
<dt><tt><b>noreturn</b></tt></dt>
<dd>This function attribute indicates that the function never returns
unwind or exceptional control flow. If the function does unwind, its
runtime behavior is undefined.</dd>
+ <dt><tt><b>optsize</b></tt></dt>
+ <dd>This attribute suggests that optimization passes and code generator passes
+ make choices that keep the code size of this function low, and otherwise
+ do optimizations specifically to reduce code size.</dd>
+
<dt><tt><b>readnone</b></tt></dt>
<dd>This attribute indicates that the function computes its result (or decides
to unwind an exception) based strictly on its arguments, without
function that doesn't have an <tt>sspreq</tt> attribute or which has
an <tt>ssp</tt> attribute, then the resulting function will have
an <tt>sspreq</tt> attribute.</dd>
-
- <dt><tt><b>noredzone</b></tt></dt>
- <dd>This attribute indicates that the code generator should not use a red
- zone, even if the target-specific ABI normally permits it.</dd>
-
- <dt><tt><b>noimplicitfloat</b></tt></dt>
- <dd>This attributes disables implicit floating point instructions.</dd>
-
- <dt><tt><b>naked</b></tt></dt>
- <dd>This attribute disables prologue / epilogue emission for the function.
- This can have very system-specific consequences.</dd>
</dl>
</div>
concatenated by LLVM and treated as a single unit, but may be separated in
the <tt>.ll</tt> file if desired. The syntax is very simple:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
module asm "inline asm code goes here"
module asm "more can go here"
</pre>
-</div>
<p>The strings can contain any character by escaping non-printable characters.
The escape sequence used is simply "\xx" where "xx" is the two digit hex code
data is to be laid out in memory. The syntax for the data layout is
simply:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
target datalayout = "<i>layout specification</i>"
</pre>
-</div>
<p>The <i>layout specification</i> consists of a list of specifications
separated by the minus sign character ('-'). Each specification starts with
</div>
-</div>
-
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
have <a href="#t_pointer">pointer</a> type. For example, the following is a
legal LLVM file:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
@X = global i32 17
@Y = global i32 42
@Z = global [2 x i32*] [ i32* @X, i32* @Y ]
</pre>
-</div>
</div>
surprising) transformations that are valid (in pseudo IR):</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = add %X, undef
%B = sub %X, undef
%C = xor %X, undef
%B = undef
%C = undef
</pre>
-</div>
<p>This is safe because all of the output bits are affected by the undef bits.
Any output bit can have a zero or one depending on the input bits.</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = or %X, undef
%B = and %X, undef
Safe:
%A = undef
%B = undef
</pre>
-</div>
<p>These logical operations have bits that are not always affected by the input.
For example, if "%X" has a zero bit, then the output of the 'and' operation will
the undef operand to the or could be set, allowing the or to be folded to
-1.</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = select undef, %X, %Y
%B = select undef, 42, %Y
%C = select %X, %Y, undef
%B = undef
%C = undef
</pre>
-</div>
<p>This set of examples show that undefined select (and conditional branch)
conditions can go "either way" but they have to come from one of the two
%Y, allowing the whole select to be eliminated.</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = xor undef, undef
%B = undef
%E = undef
%F = undef
</pre>
-</div>
<p>This example points out that two undef operands are not necessarily the same.
This can be surprising to people (and also matches C semantics) where they
to have the same semantics or the core LLVM "replace all uses with" concept
would not hold.</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%A = fdiv undef, %X
%B = fdiv %X, undef
Safe:
%A = undef
b: unreachable
</pre>
-</div>
<p>These examples show the crucial difference between an <em>undefined
value</em> and <em>undefined behavior</em>. An undefined value (like undef) is
it occurs in dead code.
</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
a: store undef -> %X
b: store %X -> undef
Safe:
a: <deleted>
b: unreachable
</pre>
-</div>
<p>These examples reiterate the fdiv example: a store "of" an undefined value
can be assumed to not have any effect: we can assume that the value is
<p>Trap value behavior is defined in terms of value <i>dependence</i>:</p>
-<p>
<ul>
<li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
their operands.</li>
<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>
+ the order in the IR. (This includes
+ <a href="#volatile">volatile operations</a>.)</li>
<li>An instruction <i>control-depends</i> on a
<a href="#terminators">terminator instruction</a>
<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
<p>Here are some examples:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
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.
; so this is defined (ignoring earlier
; undefined behavior in this example).
</pre>
-</div>
</div>
<dt><b><tt>zext (CST to TYPE)</tt></b></dt>
<dd>Zero extend a constant to another type. The bit size of CST must be
- smaller or equal to the bit size of TYPE. Both types must be
- integers.</dd>
+ smaller than the bit size of TYPE. Both types must be integers.</dd>
<dt><b><tt>sext (CST to TYPE)</tt></b></dt>
<dd>Sign extend a constant to another type. The bit size of CST must be
- smaller or equal to the bit size of TYPE. Both types must be
- integers.</dd>
+ smaller than the bit size of TYPE. Both types must be integers.</dd>
<dt><b><tt>fptrunc (CST to TYPE)</tt></b></dt>
<dd>Truncate a floating point constant to another floating point type. The
containing the asm needs to align its stack conservatively. An example
inline assembler expression is:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
i32 (i32) asm "bswap $0", "=r,r"
</pre>
-</div>
<p>Inline assembler expressions may <b>only</b> be used as the callee operand of
a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we
have:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
</pre>
-</div>
<p>Inline asms with side effects not visible in the constraint list must be
marked as having side effects. This is done through the use of the
'<tt>sideeffect</tt>' keyword, like so:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
call void asm sideeffect "eieio", ""()
</pre>
-</div>
<p>In some cases inline asms will contain code that will not work unless the
stack is aligned in some way, such as calls or SSE instructions on x86,
contain and should generate its usual stack alignment code in the prologue
if the '<tt>alignstack</tt>' keyword is present:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
call void asm alignstack "eieio", ""()
</pre>
-</div>
<p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come
first.</p>
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">
-<pre>
+<pre class="doc_code">
call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
...
!42 = !{ i32 1234567 }
</pre>
-</div>
<p>It is up to the front-end to make sense of the magic numbers it places in the
IR.</p>
example: "<tt>!foo = metadata !{!4, !3}</tt>".
<p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt>
- function is using two metadata arguments.
+ function is using two metadata arguments.</p>
- <div class="doc_code">
- <pre>
+ <pre class="doc_code">
call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
</pre>
- </div></p>
<p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is
- attached with <tt>add</tt> instruction using <tt>!dbg</tt> identifier.
+ attached with <tt>add</tt> instruction using <tt>!dbg</tt> identifier.</p>
- <div class="doc_code">
- <pre>
+ <pre class="doc_code">
%indvar.next = add i64 %indvar, 1, !dbg !21
</pre>
- </div></p>
</div>
<p>If the <tt>exact</tt> keyword is present, the result value of the
<tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would
- be rounded or if overflow would occur.</p>
+ be rounded.</p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
- store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
- volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
+ store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
+ volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
</pre>
<h5>Overview:</h5>
produce less efficient code. An alignment of 1 is always safe.</p>
<p>The optional !nontemporal metadata must reference a single metatadata
- name <index> corresponding to a metadata node with one i32 entry of
+ name <index> corresponding to a metadata node with one i32 entry of
value 1. The existence of the !nontemporal metatadata on the
instruction tells the optimizer and code generator that this load is
not expected to be reused in the cache. The code generator may
<p>For example, let's consider a C code fragment and how it gets compiled to
LLVM:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
struct RT {
char A;
int B[10][20];
return &s[1].Z.B[5][13];
}
</pre>
-</div>
<p>The LLVM code generated by the GCC frontend is:</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
%RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 }
%ST = <a href="#namedtypes">type</a> { i32, double, %RT }
ret i32* %reg
}
</pre>
-</div>
<h5>Semantics:</h5>
<p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
instruction and the variable argument handling intrinsic functions are
used.</p>
-<div class="doc_code">
-<pre>
+<pre class="doc_code">
define i32 @test(i32 %X, ...) {
; Initialize variable argument processing
%ap = alloca i8*
declare void @llvm.va_copy(i8*, i8*)
declare void @llvm.va_end(i8*)
</pre>
-</div>
</div>
pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as
follows:</p>
-<div class="doc_code">
-<pre>
+<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)
%fp = bitcast i8* %p to i32 (i32, i32)*
</pre>
-</div>
<p>The call <tt>%val = call i32 %fp(i32 %x, i32 %y)</tt> is then equivalent
to <tt>%val = call i32 %f(i8* %nval, i32 %x, i32 %y)</tt>.</p>
projects / oota-llvm.git / blobdiff