- This document describes the LLVM assembly language IR/VM. LLVM is an SSA - based representation that attempts to be a useful midlevel IR by providing - type safety, low level operations, flexibility, and the capability to - represent 'all' high level languages cleanly. + This document describes the LLVM assembly language. LLVM is an SSA based + representation that is a useful midlevel IR, providing type safety, low level + operations, flexibility, and the capability to represent 'all' high level + languages cleanly.@@ -115,22 +115,44 @@
+The LLVM code representation is designed to be used in three different forms: as +an in-memory compiler IR, as an on-disk bytecode representation, suitable for +fast loading by a dynamic compiler, and as a human readable assembly language +representation. This allows LLVM to provide a powerful intermediate +representation for efficient compiler transformations and analysis, while +providing a natural means to debug and visualize the transformations. The three +different forms of LLVM are all equivalent. This document describes the human +readable representation and notation.
-This dual nature leads to three different representations of LLVM (the human readable assembly representation, the compact bytecode representation, and the in memory, pointer based, representation). This document describes the human readable representation and notation.
- -The LLVM representation aims to be a light weight and low level while being expressive, type safe, 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. By providing type safety, 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.
+The LLVM representation aims to be a light weight and low level while being +expressive, type safe, 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 +safety, 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.
+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:
%x = add int 1, %x-...because only a phi node may refer to itself. The LLVM api provides a verification function (verify) that may be used to verify that a whole module or a single method is well formed. It is useful to validate whether an optimization pass performed a well formed transformation to the code.
+...because only a phi node may refer to itself. +The LLVM api provides a verification pass (created by the +createVerifierPass function) 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. Often, +violations pointed out by the verifier pass indicate bugs in transformation +passes.
Describe the typesetting conventions here. @@ -150,11 +172,22 @@ LLVM uses three different forms of identifiers, for different purposes:
-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.
+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 may start with a '%' character.
+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:
+Here is an example of LLVM code to multiply the integer variable '%X' +by 8:
The easy way:
@@ -177,11 +210,15 @@ This last way of multiplying %X by 8 illustrates several important lexi
- Comments are delimited with a ';' and go until the end of line. -
- Unnamed temporaries are created when the result of a computation is not assigned to a named value. +
- Unnamed temporaries are created when the result of a computation is not + assigned to a named value.
- Unnamed temporaries are numbered sequentially
-...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.
+...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.
@@ -191,9 +228,15 @@ This last way of multiplying %X by 8 illustrates several important lexi
+The LLVM type system is critical to the overall usefulness of the language and +runtime. Being strongly typed enables a number of optimizations to be performed +on the IR directly, without having to do 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 assembly language form for the type system was heavily influenced by the type problems in the C language1.
+The assembly language form for the type system was heavily influenced by the +type problems in the C language1.
@@ -202,7 +245,8 @@ The assembly language form for the type system was heavily influenced by the typ
Primitive Types
+The primitive types are the fundemental building blocks of the LLVM system. The
+current set of primitive types are as follows:
@@ -242,7 +285,7 @@ These different primitive types fall into a few useful classifications:
@@ -254,7 +297,10 @@ These different primitive types fall into a few useful classifications:
+The function type can be thought of as a function signature. It consists of a
+return type and a list of formal parameter types. Function types are usually
+used when to build virtual function tables (which are structures of pointers to
+functions), for indirect function calls, and when defining a function.
+Where '<parameter list>' is a comma seperated list of type
+specifiers. Optionally, the parameter list may include a type ...,
+which indicates that the function takes a variable number of arguments. Note
+that there currently is no way to define a function in LLVM that takes a
+variable number of arguments, but it is possible to call a function that
+is vararg.
-The primitive types are the fundemental building blocks of the LLVM system. The current set of primitive types are as follows:
-
@@ -216,7 +260,7 @@ The primitive types are the fundemental building blocks of the LLVM system. The
label Branch destination
+
bool True or False value int Signed 32 bit value long Signed 64 bit value double 64 bit floating point value lock Recursive mutex value unsigned ubyte, ushort, uint, ulong integral 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, lock first class bool, ubyte, sbyte, ushort, short,
uint, int, ulong, long, float, double
Method Type
+
Function Type
Overview:
-The method type can be thought of as a method signature. It consists of a return type and a list of formal parameter types. Method types are usually used when to build virtual function tables (which are structures of pointers to methods) and for indirect method calls.Syntax:
<returntype> (<parameter list>)
-Where '<parameter list>' is a comma seperated list of type specifiers.Examples:
@@ -331,22 +398,56 @@ Structures are accessed using 'load and 'Examples:
-
int (int) : method taking an int, returning an int float (int, int *) * : Pointer to a method that takes an int and a pointer to int, returning float. 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.
-
{ 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 method that takes an int, returning an int. { 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. |
+ + +
| @@ -361,16 +462,16 @@ Packed types should be 'nonsaturated' because standard data types are not satura |
+talk about the elements of a module: constant pool and function list.
| -Method Structure +Function Structure |
+talk about the optional constant pool
talk about how basic blocks delinate labels
talk about how basic blocks end with terminators
@@ -391,10 +492,16 @@ do and stuff also. -As was mentioned previously, every basic block in -a program ends with a "Terminator" instruction. Additionally, all terminators yield a 'void' value: they produce control flow, not values.
+As was mentioned previously, every basic block +in a program ends with a "Terminator" instruction. All of these terminator +instructions yield a 'void' value: they produce control flow, not +values.
-There are three different terminator instructions: the 'ret' instruction, the 'br' instruction, and the 'switch' instruction.
+There are four different terminator instructions: the 'ret' instruction, the 'br' instruction, the 'switch' instruction, and the 'invoke' instruction.
@@ -402,25 +509,36 @@ There are three different terminator instructions: the 'ret
-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.
+ The 'ret' instruction is used to return control flow (and optionally a
+ value) from a function, back to the caller.
+
+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.
Syntax:
- ret <type> <value> ; Return a value from a non-void method
- ret void ; Return from void method
+ ret <type> <value> ; Return a value from a non-void function
+ ret void ; Return from void function
Overview:
-The 'ret' instruction is used to return control flow (and optionally a value) from a method, back to the caller.Arguments:
-The 'ret' instruction may return any 'first class' type. Notice that a method is not well formed if there exists a 'ret' instruction inside of the method that returns a value that does not match the return type of the method.
+ +The 'ret' instruction may return any 'first +class' type. Notice that a function is not well +formed if there exists a 'ret' instruction inside of the function +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.
ret int 5 ; Return an integer value of 5 - ret void ; Return from a void method + ret void ; Return from a void function@@ -434,15 +552,25 @@ When the 'ret' instruction is executed, control flow returns back to th
+ +The 'br' instruction is used to cause control flow to transfer to a +different basic block in the current function. There are two forms of this +instruction, corresponding to a conditional branch and an unconditional +branch.
+The conditional branch form of the 'br' instruction takes a single +'bool' value and two 'label' values. The unconditional form +of the 'br' instruction takes a single 'label' value as a +target.
+Upon execution of a conditional 'br' instruction, the 'bool' +argument is evaluated. If the value is true, control flows to the +'iftrue' 'label' argument. If "cond" is false, +control flows to the 'iffalse' 'label' argument.
@@ -472,23 +600,44 @@ IfUnequal:
-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 '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.
-The two different forms of the 'switch' statement are simple hints to the underlying virtual machine implementation. For example, a virtual machine may choose to implement a small indirect branch table as a series of predicated comparisons: if it is faster for the target architecture.
+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 virtual machine implementation. For example, a virtual machine +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 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.
+ +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 index branch form simply looks up a label element directly in a table and branches to it.
+The lookup style switch statement 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.
-In either case, the compiler knows the static size of the array, because it is provided as part of the constant values type.
+The index branch form simply looks up a label element directly in a table and +branches to it.
+ +In either case, the compiler knows the static size of the array, because it is +provided as part of the constant values type.
@@ -502,11 +651,11 @@ In either case, the compiler knows the static size of the array, because it is p
; Implement a jump table using the constant pool:
void "testmeth"(int %arg0)
%switchdests = [3 x label] [ label %onzero, label %onone, label %ontwo ]
- {
+ begin
...
switch uint %val, label %otherwise, [3 x label] %switchdests...
...
- }
+ end
; Implement the equivilent jump table directly:
switch uint %val, label %otherwise, [3 x label] [ label %onzero,
@@ -518,37 +667,54 @@ In either case, the compiler knows the static size of the array, because it is p
-
'call .. with' Instruction
+
'invoke' Instruction
Syntax:
- <result> = call <method ty> %<method name>(<method args>) with label <break label>
+ <result> = invoke <ptr to function ty> %<function ptr val>(<function args>)
+ to label <normal label> except label <exception label>
-Overview:
-The 'call .. with' instruction is used to cause control flow to transfer to a specified method, with the possibility of control flow transfer to the 'break label' label, in addition to the possibility of fallthrough to the next basic block. The 'call' instruction is closely related, but does guarantees that control flow either never returns from the invoked method, or that it returns to the instruction succeeding the 'call' instruction.
-
-TODO: icall .. with needs to be defined as well for an indirect call.
+
Overview:
The 'invoke' instruction is used to cause control
+flow to transfer to a specified function, with the possibility of control flow
+transfer to either the 'normal label' label or the 'exception
+label'. The 'call' instruction is closely
+related, but guarantees that control flow either never returns from the called
+function, or that it returns to the instruction succeeding the 'call' instruction.
Arguments:
This instruction requires several arguments:
-- 'method ty': shall be the signature of the named method being invoked. This must be a method type.
-
- 'method name': method name to be invoked.
-
- 'method args': argument list whose types match the method signature argument types.
-
- 'break label': a label that specifies the break label associated with this call.
+
+
- 'ptr to function ty': shall be the signature of the pointer to
+function value being invoked. In most cases, this is a direct method
+invocation, but indirect invoke's 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.
+
+
- 'normal label': the label reached when the called function executes
+a 'ret' instruction.
+
+
- 'exception label': the label reached when an exception is thrown.
Semantics:
-This instruction is designed to operate as a standard 'call' instruction in most regards. The primary difference is that it assiciates a label with the method invocation that may be accessed via the runtime library provided by the execution environment. 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.
+This instruction is designed to operate as a standard 'call' instruction in most regards. The primary difference is that it assiciates a label with the function invocation that may be accessed via the runtime library provided by the execution environment. 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.
-For a more comprehensive explanation of this instruction look in the llvm/docs/2001-05-18-ExceptionHandling.txt document.
+For a more comprehensive explanation of this instruction look in the llvm/docs/2001-05-18-ExceptionHandling.txt document.
Example:
- %retval = call int (int) %Test(int 15) with label %TestCleanup ; {int}:retval set
+ %retval = invoke int %Test(int 15)
+ to label %Continue except label %TestCleanup ; {int}:retval set
@@ -560,7 +726,7 @@ For a more comprehensive explanation of this instruction look in the llvm/docs/2
Unary operators are used to do a simple operation to a single value.
-There is only one unary operators: the 'not' instruction.
+There is only one unary operator: the 'not' instruction.
@@ -581,8 +747,6 @@ The single argument to 'not' must be of of integr
Semantics:
The 'not' instruction returns the logical inverse of an integral type.
-Note that the 'not' instruction is is not defined over to 'bool' type. To invert a boolean value, the recommended method is to use:
-
<result> = xor bool true, <var> ; yields {bool}:result
@@ -600,7 +764,10 @@ Note that the 'not' instruction is is not defined over to 'boolBinary Operations
-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. The result value of a binary operator is not neccesarily the same type as its operands.
+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.
+The result value of a binary operator is not neccesarily the same type as its
+operands.
There are several different binary operators:
@@ -637,12 +804,17 @@ The two arguments to the 'add' instruction must be either integral or floating point values. Both arguments must have identical types.
+
+The two arguments to the 'sub' instruction must be either integral or floating point
+values. Both arguments must have identical types.
Semantics:
...
@@ -669,7 +841,9 @@ The two arguments to the 'mul' instruction must be either integral or floating point values. Both arguments must have identical types.
+
+The two arguments to the 'div' instruction must be either integral or floating point
+values. Both arguments must have identical types.
Semantics:
...
@@ -741,8 +919,11 @@ TODO: remainder or modulus?
Overview:
The 'setcc' family of instructions returns a boolean value based on a comparison of their two operands.
-
Arguments:
-The two arguments to the 'setcc' instructions must be of first class or derived type (it is not possible to compare 'label's or 'void' values). Both arguments must have identical types.
+
Arguments:
The two arguments to the 'setcc'
+instructions must be of first class or pointer type (it is not possible to compare
+'label's, 'array's, 'structure' or 'void'
+values). Both arguments must have identical types.
The 'setlt', 'setgt', 'setle', and 'setge' instructions do not operate on 'bool' typed arguments.
@@ -809,11 +990,14 @@ The two arguments to the 'and' instruction must be either integral or bool values. Both arguments must have identical types.
+
+The two arguments to the 'or' instruction must be either integral or bool values.
+Both arguments must have identical types.
Semantics:
@@ -837,10 +1021,15 @@ The two arguments to the 'or' instruction must be either integral or bool values. Both arguments must have identical types.
+
+The two arguments to the 'xor' instruction must be either integral or bool values.
+Both arguments must have identical types.
Semantics:
@@ -864,10 +1053,15 @@ The two arguments to the 'xor' instruction must be either integral type. The second argument must be an 'ubyte' type.
+
+The first argument to the 'shl' instruction must be an integral type. The second argument must be an
+'ubyte' type.
Semantics:
... 0 bits are shifted into the emptied bit positions...
@@ -924,8 +1118,8 @@ Accessing memory in SSA form is, well, sticky at best. This section describes h
Syntax:
- <result> = malloc <type> ; yields { type *}:result
- <result> = malloc [<type>], uint <NumElements> ; yields {[type] *}:result
+ <result> = malloc <type>, uint <NumElements> ; yields {type*}:result
+ <result> = malloc <type> ; yields {type*}:result
Overview:
@@ -933,9 +1127,13 @@ The 'malloc' instruction allocates memory from the system heap and retu
Arguments:
-There are two forms of the 'malloc' instruction, one for allocating a variable of a fixed type, and one for allocating an array. The array form is used to allocate an array, where the upper bound is not known until run time. If the upper bound is known at compile time, it is recommended that the first form be used with a sized array type.
+The the 'malloc' instruction allocates
+sizeof(<type>)*NumElements bytes of memory from the operating
+system, and returns a pointer of the appropriate type to the program. The
+second form of the instruction is a shorter version of the first instruction
+that defaults to allocating one element.
-'type' may be any type except for a unsized array type.
+'type' must be a sized type
Semantics:
Memory is allocated, a pointer is returned.
@@ -945,8 +1143,8 @@ Memory is allocated, a pointer is returned.
%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 [ubyte], uint %size ; yields {[ubyte]*}:array2
+ %array1 = malloc ubyte, uint 4 ; yields {ubyte*}:array1
+ %array2 = malloc [12 x ubyte], uint %size ; yields {[12 x ubyte]*}:array2
@@ -984,40 +1182,84 @@ Memory is available for use after this point. The contents of the 'valueSyntax:
- <result> = alloca <type> ; yields {type*}:result
- <result> = alloca [<type>], uint <NumElements> ; yields {[type] *}:result
+ <result> = alloca <type>, uint <NumElements> ; yields {type*}:result
+ <result> = alloca <type> ; yields {type*}:result
+The 'alloca' instruction allocates memory on the current stack frame of +the procedure that is live until the current function returns to its caller.
-'type' may be any type except for a unsized array type.
- -Note that a virtual machine may generate more efficient native code for a method if all of the fixed size 'alloca' instructions live in the first basic block of that method. +The 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.
+ +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, as well as spilled variables.
%ptr = alloca int ; yields {int*}:ptr
- %ptr = alloca [int], uint 4 ; yields {[int]*}:ptr
+ %ptr = alloca int, uint 4 ; yields {int*}:ptr
+
+
+ <result> = getelementptr <ty>* <ptrval>{, uint <aidx>|, ubyte <sidx>}*
+
+
++ +
+ +TODO. + +
+ %aptr = getelementptr {int, [12 x ubyte]}* %sptr, 1 ; yields {[12 x ubyte]*}:aptr
+ %ub = load [12x ubyte]* %aptr, 4 ;yields {ubyte}:ub
+
+
+
+
- <result> = load <ty>* <pointer> ; yields {ty}:result
- <result> = load <ty>* <arrayptr>{, uint <idx>}+ ; yields {ty}:result
- <result> = load <ty>* <structptr>{, ubyte <idx>}+ ; yields field type
+ <result> = load <ty>* <pointer>
+ <result> = load <ty>* <pointer> <index list>
- <result> = getelementptr <ty>* <arrayptr>{, uint <idx>}+ ; yields {ty*}:result
- <result> = getelementptr <ty>* <structptr>{, ubyte <idx>}+ ; yields field type*
-
-
-
- %aptr = getelementptr {int, [12 x ubyte]}* %sptr, 1 ; yields {[12 x ubyte]*}:aptr
- %ub = load [12x ubyte]* %aptr, 4 ;yields {ubyte}:ub
-
-
-
-