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
@@ -2202,7 +2201,7 @@ Safe:
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.
+ Any output bit can have a zero or one depending on the input bits.
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.
+ For example, if 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.
-
+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 have a live range. Instead, the value is
-logically read from arbitrary registers that happen to be around when needed,
-so the value is not necessarily 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.
+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.
+Finally, some targets may provide defined semantics when
- using the value as the operand to an inline assembly, but that is target
- specific.
-
+Finally, some targets may provide defined semantics when using the value as
+ the operand to an inline assembly, but that is target specific.
@@ -2456,7 +2457,7 @@ end:
to be used as constants. Constant expressions may be of
any
- trunc (CST to TYPE)
@@ -2643,8 +2644,8 @@ call void asm alignstack "eieio", ""()
The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode
- attached to it that contains a constant integer. If present, the code
- generator will use the integer as the location cookie value when report
+ attached to it that contains a list of constant integers. 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 correlate backend errors that occur with inline asm back to the
source code that produced it. For example:
@@ -2656,7 +2657,8 @@ call void asm sideeffect "something bad", ""()
, !srcloc !42
It is up to the front-end to make sense of the magic numbers it places in the
- IR.
+ IR. If the MDNode contains multiple constants, the code generator will use
+ the one that corresponds to the line of the asm that the error occurs on.
@@ -2690,16 +2692,21 @@ call void asm sideeffect "something bad", ""(), !srcloc !42
Metadata can be used as function arguments. Here llvm.dbg.value
function is using two metadata arguments.
-
- call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
-
+
+
+call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
+
+
Metadata can be attached with an instruction. Here metadata !21 is
attached with add instruction using !dbg identifier.
-
- %indvar.next = add i64 %indvar, 1, !dbg !21
-
+
+
+%indvar.next = add i64 %indvar, 1, !dbg !21
+
+
Syntax:
- <result> = udiv <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = udiv <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = udiv exact <ty> <op1>, <op2> ; yields {ty}:result
Overview:
@@ -3460,6 +3468,11 @@ Instruction
Division by zero leads to undefined behavior.
+If the exact keyword is present, the result value of the
+ udiv is a trap value if %op1 is not a
+ multiple of %op2 (as such, "((a udiv exact b) mul b) == a").
+
+
Example:
<result> = udiv i32 4, %var ; yields {i32}:result = 4 / %var
@@ -3600,9 +3613,10 @@ Instruction
Semantics:
This instruction returns the remainder of a division (where the result
- has the same sign as the dividend, op1), not the modulo
- operator (where the result has the same sign as the divisor, op2) of
- a value. For more information about the difference,
+ is either zero or has the same sign as the dividend, op1), not the
+ modulo operator (where the result is either zero or has the same sign
+ as the divisor, op2) of a value.
+ For more information about the difference,
see The
Math Forum. For a table of how this is implemented in various languages,
please see
@@ -3678,7 +3692,10 @@ Instruction
Syntax:
- <result> = shl <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = shl <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = shl nuw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = shl nsw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = shl nuw nsw <ty> <op1>, <op2> ; yields {ty}:result
Overview:
@@ -3698,6 +3715,14 @@ Instruction
vectors, each vector element of op1 is shifted by the corresponding
shift amount in op2.
+If the nuw keyword is present, then the shift produces a
+ trap value if it shifts out any non-zero bits. If
+ the nsw keyword is present, then the shift produces a
+ trap value if it shifts out any bits that disagree
+ with the resultant sign bit. As such, NUW/NSW have the same semantics as
+ they would if the shift were expressed as a mul instruction with the same
+ nsw/nuw bits in (mul %op1, (shl 1, %op2)).
+
Example:
<result> = shl i32 4, %var ; yields {i32}: 4 << %var
@@ -3717,7 +3742,8 @@ Instruction
Syntax:
- <result> = lshr <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = lshr <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = lshr exact <ty> <op1>, <op2> ; yields {ty}:result
Overview:
@@ -3737,6 +3763,11 @@ Instruction
vectors, each vector element of op1 is shifted by the corresponding
shift amount in op2.
+If the exact keyword is present, the result value of the
+ lshr is a trap value if any of the bits
+ shifted out are non-zero.
+
+
Example:
<result> = lshr i32 4, 1 ; yields {i32}:result = 2
@@ -3756,7 +3787,8 @@ Instruction
Syntax:
- <result> = ashr <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = ashr <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = ashr exact <ty> <op1>, <op2> ; yields {ty}:result
Overview:
@@ -3777,6 +3809,10 @@ Instruction
the arguments are vectors, each vector element of op1 is shifted by
the corresponding shift amount in op2.
+If the exact keyword is present, the result value of the
+ ashr is a trap value if any of the bits
+ shifted out are non-zero.
+
Example:
<result> = ashr i32 4, 1 ; yields {i32}:result = 2
@@ -4140,10 +4176,18 @@ Instruction
Arguments:
The first operand of an 'extractvalue' instruction is a value
- of struct, union or
+ of struct or
array type. The operands are constant indices to
specify which value to extract in a similar manner as indices in a
'getelementptr' instruction.
+ The major differences to getelementptr indexing are:
+
+ - Since the value being indexed is not a pointer, the first index is
+ omitted and assumed to be zero.
+ - At least one index must be specified.
+ - Not only struct indices but also array indices must be in
+ bounds.
+
Semantics:
The result is the value at the position in the aggregate specified by the
@@ -4174,11 +4218,11 @@ Instruction
Arguments:
The first operand of an 'insertvalue' instruction is a value
- of struct, union or
+ of struct or
array type. The second operand is a first-class
value to insert. The following operands are constant indices indicating
the position at which to insert the value in a similar manner as indices in a
- 'getelementptr' instruction. The
+ 'extractvalue' instruction. The
value to insert must have the same type as the value identified by the
indices.
@@ -4407,12 +4451,12 @@ Instruction
indexes a value of the type pointed to (not necessarily the value directly
pointed to, since the first index can be non-zero), etc. The first type
indexed into must be a pointer value, subsequent types can be arrays,
- vectors, structs and unions. Note that subsequent types being indexed into
+ vectors, and structs. Note that subsequent types being indexed into
can never be pointers, since that would require loading the pointer before
continuing calculation.
The type of each index argument depends on the type it is indexing into.
- When indexing into a (optionally packed) structure or union, only i32
+ When indexing into a (optionally packed) structure, only i32
integer constants are allowed. When indexing into an array, pointer
or vector, integers of any width are allowed, and they are not required to be
constant.
@@ -4539,12 +4583,12 @@ entry:
type ty2.
Arguments:
-The 'trunc' instruction takes a value to trunc, which must
- be an integer type, and a type that specifies the
- size and type of the result, which must be
- an integer type. The bit size of value must
- be larger than the bit size of ty2. Equal sized types are not
- allowed.
+The 'trunc' instruction takes a value to trunc, and a type to trunc it to.
+ Both types must be of integer types, or vectors
+ of the same number of integers.
+ The bit size of the value must be larger than
+ the bit size of the destination type, ty2.
+ Equal sized types are not allowed.
Semantics:
The 'trunc' instruction truncates the high order bits
@@ -4554,9 +4598,10 @@ entry:
Example:
- %X = trunc i32 257 to i8 ; yields i8:1
- %Y = trunc i32 123 to i1 ; yields i1:true
- %Z = trunc i32 122 to i1 ; yields i1:false
+ %X = trunc i32 257 to i8 ; yields i8:1
+ %Y = trunc i32 123 to i1 ; yields i1:true
+ %Z = trunc i32 122 to i1 ; yields i1:false
+ %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
@@ -4578,10 +4623,11 @@ entry:
Arguments:
-The 'zext' instruction takes a value to cast, which must be of
- integer type, and a type to cast it to, which must
- also be of integer type. The bit size of the
- value must be smaller than the bit size of the destination type,
+
The 'zext' instruction takes a value to cast, and a type to cast it to.
+ Both types must be of integer types, or vectors
+ of the same number of integers.
+ The bit size of the value must be smaller than
+ the bit size of the destination type,
ty2.
Semantics:
@@ -4594,6 +4640,7 @@ entry:
%X = zext i32 257 to i64 ; yields i64:257
%Y = zext i1 true to i32 ; yields i32:1
+ %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
@@ -4613,10 +4660,11 @@ entry:
The 'sext' sign extends value to the type ty2.
Arguments:
-The 'sext' instruction takes a value to cast, which must be of
- integer type, and a type to cast it to, which must
- also be of integer type. The bit size of the
- value must be smaller than the bit size of the destination type,
+
The 'sext' instruction takes a value to cast, and a type to cast it to.
+ Both types must be of integer types, or vectors
+ of the same number of integers.
+ The bit size of the value must be smaller than
+ the bit size of the destination type,
ty2.
Semantics:
@@ -4630,6 +4678,7 @@ entry:
%X = sext i8 -1 to i16 ; yields i16 :65535
%Y = sext i1 true to i32 ; yields i32:-1
+ %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
@@ -6117,8 +6166,8 @@ LLVM.
Syntax:
This is an overloaded intrinsic. You can use llvm.memset on any integer bit
- width and for different address spaces. Not all targets support all bit
- widths however.
+ width and for different address spaces. However, not all targets support all
+ bit widths.
declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>,
@@ -6132,14 +6181,14 @@ LLVM.
particular byte value.
Note that, unlike the standard libc function, the llvm.memset
- intrinsic does not return a value, takes extra alignment/volatile arguments,
- and the destination can be in an arbitrary address space.
+ intrinsic does not return a value and takes extra alignment/volatile
+ arguments. Also, the destination can be in an arbitrary address space.
Arguments:
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 integer argument
+ byte value with which to fill it, the third argument is an integer argument
specifying the number of bytes to fill, and the fourth argument is the known
- alignment of destination location.
+ alignment of the destination location.
If the call to this intrinsic has an alignment value that is not 0 or 1,
then the caller guarantees that the destination pointer is aligned to that
@@ -7519,7 +7568,7 @@ LLVM.
Syntax:
- declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) readonly
+ declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
Overview:
@@ -7694,7 +7743,7 @@ LLVM.
the AllocaInst stack slot to be before local variables on the
stack. This is to ensure that if a local variable on the stack is
overwritten, it will destroy the value of the guard. When the function exits,
- the guard on the stack is checked against the original guard. If they're
+ the guard on the stack is checked against the original guard. If they are
different, then the program aborts by calling the __stack_chk_fail()
function.
@@ -7714,25 +7763,24 @@ LLVM.
Overview:
-The llvm.objectsize intrinsic is designed to provide information
- to the optimizers to discover at compile time either a) when an
- operation like memcpy will either overflow a buffer that corresponds to
- an object, or b) to determine that a runtime check for overflow isn't
- necessary. An object in this context means an allocation of a
- specific class, structure, array, or other object.
+The llvm.objectsize intrinsic is designed to provide information to
+ the optimizers to determine at compile time whether a) an operation (like
+ memcpy) will overflow a buffer that corresponds to an object, or b) that a
+ runtime check for overflow isn't necessary. An object in this context means
+ an allocation of a specific class, structure, array, or other object.
Arguments:
-The llvm.objectsize intrinsic takes two arguments. The first
+
The llvm.objectsize intrinsic takes two arguments. The first
argument is a pointer to or into the object. The second argument
- is a boolean 0 or 1. This argument determines whether you want the
- maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or
+ is a boolean 0 or 1. This argument determines whether you want the
+ maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or
1, variables are not allowed.
Semantics:
The llvm.objectsize intrinsic is lowered to either a constant
- representing the size of the object concerned or i32/i64 -1 or 0
- (depending on the type argument if the size cannot be determined
- at compile time.
+ representing the size of the object concerned, or i32/i64 -1 or 0,
+ depending on the type argument, if the size cannot be determined at
+ compile time.