X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FLangRef.html;h=6206d774a07944f4e9a46d9b57f99f92520833e0;hb=7d6915cf43a1c436dce75760208c99f309700a57;hp=41379db37f7cc0268740362cafba331b58fd2e29;hpb=d3f876c93c9ce33899a9feca3c0e8de1a895008f;p=oota-llvm.git diff --git a/docs/LangRef.html b/docs/LangRef.html index 41379db37f7..6206d774a07 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -17,6 +17,15 @@
The LLVM representation aims to be a light-weight and low-level +
The LLVM representation aims to be light-weight and low-level while being expressive, typed, and extensible at the same time. It aims to be a "universal IR" of sorts, by being at a low enough level that high-level ideas may be cleanly mapped to it (similar to how @@ -201,7 +223,7 @@ following instruction is syntactically okay, but not well formed:
...because the definition of %x does not dominate all of its uses. The LLVM infrastructure provides a verification pass that may be used to verify that an LLVM module is well formed. This pass is -automatically run by the parser after parsing input assembly, and by +automatically run by the parser after parsing input assembly and by the optimizer before it outputs bytecode. The violations pointed out by the verifier pass indicate bugs in transformation passes or input to the parser.
@@ -218,71 +240,327 @@ the parser. purposes:LLVM requires that values start with a '%' sign for two reasons: -Compilers don't need to worry about name clashes with reserved words, -and the set of reserved words may be expanded in the future without -penalty. Additionally, unnamed identifiers allow a compiler to quickly -come up with a temporary variable without having to avoid symbol table -conflicts.
+ +LLVM requires that values start with a '%' sign for two reasons: Compilers +don't need to worry about name clashes with reserved words, and the set of +reserved words may be expanded in the future without penalty. Additionally, +unnamed identifiers allow a compiler to quickly come up with a temporary +variable without having to avoid symbol table conflicts.
+Reserved words in LLVM are very similar to reserved words in other languages. There are keywords for different opcodes ('add', 'cast', 'ret', etc...), for primitive type names ('void', 'uint', -etc...), and others. These reserved words cannot conflict with -variable names, because none of them start with a '%' character.
-Here is an example of LLVM code to multiply the integer variable '%X' -by 8:
+href="#i_add">add', 'cast', 'ret', etc...), for primitive type names ('void', 'uint', etc...), +and others. These reserved words cannot conflict with variable names, because +none of them start with a '%' character. + +Here is an example of LLVM code to multiply the integer variable +'%X' by 8:
+The easy way:
-%result = mul uint %X, 8+ +
+ %result = mul uint %X, 8 ++
After strength reduction:
-%result = shl uint %X, ubyte 3+ +
+ %result = shl uint %X, ubyte 3 ++
And the hard way:
-add uint %X, %X ; yields {uint}:%0 - add uint %0, %0 ; yields {uint}:%1 - %result = add uint %1, %1+ +
+ add uint %X, %X ; yields {uint}:%0 + add uint %0, %0 ; yields {uint}:%1 + %result = add uint %1, %1 ++
This last way of multiplying %X by 8 illustrates several important lexical features of LLVM:
+...and it also show a convention that we follow in this document. -When demonstrating instructions, we will follow an instruction with a -comment that defines the type and name of value produced. Comments are -shown in italic text.
-The one non-intuitive notation for constants is the optional -hexidecimal form of floating point constants. For example, the form 'double -0x432ff973cafa8000' is equivalent to (but harder to read than) 'double -4.5e+15' which is also supported by the parser. The only time -hexadecimal floating point constants are useful (and the only time that -they are generated by the disassembler) is when an FP constant has to -be emitted that is not representable as a decimal floating point number -exactly. For example, NaN's, infinities, and other special cases are -represented in their IEEE hexadecimal format so that assembly and -disassembly do not cause any bits to change in the constants.
+ +...and it also shows a convention that we follow in this document. When +demonstrating instructions, we will follow an instruction with a comment that +defines the type and name of value produced. Comments are shown in italic +text.
+ + + + + + + + + +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:
+ +; Declare the string constant as a global constant... +%.LC0 = internal constant [13 x sbyte] c"hello world\0A\00" ; [13 x sbyte]* + +; External declaration of the puts function +declare int %puts(sbyte*) ; int(sbyte*)* + +; Definition of main function +int %main() { ; int()* + ; Convert [13x sbyte]* to sbyte *... + %cast210 = getelementptr [13 x sbyte]* %.LC0, long 0, long 0 ; sbyte* + + ; Call puts function to write out the string to stdout... + call int %puts(sbyte* %cast210) ; int + ret int 0+ +
}
This example is made up of a global variable +named ".LC0", an external declaration of the "puts" +function, and a function definition +for "main".
+ +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.
+ ++All Global Variables and Functions have one of the following types of linkage: +
+ +LLVM functions, calls +and invokes can all have an optional calling convention +specified for the call. The calling convention of any pair of dynamic +caller/callee must match, or the behavior of the program is undefined. The +following calling conventions are supported by LLVM, and more may be added in +the future:
+ +More calling conventions can be added/defined on an as-needed basis, to +support pascal conventions or any other well-known target-independent +convention.
+ +Global variables define regions of memory allocated at compilation time +instead of run-time. Global variables may optionally be initialized. 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). Note that variables that need runtime initialization +cannot be marked "constant", as there is a store to the variable.
+ ++LLVM explicitly allows declarations of global variables to be marked +constant, even if the final definition of the global is not. This capability +can be used to enable slightly better optimization of the program, but requires +the language definition to guarantee that optimizations based on the +'constantness' are valid for the translation units that do not include the +definition. +
+ +As SSA values, global variables define pointer values that are in +scope (i.e. they dominate) all basic blocks in the program. Global +variables always define a pointer to their "content" type because they +describe a region of memory, and all memory objects in LLVM are +accessed through pointers.
+ +LLVM function definitions consist of an optional linkage +type, an optional calling convention, a return +type, a function name, a (possibly empty) argument list, an opening curly brace, +a list of basic blocks, and a closing curly brace. LLVM function declarations +are defined with the "declare" keyword, an optional calling convention, a return type, a function name, and +a possibly empty list of arguments.
+ +A function definition contains a list of basic blocks, forming the CFG for +the function. Each basic block may optionally start with a label (giving the +basic block a symbol table entry), contains a list of instructions, and ends +with a terminator instruction (such as a branch or +function return).
+ +The first basic block in a program is special in two ways: it is immediately +executed on entrance to the function, and it is not allowed to have predecessor +basic blocks (i.e. there can not be any branches to the entry block of a +function). Because the block can have no predecessors, it also cannot have any +PHI nodes.
+ +LLVM functions are identified by their name and type signature. Hence, two +functions with the same name but different parameter lists or return values are +considered different functions, and LLVM will resolve references to each +appropriately.
+ +The LLVM type system is one of the most important features of the intermediate representation. Being typed enables a number of optimizations to be performed on the IR directly, without having to do @@ -290,14 +568,14 @@ extra analyses on the side before the transformation. A strong type system makes it easier to read the generated code and enables novel analyses and transformations that are not feasible to perform on normal three address code representations.
-The primitive types are the fundamental building blocks of the LLVM -system. The current set of primitive types are as follows:
+system. The current set of primitive types is as follows:Type | Description |
---|---|
void | No value |
ubyte | Unsigned 8 bit value |
ushort | Unsigned 16 bit value |
uint | Unsigned 32 bit value |
ulong | Unsigned 64 bit value |
float | 32 bit floating point value |
ubyte | Unsigned 8-bit value |
ushort | Unsigned 16-bit value |
uint | Unsigned 32-bit value |
ulong | Unsigned 64-bit value |
float | 32-bit floating point value |
label | Branch destination |
The real power in LLVM comes from the derived types in the system. This is what allows a programmer to represent arrays, functions, pointers, and other useful types. Note that these derived types may be recursive: For example, it is possible to have a two dimensional array.
+The array type is a very simple derived type that arranges elements sequentially in memory. The array type requires a size (number of elements) and an underlying data type.
+[<# elements> x <elementtype>]-
The number of elements is a constant integer value, elementtype may + +
+ [<# elements> x <elementtype>] ++ +
The number of elements is a constant integer value; elementtype may be any type with a size.
+
- 3x4 array integer values. + 3x4 array of integer values. 12x10 array of single precision floating point values. 2x3x4 array of unsigned integer values. |
Note that 'variable sized arrays' can be implemented in LLVM With a zero +length array. Normally accesses past the end of an array are undefined in +LLVM (e.g. it is illegal to access the 5th element of a 3 element array). +As a special case, however, zero length arrays are recognized to be variable +length. This allows implementation of 'pascal style arrays' with the LLVM +type "{ int, [0 x float]}", for example.
+A packed type is a simple derived type that represents a vector of elements. Packed types are used when multiple primitive data are operated in parallel using a single instruction (SIMD). A packed type requires a size (number of elements) and an underlying primitive data type. Packed types are considered first class.
+< <# elements> x <elementtype> >-
The number of elements is a constant integer value, elementtype may + +
+ < <# elements> x <elementtype> > ++ +
The number of elements is a constant integer value; elementtype may be any integral or floating point type.
+@@ -557,180 +866,248 @@ be any integral or floating point type. |
Opaque types are used to represent unknown types in the system. This +corresponds (for example) to the C notion of a foward declared structure type. +In LLVM, opaque types can eventually be resolved to any type (not just a +structure type).
+ ++ opaque ++ +
+ opaque + | +
+ An opaque type. + |
+
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:
-; Declare the string constant as a global constant... -%.LC0 = internal constant [13 x sbyte] c"hello world\0A\00" ; [13 x sbyte]* -; External declaration of the puts function -declare int %puts(sbyte*) ; int(sbyte*)* +LLVM has several different basic types of constants. This section describes +them all and their syntax.
-; Definition of main function -int %main() { ; int()* - ; Convert [13x sbyte]* to sbyte *... - %cast210 = getelementptr [13 x sbyte]* %.LC0, long 0, long 0 ; sbyte* +
This example is made up of a global variable -named ".LC0", an external declaration of the "puts" -function, and a function definition -for "main".
- 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: -
+
+ +
+ +
The one non-intuitive notation for constants is the optional hexadecimal form +of floating point constants. For example, the form 'double +0x432ff973cafa8000' is equivalent to (but harder to read than) 'double +4.5e+15'. The only time hexadecimal floating point constants are required +(and the only time that they are generated by the disassembler) is when a +floating point constant must be emitted but it cannot be represented as a +decimal floating point number. For example, NaN's, infinities, and other +special values are represented in their IEEE hexadecimal format so that +assembly and disassembly do not cause any bits to change in the constants.
+ +Aggregate constants arise from aggregation of simple constants +and smaller aggregate constants.
+ ++ +
+ +
- +
Global variables define regions of memory allocated at compilation -time instead of run-time. Global variables may optionally be -initialized. A variable may be defined as a global "constant", which -indicates that the contents of the variable will never be modified -(opening options for optimization).
+The addresses of global variables and functions are always implicitly valid (link-time) +constants. These constants are explicitly referenced when the identifier for the global is used and always have pointer type. For example, the following is a legal LLVM +file:
-As SSA values, global variables define pointer values that are in -scope (i.e. they dominate) for all basic blocks in the program. Global -variables always define a pointer to their "content" type because they -describe a region of memory, and all memory objects in LLVM are -accessed through pointers.
++ %X = global int 17 + %Y = global int 42 + %Z = global [2 x int*] [ int* %X, int* %Y ] +
The string 'undef' is recognized as a type-less constant that has + no specific value. Undefined values may be of any type and be used anywhere + a constant is permitted.
+ +Undefined values indicate to the compiler that the program is well defined + no matter what value is used, giving the compiler more freedom to optimize. +
+LLVM function definitions are composed of a (possibly empty) argument list, -an opening curly brace, a list of basic blocks, and a closing curly brace. LLVM -function declarations are defined with the "declare" keyword, a -function name, and a function signature.
+Constant expressions are used to allow expressions involving other constants +to be used as constants. Constant expressions may be of any first class type and may involve any LLVM operation +that does not have side effects (e.g. load and call are not supported). The +following is the syntax for constant expressions:
-A function definition contains a list of basic blocks, forming the CFG for -the function. Each basic block may optionally start with a label (giving the -basic block a symbol table entry), contains a list of instructions, and ends -with a terminator instruction (such as a branch or -function return).
+The first basic block in program is special in two ways: it is immediately -executed on entrance to the function, and it is not allowed to have predecessor -basic blocks (i.e. there can not be any branches to the entry block of a -function). Because the block can have no predecessors, it also cannot have any -PHI nodes.
+LLVM functions are identified by their name and type signature. Hence, two -functions with the same name but different parameter lists or return values are -considered different functions, and LLVM will resolves references to each -appropriately.
+The LLVM instruction set consists of several different classifications of instructions: terminator -instructions, binary instructions, , binary instructions, +bitwise binary instructions, memory instructions, and other instructions.
+As mentioned previously, every basic block in a program ends with a "Terminator" instruction, which indicates which block should be executed after the current block is finished. These terminator instructions typically yield a 'void' value: they produce control flow, not values (the one exception being the 'invoke' instruction).
-There are five different terminator instructions: the 'There are six different terminator instructions: the 'ret' instruction, the 'br' instruction, the 'switch' instruction, the 'invoke' instruction, the 'unwind' instruction, and the 'unreachable' instruction.
+The 'ret' instruction is used to return control flow (and a -value) from a function, back to the caller.
+value) from a function back to the caller.There are two forms of the 'ret' instruction: one that returns a value and then causes control flow, and one that just causes control flow to occur.
@@ -757,7 +1134,7 @@ returns back to the calling function's context. If the caller is a "call" instruction, execution continues at the instruction after the call. If the caller was an "invoke" instruction, execution continues -at the beginning "normal" of the destination block. If the instruction +at the beginning of the "normal" destination block. If the instruction returns a value, that value shall set the call or invoke instruction's return value.<result> = invoke <ptr to function ty> %<function ptr val>(<function args>)+ +
to label <normal label> except label <exception label>
+ <result> = invoke [cconv] <ptr to function ty> %<function ptr val>(<function args>) + to label <normal label> except label <exception label> ++
The 'invoke' instruction causes control to transfer to a -specified function, with the possibility of control flow transfer to -either the 'normal' label label or the 'exception'label. -If the callee function returns with the "ret" -instruction, control flow will return to the "normal" label. If the -callee (or any indirect callees) returns with the "unwind" -instruction, control is interrupted, and continued at the dynamically -nearest "except" label.
+ +The 'invoke' instruction causes control to transfer to a specified +function, with the possibility of control flow transfer to either the +'normal' label or the +'exception' label. If the callee function returns with the +"ret" instruction, control flow will return to the +"normal" label. If the callee (or any indirect callees) returns with the "unwind" instruction, control is interrupted and +continued at the dynamically nearest "exception" label.
+This instruction requires several arguments:
+This instruction is designed to operate as a standard 'call' instruction in most regards. The -primary difference is that it establishes an association with a label, -which is used by the runtime library to unwind the stack.
-This instruction is used in languages with destructors to ensure -that proper cleanup is performed in the case of either a longjmp -or a thrown exception. Additionally, this is important for -implementation of 'catch' clauses in high-level languages that -support them.
+href="#i_call">call' instruction in most regards. The primary +difference is that it establishes an association with a label, which is used by +the runtime library to unwind the stack. + +This instruction is used in languages with destructors to ensure that proper +cleanup is performed in the case of either a longjmp or a thrown +exception. Additionally, this is important for implementation of +'catch' clauses in high-level languages that support them.
+%retval = invoke int %Test(int 15)
to label %Continue
except label %TestCleanup ; {int}:retval set ++ %retval = invoke int %Test(int 15) to label %Continue + except label %TestCleanup ; {int}:retval set + %retval = invoke coldcc int %Test(int 15) to label %Continue + except label %TestCleanup ; {int}:retval set
Binary operators are used to do most of the computation in a program. They require two operands, execute an operation on them, and -produce a single value. Although, that single value might represent +produce a single value. The operands might represent multiple data, as is the case with the packed data type. The result value of a binary operator is not necessarily the same type as its operands.
@@ -1135,7 +1543,7 @@ OperationsBitwise binary operators are used to do various forms of bit-twiddling in a program. They are generally very efficient -instructions, and can commonly be strength reduced from other +instructions and can commonly be strength reduced from other instructions. They require two operands, execute an operation on them, and produce a single value. The resulting value of the bitwise binary operators is always the same type as its first operand.
@@ -1360,7 +1768,7 @@ OperationsA key design point of an SSA-based representation is how it represents memory. In LLVM, no memory locations are in SSA form, which makes things very simple. This section describes how to read, write, -allocate and free memory in LLVM.
+allocate, and free memory in LLVM.The 'free' instruction returns memory back to the unused -memory heap, to be reallocated in the future.
+memory heap to be reallocated in the future.
'value' shall be a pointer value that points to a value that was allocated with the 'malloc' instruction.
Access to the memory pointed to by the pointer is not longer defined +
Access to the memory pointed to by the pointer is no longer defined after this instruction executes.
%array = malloc [4 x ubyte] ; yields {[4 x ubyte]*}:array @@ -1428,17 +1836,17 @@ Instruction stack frame of the procedure that is live until the current function returns to its caller.Arguments:
-The the 'alloca' instruction allocates sizeof(<type>)*NumElements +
The 'alloca' instruction allocates sizeof(<type>)*NumElements bytes of memory on the runtime stack, returning a pointer of the appropriate type to the program. The second form of the instruction is a shorter version of the first that defaults to allocating one element.
'type' may be any sized type.
Semantics:
-Memory is allocated, a pointer is returned. 'alloca'd +
Memory is allocated; a pointer is returned. 'alloca'd memory is automatically released when the function returns. The 'alloca' instruction is commonly used to represent automatic variables that must have an address available. When the function returns (either with the ret or invoke + href="#i_ret">ret or unwind instructions), the memory is reclaimed.
Example:
%ptr = alloca int ; yields {int*}:ptr @@ -1483,7 +1891,7 @@ InstructionThere are two arguments to the 'store' instruction: a value to store and an address to store it into. The type of the '<pointer>' operand must be a pointer to the type of the '<value>' -operand. If the store is marked as volatile then the +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.
@@ -1519,8 +1927,9 @@ subelement of an aggregate data structure. elements of the aggregate object to index to. The actual types of the arguments provided depend on the type of the first pointer argument. The 'getelementptr' instruction is used to index down through the type -levels of a structure. When indexing into a structure, only uint -integer constants are allowed. When indexing into an array or pointer +levels of a structure or to a specific index in an array. When indexing into a +structure, only uint +integer constants are allowed. When indexing into an array or pointer, int and long indexes are allowed of any sign.For example, let's consider a C code fragment and how it gets @@ -1561,7 +1970,7 @@ compiled to LLVM:
Semantics:
The index types specified for the 'getelementptr' instruction depend -on the pointer type that is being index into. Pointer +on the pointer type that is being indexed into. Pointer and array types require uint, int, ulong, or long values, and structure types require uint constants.
@@ -1573,7 +1982,7 @@ the structure, yielding a '%RT' = '{ sbyte, [10 x [20 x int]], sbyte }' type, another structure. The third index indexes into the second element of the structure, yielding a '[10 x [20 x int]]' type, an array. The two dimensions of the array are subscripted into, yielding an -'int' type. The 'getelementptr' instruction return a pointer +'int' type. The 'getelementptr' instruction returns a pointer to this element, thus computing a value of 'int*' type.Note that it is perfectly legal to index partially through a @@ -1581,7 +1990,7 @@ structure, returning a pointer to an inner element. Because of this, the LLVM code for the given testcase is equivalent to:
- int* "foo"(%ST* %s) { + int* %foo(%ST* %s) { %t1 = getelementptr %ST* %s, int 1 ; yields %ST*:%t1 %t2 = getelementptr %ST* %t1, int 0, uint 2 ; yields %RT*:%t2 %t3 = getelementptr %RT* %t2, int 0, uint 1 ; yields [10 x [20 x int]]*:%t3 @@ -1590,7 +1999,15 @@ the LLVM code for the given testcase is equivalent to: ret int* %t5 }+ +Note that it is undefined to access an array out of bounds: array and +pointer indexes must always be within the defined bounds of the array type. +The one exception for this rules is zero length arrays. These arrays are +defined to be accessible as variable length arrays, which requires access +beyond the zero'th element.
+Example:
+; yields [12 x ubyte]*:aptr %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1 @@ -1720,7 +2137,7 @@ The 'select' instruction requires a boolean value indicating the conditIf the boolean condition evaluates to true, the instruction returns the first -value argument, otherwise it returns the second value argument. +value argument; otherwise, it returns the second value argument.
Example:
@@ -1735,35 +2152,61 @@ value argument, otherwise it returns the second value argument. - + ++- - - - -Syntax:
-<result> = call <ty>* <fnptrval>(<param list>)++ <result> = [tail] call [cconv] <ty>* <fnptrval>(<param list>) ++Overview:
+The 'call' instruction represents a simple function call.
+Arguments:
+This instruction requires several arguments:
++
- -
+'ty': shall be the signature of the pointer to function -value being invoked. The argument types must match the types implied -by this signature.
+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 "cconv" marker indicates which calling + convention the call should use. If none is specified, the call defaults + to using C calling conventions.
- -
+'fnptrval': An LLVM value containing a pointer to a -function to be invoked. In most cases, this is a direct function -invocation, but indirect calls are just as possible, -calling an arbitrary pointer to function values.
+'ty': shall be the signature of the pointer to function value + being invoked. The argument types must match the types implied by this + signature. This type can be omitted if the function is not varargs and + if the function type does not return a pointer to a function.
+- +
'fnptrval': An LLVM value containing a pointer to a function to + be invoked. In most cases, this is a direct function invocation, but + indirect calls are just as possible, calling an arbitrary pointer + to function value.
'function args': argument list whose types match the -function signature argument types. If the function signature -indicates the function accepts a variable number of arguments, the -extra arguments can be specified.
+ 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.Semantics:
+The 'call' instruction is used to cause control flow to transfer to a specified function, with its incoming arguments bound to the specified values. Upon a 'ret' @@ -1771,60 +2214,16 @@ instruction in the called function, control flow continues with the instruction after the function call, and the return value of the function is bound to the result argument. This is a simpler case of the invoke instruction.
-Example:
-%retval = call int %test(int %argc)-
call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);-@@ -1837,35 +2236,36 @@ section.Syntax:
+Example:
- <resultarglist> = vanext <va_list> <arglist>, <argty> + %retval = call int %test(int %argc) + call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42); + %X = tail call int %foo() + %Y = tail call fastcc int %foo()-Overview:
- -The 'vanext' instruction is used to access arguments passed -through the "variable argument" area of a function call. It is used to -implement the va_arg macro in C.
- -Arguments:
- -This instruction takes a va_list value and the type of the -argument. It returns another va_list. The actual type of -va_list may be defined differently for different targets. Most targets -use a va_list type of sbyte* or some other pointer type.
- -Semantics:
- -The 'vanext' instruction advances the specified va_list -past an argument of the specified type. In conjunction with the vaarg instruction, it is used to implement -the va_arg macro available in C. For more information, see -the variable argument handling Intrinsic -Functions.
- -It is legal for this instruction to be called in a function which -does not take a variable number of arguments, for example, the vfprintf -function.
- -vanext is an LLVM instruction instead of an intrinsic function because it takes a type as an -argument. The type refers to the current argument in the va_list, it -tells the compiler how far on the stack it needs to advance to find the next -argument
- -Example:
- -See the variable argument processing -section.
-Syntax:
- <resultval> = vaarg <va_list> <arglist>, <argty> + <resultval> = va_arg <va_list*> <arglist>, <argty>Overview:
-The 'vaarg' instruction is used to access arguments passed through +
The 'va_arg' instruction is used to access arguments passed through the "variable argument" area of a function call. It is used to implement the va_arg macro in C.
Arguments:
-This instruction takes a va_list value and the type of the -argument. It returns a value of the specified argument type. Again, the actual -type of va_list is target specific.
+This instruction takes a va_list* value and the type of +the argument. It returns a value of the specified argument type and +increments the va_list to poin to the next argument. Again, the +actual type of va_list is target specific.
Semantics:
-The 'vaarg' instruction loads an argument of the specified type from -the specified va_list. In conjunction with the vanext instruction, it is used to implement the -va_arg macro available in C. For more information, see the variable -argument handling Intrinsic Functions.
+The 'va_arg' instruction loads an argument of the specified +type from the specified va_list and causes the +va_list to point to the next argument. For more information, +see the variable argument handling Intrinsic +Functions.
It is legal for this instruction to be called in a function which does not take a variable number of arguments, for example, the vfprintf function.
-vaarg is an LLVM instruction instead of an intrinsic function because it takes an type as an +
va_arg is an LLVM instruction instead of an intrinsic function because it takes a type as an argument.
Example:
@@ -1881,14 +2281,14 @@ argument.@@ -1931,20 +2327,19 @@ used.LLVM supports the notion of an "intrinsic function". These functions have -well known names and semantics, and are required to follow certain +well known names and semantics and are required to follow certain restrictions. Overall, these instructions represent an extension mechanism for the LLVM language that does not require changing all of the transformations in LLVM to add to the language (or the bytecode reader/writer, the parser, etc...).
-Intrinsic function names must all start with an "llvm." prefix, this -prefix is reserved in LLVM for intrinsic names, thus functions may not be named +
Intrinsic function names must all start with an "llvm." prefix. This +prefix is reserved in LLVM for intrinsic names; thus, functions may not be named this. Intrinsic functions must always be external functions: you cannot define the body of intrinsic functions. Intrinsic functions may only be used in call or invoke instructions: it is illegal to take the address of an intrinsic @@ -1896,12 +2296,8 @@ function. Additionally, because intrinsic functions are part of the LLVM language, it is required that they all be documented here if any are added.
--Adding an intrinsic to LLVM is straight-forward if it is possible to express the -concept in LLVM directly (ie, code generator support is not _required_). To do -this, extend the default implementation of the IntrinsicLowering class to handle -the intrinsic. Code generators use this class to lower intrinsics they do not -understand to raw LLVM instructions that they do. +
To learn how to add an intrinsic function, please see the Extending LLVM Guide.
int %test(int %X, ...) { ; Initialize variable argument processing - %ap = call sbyte* %llvm.va_start() + %ap = alloca sbyte* + call void %llvm.va_start(sbyte** %ap) ; Read a single integer argument - %tmp = vaarg sbyte* %ap, int - - ; Advance to the next argument - %ap2 = vanext sbyte* %ap, int + %tmp = va_arg sbyte** %ap, int ; Demonstrate usage of llvm.va_copy and llvm.va_end - %aq = call sbyte* %llvm.va_copy(sbyte* %ap2) - call void %llvm.va_end(sbyte* %aq) + %aq = alloca sbyte* + call void %llvm.va_copy(sbyte** %aq, sbyte** %ap) + call void %llvm.va_end(sbyte** %aq) ; Stop processing of arguments. - call void %llvm.va_end(sbyte* %ap2) + call void %llvm.va_end(sbyte** %ap) ret int %tmp }@@ -1958,19 +2353,25 @@ int %test(int %X, ...) {@@ -1980,7 +2381,7 @@ within the body of a variable argument function.Syntax:
-call <va_list> ()* %llvm.va_start()+declare void %llvm.va_start(<va_list>* <arglist>)Overview:
-The 'llvm.va_start' intrinsic returns a new <arglist> -for subsequent use by the variable argument intrinsics.
+The 'llvm.va_start' intrinsic initializes +*<arglist> for subsequent use by va_arg.
+ +Arguments:
+ +The argument is a pointer to a va_list element to initialize.
+Semantics:
-The 'llvm.va_start' intrinsic works just like the va_start -macro available in C. In a target-dependent way, it initializes and -returns a va_list element, so that the next vaarg -will produce the first variable argument passed to the function. Unlike -the C va_start macro, this intrinsic does not need to know the + +
The 'llvm.va_start' intrinsic works just like the va_start +macro available in C. In a target-dependent way, it initializes the +va_list element the argument points to, so that the next call to +va_arg will produce the first variable argument passed to the function. +Unlike the C va_start macro, this intrinsic does not need to know the last argument of the function, the compiler can figure that out.
-Note that this intrinsic function is only legal to be called from -within the body of a variable argument function.
+@@ -2056,12 +2460,12 @@ href="GarbageCollection.html">Accurate Garbage Collection with LLVM.Syntax:
-call void (<va_list>)* %llvm.va_end(<va_list> <arglist>)+declare void %llvm.va_end(<va_list*> <arglist>)Overview:
The 'llvm.va_end' intrinsic destroys <arglist> which has been initialized previously with llvm.va_start @@ -2005,24 +2406,27 @@ with calls to llvm.va_end.
Syntax:
- call <va_list> (<va_list>)* %llvm.va_copy(<va_list> <destarglist>) + declare void %llvm.va_copy(<va_list>* <destarglist>, + <va_list>* <srcarglist>)Overview:
-The 'llvm.va_copy' intrinsic copies the current argument position -from the source argument list to the destination argument list.
+The 'llvm.va_copy' intrinsic copies the current argument position from +the source argument list to the destination argument list.
Arguments:
-The argument is the va_list to copy.
+The first argument is a pointer to a va_list element to initialize. +The second argument is a pointer to a va_list element to copy from.
+Semantics:
-The 'llvm.va_copy' intrinsic works just like the va_copy -macro available in C. In a target-dependent way, it copies the source -va_list element into the returned list. This intrinsic is necessary -because the llvm.va_start intrinsic may be +
The 'llvm.va_copy' intrinsic works just like the va_copy macro +available in C. In a target-dependent way, it copies the source +va_list element into the destination list. This intrinsic is necessary +because the llvm.va_begin intrinsic may be arbitrarily complex and require memory allocation, for example.
Syntax:
- call void (<ty>**, <ty2>*)* %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata) + declare void %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)Overview:
-The 'llvm.gcroot' intrinsic declares the existance of a GC root to +
The 'llvm.gcroot' intrinsic declares the existence of a GC root to the code generator, and allows some metadata to be associated with it.
Arguments:
@@ -2090,7 +2494,7 @@ the runtime to find the pointer at GC safe points.Syntax:
- call sbyte* (sbyte**)* %llvm.gcread(sbyte** %Ptr) + declare sbyte* %llvm.gcread(sbyte** %Ptr)Overview:
@@ -2123,7 +2527,7 @@ garbage collector runtime, as needed.Syntax:
- call void (sbyte*, sbyte**)* %llvm.gcwrite(sbyte* %P1, sbyte** %P2) + declare void %llvm.gcwrite(sbyte* %P1, sbyte** %P2)Overview:
@@ -2169,7 +2573,7 @@ be implemented with code generator support.Syntax:
- call void* ()* %llvm.returnaddress(uint <level>) + declare void* %llvm.returnaddress(uint <level>)Overview:
@@ -2198,7 +2602,7 @@ for arguments other than zero, so it should only be used for debugging purposes.Note that calling this intrinsic does not prevent function inlining or other -aggressive transformations, so the value returned may not that of the obvious +aggressive transformations, so the value returned may not be that of the obvious source-language caller.
@@ -2213,7 +2617,7 @@ source-language caller.Syntax:
- call void* ()* %llvm.frameaddress(uint <level>) + declare void* %llvm.frameaddress(uint <level>)Overview:
@@ -2242,11 +2646,98 @@ for arguments other than zero, so it should only be used for debugging purposes.Note that calling this intrinsic does not prevent function inlining or other -aggressive transformations, so the value returned may not that of the obvious +aggressive transformations, so the value returned may not be that of the obvious source-language caller.
+ + + ++ ++ + + + +Syntax:
++ declare void %llvm.prefetch(sbyte * <address>, + uint <rw>, uint <locality>) ++ +Overview:
+ + ++The 'llvm.prefetch' intrinsic is a hint to the code generator to insert +a prefetch instruction if supported; otherwise, it is a noop. Prefetches have +no +effect on the behavior of the program but can change its performance +characteristics. +
+ +Arguments:
+ ++address is the address to be prefetched, rw is the specifier +determining if the fetch should be for a read (0) or write (1), and +locality is a temporal locality specifier ranging from (0) - no +locality, to (3) - extremely local keep in cache. The rw and +locality arguments must be constant integers. +
+ +Semantics:
+ ++This intrinsic does not modify the behavior of the program. In particular, +prefetches cannot trap and do not produce a value. On targets that support this +intrinsic, the prefetch can provide hints to the processor cache for better +performance. +
+ ++ ++ +Syntax:
++ declare void %llvm.pcmarker( uint <id> ) ++ +Overview:
+ + ++The 'llvm.pcmarker' intrinsic is a method to export a Program Counter +(PC) in a region of +code to simulators and other tools. The method is target specific, but it is +expected that the marker will use exported symbols to transmit the PC of the marker. +The marker makes no guaranties that it will remain with any specific instruction +after optimizations. It is possible that the presense of a marker will inhibit +optimizations. The intended use is to be inserted after optmizations to allow +correlations of simulation runs. +
+ +Arguments:
+ ++id is a numerical id identifying the marker. +
+ +Semantics:
+ ++This intrinsic does not modify the behavior of the program. Backends that do not +support this intrinisic may ignore it. +
+ +Operating System Intrinsics @@ -2269,7 +2760,7 @@ operating system level code.@@ -2308,7 +2799,9 @@ unsigned 16 bit value, and the return value must be 8, 16, or 32 bits.Syntax:
- call <integer type> (<integer type>)* %llvm.readport (<integer type> <address>) + declare <integer type> %llvm.readport (<integer type> <address>)Overview:
@@ -2294,7 +2785,7 @@ The 'llvm.readport' intrinsic reads data from the hardware I/O port specified by address and returns the value. The address and return value must be integers, but the size is dependent upon the platform upon which the program is code generated. For example, on x86, the address must be an -unsigned 16 bit value, and the return value must be 8, 16, or 32 bits. +unsigned 16-bit value, and the return value must be 8, 16, or 32 bits.Syntax:
- call void (<integer type>, <integer type>)* %llvm.writeport (<integer type> <value>, <integer type> <address>) + call void (<integer type>, <integer type>)* + %llvm.writeport (<integer type> <value>, + <integer type> <address>)Overview:
@@ -2336,7 +2829,7 @@ being a memory location for memory mapped I/O). The 'llvm.writeport' intrinsic writes value to the I/O port specified by address. The address and value must be integers, but the size is dependent upon the platform upon which the program is code generated. -For example, on x86, the address must be an unsigned 16 bit value, and the +For example, on x86, the address must be an unsigned 16-bit value, and the value written must be 8, 16, or 32 bits in length. @@ -2351,7 +2844,7 @@ value written must be 8, 16, or 32 bits in length.Syntax:
- call <result> (<ty>*)* %llvm.readio (<ty> * <pointer>) + declare <result> %llvm.readio (<ty> * <pointer>)Overview:
@@ -2376,7 +2869,7 @@ The 'llvm.readio' intrinsic reads data from a memory mapped I/O location specified by pointer and returns the value. The argument must be a pointer, and the return value must be a first class type. However, certain architectures -may not support I/O on all first class types. For example, 32 bit processors +may not support I/O on all first class types. For example, 32-bit processors may only support I/O on data types that are 32 bits or less. @@ -2399,7 +2892,7 @@ ensures that accesses to memory mapped I/O registers occur in program order.Syntax:
- call void (<ty1>, <ty2>*)* %llvm.writeio (<ty1> <value>, <ty2> * <pointer>) + declare void %llvm.writeio (<ty1> <value>, <ty2> * <pointer>)Overview:
@@ -2423,7 +2916,7 @@ data should be written. The 'llvm.writeio' intrinsic writes value to the memory mapped I/O address specified by pointer. The value must be a first class type. However, certain architectures -may not support I/O on all first class types. For example, 32 bit processors +may not support I/O on all first class types. For example, 32-bit processors may only support I/O on data types that are 32 bits or less. @@ -2461,8 +2954,8 @@ for more efficient code generation.Syntax:
- call void (sbyte*, sbyte*, uint, uint)* %llvm.memcpy(sbyte* <dest>, sbyte* <src>, - uint <len>, uint <align>) + declare void %llvm.memcpy(sbyte* <dest>, sbyte* <src>, + uint <len>, uint <align>)Overview:
@@ -2513,8 +3006,8 @@ be set to 0 or 1.Syntax:
- call void (sbyte*, sbyte*, uint, uint)* %llvm.memmove(sbyte* <dest>, sbyte* <src>, - uint <len>, uint <align>) + declare void %llvm.memmove(sbyte* <dest>, sbyte* <src>, + uint <len>, uint <align>)Overview:
@@ -2566,8 +3059,8 @@ be set to 0 or 1.Syntax:
- call void (sbyte*, ubyte, uint, uint)* %llvm.memset(sbyte* <dest>, ubyte <val>, - uint <len>, uint <align>) + declare void %llvm.memset(sbyte* <dest>, ubyte <val>, + uint <len>, uint <align>)Overview:
@@ -2617,8 +3110,7 @@ this can be specified as the fourth argument, otherwise it should be set to 0 orSyntax:
- call bool (<float or double>, <float or double>)* %llvm.isunordered(<float or double> Val1, - <float or double> Val2) + declare bool %llvm.isunordered(<float or double> Val1, <float or double> Val2)Overview:
@@ -2643,7 +3135,159 @@ false. + + + ++ ++ + + + +Syntax:
++ declare <float or double> %llvm.sqrt(<float or double> Val) ++ +Overview:
+ ++The 'llvm.sqrt' intrinsic returns the sqrt of the specified operand, +returning the same value as the libm 'sqrt' function would. Unlike +sqrt in libm, however, llvm.sqrt has undefined behavior for +negative numbers (which allows for better optimization). +
+ +Arguments:
+ ++The argument and return value are floating point numbers of the same type. +
+ +Semantics:
+ ++This function returns the sqrt of the specified operand if it is a positive +floating point number. +
+++ + + + ++LLVM provides intrinsics for a few important bit counting operations. +These allow efficient code generation for some algorithms. +
+ ++ ++ + + + +Syntax:
++ declare int %llvm.ctpop(int <src>) + ++ +Overview:
+ ++The 'llvm.ctpop' intrinsic counts the number of ones in a variable. +
+ +Arguments:
+ ++The only argument is the value to be counted. The argument may be of any +integer type. The return type must match the argument type. +
+ +Semantics:
+ ++The 'llvm.ctpop' intrinsic counts the 1's in a variable. +
++ ++ + + + + + +Syntax:
++ declare int %llvm.ctlz(int <src>) + ++ +Overview:
+ ++The 'llvm.ctlz' intrinsic counts the number of leading zeros in a +variable. +
+ +Arguments:
+ ++The only argument is the value to be counted. The argument may be of any +integer type. The return type must match the argument type. +
+ +Semantics:
+ ++The 'llvm.ctlz' intrinsic counts the leading (most significant) zeros +in a variable. If the src == 0 then the result is the size in bits of the type +of src. For example, llvm.cttz(int 2) = 30. +
++ +Syntax:
++ declare int %llvm.cttz(int <src>) + ++ +Overview:
+ ++The 'llvm.cttz' intrinsic counts the number of trailing zeros. +
+ +Arguments:
+ ++The only argument is the value to be counted. The argument may be of any +integer type. The return type must match the argument type. +
+ +Semantics:
++The 'llvm.cttz' intrinsic counts the trailing (least significant) zeros +in a variable. If the src == 0 then the result is the size in bits of the type +of src. For example, llvm.cttz(2) = 1. +
+