@@ -539,208 +809,305 @@ reference to another object, which must live in memory.
-
-
- | [4x int]* |
- : pointer to array
-of four int values |
-
-
- | int (int *) * |
- : A pointer to a function that takes an int, returning
-an int. |
-
-
+
+
+
+ [4x int]*
+ int (int *) *
+ |
+
+ A pointer to array of
+ four int values
+ A pointer to a function that takes an int*, returning an
+ int.
+ |
+
-
-
+
+
+
+
Overview:
+
+
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.
+
+
Syntax:
+
+
+ < <# elements> x <elementtype> >
+
+
+
The number of elements is a constant integer value; elementtype may
+be any integral or floating point type.
+
+
Examples:
+
+
+
+
+ <4 x int>
+ <8 x float>
+ <2 x uint>
+ |
+
+ Packed vector of 4 integer values.
+ Packed vector of 8 floating-point values.
+ Packed vector of 2 unsigned integer values.
+ |
+
+
-Mention/decide that packed types work with saturation or not. Maybe have a packed+saturated type in addition to just a packed type.
+
Overview:
-Packed types should be 'nonsaturated' because standard data types are not saturated. Maybe have a saturated packed 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).
+
Syntax:
+
+
+ opaque
+
+
+
Examples:
+
+
+
+ |
+ 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*
+
-
; 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:
-
- - internal
- - Global values with internal linkage are only directly accessible
-by objects in the current module. In particular, linking code into a
-module with an internal global value may cause the internal to be
-renamed as necessary to avoid collisions. Because the symbol is
-internal to the module, all references can be updated. This
-corresponds to the notion of the 'static' keyword in C, or the
-idea of "anonymous namespaces" in C++.
-
+ - Boolean constants
+
+ - The two strings 'true' and 'false' are both valid
+ constants of the bool type.
- - linkonce:
- - "linkonce" linkage is similar to internal
-linkage, with the twist that linking together two modules defining the
-same linkonce globals will cause one of the globals to be
-discarded. This is typically used to implement inline functions.
-Unreferenced linkonce globals are allowed to be discarded.
-
+
+ - Integer constants
+
+ - Standard integers (such as '4') are constants of the integer type. Negative numbers may be used with signed
+ integer types.
- - weak:
- - "weak" linkage is exactly the same as linkonce
-linkage, except that unreferenced weak globals may not be
-discarded. This is used to implement constructs in C such as "int
-X;" at global scope.
-
+
+ - Floating point constants
+
+ - Floating point constants use standard decimal notation (e.g. 123.421),
+ exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
+ notation (see below). Floating point constants must have a floating point type.
+
+ - Null pointer constants
+
+ - The identifier 'null' is recognized as a null pointer constant
+ and must be of pointer type.
+
+
+
+
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.
+
+
+ - Structure constants
+
+ - Structure constants are represented with notation similar to structure
+ type definitions (a comma separated list of elements, surrounded by braces
+ ({})). For example: "{ int 4, float 17.0, int* %G }",
+ where "%G" is declared as "%G = external global int". Structure constants
+ must have structure type, and the number and
+ types of elements must match those specified by the type.
- - appending:
- - "appending" linkage may only be applied to global
-variables of pointer to array type. When two global variables with
-appending linkage are linked together, the two global arrays are
-appended together. This is the LLVM, typesafe, equivalent of having
-the system linker append together "sections" with identical names when
-.o files are linked.
-
+
+ - Array constants
+
+ - Array constants are represented with notation similar to array type
+ definitions (a comma separated list of elements, surrounded by square brackets
+ ([])). For example: "[ int 42, int 11, int 74 ]". Array
+ constants must have array type, and the number and
+ types of elements must match those specified by the type.
- - externally visible:
- - If none of the above identifiers are used, the global is
-externally visible, meaning that it participates in linkage and can be
-used to resolve external symbol references.
-
+
+ - Packed constants
+
+ - Packed constants are represented with notation similar to packed type
+ definitions (a comma separated list of elements, surrounded by
+ less-than/greater-than's (<>)). For example: "< int 42,
+ int 11, int 74, int 100 >". Packed constants must have packed type, and the number and types of elements must
+ match those specified by the type.
+
+
+ - Zero initialization
+
+ - The string 'zeroinitializer' can be used to zero initialize a
+ value to zero of any type, including scalar and aggregate types.
+ This is often used to avoid having to print large zero initializers (e.g. for
+ large arrays), and is always exactly equivalent to using explicit zero
+ initializers.
-
-
For example, since the ".LC0"
-variable is defined to be internal, if another module defined a ".LC0"
-variable and was linked with this one, one of the two would be renamed,
-preventing a collision. Since "main" and "puts" are
-external (i.e., lacking any linkage declarations), they are accessible
-outside of the current module. It is illegal for a function declaration
-to have any linkage type other than "externally visible".
+
-
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.
+
+
-
Functions
+
-
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).
+
+ - cast ( CST to TYPE )
-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.
+ - Cast a constant to another type.
-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.
+ - getelementptr ( CSTPTR, IDX0, IDX1, ... )
-
+
Perform the getelementptr operation on
+ constants. As with the getelementptr
+ instruction, the index list may have zero or more indexes, which are required
+ to make sense for the type of "CSTPTR".
+
OPCODE ( LHS, RHS )
+
+
Perform the specified operation of the LHS and RHS constants. OPCODE may
+ be any of the binary or bitwise
+ binary operations. The constraints on operands are the same as those for
+ the corresponding instruction (e.g. no bitwise operations on floating point
+ values are allowed).
+
+
+
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, and the 'unwind' instruction.
+the '
invoke' instruction, the '
unwind' instruction, and the '
unreachable' instruction.
+
Overview:
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.
@@ -764,10 +1131,10 @@ match the return type of the function.
Semantics:
When the 'ret' instruction is executed, control flow
returns back to the calling function's context. If the caller is a "call instruction, execution continues at
+ href="#i_call">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.
Example:
@@ -831,16 +1198,16 @@ table is not allowed to contain duplicate constant entries.
The switch instruction specifies a table of values and
destinations. When the 'switch' instruction is executed, this
-table is searched for the given value. If the value is found, the
-corresponding destination is branched to, otherwise the default value
-it transfered to.
+table is searched for the given value. If the value is found, control flow is
+transfered to the corresponding destination; otherwise, control flow is
+transfered to the default destination.
Implementation:
Depending on properties of the target machine and the particular
switch instruction, this instruction may be code generated in different
-ways, for example as a series of chained conditional branches, or with a lookup
-table.
+ways. For example, it could be generated as a series of chained conditional
+branches or with a lookup table.
Example:
@@ -858,79 +1225,149 @@ table.
uint 2, label %ontwo ]
+
-
+
+
+
Syntax:
-
<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>
+
+
Overview:
-
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.
+
Arguments:
+
This instruction requires several arguments:
+
- - 'ptr to function ty': shall be the signature of the
-pointer to function value being invoked. In most cases, this is a
-direct function invocation, but indirect invokes are just as
-possible, branching off an arbitrary pointer to function value.
- - 'function ptr val': An LLVM value containing a pointer
-to a function to be invoked.
- - '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.
- - 'normal label': the label reached when the called
-function executes a 'ret' instruction.
- - 'exception label': the label reached when a callee
-returns with the unwind 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.
+
+ - 'ptr to function ty': shall be the signature of the pointer to
+ function value being invoked. In most cases, this is a direct function
+ invocation, but indirect invokes are just as possible, branching off
+ an arbitrary pointer to function value.
+
+
+ - 'function ptr val': An LLVM value containing a pointer to a
+ function to be invoked.
+
+ - '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.
+
+ - 'normal label': the label reached when the called function
+ executes a 'ret' instruction.
+
+ - 'exception label': the label reached when a callee returns with
+ the unwind instruction.
+
+
Semantics:
+
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.
+
Example:
-
%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
+
+
+
+
Syntax:
+
+ unwind
+
+
Overview:
+
+
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.
+
+
Semantics:
+
+
The 'unwind' intrinsic 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.
The 'add' instruction returns the sum of its two operands.
Arguments:
The two arguments to the 'add' instruction must be either integer or floating point
-values. Both arguments must have identical types.
+ href="#t_integer">integer or floating point values.
+ This instruction can also take packed versions of the values.
+Both arguments must have identical types.
Semantics:
The value produced is the integer or floating point sum of the two
operands.
@@ -969,7 +1407,9 @@ instruction present in most other intermediate representations.
Arguments:
The two arguments to the 'sub' instruction must be either integer or floating point
-values. Both arguments must have identical types.
+values.
+This instruction can also take packed versions of the values.
+Both arguments must have identical types.
Semantics:
The value produced is the integer or floating point difference of
the two operands.
@@ -991,7 +1431,9 @@ operands.
Arguments:
The two arguments to the 'mul' instruction must be either integer or floating point
-values. Both arguments must have identical types.
+values.
+This instruction can also take packed versions of the values.
+Both arguments must have identical types.
Semantics:
The value produced is the integer or floating point product of the
two operands.
@@ -1014,7 +1456,9 @@ operands.
Arguments:
The two arguments to the 'div' instruction must be either integer or floating point
-values. Both arguments must have identical types.
+values.
+This instruction can also take packed versions of the values.
+Both arguments must have identical types.
Semantics:
The value produced is the integer or floating point quotient of the
two operands.
@@ -1035,7 +1479,9 @@ division of its two operands.
Arguments:
The two arguments to the 'rem' instruction must be either integer or floating point
-values. Both arguments must have identical types.
+values.
+This instruction can also take packed versions of the values.
+Both arguments must have identical types.
Semantics:
This returns the remainder of a division (where the result
has the same sign as the divisor), not the modulus (where the
@@ -1097,7 +1543,7 @@ Operations
Bitwise 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.
@@ -1322,7 +1768,7 @@ Operations
A 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.
Overview:
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.
Arguments:
'value' shall be a pointer value that points to a value
that was allocated with the 'malloc'
instruction.
Semantics:
-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.
Example:
%array = malloc [4 x ubyte] ; yields {[4 x ubyte]*}:array
@@ -1390,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
@@ -1445,7 +1891,7 @@ Instruction
There 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.
@@ -1481,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
@@ -1511,8 +1958,11 @@ compiled to LLVM:
%RT = type { sbyte, [10 x [20 x int]], sbyte }
%ST = type { int, double, %RT }
- int* "foo"(%ST* %s) {
- %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13
+ implementation
+
+ int* %foo(%ST* %s) {
+ entry:
+ %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13
ret int* %reg
}
@@ -1520,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.
@@ -1532,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
@@ -1540,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
@@ -1549,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
@@ -1679,7 +2137,7 @@ The 'select' instruction requires a boolean value indicating the condit
If 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:
@@ -1694,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.
-
-
'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.
+ The optional "cconv" marker indicates which calling
+ convention the call should use. If none is specified, the call defaults
+ to using C calling conventions.
+
+ -
+
'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'
@@ -1730,68 +2214,64 @@ 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);
+
+
+ %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()
+
+
-
Syntax:
-
<resultarglist> = vanext <va_list> <arglist>, <argty>
-
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 valist value and the type of the
-argument. It returns another valist.
-
Semantics:
-
The 'vanext' instruction advances the specified valist
-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 an type as
-an 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 "variable argument" area of a function call. It is used to
-implement the va_arg macro in C.
+
+
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 valist value and the type of the
-argument. It returns a value of the specified argument type.
+
+
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
+
+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
+
+
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 argument.
+
+va_arg is an LLVM instruction instead of an intrinsic function because it takes a type as an
+argument.
+
Example:
-See the variable argument processing
-section.
+
+See the variable argument processing section.
+
@@ -1801,14 +2281,14 @@ section.
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
@@ -1816,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.
@@ -1851,20 +2327,19 @@ used.
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
}
@@ -1878,19 +2353,25 @@ int %test(int %X, ...) {
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.
+
@@ -1900,7 +2381,7 @@ within the body of a variable argument function.
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
@@ -1925,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.
@@ -1976,12 +2460,12 @@ href="GarbageCollection.html">Accurate Garbage Collection with LLVM.
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:
@@ -2010,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:
@@ -2043,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:
@@ -2089,7 +2573,7 @@ be implemented with code generator support.
Syntax:
- call void* ()* %llvm.returnaddress(uint <level>)
+ declare void* %llvm.returnaddress(uint <level>)
Overview:
@@ -2118,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.
Syntax:
- call void* ()* %llvm.frameaddress(uint <level>)
+ declare void* %llvm.frameaddress(uint <level>)
Overview:
@@ -2162,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
@@ -2189,7 +2760,7 @@ operating system level code.
Syntax:
- call <integer type> (<integer type>)* %llvm.readport (<integer type> <address>)
+ declare <integer type> %llvm.readport (<integer type> <address>)
Overview:
@@ -2214,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.
@@ -2228,7 +2799,9 @@ 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:
@@ -2256,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.
@@ -2271,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:
@@ -2296,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.
@@ -2319,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:
@@ -2343,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.
@@ -2357,7 +2930,6 @@ ensures that accesses to memory mapped I/O registers occur in program order.
-
Standard C Library Intrinsics
@@ -2382,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:
@@ -2434,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:
@@ -2487,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:
@@ -2538,8 +3110,7 @@ this can be specified as the fourth argument, otherwise it should be set to 0 or
Syntax:
- 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:
@@ -2564,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.
+
+