LLVM programs are composed of "Module"s, each of which is a translation unit - of the input programs. Each module consists of functions, global variables, - and symbol table entries. Modules may be combined together with the LLVM - linker, which merges function (and global variable) definitions, resolves - forward declarations, and merges symbol table entries. Here is an example of - the "hello world" module:
+LLVM programs are composed of Modules, each of which is a + translation unit of the input programs. Each module consists of functions, + global variables, and symbol table entries. Modules may be combined together + with the LLVM linker, which merges function (and global variable) + definitions, resolves forward declarations, and merges symbol table + entries. Here is an example of the "hello world" module:
; Declare the string constant as a global constant. -@.LC0 = internal constant [13 x i8] c"hello world\0A\00" ; [13 x i8]* +@.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" ; External declaration of the puts function -declare i32 @puts(i8*) ; i32 (i8*)* +declare i32 @puts(i8* nocapture) nounwind ; Definition of main function define i32 @main() { ; i32()* ; Convert [13 x i8]* to i8 *... - %cast210 = getelementptr [13 x i8]* @.LC0, i64 0, i64 0 ; i8* + %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0 ; Call puts function to write out the string to stdout. - call i32 @puts(i8* %cast210) ; i32 + call i32 @puts(i8* %cast210) ret i32 0 } ; Named metadata -!1 = metadata !{i32 41} +!1 = metadata !{i32 42} !foo = !{!1, null}
This example is made up of a global variable named - ".LC0", an external declaration of the "puts" function, + ".str", an external declaration of the "puts" function, a function definition for "main" and named metadata - "foo".
+ "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 +
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 represented by a pointer to a memory location (in this case, a pointer to an array of char, and a pointer to a function), and have one of the following linkage types.
@@ -558,15 +577,6 @@ define i32 @main() { ; i32()* linker. The symbols are removed by the linker from the final linked image (executable or dynamic library). -Global variables define regions of memory allocated at compilation time instead of run-time. Global variables may optionally be initialized, may have an explicit section to be placed in, and may have an optional explicit - alignment specified. A variable may be defined as "thread_local", which + alignment specified.
+ +A variable may be defined as thread_local, which means that it will not be shared by threads (each thread will have a - separated copy of the variable). A variable may be defined as a global + separated copy of the variable). Not all targets support thread-local + variables. Optionally, a TLS model may be specified:
+ +The models correspond to the ELF TLS models; see + ELF + Handling For Thread-Local Storage for more information on under which + circumstances the different models may be used. The target may choose a + different TLS model if the specified model is not supported, or if a better + choice of model can be made.
+ +A variable may be defined as a global "constant," which indicates that the contents of the variable will never be modified (enabling better optimization, allowing the global data to be placed in the read-only section of an executable, etc). @@ -879,6 +920,13 @@ define i32 @main() { ; i32()* @G = addrspace(5) constant float 1.0, section "foo", align 4 +
The following example defines a thread-local global with + the initialexec TLS model:
+ ++@G = thread_local(initialexec) global i32 0, align 4 ++
setjmp is an example of such a function. The compiler
+ disables some optimizations (like tail calls) in the caller of these
+ functions.setjmp is an example of such a function.
- The compiler disables some optimizations (like tail calls) in the caller of
- these functions.fence instructions
treat these orderings somewhat differently since they don't take an address.
See that instruction's documentation for details.
@@ -1707,7 +1757,7 @@ in signal handlers).
| Type | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| half | 16-bit floating point value | |||||||||||||
| float | 32-bit floating point value | |||||||||||||
| double | 64-bit floating point value | |||||||||||||
| fp128 | 128-bit floating point value (112-bit mantissa) |
| <2 x i64> | Vector of 2 64-bit integer values. | +
| <4 x i64*> | +Vector of 4 pointers to 64-bit integer values. | +
When using the hexadecimal form, constants of types float and double are +
When using the hexadecimal form, constants of types half, float, and double are represented using the 16-digit form shown above (which matches the IEEE754 - representation for double); float values must, however, be exactly - representable as IEE754 single precision. Hexadecimal format is always used + representation for double); half and float values must, however, be exactly + representable as IEE754 half and single precision, respectively. + Hexadecimal format is always used for long double, and there are three forms of long double. The 80-bit format used by x86 is represented as 0xK followed by 20 hexadecimal digits. The 128-bit format used by PowerPC (two adjacent doubles) is represented by 0xM followed by 32 hexadecimal digits. The IEEE 128-bit format is represented by 0xL followed by 32 hexadecimal digits; no currently supported target uses this format. Long doubles will only work if - they match the long double format on your target. All hexadecimal formats - are big-endian (sign bit at the left).
+ they match the long double format on your target. The IEEE 16-bit format + (half precision) is represented by 0xH followed by 4 hexadecimal + digits. All hexadecimal formats are big-endian (sign bit at the left).There are no constants of type x86mmx.
@@ -2500,22 +2557,21 @@ b: unreachableTrap 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.
+Poison values are similar to undef values, however + they also 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 +
There is currently no way of representing a poison 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:
+Poison 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, they 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.
+Poison Values have the same behavior as undef values, + with the additional affect that any instruction which has a dependence + on a poison value has undefined behavior.
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 + %poison = sub nuw i32 0, 1 ; Results in a poison value. + %still_poison = and i32 %poison, 0 ; 0, but also poison. + %poison_yet_again = getelementptr i32* @h, i32 %still_poison + store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned - store i32 %trap, i32* @g ; Trap value conceptually stored to memory. - %trap2 = load i32* @g ; Returns a trap value, not just undef. + store i32 %poison, i32* @g ; Poison value stored to memory. + %poison2 = load i32* @g ; Poison value loaded back from memory. - volatile store i32 %trap, i32* @g ; External observation; undefined behavior. + store volatile i32 %poison, i32* @g ; External observation; undefined behavior. %narrowaddr = bitcast i32* @g to i16* %wideaddr = bitcast i32* @g to i64* - %trap3 = load i16* %narrowaddr ; Returns a trap value. - %trap4 = load i64* %wideaddr ; Returns a trap value. + %poison3 = load i16* %narrowaddr ; Returns a poison value. + %poison4 = load i64* %wideaddr ; Returns a poison value. - %cmp = icmp slt i32 %trap, 0 ; Returns a trap value. - br i1 %cmp, label %true, label %end ; Branch to either destination. + %cmp = icmp slt i32 %poison, 0 ; Returns a poison value. + br i1 %cmp, label %true, label %end ; Branch to either destination. true: - volatile store i32 0, i32* @g ; This is control-dependent on %cmp, so - ; it has undefined behavior. + store volatile 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. + ; Both edges into this PHI are + ; control-dependent on %cmp, so this + ; always results in a poison value. - volatile store i32 0, i32* @g ; This would depend on the store in %true - ; if %cmp is true, or the store in %entry - ; otherwise, so this is undefined behavior. + store volatile i32 0, i32* @g ; This would depend on the store in %true + ; if %cmp is true, or the store in %entry + ; otherwise, so this is undefined behavior. br i1 %cmp, label %second_true, label %second_end - ; The same branch again, but this time the - ; true block doesn't have side effects. + ; The same branch again, but this time the + ; true block doesn't have side effects. second_true: ; No side effects! ret void second_end: - volatile store i32 0, i32* @g ; This time, the instruction always depends - ; on the store in %end. Also, it is - ; control-equivalent to %end, so this is - ; well-defined (again, ignoring earlier - ; undefined behavior in this example). + store volatile i32 0, i32* @g ; This time, the instruction always depends + ; on the store in %end. Also, it is + ; control-equivalent to %end, so this is + ; well-defined (ignoring earlier undefined + ; behavior in this example).
LLVM supports inline assembler expressions (as opposed - to Module-Level Inline Assembly) through the use of + to Module-Level Inline Assembly) through the use of a special value. This value represents the inline assembler as a string (containing the instructions to emit), a list of operand constraints (stored as a string), a flag that indicates whether or not the inline asm @@ -2813,8 +2868,9 @@ i32 (i32) asm "bswap $0", "=r,r"
Inline assembler expressions may only be used as the callee operand of - a call instruction. Thus, typically we - have:
+ a call or an + invoke instruction. + Thus, typically we have:%X = call i32 asm "bswap $0", "=r,r"(i32 %Y) @@ -2839,26 +2895,40 @@ call void asm sideeffect "eieio", ""() call void asm alignstack "eieio", ""()-
If both keywords appear the 'sideeffect' keyword must come - first.
+Inline asms also support using non-standard assembly dialects. The assumed + dialect is ATT. When the 'inteldialect' keyword is present, the + inline asm is using the Intel dialect. Currently, ATT and Intel are the + only supported dialects. An example is:
+ ++call void asm inteldialect "eieio", ""() ++ +
If multiple keywords appear the 'sideeffect' keyword must come + first, the 'alignstack' keyword second and the + 'inteldialect' keyword last.
+ +The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode - 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:
+The call instructions that wrap inline asm nodes may have a + "!srcloc" MDNode 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:
call void asm sideeffect "something bad", ""(), !srcloc !42 @@ -2867,7 +2937,7 @@ 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. If the MDNode contains multiple constants, the code generator will use + 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.
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"".
+ 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.
+ exclamation point). Metadata nodes can have any values as their operand. For + example: + +
+!{ metadata !"test\00", i32 10}
+
+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}". + example:
+ +
+!foo = metadata !{!4, !3}
+
+Metadata can be used as function arguments. Here llvm.dbg.value - function is using two metadata arguments.
+ function is using two metadata arguments:@@ -2911,7 +2994,8 @@ 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.
+ attached to the add instruction using the !dbg + identifier:@@ -2922,6 +3006,7 @@ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)More information about specific metadata nodes recognized by the optimizers and code generator is found below.
+'tbaa' Metadata
@@ -2966,35 +3051,318 @@ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
The llvm.memcpy is often used to implement +aggregate assignment operations in C and similar languages, however it is +defined to copy a contiguous region of memory, which is more than strictly +necessary for aggregate types which contain holes due to padding. Also, it +doesn't contain any TBAA information about the fields of the aggregate.
+ +!tbaa.struct metadata can describe which memory subregions in a memcpy +are padding and what the TBAA tags of the struct are.
+ +The current metadata format is very simple. !tbaa.struct metadata nodes + are a list of operands which are in conceptual groups of three. For each + group of three, the first operand gives the byte offset of a field in bytes, + the second gives its size in bytes, and the third gives its + tbaa tag. e.g.:
+ +
+!4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }
+
+This describes a struct with two fields. The first is at offset 0 bytes + with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes + and has size 4 bytes and has tbaa tag !2.
+ +Note that the fields need not be contiguous. In this example, there is a + 4 byte gap between the two fields. This gap represents padding which + does not carry useful data and need not be preserved.
+ +fpaccuracy metadata may be attached to any instruction of floating - point type. It expresses the maximum relative error of the result of - that instruction, in ULPs. ULP is defined as follows:
+fpmath metadata may be attached to any instruction of floating point + type. It can be used to express the maximum acceptable error in the result of + that instruction, in ULPs, thus potentially allowing the compiler to use a + more efficient but less accurate method of computing it. ULP is defined as + follows:
+ ++ ++ +If x is a real number that lies between two finite consecutive + floating-point numbers a and b, without being equal to one + of them, then ulp(x) = |b - a|, otherwise ulp(x) is the + distance between the two non-equal finite floating-point numbers nearest + x. Moreover, ulp(NaN) is NaN.
+ +
The metadata node shall consist of a single positive floating point number + representing the maximum relative error, for example:
+ +
+!0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
+
++ +-If x is a real number that lies between two finite consecutive floating-point -numbers a and b, without being equal to one of them, then ulp(x) = |b - a|, -otherwise ulp(x) is the distance between the two non-equal finite -floating-point numbers nearest x. Moreover, ulp(NaN) is NaN. -
The maximum relative error may be any rational number. The metadata node - shall consist of a pair of unsigned integers respectively representing - the numerator and denominator. For example, 2.5 ULP:
+range metadata may be attached only to loads of integer types. It + expresses the possible ranges the loaded value is in. The ranges are + represented with a flattened list of integers. The loaded value is known to + be in the union of the ranges defined by each consecutive pair. Each pair + has the following properties:
+In addition, the pairs must be in signed order of the lower bound and + they must be non-contiguous.
+Examples:
-!0 = metadata !{ i32 5, i32 2 }
+ %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
+ %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
+ %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
+ %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5
+...
+!0 = metadata !{ i8 0, i8 2 }
+!1 = metadata !{ i8 255, i8 2 }
+!2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
+!3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
Information about the module as a whole is difficult to convey to LLVM's + subsystems. The LLVM IR isn't sufficient to transmit this + information. The llvm.module.flags named metadata exists in order to + facilitate this. These flags are in the form of key / value pairs — + much like a dictionary — making it easy for any subsystem who cares + about a flag to look it up.
+ +The llvm.module.flags metadata contains a list of metadata + triplets. Each triplet has the following form:
+ +When two (or more) modules are merged together, the resulting + llvm.module.flags metadata is the union of the + modules' llvm.module.flags metadata. The only exception being a flag + with the Override behavior, which may override another flag's value + (see below).
+ +The following behaviors are supported:
+ +| Value | +Behavior | +
|---|---|
| 1 | +
+
|
+
| 2 | +
+
|
+
| 3 | +
+
|
+
| 4 | +
+
|
+
An example of module flags:
+ +
+!0 = metadata !{ i32 1, metadata !"foo", i32 1 }
+!1 = metadata !{ i32 4, metadata !"bar", i32 37 }
+!2 = metadata !{ i32 2, metadata !"qux", i32 42 }
+!3 = metadata !{ i32 3, metadata !"qux",
+ metadata !{
+ metadata !"foo", i32 1
+ }
+}
+!llvm.module.flags = !{ !0, !1, !2, !3 }
+
+
+Metadata !0 has the ID !"foo" and the value '1'. The + behavior if two or more !"foo" flags are seen is to emit an + error if their values are not equal.
Metadata !1 has the ID !"bar" and the value '37'. The + behavior if two or more !"bar" flags are seen is to use the + value '37' if their values are not equal.
Metadata !2 has the ID !"qux" and the value '42'. The + behavior if two or more !"qux" flags are seen is to emit a + warning if their values are not equal.
Metadata !3 has the ID !"qux" and the value:
+ +
+metadata !{ metadata !"foo", i32 1 }
+
+
+ The behavior is to emit an error if the llvm.module.flags does + not contain a flag with the ID !"foo" that has the value + '1'. If two or more !"qux" flags exist, then they must have + the same value or an error will be issued.
On the Mach-O platform, Objective-C stores metadata about garbage collection + in a special section called "image info". The metadata consists of a version + number and a bitmask specifying what types of garbage collection are + supported (if any) by the file. If two or more modules are linked together + their garbage collection metadata needs to be merged rather than appended + together.
+ +The Objective-C garbage collection module flags metadata consists of the + following key-value pairs:
+ +| Key | +Value | +
|---|---|
| Objective-C Version | +[Required] — The Objective-C ABI + version. Valid values are 1 and 2. | +
| Objective-C Image Info Version | +[Required] — The version of the image info + section. Currently always 0. | +
| Objective-C Image Info Section | +[Required] — The section to place the + metadata. Valid values are "__OBJC, __image_info, regular" for + Objective-C ABI version 1, and "__DATA,__objc_imageinfo, regular, + no_dead_strip" for Objective-C ABI version 2. | +
| Objective-C Garbage Collection | +[Required] — Specifies whether garbage + collection is supported or not. Valid values are 0, for no garbage + collection, and 2, for garbage collection supported. | +
| Objective-C GC Only | +[Optional] — Specifies that only garbage + collection is supported. If present, its value must be 6. This flag + requires that the Objective-C Garbage Collection flag have the + value 2. | +
Some important flag interactions:
+ +The 'exception' label is a landing pad for the exception. As such, 'exception' label is required to have the "landingpad" instruction, which contains - the information about about the behavior of the program after unwinding + the information about the behavior of the program after unwinding happens, as its first non-PHI instruction. The restrictions on the "landingpad" instruction's tightly couples it to the "invoke" instruction, so that the important information contained @@ -3411,8 +3778,9 @@ IfUnequal:
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
@@ -3446,38 +3811,6 @@ that the invoke/unwind semantics are likely to change in future versions.
unwind label %TestCleanup ; {i32}:retval set
-
-
-
-
-- unwind -- -
The 'unwind' instruction unwinds the stack, continuing control flow - at the first callee in the dynamic call stack which used - an invoke instruction to perform the call. - This is primarily used to implement exception handling.
- -The 'unwind' instruction causes execution of the current function to - immediately halt. The dynamic call stack is then searched for the - first invoke instruction on the call stack. - Once found, execution continues at the "exceptional" destination block - 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.
-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 a trap value if unsigned and/or signed overflow, + is a poison value if unsigned and/or signed overflow, respectively, occurs.
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 a trap value if unsigned and/or signed overflow, + is a poison value if unsigned and/or signed overflow, respectively, occurs.
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 a trap value if unsigned and/or signed overflow, + is a poison value if unsigned and/or signed overflow, respectively, occurs.
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 + udiv is a poison value if %op1 is not a multiple of %op2 (as such, "((a udiv exact b) mul b) == a").
@@ -3872,7 +4205,7 @@ that the invoke/unwind semantics are likely to change in future versions. a 32-bit division of -2147483648 by -1.If the exact keyword is present, the result value of the - sdiv is a trap value if the result would + sdiv is a poison value if the result would be rounded.
If the nuw keyword is present, then the shift produces a - trap value if it shifts out any non-zero bits. If + poison 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 + poison 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)).
@@ -4130,7 +4463,7 @@ that the invoke/unwind semantics are likely to change in future versions. 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 + lshr is a poison value if any of the bits shifted out are non-zero.
@@ -4178,7 +4511,7 @@ that the invoke/unwind semantics are likely to change in future versions. 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 + ashr is a poison value if any of the bits shifted out are non-zero.
| In0 | -In1 | -Out | +In0 | +In1 | +Out | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | @@ -4281,9 +4614,9 @@ that the invoke/unwind semantics are likely to change in future versions.
| In0 | -In1 | -Out | +In0 | +In1 | +Out | ||
|---|---|---|---|---|---|---|---|
| 0 | @@ -4345,9 +4678,9 @@ that the invoke/unwind semantics are likely to change in future versions.
| In0 | -In1 | -Out | +In0 | +In1 | +Out |
|---|---|---|---|---|---|
| 0 | @@ -4489,7 +4822,7 @@ that the invoke/unwind semantics are likely to change in future versions.