This example is made up of a global variable named - ".LC0", an external declaration of the "puts" function, and + ".LC0", an external declaration of the "puts" function, a function definition for - "main".
+ "main" and named metadata + "foo".In general, a module is made up of a list of global values, where both functions and global variables are global values. Global values are @@ -556,10 +577,17 @@ define i32 @main() { ; i32()*
LLVM allows an explicit section to be specified for globals. If the target supports it, it will emit globals to the section specified.
-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.
+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.
For example, the following defines a global in a numbered address space with an initializer, section, and alignment:
@@ -828,7 +880,7 @@ define i32 @main() { ; i32()*LLVM function definitions consist of the "define" keyord, an +
LLVM function definitions consist of the "define" keyword, an optional linkage type, an optional visibility style, an optional calling convention, a return type, an optional @@ -841,7 +893,7 @@ define i32 @main() { ; i32()*
LLVM function declarations consist of the "declare" keyword, an optional linkage type, an optional - visibility style, an optional + visibility style, an optional calling convention, a return type, an optional parameter attribute for the return type, a function name, a possibly empty list of arguments, an optional alignment, and an @@ -902,6 +954,27 @@ define [linkage] [visibility]
Named metadata is a collection of metadata. Metadata + nodes (but not metadata strings) and null are the only valid operands for + a named metadata.
+ +
+!1 = metadata !{metadata !"one"}
+!name = !{null, !1}
+
+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 datalayout keyword. The default specifications are given in this list:
Certain memory accesses, such as loads, stores, and llvm.memcpys may be marked volatile. +The optimizers must not change the number of volatile operations or change their +order of execution relative to other volatile operations. The optimizers +may change the order of volatile operations relative to non-volatile +operations. This is not Java's "volatile" and has no cross-thread +synchronization behavior.
+ +Note that the code generator does not yet support large integer types to be - used as function return types. The specific limit on how large a return type - the code generator can currently handle is target-dependent; currently it's - often 64 bits for 32-bit targets and 128 bits for 64-bit targets.
- @@ -1525,6 +1617,21 @@ Classifications possible to have a two dimensional array, using an array as the element type of another array. + + + + + + +Aggregate Types are a subset of derived types that can contain multiple + member types. Arrays, + structs, vectors and + unions are aggregate types.
+ +Except when the inbounds keyword is present, there is no limitation - on indexing beyond the end of the array implied by the static type (though - any loads or stores must of course be within the bounds of the allocated - object!). This means that single-dimension 'variable sized array' addressing - can be implemented in LLVM with a zero length array type. An implementation - of 'pascal style arrays' in LLVM could use the type - "{ i32, [0 x float]}", for example.
- -Note that the code generator does not yet support large aggregate types to be - used as function return types. The specific limit on how large an aggregate - return type the code generator can currently handle is target-dependent, and - also dependent on the aggregate element types.
+There is no restriction on indexing beyond the end of the array implied by + a static type (though there are restrictions on indexing beyond the bounds + of an allocated object in some cases). This means that single-dimension + 'variable sized array' addressing can be implemented in LLVM with a zero + length array type. An implementation of 'pascal style arrays' in LLVM could + use the type "{ i32, [0 x float]}", for example.
@@ -1599,9 +1700,9 @@ ClassificationsThe function type can be thought of as a function signature. It consists of a return type and a list of formal parameter types. The return type of a - function type is a scalar type, a void type, or a struct type. If the return - type is a struct type then all struct elements must be of first class types, - and the struct must have at least one element.
+ function type is a scalar type, a void type, a struct type, or a union + type. If the return type is a struct type then all struct elements must be + of first class types, and the struct must have at least one element.
@@ -1613,7 +1714,7 @@ Classifications
which indicates that the function takes a variable number of arguments.
Variable argument functions can access their arguments with
the variable argument handling intrinsic
- functions. '<returntype>' is a any type except
+ functions. '<returntype>' is any type except
label.
Examples:
@@ -1623,18 +1724,17 @@ Classifications
function taking an i32, returning an i32
- float (i16 signext, i32 *) *
+ float (i16, i32 *) *
- Pointer to a function that takes
- an i16 that should be sign extended and a
- pointer to i32, returning
- float.
+ Pointer to a function that takes
+ an i16 and a pointer to i32,
+ returning float.
i32 (i8*, ...)
- A vararg function that takes at least one
- pointer to i8 (char in C),
- which returns an integer. This is the signature for printf in
+ A vararg function that takes at least one
+ pointer to i8 (char in C),
+ which returns an integer. This is the signature for printf in
LLVM.
@@ -1658,10 +1758,12 @@ Classifications
underlying processor. The elements of a structure may be any type that has a
size.
-Structures are accessed using 'load and
- 'store' by getting a pointer to a field with
- the 'getelementptr' instruction.
-
+Structures in memory are accessed using 'load'
+ and 'store' by getting a pointer to a field
+ with the 'getelementptr' instruction.
+ Structures in registers are accessed using the
+ 'extractvalue' and
+ 'insertvalue' instructions.
Syntax:
{ <type list> }
@@ -1681,11 +1783,6 @@ Classifications
-Note that the code generator does not yet support large aggregate types to be
- used as function return types. The specific limit on how large an aggregate
- return type the code generator can currently handle is target-dependent, and
- also dependent on the aggregate element types.
-
@@ -1726,16 +1823,66 @@ Classifications
+
+
+
+
+
+Overview:
+A union type describes an object with size and alignment suitable for
+ an object of any one of a given set of types (also known as an "untagged"
+ union). It is similar in concept and usage to a
+ struct, except that all members of the union
+ have an offset of zero. The elements of a union may be any type that has a
+ size. Unions must have at least one member - empty unions are not allowed.
+
+
+The size of the union as a whole will be the size of its largest member,
+ and the alignment requirements of the union as a whole will be the largest
+ alignment requirement of any member.
+
+Union members are accessed using 'load and
+ 'store' by getting a pointer to a field with
+ the 'getelementptr' instruction.
+ Since all members are at offset zero, the getelementptr instruction does
+ not affect the address, only the type of the resulting pointer.
+
+Syntax:
+
+ union { <type list> }
+
+
+Examples:
+
+
+ union { i32, i32*, float }
+ A union of three types: an i32, a pointer to
+ an i32, and a float.
+
+
+ union { float, i32 (i32) * }
+ A union, where the first element is a float and the
+ second element is a pointer to a
+ function that takes an i32, returning
+ an i32.
+
+
+
+
+
Overview:
-As in many languages, the pointer type represents a pointer or reference to
- another object, which must live in memory. Pointer types may have an optional
- address space attribute defining the target-specific numbered address space
- where the pointed-to object resides. The default address space is zero.
+The pointer type is used to specify memory locations.
+ Pointers are commonly used to reference objects in memory.
+
+Pointer types may have an optional address space attribute defining the
+ numbered address space where the pointed-to object resides. The default
+ address space is number zero. The semantics of non-zero address
+ spaces are target-specific.
Note that LLVM does not permit pointers to void (void*) nor does it
permit pointers to labels (label*). Use i8* instead.
@@ -1776,8 +1923,7 @@ Classifications
A vector type is a simple derived type that represents a vector of elements.
Vector types are used when multiple primitive data are operated in parallel
using a single instruction (SIMD). A vector type requires a size (number of
- elements) and an underlying primitive data type. Vectors must have a power
- of two length (1, 2, 4, 8, 16 ...). Vector types are considered
+ elements) and an underlying primitive data type. Vector types are considered
first class.
Syntax:
@@ -1804,11 +1950,6 @@ Classifications
-Note that the code generator does not yet support large vector types to be
- used as function return types. The specific limit on how large a vector
- return type codegen can currently handle is target-dependent; currently it's
- often a few times longer than a hardware vector register.
-
@@ -1970,6 +2111,14 @@ Classifications
the number and types of elements must match those specified by the
type.%A = xor undef, undef - + %B = undef %C = xor %B, %B @@ -2157,7 +2307,7 @@ 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. - +a: store undef -> %X @@ -2169,13 +2319,121 @@ b: unreachableThese 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 +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.
Trap values are similar to undef values, 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.
+ +There is currently no way of representing a trap value in the IR; they + only exist when produced by operations such as + add with the nsw flag.
+ +Trap value behavior is defined in terms of value dependence:
+ ++
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.
+ +Here are some examples:
+ ++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). ++
The 'blockaddress' constant computes the address of the specified basic block in the specified function, and always has an i8* type. Taking the address of the entry block is illegal.
- +This value only has defined behavior when used as an operand to the 'indirectbr' instruction or for comparisons against null. Pointer equality tests between labels addresses is undefined @@ -2195,7 +2453,7 @@ has undefined behavior.
pointer sized value as long as the bits are not inspected. This allows ptrtoint and arithmetic to be performed on these values so long as the original value is reconstituted before the indirectbr. - +Finally, some targets may provide defined semantics when using the value as the operand to an inline assembly, but that is target specific. @@ -2324,38 +2582,6 @@ has undefined behavior.
Embedded metadata provides a way to attach arbitrary data to the instruction - stream without affecting the behaviour of the program. There are two - metadata primitives, strings and nodes. All metadata has the - metadata type and is identified in syntax by a preceding exclamation - point ('!').
- -A metadata string is a string surrounded by double quotes. It can contain - any character by escaping non-printable characters with "\xx" where "xx" is - the two digit hex code. For example: "!"test\00"".
- -Metadata nodes are represented with notation similar to structure constants - (a comma separated list of elements, surrounded by braces and preceded by an - exclamation point). For example: "!{ metadata !"test\00", i32 - 10}".
- -A metadata node will attempt to track changes to the values it holds. In the - event that a value is deleted, it will be replaced with a typeless - "null", such as "metadata !{null, i32 10}".
- -Optimizations may rely on metadata to provide additional information about - the program that isn't available in the instructions, or that isn't easily - computable. Similarly, the code generator may expect a certain metadata - format to be used to express debugging information.
- -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 + 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:
+ +
+call void asm sideeffect "something bad", ""(), !srcloc !42
+...
+!42 = !{ i32 1234567 }
+
+It is up to the front-end to make sense of the magic numbers it places in the + IR.
+ +LLVM IR allows metadata to be attached to instructions in the program that + can convey extra information about the code to the optimizers and code + generator. One example application of metadata is source-level debug + information. There are two metadata primitives: strings and nodes. All + metadata has the metadata type and is identified in syntax by a + preceding exclamation point ('!').
+ +A metadata string is a string surrounded by double quotes. It can contain + any character by escaping non-printable characters with "\xx" where "xx" is + the two digit hex code. For example: "!"test\00"".
+ +Metadata nodes are represented with notation similar to structure constants + (a comma separated list of elements, surrounded by braces and preceded by an + exclamation point). For example: "!{ metadata !"test\00", i32 + 10}". Metadata nodes can have any values as their operand.
+ +A named metadata is a collection of + metadata nodes, which can be looked up in the module symbol table. For + example: "!foo = metadata !{!4, !3}". + +
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) ++
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 ++
TODO: Describe this.
+
+%0 = type { i32, void ()* }
+@llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
+
+The @llvm.global_ctors 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. +
+%0 = type { i32, void ()* }
+@llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
+
-TODO: Describe this.
+The @llvm.global_dtors 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. +
There are six different terminator instructions: the +
There are seven different terminator instructions: the 'ret' instruction, the 'br' instruction, the 'switch' instruction, the @@ -2601,14 +2907,6 @@ Instruction ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2 -
Note that the code generator does not yet fully support large - return values. The specific sizes that are currently supported are - dependent on the target. For integers, on 32-bit targets the limit - is often 64 bits, and on 64-bit targets the limit is often 128 bits. - For aggregate types, the current limits are dependent on the element - types; for example targets are often limited to 2 total integer - elements and 2 total floating-point elements.
- @@ -2731,7 +3029,7 @@ IfUnequal: rest of the arguments indicate the full set of possible destinations that the address may point to. Blocks are allowed to occur multiple times in the destination list, though this isn't particularly useful. - +This destination list is required so that dataflow analysis has an accurate understanding of the CFG.
@@ -2798,9 +3096,10 @@ IfUnequal: function to be invoked.Note that the code generator does not yet completely support unwind, and +that the invoke/unwind semantics are likely to change in future versions.
+
%retval = invoke i32 @Test(i32 15) to label %Continue
@@ -2865,6 +3167,9 @@ Instruction
specified by the invoke instruction. If there is no invoke
instruction in the dynamic call chain, undefined behavior results.
+Note that the code generator does not yet completely support unwind, and
+that the invoke/unwind semantics are likely to change in future versions.
+
@@ -2940,7 +3245,8 @@ Instruction
nuw and nsw stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the nuw and/or
nsw keywords are present, the result value of the add
- is undefined if unsigned and/or signed overflow, respectively, occurs.
+ is a trap value if unsigned and/or signed overflow,
+ respectively, occurs.
Example:
@@ -3020,7 +3326,8 @@ Instruction
nuw and nsw stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the nuw and/or
nsw keywords are present, the result value of the sub
- is undefined if unsigned and/or signed overflow, respectively, occurs.
+ is a trap value if unsigned and/or signed overflow,
+ respectively, occurs.
Example:
@@ -3088,7 +3395,7 @@ Instruction
The two arguments to the 'mul' instruction must
be integer or vector of
integer values. Both arguments must have identical types.
-
+
Semantics:
The value produced is the integer product of the two operands.
@@ -3106,7 +3413,8 @@ Instruction
nuw and nsw stand for "No Unsigned Wrap"
and "No Signed Wrap", respectively. If the nuw and/or
nsw keywords are present, the result value of the mul
- is undefined if unsigned and/or signed overflow, respectively, occurs.
+ is a trap value if unsigned and/or signed overflow,
+ respectively, occurs.
Example:
@@ -3160,7 +3468,7 @@ Instruction
The 'udiv' instruction returns the quotient of its two operands.
Arguments:
-The two arguments to the 'udiv' instruction must be
+
The two arguments to the 'udiv' instruction must be
integer or vector of integer
values. Both arguments must have identical types.
@@ -3195,7 +3503,7 @@ Instruction
The 'sdiv' instruction returns the quotient of its two operands.
Arguments:
-The two arguments to the 'sdiv' instruction must be
+
The two arguments to the 'sdiv' instruction must be
integer or vector of integer
values. Both arguments must have identical types.
@@ -3211,8 +3519,8 @@ Instruction
a 32-bit division of -2147483648 by -1.
If the exact keyword is present, the result value of the
- sdiv is undefined if the result would be rounded or if overflow
- would occur.
+ sdiv is a trap value if the result would
+ be rounded or if overflow would occur.
Example:
@@ -3266,7 +3574,7 @@ Instruction
division of its two arguments.
Arguments:
-The two arguments to the 'urem' instruction must be
+
The two arguments to the 'urem' instruction must be
integer or vector of integer
values. Both arguments must have identical types.
@@ -3306,7 +3614,7 @@ Instruction
elements must be integers.
Arguments:
-The two arguments to the 'srem' instruction must be
+
The two arguments to the 'srem' instruction must be
integer or vector of integer
values. Both arguments must have identical types.
@@ -3401,7 +3709,7 @@ Instruction
Both arguments to the 'shl' instruction must be the
same integer or vector of
integer type. 'op2' is treated as an unsigned value.
-
+
Semantics:
The value produced is op1 * 2op2 mod
2n, where n is the width of the result. If op2
@@ -3437,7 +3745,7 @@ Instruction
operand shifted to the right a specified number of bits with zero fill.
Arguments:
-Both arguments to the 'lshr' instruction must be the same
+
Both arguments to the 'lshr' instruction must be the same
integer or vector of integer
type. 'op2' is treated as an unsigned value.
@@ -3477,7 +3785,7 @@ Instruction
extension.
Arguments:
-Both arguments to the 'ashr' instruction must be the same
+
Both arguments to the 'ashr' instruction must be the same
integer or vector of integer
type. 'op2' is treated as an unsigned value.
@@ -3517,7 +3825,7 @@ Instruction
operands.
Arguments:
-The two arguments to the 'and' instruction must be
+
The two arguments to the 'and' instruction must be
integer or vector of integer
values. Both arguments must have identical types.
@@ -3576,7 +3884,7 @@ Instruction
two operands.
Arguments:
-The two arguments to the 'or' instruction must be
+
The two arguments to the 'or' instruction must be
integer or vector of integer
values. Both arguments must have identical types.
@@ -3639,7 +3947,7 @@ Instruction
complement" operation, which is the "~" operator in C.
Arguments:
-The two arguments to the 'xor' instruction must be
+
The two arguments to the 'xor' instruction must be
integer or vector of integer
values. Both arguments must have identical types.
@@ -3687,7 +3995,7 @@ Instruction
-
+
@@ -3810,26 +4118,27 @@ Instruction
Example:
- <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
<4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
<4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle.
- <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
+ <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
<4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
<8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32>
-
+
-LLVM supports several instructions for working with aggregate values.
+LLVM supports several instructions for working with
+ aggregate values.
@@ -3846,14 +4155,14 @@ Instruction
Overview:
-The 'extractvalue' instruction extracts the value of a struct field
- or array element from an aggregate value.
+The 'extractvalue' instruction extracts the value of a member field
+ from an aggregate value.
Arguments:
The first operand of an 'extractvalue' instruction is a value
- of struct or array type. The
- operands are constant indices to specify which value to extract in a similar
- manner as indices in a
+ of struct, union or
+ array type. The operands are constant indices to
+ specify which value to extract in a similar manner as indices in a
'getelementptr' instruction.
Semantics:
@@ -3876,20 +4185,19 @@ Instruction
Syntax:
- <result> = insertvalue <aggregate type> <val>, <ty> <val>, <idx> ; yields <n x <ty>>
+ <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx> ; yields <aggregate type>
Overview:
-The 'insertvalue' instruction inserts a value into a struct field or
- array element in an aggregate.
-
+The 'insertvalue' instruction inserts a value into a member field
+ in an aggregate value.
Arguments:
The first operand of an 'insertvalue' instruction is a value
- 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
+ of struct, union 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
value to insert must have the same type as the value identified by the
indices.
@@ -3901,14 +4209,15 @@ Instruction
Example:
- <result> = insertvalue {i32, float} %agg, i32 1, 0 ; yields {i32, float}
+ %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef}
+ %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val}
-
+
@@ -3980,8 +4289,9 @@ Instruction
Syntax:
- <result> = load <ty>* <pointer>[, align <alignment>]
- <result> = volatile load <ty>* <pointer>[, align <alignment>]
+ <result> = load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ <result> = volatile load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]
+ !<index> = !{ i32 1 }
Overview:
@@ -3992,18 +4302,25 @@ Instruction
from which to load. The pointer must point to
a first class type. If the load is
marked as volatile, then the optimizer is not allowed to modify the
- number or order of execution of this load with other
- volatile load and store
- instructions.
+ number or order of execution of this load with other volatile operations.
-The optional constant "align" argument specifies the alignment of the
+
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
- omitted "align" argument means that the operation has the preferential
+ omitted align argument means that the operation has the preferential
alignment for the target. It is the responsibility of the code emitter to
ensure that the alignment information is correct. Overestimating the
- alignment results in an undefined behavior. Underestimating the alignment may
+ alignment results in undefined behavior. Underestimating the alignment may
produce less efficient code. An alignment of 1 is always safe.
+The optional !nontemporal metadata must reference a single
+ metatadata 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 select special instructions to save cache bandwidth,
+ such as the MOVNT instruction on x86.
+
Semantics:
The location of memory pointed to is loaded. If the value being loaded is of
scalar type then the number of bytes read does not exceed the minimum number
@@ -4030,8 +4347,8 @@ Instruction
Syntax:
- store <ty> <value>, <ty>* <pointer>[, align <alignment>] ; yields {void}
- volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>] ; yields {void}
+ store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !] ; yields {void}
+ volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !] ; yields {void}
Overview:
@@ -4042,11 +4359,10 @@ Instruction
and an address at which to store it. The type of the
'<pointer>' operand must be a pointer to
the first class type of the
- '<value>' operand. If the store is marked
- as volatile, then the optimizer is not allowed to modify the number
- or order of execution of this store with other
- volatile load and store
- instructions.
+ '<value>' operand. If the store is marked as
+ volatile, then the optimizer is not allowed to modify the number or
+ order of execution of this store with other volatile operations.
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
@@ -4056,6 +4372,15 @@ Instruction
alignment results in an undefined behavior. Underestimating the alignment may
produce less efficient code. An alignment of 1 is always safe.
+The optional !nontemporal metadata must reference a single metatadata
+ name 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
+ select special instructions to save cache bandwidth, such as the
+ MOVNT instruction on x86.
+
+
Semantics:
The contents of memory are updated to contain '<value>' at the
location specified by the '<pointer>' operand. If
@@ -4090,8 +4415,8 @@ Instruction
Overview:
The 'getelementptr' instruction is used to get the address of a
- subelement of an aggregate data structure. It performs address calculation
- only and does not access memory.
+ subelement of an aggregate data structure.
+ It performs address calculation only and does not access memory.
Arguments:
The first argument is always a pointer, and forms the basis of the
@@ -4101,15 +4426,15 @@ Instruction
indexes the pointer value given as the first argument, the second index
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
- and structs. Note that subsequent types being indexed into can never be
- pointers, since that would require loading the pointer before continuing
- calculation.
+ indexed into must be a pointer value, subsequent types can be arrays,
+ vectors, structs and unions. 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, 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
+ When indexing into a (optionally packed) structure or union, 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.
For example, let's consider a C code fragment and how it gets compiled to
@@ -4176,13 +4501,14 @@ entry:
If the inbounds keyword is present, the result value of the
- getelementptr is undefined if the base pointer is not an
- in bounds 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
- in bounds address of that allocated object.
- The in bounds addresses for an allocated object are all the addresses
- that point into the object, plus the address one byte past the end.
+ getelementptr is a trap value if the
+ base pointer is not an in bounds 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 in bounds address of that allocated
+ object. The in bounds addresses for an allocated object are all
+ the addresses that point into the object, plus the address one byte past
+ the end.
If the inbounds keyword is not present, the offsets are added to
the base address with silently-wrapping two's complement arithmetic, and
@@ -4271,15 +4597,15 @@ entry:
Overview:
-The 'zext' instruction zero extends its operand to type
+
The 'zext' instruction zero extends its operand to type
ty2.
Arguments:
-The 'zext' instruction takes a value to cast, which must be of
+
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,
+ value must be smaller than the bit size of the destination type,
ty2.
Semantics:
@@ -4311,10 +4637,10 @@ entry:
The 'sext' sign extends value to the type ty2.
Arguments:
-The 'sext' instruction takes a value to cast, which must be of
+
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,
+ value must be smaller than the bit size of the destination type,
ty2.
Semantics:
@@ -4352,12 +4678,12 @@ entry:
The 'fptrunc' instruction takes a floating
point value to cast and a floating point type
to cast it to. The size of value must be larger than the size of
- ty2. This implies that fptrunc cannot be used to make a
+ ty2. This implies that fptrunc cannot be used to make a
no-op cast.
Semantics:
The 'fptrunc' instruction truncates a value from a larger
- floating point type to a smaller
+ floating point type to a smaller
floating point type. If the value cannot fit
within the destination type, ty2, then the results are
undefined.
@@ -4386,7 +4712,7 @@ entry:
floating point value.
Arguments:
-The 'fpext' instruction takes a
+
The 'fpext' instruction takes a
floating point value to cast, and
a floating point type to cast it to. The source
type must be smaller than the destination type.
@@ -4429,7 +4755,7 @@ entry:
vector integer type with the same number of elements as ty
Semantics:
-The 'fptoui' instruction converts its
+
The 'fptoui' instruction converts its
floating point operand into the nearest (rounding
towards zero) unsigned integer value. If the value cannot fit
in ty2, the results are undefined.
@@ -4455,7 +4781,7 @@ entry:
Overview:
-The 'fptosi' instruction converts
+
The 'fptosi' instruction converts
floating point value to
type ty2.
@@ -4467,7 +4793,7 @@ entry:
vector integer type with the same number of elements as ty
Semantics:
-The 'fptosi' instruction converts its
+
The 'fptosi' instruction converts its
floating point operand into the nearest (rounding
towards zero) signed integer value. If the value cannot fit in ty2,
the results are undefined.
@@ -4664,7 +4990,7 @@ entry:
%X = bitcast i8 255 to i8 ; yields i8 :-1
%Y = bitcast i32* %x to sint* ; yields sint*:%x
- %Z = bitcast <2 x int> %V to i64; ; yields i64: %V
+ %Z = bitcast <2 x int> %V to i64; ; yields i64: %V
@@ -4724,11 +5050,11 @@ entry:
result, as follows:
- - eq: yields true if the operands are equal,
+
- eq: yields true if the operands are equal,
false otherwise. No sign interpretation is necessary or
performed.
- - ne: yields true if the operands are unequal,
+
- ne: yields true if the operands are unequal,
false otherwise. No sign interpretation is necessary or
performed.
@@ -4845,42 +5171,42 @@ entry:
- false: always yields false, regardless of operands.
- - oeq: yields true if both operands are not a QNAN and
+
- oeq: yields true if both operands are not a QNAN and
op1 is equal to op2.
- ogt: yields true if both operands are not a QNAN and
- op1 is greather than op2.
+ op1 is greater than op2.
- - oge: yields true if both operands are not a QNAN and
+
- oge: yields true if both operands are not a QNAN and
op1 is greater than or equal to op2.
- - olt: yields true if both operands are not a QNAN and
+
- olt: yields true if both operands are not a QNAN and
op1 is less than op2.
- - ole: yields true if both operands are not a QNAN and
+
- ole: yields true if both operands are not a QNAN and
op1 is less than or equal to op2.
- - one: yields true if both operands are not a QNAN and
+
- one: yields true if both operands are not a QNAN and
op1 is not equal to op2.
- ord: yields true if both operands are not a QNAN.
- - ueq: yields true if either operand is a QNAN or
+
- ueq: yields true if either operand is a QNAN or
op1 is equal to op2.
- - ugt: yields true if either operand is a QNAN or
+
- ugt: yields true if either operand is a QNAN or
op1 is greater than op2.
- - uge: yields true if either operand is a QNAN or
+
- uge: yields true if either operand is a QNAN or
op1 is greater than or equal to op2.
- - ult: yields true if either operand is a QNAN or
+
- ult: yields true if either operand is a QNAN or
op1 is less than op2.
- - ule: yields true if either operand is a QNAN or
+
- ule: yields true if either operand is a QNAN or
op1 is less than or equal to op2.
- - une: yields true if either operand is a QNAN or
+
- une: yields true if either operand is a QNAN or
op1 is not equal to op2.
- uno: yields true if either operand is a QNAN.
@@ -5011,15 +5337,34 @@ Loop: ; Infinite loop that counts from 0 on up...
This instruction requires several arguments:
- - The optional "tail" marker indicates whether the callee function accesses
- any allocas or varargs in the caller. If the "tail" marker is present,
- the function call is eligible for tail call optimization. Note that calls
- may be marked "tail" even if they do not occur before
- a ret instruction.
+ - The optional "tail" marker indicates that the callee function does not
+ access any allocas or varargs in the caller. Note that calls may be
+ marked "tail" even if they do not occur before
+ a ret instruction. If the "tail" marker is
+ present, the function call is eligible for tail call optimization,
+ but might not in fact be
+ optimized into a jump. The code generator may optimize calls marked
+ "tail" with either 1) automatic
+ sibling call optimization when the caller and callee have
+ matching signatures, or 2) forced tail call optimization when the
+ following extra requirements are met:
+
+ - Caller and callee both have the calling
+ convention fastcc.
+ - The call is in tail position (ret immediately follows call and ret
+ uses value of call or is void).
+ - Option -tailcallopt is enabled,
+ or
llvm::GuaranteedTailCallOpt is true.
+ - Platform specific
+ constraints are met.
+
+
- The optional "cconv" marker indicates which calling
convention the call should use. If none is specified, the call
- defaults to using C calling conventions.
+ defaults to using C calling conventions. The calling convention of the
+ call must match the calling convention of the target function, or else the
+ behavior is undefined.
- The optional Parameter Attributes list for
return values. Only 'zeroext', 'signext', and
@@ -5040,10 +5385,10 @@ Loop: ; Infinite loop that counts from 0 on up...
to function value.
- 'function args': argument list whose types match the function
- signature argument types. All arguments must be of
- first class type. If the function signature
- indicates the function accepts a variable number of arguments, the extra
- arguments can be specified.
+ signature argument types and parameter attributes. All arguments must be
+ of first class type. If the function
+ signature indicates the function accepts a variable number of arguments,
+ the extra arguments can be specified.
- The optional function attributes list. Only
'noreturn', 'nounwind', 'readonly' and
@@ -5078,7 +5423,7 @@ Loop: ; Infinite loop that counts from 0 on up...
standard C99 library as being the C99 library functions, and may perform
optimizations or generate code for them under that assumption. This is
something we'd like to change in the future to provide better support for
-freestanding environments and non-C-based langauges.
+freestanding environments and non-C-based languages.
@@ -5172,7 +5517,7 @@ freestanding environments and non-C-based langauges.
suffix is required. Because the argument's type is matched against the return
type, it does not require its own name suffix.
-
To learn how to add an intrinsic function, please see the
+
To learn how to add an intrinsic function, please see the
Extending LLVM Guide.
@@ -5634,7 +5979,7 @@ LLVM.
Semantics:
This intrinsic does not modify the behavior of the program. Backends that do
- not support this intrinisic may ignore it.
+ not support this intrinsic may ignore it.
@@ -5688,17 +6033,14 @@ LLVM.
Syntax:
This is an overloaded intrinsic. You can use llvm.memcpy on any
- integer bit width. Not all targets support all bit widths however.
+ integer bit width and for different address spaces. Not all targets support
+ all bit widths however.
- declare void @llvm.memcpy.i8(i8 * <dest>, i8 * <src>,
- i8 <len>, i32 <align>)
- declare void @llvm.memcpy.i16(i8 * <dest>, i8 * <src>,
- i16 <len>, i32 <align>)
- declare void @llvm.memcpy.i32(i8 * <dest>, i8 * <src>,
- i32 <len>, i32 <align>)
- declare void @llvm.memcpy.i64(i8 * <dest>, i8 * <src>,
- i64 <len>, i32 <align>)
+ declare void @llvm.memcpy.p0i8.p0i8.i32(i8 * <dest>, i8 * <src>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memcpy.p0i8.p0i8.i64(i8 * <dest>, i8 * <src>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
Overview:
@@ -5706,19 +6048,28 @@ LLVM.
source location to the destination location.
Note that, unlike the standard libc function, the llvm.memcpy.*
- intrinsics do not return a value, and takes an extra alignment argument.
+ intrinsics do not return a value, takes extra alignment/isvolatile arguments
+ and the pointers can be in specified address spaces.
Arguments:
+
The first argument is a pointer to the destination, the second is a pointer
to the source. The third argument is an integer argument specifying the
- number of bytes to copy, and the fourth argument is the alignment of the
- source and destination locations.
+ number of bytes to copy, the fourth argument is the alignment of the
+ source and destination locations, and the fifth is a boolean indicating a
+ volatile access.
-If the call to this intrinisic has an alignment value that is not 0 or 1,
+
If the call to this intrinsic has an alignment value that is not 0 or 1,
then the caller guarantees that both the source and destination pointers are
aligned to that boundary.
+If the isvolatile parameter is true, the
+ llvm.memcpy call is a volatile operation.
+ The detailed access behavior is not very cleanly specified and it is unwise
+ to depend on it.
+
Semantics:
+
The 'llvm.memcpy.*' intrinsics copy a block of memory from the
source location to the destination location, which are not allowed to
overlap. It copies "len" bytes of memory over. If the argument is known to
@@ -5736,17 +6087,14 @@ LLVM.
Syntax:
This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
- width. Not all targets support all bit widths however.
+ width and for different address space. Not all targets support all bit
+ widths however.
- declare void @llvm.memmove.i8(i8 * <dest>, i8 * <src>,
- i8 <len>, i32 <align>)
- declare void @llvm.memmove.i16(i8 * <dest>, i8 * <src>,
- i16 <len>, i32 <align>)
- declare void @llvm.memmove.i32(i8 * <dest>, i8 * <src>,
- i32 <len>, i32 <align>)
- declare void @llvm.memmove.i64(i8 * <dest>, i8 * <src>,
- i64 <len>, i32 <align>)
+ declare void @llvm.memmove.p0i8.p0i8.i32(i8 * <dest>, i8 * <src>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memmove.p0i8.p0i8.i64(i8 * <dest>, i8 * <src>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
Overview:
@@ -5756,19 +6104,28 @@ LLVM.
overlap.
Note that, unlike the standard libc function, the llvm.memmove.*
- intrinsics do not return a value, and takes an extra alignment argument.
+ intrinsics do not return a value, takes extra alignment/isvolatile arguments
+ and the pointers can be in specified address spaces.
Arguments:
+
The first argument is a pointer to the destination, the second is a pointer
to the source. The third argument is an integer argument specifying the
- number of bytes to copy, and the fourth argument is the alignment of the
- source and destination locations.
+ number of bytes to copy, the fourth argument is the alignment of the
+ source and destination locations, and the fifth is a boolean indicating a
+ volatile access.
-If the call to this intrinisic has an alignment value that is not 0 or 1,
+
If the call to this intrinsic has an alignment value that is not 0 or 1,
then the caller guarantees that the source and destination pointers are
aligned to that boundary.
+If the isvolatile parameter is true, the
+ llvm.memmove call is a volatile operation.
+ The detailed access behavior is not very cleanly specified and it is unwise
+ to depend on it.
+
Semantics:
+
The 'llvm.memmove.*' intrinsics copy a block of memory from the
source location to the destination location, which may overlap. It copies
"len" bytes of memory over. If the argument is known to be aligned to some
@@ -5786,17 +6143,14 @@ LLVM.
Syntax:
This is an overloaded intrinsic. You can use llvm.memset on any integer bit
- width. Not all targets support all bit widths however.
+ width and for different address spaces. Not all targets support all bit
+ widths however.
- declare void @llvm.memset.i8(i8 * <dest>, i8 <val>,
- i8 <len>, i32 <align>)
- declare void @llvm.memset.i16(i8 * <dest>, i8 <val>,
- i16 <len>, i32 <align>)
- declare void @llvm.memset.i32(i8 * <dest>, i8 <val>,
- i32 <len>, i32 <align>)
- declare void @llvm.memset.i64(i8 * <dest>, i8 <val>,
- i64 <len>, i32 <align>)
+ declare void @llvm.memset.p0i8.i32(i8 * <dest>, i8 <val>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memset.p0i8.i64(i8 * <dest>, i8 <val>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
Overview:
@@ -5804,7 +6158,8 @@ LLVM.
particular byte value.
Note that, unlike the standard libc function, the llvm.memset
- intrinsic does not return a value, and takes an extra alignment argument.
+ intrinsic does not return a value, takes extra alignment/volatile arguments,
+ and 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
@@ -5812,10 +6167,15 @@ LLVM.
specifying the number of bytes to fill, and the fourth argument is the known
alignment of destination location.
-If the call to this intrinisic has an alignment value that is not 0 or 1,
+
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
boundary.
+If the isvolatile parameter is true, the
+ llvm.memset call is a volatile operation.
+ The detailed access behavior is not very cleanly specified and it is unwise
+ to depend on it.
+
Semantics:
The 'llvm.memset.*' intrinsics fill "len" bytes of memory starting
at the destination location. If the argument is known to be aligned to some
@@ -6435,6 +6795,97 @@ LLVM.
+
+
+
+
+
+Half precision floating point is a storage-only format. This means that it is
+ a dense encoding (in memory) but does not support computation in the
+ format.
+
+This means that code must first load the half-precision floating point
+ value as an i16, then convert it to float with llvm.convert.from.fp16.
+ Computation can then be performed on the float value (including extending to
+ double etc). To store the value back to memory, it is first converted to
+ float if needed, then converted to i16 with
+ llvm.convert.to.fp16, then
+ storing as an i16 value.
+
+
+
+
+
+
+
+Syntax:
+
+ declare i16 @llvm.convert.to.fp16(f32 %a)
+
+
+Overview:
+The 'llvm.convert.to.fp16' intrinsic function performs
+ a conversion from single precision floating point format to half precision
+ floating point format.
+
+Arguments:
+The intrinsic function contains single argument - the value to be
+ converted.
+
+Semantics:
+The 'llvm.convert.to.fp16' intrinsic function performs
+ a conversion from single precision floating point format to half precision
+ floating point format. The return value is an i16 which
+ contains the converted number.
+
+Examples:
+
+ %res = call i16 @llvm.convert.to.fp16(f32 %a)
+ store i16 %res, i16* @x, align 2
+
+
+
+
+
+
+
+
+
+Syntax:
+
+ declare f32 @llvm.convert.from.fp16(i16 %a)
+
+
+Overview:
+The 'llvm.convert.from.fp16' intrinsic function performs
+ a conversion from half precision floating point format to single precision
+ floating point format.
+
+Arguments:
+The intrinsic function contains single argument - the value to be
+ converted.
+
+Semantics:
+The 'llvm.convert.from.fp16' intrinsic function performs a
+ conversion from half single precision floating point format to single
+ precision floating point format. The input half-float value is represented by
+ an i16 value.
+
+Examples:
+
+ %a = load i16* @x, align 2
+ %res = call f32 @llvm.convert.from.fp16(i16 %a)
+
+
+
+
Debugger Intrinsics
@@ -6583,7 +7034,7 @@ LLVM.
Arguments:
The llvm.memory.barrier intrinsic requires five boolean arguments.
The first four arguments enables a specific barrier as listed below. The
- fith argument specifies that the barrier applies to io or device or uncached
+ fifth argument specifies that the barrier applies to io or device or uncached
memory.
@@ -6607,11 +7058,11 @@ LLVM.
- ll: All loads before the barrier must complete before any load
after the barrier begins.
- - ls: All loads before the barrier must complete before any
+
- ls: All loads before the barrier must complete before any
store after the barrier begins.
- - ss: All stores before the barrier must complete before any
+
- ss: All stores before the barrier must complete before any
store after the barrier begins.
- - sl: All stores before the barrier must complete before any
+
- sl: All stores before the barrier must complete before any
load after the barrier begins.
@@ -6824,7 +7275,7 @@ LLVM.
Overview:
-This intrinsic subtracts delta to the value stored in memory at
+
This intrinsic subtracts delta to the value stored in memory at
ptr. It yields the original value at ptr.
Arguments:
@@ -6980,7 +7431,7 @@ LLVM.
Overview:
-These intrinsics takes the signed or unsigned minimum or maximum of
+
These intrinsics takes the signed or unsigned minimum or maximum of
delta and the value stored in memory at ptr. It yields the
original value at ptr.
@@ -7276,6 +7727,42 @@ LLVM.
+
+
+
+
+
+Syntax:
+
+ declare i32 @llvm.objectsize.i32( i8* <object>, i1 <type> )
+ declare i64 @llvm.objectsize.i64( i8* <object>, i1 <type> )
+
+
+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.
+
+Arguments:
+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
+ 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.
+
+
+