| llvm Assembly Language Reference Manual | +
| LLVM Language Reference Manual |
Written by Chris Lattner and Vikram Adve
+ + @@ -126,7 +137,7 @@ simple SSA value instead of a memory location.
@@ -135,11 +146,11 @@ syntactically okay, but not well formed:
%x = add int 1, %x
-...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 the optimizer before it outputs bytecode. The
-violations pointed out by the verifier pass indicate bugs in transformation
+...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 the optimizer before it outputs bytecode.
+The violations pointed out by the verifier pass indicate bugs in transformation
passes or input to the parser.
@@ -208,7 +219,7 @@ 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 unintuitive notation for constants is the optional hexidecimal form of
+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
@@ -284,7 +295,8 @@ These different primitive types fall into a few useful classifications:
@@ -485,7 +497,7 @@ declarations, and merges symbol table entries. Here is an example of the "hello
; Definition of main function
int "main"() { ; int()*
; Convert [13x sbyte]* to sbyte *...
- %cast210 = getelementptr [13 x sbyte]* %.LC0, uint 0, uint 0 ; 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
@@ -616,7 +628,7 @@ that returns a value that does not match the return type of the function.
When the 'ret' instruction is executed, control flow returns back to
the calling function's context. If the instruction returns a value, that value
-shall be propogated into the calling function's data space.
+shall be propagated into the calling function's data space.
-The 'switch' statement supports two different styles of indirect
-branching: lookup branching and indexed branching. Lookup branching is
-generally useful if the values to switch on are spread far appart, where index
-branching is useful if the values to switch on are generally dense.
-
-The two different forms of the 'switch' statement are simple hints to
-the underlying implementation. For example, the compiler may choose to
-implement a small indirect branch table as a series of predicated comparisons:
-if it is faster for the target architecture.
-
-
-The indexed form of the 'switch' instruction uses three parameters: an
-'uint' index value, a default 'label' and a sized array of
-'label's. The 'dests' array must be a constant array.
+The 'switch' instruction uses three parameters: a 'uint'
+comparison value 'value', a default 'label' destination, and
+an array of pairs of comparison value constants and 'label's.
+branched to, otherwise the default value it transfered to.
-The index branch form simply looks up a label element directly in a table and
-branches to it.
+
+Depending on properties of the target machine and the particular switch
+instruction, this instruction may be code generated as a series of chained
+conditional branches, or with a lookup table.
The 'add' instruction returns the sum of its two operands.
+The two arguments to the 'add' instruction must be either integer or floating point values. Both arguments must have identical types.
+The value produced is the integer or floating point sum of the two operands.
Well Formedness
-It is important to note that this document describes 'well formed' llvm assembly
+It is important to note that this document describes 'well formed' LLVM assembly
language. There is a difference between what the parser accepts and what is
considered 'well formed'. For example, the following instruction is
syntactically okay, but not well formed:
signed sbyte, short, int, long, float, double unsigned ubyte, ushort, uint, ulong integral ubyte, sbyte, ushort, short, uint, int, ulong, long integer ubyte, sbyte, ushort, short, uint, int, ulong, long integral bool, ubyte, sbyte, ushort, short, uint, int, ulong, long floating point float, double first class bool, ubyte, sbyte, ushort, short,
uint, int, ulong, long, float, double, pointerExample:
@@ -672,14 +684,8 @@ IfUnequal:
Syntax:
- ; Definitions for lookup indirect branch
- %switchtype = type [<anysize> x { uint, label }]
-
- ; Lookup indirect branch
- switch uint <value>, label <defaultdest>, %switchtype <switchtable>
+ switch int <value>, label <defaultdest> [ int <val>, label &dest>, ... ]
- ; Indexed indirect branch
- switch uint <idxvalue>, label <defaultdest>, [<anysize> x label] <desttable>
Overview:
@@ -688,54 +694,38 @@ The 'switch' instruction is used to transfer control flow to one of
several different places. It is a generalization of the 'br'
instruction, allowing a branch to occur to one of many possible destinations.Arguments:
-The lookup form of the 'switch' instruction uses three parameters: a
-'uint' comparison value 'value', a default 'label'
-destination, and an array of pairs of comparison value constants and
-'label's. The sized array must be a constant value.Semantics:
-The lookup style switch statement specifies a table of values and destinations.
+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. Implementation:
-In either case, the compiler knows the static size of the array, because it is
-provided as part of the constant values type.Example:
; Emulate a conditional br instruction
%Val = cast bool %value to uint
- switch uint %Val, label %truedest, [1 x label] [label %falsedest ]
+ switch int %Val, label %truedest [int 0, label %falsedest ]
; Emulate an unconditional br instruction
- switch uint 0, label %dest, [ 0 x label] [ ]
+ switch int 0, label %dest [ ]
; Implement a jump table:
- switch uint %val, label %otherwise, [3 x label] [ label %onzero,
- label %onone,
- label %ontwo ]
-
+ switch int %val, label %otherwise [ int 0, label %onzero,
+ int 1, label %onone,
+ int 2, label %ontwo ]
@@ -766,7 +756,7 @@ This instruction requires several arguments:Arguments:
-The two arguments to the 'add' instruction must be either integral or floating point values. Both arguments must have identical types.Semantics:
-The value produced is the integral or floating point sum of the two operands.Example:
@@ -858,12 +848,12 @@ instruction present in most other intermediate representations.
Arguments:
The two arguments to the 'sub' instruction must be either integral or floating point
+href="#t_integer">integer
The 'mul' instruction returns the product of its two operands.
+The two arguments to the 'mul' instruction must be either integer or floating point values. Both arguments must have identical types.
There is no signed vs unsigned multiplication. The appropriate action is taken @@ -916,12 +906,12 @@ The 'div' instruction returns the quotient of its two operands.
The 'rem' instruction returns the remainder from the division of its two operands.
+The two arguments to the 'rem' instruction must be either integer or floating point values. Both arguments must have identical types.
+The two arguments to the 'and' instruction must be integral values. Both arguments must have identical +types.
+The two arguments to the 'or' instruction must be integral values. Both arguments must have identical +types.
+The two arguments to the 'xor' instruction must be integral values. Both arguments must have identical +types.
The 'shr' instruction returns the first operand shifted to the right a specified number of bits.
+The first argument to the 'shr' instruction must be an integer type. The second argument must be an 'ubyte' type.
- <result> = getelementptr <ty>* <ptrval>{, uint <aidx>|, ubyte <sidx>}*
+ <result> = getelementptr <ty>* <ptrval>{, long <aidx>|, ubyte <sidx>}*
@@ -1462,11 +1452,11 @@ given testcase is equivalent to:
int* "foo"(%ST* %s) {
- %t1 = getelementptr %ST* %s , uint 1 ; yields %ST*:%t1
- %t2 = getelementptr %ST* %t1, uint 0, ubyte 2 ; yields %RT*:%t2
- %t3 = getelementptr %RT* %t2, uint 0, ubyte 1 ; yields [10 x [20 x int]]*:%t3
- %t4 = getelementptr [10 x [20 x int]]* %t3, uint 0, uint 5 ; yields [20 x int]*:%t4
- %t5 = getelementptr [20 x int]* %t4, uint 0, uint 13 ; yields int*:%t5
+ %t1 = getelementptr %ST* %s , long 1 ; yields %ST*:%t1
+ %t2 = getelementptr %ST* %t1, long 0, ubyte 2 ; yields %RT*:%t2
+ %t3 = getelementptr %RT* %t2, long 0, ubyte 1 ; yields [10 x [20 x int]]*:%t3
+ %t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5 ; yields [20 x int]*:%t4
+ %t5 = getelementptr [20 x int]* %t4, long 0, long 13 ; yields int*:%t5
ret int* %t5
}
@@ -1476,7 +1466,7 @@ int* "foo"(%ST* %s) {
; yields [12 x ubyte]*:aptr
- %aptr = getelementptr {int, [12 x ubyte]}* %sptr, uint 0, ubyte 1
+ %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
@@ -1592,7 +1582,7 @@ invoked. The argument types must match the types implied by this signature.
-
+
+
+
+
+
'va_arg' Instruction
+
+
Syntax:
+
+ <result> = va_arg <va_list>* <arglist>, <retty>
+
+
+Overview:
+
+The 'va_arg' instruction is used to access arguments passed through the
+"variable argument" area of a function call. It corresponds directly to the
+va_arg macro in C.Arguments:
+
+This instruction takes a pointer to a valist value to read a new
+argument from. The return type of the instruction is defined by the second
+argument, a type.Semantics:
+
+The 'va_arg' instruction works just like the va_arg macro
+available in C. In a target-dependent way, it reads the argument indicated by
+the value the arglist points to, updates the arglist, then returns a value of
+the specified type. This instruction should be used in conjunction with 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.
- +va_arg is an LLVM instruction instead of an intrinsic function because the return type depends on an +argument.
+ +
+ +
| -Related Work +Intrinsic Functions |
-Codesigned virtual machines.
+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 +function. Additionally, because intrinsic functions are part of the LLVM +language, it is required that they all be documented here if any are added.
-
| +Variable Argument Handling Intrinsics + |
+Variable argument support is defined in LLVM with the va_arg instruction and these three intrinsic +functions. These function correspond almost directly to the similarly named +macros defined in the <stdarg.h> header file.
-
-
+All of these functions operate on arguments that use a target-specific type
+"va_list". The LLVM assembly language reference manual does not define
+what this type is, so all transformations should be prepared to handle
+intrinsics with any type used.
-
-
+This example shows how the va_arg instruction
+and the variable argument handling intrinsic functions are used.
-
-
-
+
+int %test(int %X, ...) {
+ ; Allocate two va_list items. On this target, va_list is of type sbyte*
+ %ap = alloca sbyte*
+ %aq = alloca sbyte*
-
-
+ ; Read a single integer argument
+ %tmp = va_arg sbyte** %ap, int
-
-
+ ; Demonstrate usage of llvm.va_copy and llvm_va_end
+ %apv = load sbyte** %ap
+ call void %llvm.va_copy(sbyte** %aq, sbyte* %apv)
+ call void %llvm.va_end(sbyte** %aq)
-
-
+ ; Stop processing of arguments.
+ call void %llvm.va_end(sbyte** %ap)
+ ret int %tmp
+}
+
-
-
+
+
+ call void (va_list*)* %llvm.va_start(<va_list>* <arglist>) +-more... +
+ +
+ +
+
+
+
+
+
+
+
+
'llvm.va_end' Intrinsic
+
+
Syntax:
+
+ call void (va_list*)* %llvm.va_end(<va_list>* <arglist>)
+
+
+Overview:
+
+The 'llvm.va_end' intrinsic destroys *<arglist> which
+has been initialized previously with llvm.va_begin.Arguments:
+
+The argument is a pointer to a va_list element to destroy.Semantics:
+
+The 'llvm.va_end' intrinsic works just like the va_end macro
+available in C. In a target-dependent way, it destroys the va_list
+that the argument points to. Calls to llvm.va_start and llvm.va_copy must be matched exactly with calls
+to llvm.va_end.
+
+
+
+
+
+
+
+
+
+
@@ -1695,7 +1810,7 @@ more...
'llvm.va_copy' Intrinsic
+
+
Syntax:
+
+ call void (va_list*, va_list)* %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.Arguments:
+
+The first argument is a pointer to a va_list element to initialize.
+The second argument is 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 destination list. This intrinsic is necessary
+because the llvm.va_begin intrinsic may be
+arbitrarily complex and require memory allocation, for example.