| LLVM Language Reference Manual |
Written by Chris Lattner and Vikram Adve
| Abstract |
This document is a reference manual for the LLVM assembly language. LLVM is an SSA based representation that provides type safety, low-level operations, flexibility, and the capability of representing 'all' high-level languages cleanly. It is the common code representation used throughout all phases of the LLVM compilation strategy.
| Introduction |
The LLVM representation aims to be a 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 microprocessors are "universal IR's", allowing many source languages to be mapped to them). By providing type information, LLVM can be used as the target of optimizations: for example, through pointer analysis, it can be proven that a C automatic variable is never accessed outside of the current function... allowing it to be promoted to a simple SSA value instead of a memory location.
%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 passes or input to the parser.
| Identifiers |
LLVM requires the 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:
The easy way:
%result = mul uint %X, 8After strength reduction:
%result = shl uint %X, ubyte 3And the hard way:
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.
| Type System |
| Primitive Types |
|
|
| signed | sbyte, short, int, long, float, double |
| unsigned | ubyte, ushort, uint, ulong |
| 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, pointer |
| Derived Types |
[<# elements> x <elementtype>]The number of elements is a constant integer value, elementtype may be any type with a size.
| [3 x [4 x int]] | : 3x4 array integer values. |
| [12 x [10 x float]] | : 12x10 array of single precision floating point values. |
| [2 x [3 x [4 x uint]]] | : 2x3x4 array of unsigned integer values. |
<returntype> (<parameter list>)Where '<parameter list>' is a comma-separated list of type specifiers. Optionally, the parameter list may include a type ..., which indicates that the function takes a variable number of arguments. Variable argument functions can access their arguments with the variable argument handling intrinsic functions.
| int (int) | : function taking an int, returning an int |
| float (int, int *) * | : Pointer to a function that takes an int and a pointer to int, returning float. |
| int (sbyte *, ...) | : A vararg function that takes at least one pointer to sbyte (signed char in C), which returns an integer. This is the signature for printf in LLVM. |
Structures are accessed using 'load and 'store' by getting a pointer to a field with the 'getelementptr' instruction.
{ <type list> }
| { int, int, int } | : a triple of three int values |
| { float, int (int) * } | : A pair, where the first element is a float and the second element is a pointer to a function that takes an int, returning an int. |
<type> *
| [4x int]* | : pointer to array of four int values |
| int (int *) * | : A pointer to a function that takes an int, returning an int. |
| High Level Structure |
| Module Structure |
; 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".
| Global Variables |
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.
| Functions |
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.
| Instruction Reference |
| Terminator Instructions |
There are five different terminator instructions: the 'ret' instruction, the 'br' instruction, the 'switch' instruction, the 'invoke' instruction, and the 'unwind' instruction.
ret <type> <value> ; Return a value from a non-void function ret void ; Return from void function
There are two forms of the 'ret' instructruction: one that returns a value and then causes control flow, and one that just causes control flow to occur.
ret int 5 ; Return an integer value of 5 ret void ; Return from a void function
br bool <cond>, label <iftrue>, label <iffalse> br label <dest> ; Unconditional branch
Test: %cond = seteq int %a, %b br bool %cond, label %IfEqual, label %IfUnequal IfEqual: ret int 1 IfUnequal: ret int 0
switch uint <value>, label <defaultdest> [ int <val>, label &dest>, ... ]
; Emulate a conditional br instruction
%Val = cast bool %value to uint
switch uint %Val, label %truedest [int 0, label %falsedest ]
; Emulate an unconditional br instruction
switch uint 0, label %dest [ ]
; Implement a jump table:
switch uint %val, label %otherwise [ int 0, label %onzero,
int 1, label %onone,
int 2, label %ontwo ]
<result> = invoke <ptr to function ty> %<function ptr val>(<function args>)
to label <normal label> except label <exception label>
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
unwind
| Binary Operations |
There are several different binary operators:
<result> = add <ty> <var1>, <var2> ; yields {ty}:result
<result> = add int 4, %var ; yields {int}:result = 4 + %var
<result> = sub <ty> <var1>, <var2> ; yields {ty}:result
Note that the 'sub' instruction is used to represent the 'neg' instruction present in most other intermediate representations.
<result> = sub int 4, %var ; yields {int}:result = 4 - %var
<result> = sub int 0, %val ; yields {int}:result = -%var
<result> = mul <ty> <var1>, <var2> ; yields {ty}:result
There is no signed vs unsigned multiplication. The appropriate action is taken based on the type of the operand.
<result> = mul int 4, %var ; yields {int}:result = 4 * %var
<result> = div <ty> <var1>, <var2> ; yields {ty}:result
<result> = div int 4, %var ; yields {int}:result = 4 / %var
<result> = rem <ty> <var1>, <var2> ; yields {ty}:result
<result> = rem int 4, %var ; yields {int}:result = 4 % %var
<result> = seteq <ty> <var1>, <var2> ; yields {bool}:result
<result> = setne <ty> <var1>, <var2> ; yields {bool}:result
<result> = setlt <ty> <var1>, <var2> ; yields {bool}:result
<result> = setgt <ty> <var1>, <var2> ; yields {bool}:result
<result> = setle <ty> <var1>, <var2> ; yields {bool}:result
<result> = setge <ty> <var1>, <var2> ; yields {bool}:result
<result> = seteq int 4, 5 ; yields {bool}:result = false
<result> = setne float 4, 5 ; yields {bool}:result = true
<result> = setlt uint 4, 5 ; yields {bool}:result = true
<result> = setgt sbyte 4, 5 ; yields {bool}:result = false
<result> = setle sbyte 4, 5 ; yields {bool}:result = true
<result> = setge sbyte 4, 5 ; yields {bool}:result = false
| Bitwise Binary Operations |
<result> = and <ty> <var1>, <var2> ; yields {ty}:result
| In0 | In1 | Out |
| 0 | 0 | 0 |
| 0 | 1 | 0 |
| 1 | 0 | 0 |
| 1 | 1 | 1 |
<result> = and int 4, %var ; yields {int}:result = 4 & %var
<result> = and int 15, 40 ; yields {int}:result = 8
<result> = and int 4, 8 ; yields {int}:result = 0
<result> = or <ty> <var1>, <var2> ; yields {ty}:result
| In0 | In1 | Out |
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 1 |
<result> = or int 4, %var ; yields {int}:result = 4 | %var
<result> = or int 15, 40 ; yields {int}:result = 47
<result> = or int 4, 8 ; yields {int}:result = 12
<result> = xor <ty> <var1>, <var2> ; yields {ty}:result
| In0 | In1 | Out |
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 0 |
<result> = xor int 4, %var ; yields {int}:result = 4 ^ %var
<result> = xor int 15, 40 ; yields {int}:result = 39
<result> = xor int 4, 8 ; yields {int}:result = 12
<result> = xor int %V, -1 ; yields {int}:result = ~%V
<result> = shl <ty> <var1>, ubyte <var2> ; yields {ty}:result
<result> = shl int 4, ubyte %var ; yields {int}:result = 4 << %var
<result> = shl int 4, ubyte 2 ; yields {int}:result = 16
<result> = shl int 1, ubyte 10 ; yields {int}:result = 1024
<result> = shr <ty> <var1>, ubyte <var2> ; yields {ty}:result
<result> = shr int 4, ubyte %var ; yields {int}:result = 4 >> %var
<result> = shr uint 4, ubyte 1 ; yields {uint}:result = 2
<result> = shr int 4, ubyte 2 ; yields {int}:result = 1
<result> = shr sbyte 4, ubyte 3 ; yields {sbyte}:result = 0
<result> = shr sbyte -2, ubyte 1 ; yields {sbyte}:result = -1
| Memory Access Operations |
<result> = malloc <type>, uint <NumElements> ; yields {type*}:result
<result> = malloc <type> ; yields {type*}:result
'type' must be a sized type.
%array = malloc [4 x ubyte ] ; yields {[%4 x ubyte]*}:array
%size = add uint 2, 2 ; yields {uint}:size = uint 4
%array1 = malloc ubyte, uint 4 ; yields {ubyte*}:array1
%array2 = malloc [12 x ubyte], uint %size ; yields {[12 x ubyte]*}:array2
free <type> <value> ; yields {void}
%array = malloc [4 x ubyte] ; yields {[4 x ubyte]*}:array
free [4 x ubyte]* %array
<result> = alloca <type>, uint <NumElements> ; yields {type*}:result
<result> = alloca <type> ; yields {type*}:result
'type' may be any sized type.
%ptr = alloca int ; yields {int*}:ptr
%ptr = alloca int, uint 4 ; yields {int*}:ptr
<result> = load <ty>* <pointer> <result> = volatile load <ty>* <pointer>
%ptr = alloca int ; yields {int*}:ptr
store int 3, int* %ptr ; yields {void}
%val = load int* %ptr ; yields {int}:val = int 3
store <ty> <value>, <ty>* <pointer> ; yields {void}
volatile store <ty> <value>, <ty>* <pointer> ; yields {void}
%ptr = alloca int ; yields {int*}:ptr
store int 3, int* %ptr ; yields {void}
%val = load int* %ptr ; yields {int}:val = int 3
<result> = getelementptr <ty>* <ptrval>{, long <aidx>|, ubyte <sidx>}*
For example, lets consider a C code fragment and how it gets compiled to LLVM:
struct RT {
char A;
int B[10][20];
char C;
};
struct ST {
int X;
double Y;
struct RT Z;
};
int *foo(struct ST *s) {
return &s[1].Z.B[5][13];
}
The LLVM code generated by the GCC frontend is:
%RT = type { sbyte, [10 x [20 x int]], sbyte }
%ST = type { int, double, %RT }
int* "foo"(%ST* %s) {
%reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13
ret int* %reg
}
In the example above, the first index is indexing into the '%ST*' type, which is a pointer, yielding a '%ST' = '{ int, double, %RT }' type, a structure. The second index indexes into the third element of 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 to this element, thus yielding a 'int*' type.
Note that it is perfectly legal to index partially through a 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) {
%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
}
; yields [12 x ubyte]*:aptr
%aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
| Other Operations |
<result> = phi <ty> [ <val0>, <label0>], ...
There must be no non-phi instructions between the start of a basic block and the PHI instructions: i.e. PHI instructions must be first in a basic block.
Loop: ; Infinite loop that counts from 0 on up... %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ] %nextindvar = add uint %indvar, 1 br label %Loop
<result> = cast <ty> <value> to <ty2> ; yields ty2
When casting to bool, any value that would be considered true in the context of a C 'if' condition is converted to the boolean 'true' values, all else are 'false'.
When extending an integral value from a type of one signness to another (for example 'sbyte' to 'ulong'), the value is sign-extended if the source value is signed, and zero-extended if the source value is unsigned. bool values are always zero extended into either zero or one.
%X = cast int 257 to ubyte ; yields ubyte:1 %Y = cast int 123 to bool ; yields bool:true
<result> = call <ty>* <fnptrval>(<param list>)
%retval = call int %test(int %argc) call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
<resultarglist> = vanext <va_list> <arglist>, <argty>
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.
<resultval> = vaarg <va_list> <arglist>, <argty>
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.
| Intrinsic Functions |
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.
Unless an intrinsic function is target-specific, there must be a lowering pass to eliminate the intrinsic or all backends must support the intrinsic function.
| Variable Argument Handling Intrinsics |
All of these functions operate on arguments that use a target-specific value 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 vanext instruction and the variable argument handling intrinsic functions are used.
int %test(int %X, ...) {
; Initialize variable argument processing
%ap = call sbyte*()* %llvm.va_start()
; Read a single integer argument
%tmp = vaarg sbyte* %ap, int
; Advance to the next argument
%ap2 = vanext sbyte* %ap, int
; Demonstrate usage of llvm.va_copy and llvm.va_end
%aq = call sbyte* (sbyte*)* %llvm.va_copy(sbyte* %ap2)
call void %llvm.va_end(sbyte* %aq)
; Stop processing of arguments.
call void %llvm.va_end(sbyte* %ap2)
ret int %tmp
}
call va_list ()* %llvm.va_start()
Note that this intrinsic function is only legal to be called from within the body of a variable argument function.
call void (va_list)* %llvm.va_end(va_list <arglist>)
call va_list (va_list)* %llvm.va_copy(va_list <destarglist>)