<dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt>: </dt>
<dd>Similar to private, but the symbol is passed through the assembler and
- removed by the linker after evaluation.</dd>
+ removed by the linker after evaluation. Note that (unlike private
+ symbols) linker_private symbols are subject to coalescing by the linker:
+ weak symbols get merged and redefinitions are rejected. However, unlike
+ normal strong symbols, they are removed by the linker from the final
+ linked image (executable or dynamic library).</dd>
<dt><tt><b><a name="linkage_internal">internal</a></b></tt>: </dt>
<dd>Similar to private, but the value shows as a local symbol
function into callers whenever possible, ignoring any active inlining size
threshold for this caller.</dd>
+ <dt><tt>inlinehint</tt></dt>
+ <dd>This attribute indicates that the source code contained a hint that inlining
+ 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>noinline</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
<div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
<div class="doc_text">
-<p>The string '<tt>undef</tt>' is recognized as a type-less constant that has no
- specific value. Undefined values may be of any type and be used anywhere a
- constant is permitted.</p>
+<p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
+ indicates that the user of the value may recieve an unspecified bit-pattern.
+ Undefined values may be of any type (other than label or void) and be used
+ anywhere a constant is permitted.</p>
+
+<p>Undefined values are useful because they indicate to the compiler that the
+ program is well defined no matter what value is used. This gives the
+ compiler more freedom to optimize. Here are some examples of (potentially
+ surprising) transformations that are valid (in pseudo IR):</p>
+
+
+<div class="doc_code">
+<pre>
+ %A = add %X, undef
+ %B = sub %X, undef
+ %C = xor %X, undef
+Safe:
+ %A = 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>
+ %A = or %X, undef
+ %B = and %X, undef
+Safe:
+ %A = -1
+ %B = 0
+Unsafe:
+ %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
+always be a zero, no matter what the corresponding bit from the undef is. As
+such, it is unsafe to optimize or assume that the result of the and is undef.
+However, it is safe to assume that all bits of the undef could be 0, and
+optimize the and to 0. Likewise, it is safe to assume that all the bits of
+the undef operand to the or could be set, allowing the or to be folded to
+-1.</p>
+
+<div class="doc_code">
+<pre>
+ %A = select undef, %X, %Y
+ %B = select undef, 42, %Y
+ %C = select %X, %Y, undef
+Safe:
+ %A = %X (or %Y)
+ %B = 42 (or %Y)
+ %C = %Y
+Unsafe:
+ %A = 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
+operands. In the %A example, if %X and %Y were both known to have a clear low
+bit, then %A would have to have a cleared low bit. However, in the %C example,
+the optimizer is allowed to assume that the undef operand could be the same as
+%Y, allowing the whole select to be eliminated.</p>
+
+
+<div class="doc_code">
+<pre>
+ %A = xor undef, undef
+
+ %B = undef
+ %C = xor %B, %B
+
+ %D = undef
+ %E = icmp lt %D, 4
+ %F = icmp gte %D, 4
+
+Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+ %D = 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
+assume that "X^X" is always zero, even if X is undef. This isn't true for a
+number of reasons, but the short answer is that an undef "variable" can
+arbitrarily change its value over its "live range". This is true because the
+"variable" doesn't actually <em>have a live range</em>. Instead, the value is
+logically read from arbitrary registers that happen to be around when needed,
+so the value is not neccesarily consistent over time. In fact, %A and %C need
+to have the same semantics or the core LLVM "replace all uses with" concept
+would not hold.</p>
+
+<div class="doc_code">
+<pre>
+ %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
+allowed to have an arbitrary bit-pattern. This means that the %A operation
+can be constant folded to undef because the undef could be an SNaN, and fdiv is
+not (currently) defined on SNaN's. However, in the second example, we can make
+a more aggressive assumption: because the undef is allowed to be an arbitrary
+value, we are allowed to assume that it could be zero. Since a divide by zero
+has <em>undefined behavior</em>, we are allowed to assume that the operation
+does not execute at all. This allows us to delete the divide and all code after
+it: since the undefined operation "can't happen", the optimizer can assume that
+it occurs in dead code.
+</p>
+
+<div class="doc_code">
+<pre>
+a: store undef -> %X
+b: store %X -> undef
+Safe:
+a: <deleted>
+b: unreachable
+</pre>
+</div>
-<p>Undefined values indicate to the compiler that the program is well defined no
- matter what value is used, giving the compiler more freedom to optimize.</p>
+<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
+overwritten with bits that happen to match what was already there. However, a
+store "to" an undefined location could clobber arbitrary memory, therefore, it
+has undefined behavior.</p>
</div>
<h5>Syntax:</h5>
<pre>
<result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
<result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
<result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
<result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = exact sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sdiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
projects / oota-llvm.git / blobdiff