-Google code hosting: http://code.google.com/p/llvm-py/ -
-Browse SVN: http://code.google.com/p/llvm-py/source/browse
+Discussions: http://groups.google.com/group/llvm-py +
+SVN HEAD can be checked out like so:
The latest release is 0.6, released 31-Aug-2010 (Changelog below). 0.6 works only with LLVM 2.7.
Download it here: -* llvm-py-0.6.tar.bz2 (primary) -* llvm-py-0.6.tar.bz2 (mirror)
Download it here:
+llvm-py-0.6.tar.bz2 (primary) +
++llvm-py-0.6.tar.bz2 (mirror) +
+Older versions are available here.
The latest code can be checked out from SVN like so:
0.6, 31-Aug-2010: +0.7, in progress: + + * Add llvm.core.Argument.alignment property. + * Migrate to LLVM 2.8. + * Fix ffi link issue on darwin (Albert Mietus) (Issue #29). + * LLVM tutorial ported (Max Shawabkeh) (Issue #33). + + +0.6, 31-Aug-2010: * Add and remove function attributes (Krzysztof Goj) (Issue #21). * Wrap fadd,fsub,fmul (Aaron S Lav) (Issue #31). @@ -130,11 +147,10 @@ package.
Let’s create a (LLVM) module containing a single function, corresponding to the C function:
Here’s how it looks like:
Let’s compile this function in-memory and run it.
The following JIT tutorials were contributed by Sebastien Binet.
LLVM (Low-Level Virtual Machine) provides enough @@ -77,8 +76,6 @@ versions.
llvm-py has been built and tested with Python 2.6. It should work with Python 2.4 and 2.5. It has not been tried with Python 3.x (patches welcome).
llvm-py is distributed as a source tarball. You’ll need to build and @@ -87,7 +84,7 @@ required for this:
-C and C compilers (gcc/g) +C and C++ compilers (gcc/g++)
On debian-based systems, the first three can be installed with the command sudo apt-get install gcc g++ python python-dev. Ensure that your distro’s respository has the appropriate version of LLVM!
It does not matter which compiler LLVM itself was built with (g, -llvm-g or any other); llvm-py can be built with any compiler. It has +
It does not matter which compiler LLVM itself was built with (g++, +llvm-g++ or any other); llvm-py can be built with any compiler. It has been tried only with gcc/g++ though.
The result of an LLVM build is a set of static libraries and object files. The llvm-py contains an extension package that is built into a shared object (_core.so) which links to these static libraries and @@ -125,9 +121,7 @@ configuring LLVM (default is no PIC), like this:
~/llvm$ ./configure --enable-pic --enable-optimized
Inorder to build llvm-py, it’s build script needs to know from where it can invoke the llvm helper program, llvm-config. If you’ve installed LLVM, then this will be available in your PATH, and nothing further @@ -137,9 +131,7 @@ of llvm-config to the build script.
You’ll need to be root to install llvm-py. Remember that your PATH is different from that of root, so even if llvm-config is in your PATH, it may not be available when you do sudo.
The commands illustrated below assume that the LLVM source is available under /home/mdevan/llvm. If you’ve a previous version of llvm-py installed, it is recommended to remove it first, as described @@ -175,9 +167,7 @@ only if you need to debug into LLVM also.
If you’d installed llvm-py with the --user option, then llvm-py would be present under ~/.local/lib/python2.6/site-packages. Otherwise, it might be under /usr/lib/python2.6/site-packages @@ -192,15 +182,11 @@ the "egg" can be removed like so:
See the Python documentation for more information.
This section explains a few concepts related to LLVM, not specific to llvm-py.
The intermediate representation, or IR for short, is an in-memory data structure that represents executable code. The IR data structures allow for creation of types, constants, functions, function arguments, @@ -256,9 +242,7 @@ level than the usual assembly language; for example there are instructions related to variable argument handling, exception handling, and garbage collection. These allow high-level languages to be represented cleanly in the IR.
All LLVM instructions are represented in the Static Single Assignment (SSA) form. Essentially, this means that any variable can be assigned to only once. Such a representation facilitates better optimization, among @@ -290,9 +274,7 @@ reached the PHI node. The argument a1 of the PHI node is associated with the block "a1 = 1;" and a2 with the block "a2 = 2;".
PHI nodes have to be explicitly created in the LLVM IR. Accordingly the LLVM instruction set has an instruction called phi.
The LLVM IR can be represented offline in two formats - a textual, human-readable form, similar to assembly language, called the LLVM assembly language (files with .ll extension) @@ -306,7 +288,7 @@ language code.
Just to get a feel of the LLVM assembly language, here’s a function in C, and the corresponding LLVM assembly (as generated by the demo page):
The LLVM Language Reference defines the LLVM assembly language including the entire instruction set.
Modules, in the LLVM IR, are similar to a single C language source file (.c file). A module contains:
LLVM provides quite a few optimization algorithms that work on the IR. These algorithms are organized as passes. Each pass does something specific, like combining redundant instructions. Passes need not always @@ -406,18 +384,11 @@ any stage, and perform any transforms on it as you like.)
TODO
TODO
TODO
The llvm-py is a Python package, consisting of 6 modules, that wrap @@ -584,7 +555,7 @@ constants PASS_* that represent various passes llvm.core". However, you might find it more convenient to import llvm-py modules thus:
Modules are top-level container objects. You need to create a module object first, before you can add global variables, aliases or functions. Modules are created using the static method Module.new:
There is corresponding serialization method also, called to_bitcode:
Types are what you think they are. A instance of llvm.core.Type, or one of its derived classes, represent a type. llvm-py does not use as many classes to represent types as does LLVM itself. Some types are @@ -1009,7 +977,7 @@ cellspacing="0" cellpadding="4">
The class-level documentation follows:
Example:
@@ -1229,7 +1197,7 @@ http://www.gnu.org/software/src-highlite -->
@@ -1264,7 +1232,7 @@ http://www.gnu.org/software/src-highlite --> function. Used like this:
@@ -1313,7 +1281,7 @@ http://www.gnu.org/software/src-highlite --> Used like this:
@@ -1364,7 +1332,7 @@ http://www.gnu.org/software/src-highlite -->
@@ -1393,7 +1361,7 @@ http://www.gnu.org/software/src-highlite -->
@@ -1422,7 +1390,7 @@ http://www.gnu.org/software/src-highlite -->
Here is an example that demonstrates the creation of types:
TypeHandle objects are used to create recursive types, like this linked list node structure in C:
llvm.core.Value is the base class of all values computed by a program that may be used as operands to other values. A value has a type associated with it (an object of llvm.core.Type).
Value objects have a type (read-only), and a name (read-write).
User-s are values that refer to other values. The values so refered can be retrived by the properties of User. This is the reverse of the Value.uses. Together these can be used to traverse the use-def chains of the SSA.
@@ -1698,16 +1660,14 @@ chains of the SSA.
Constant-s represents constants that appear within the code. The values of such objects are known at creation time. Constants can be created from Python constants. A constant expression is also a constant — given a Constant object, an operation (like addition, subtraction etc) can be specified, to yield a new Constant object. Let’s see some examples:
@@ -2126,9 +2086,7 @@ cellspacing="0" cellpadding="4">
See table of operations above for full list. There are no other methods.
The following subclasses of Constant do not provide additional methods, they serve only to provide richer type information.
These types are helpful in isinstance checks, like so:
The class llvm.core.GlobalValue represents module-scope aliases, variables and functions. Global variables are represented by the sub-class llvm.core.GlobalVariable and functions by llvm.core.Function.
@@ -2396,9 +2352,7 @@ to can be retrieved using the module property (read-only).
Global variables (llvm.core.GlobalVariable) are subclasses of llvm.core.GlobalValue and represent module-level variables. These can have optional initializers and can be marked as constants. Global @@ -2406,7 +2360,7 @@ variables can be created either by using the add_global_variable method of the Module class (see above), or by using the static method GlobalVariable.new.
Global variables can be delete using the delete method. Do not use the object after calling delete on it.
@@ -2513,9 +2467,7 @@ gv = None
Functions are represented by llvm.core.Function objects. They are contained within modules, and can be created either with the method module_obj.add_function or the static constructor Function.new. @@ -2524,7 +2476,7 @@ References to functions already present in a module can be retrieved via Function.get. All functions in a module can be enumerated by iterating over module_obj.functions.
Functions can be verified with the verify method. Note that this may not work properly (aborts on errors).
Function attributes, as documented +
Function attributes, as documented here, can be set on functions using the methods add_attribute and remove_attribute. The following values may be used to refer to the @@ -2968,7 +2920,7 @@ cellspacing="0" cellpadding="4">
Here is how attributes can be set and removed:
@@ -3175,16 +3127,15 @@ f.
The args property of llvm.core.Function objects yields llvm.core.Argument objects. This allows for setting attributes for functions arguments. Argument objects cannot be constructed from user -code, the only way to get a reference to these are via functions.
The method add_attribute and remove_attribute can be used to add or remove the following attributes:
The corresponding +
These method work exactly like the corresponding methods +of the Function class above. Refer LLVM docs -provide more information.
The alignment of any parameter can be set via the alignment +for information on what each attribute means.
The alignment of any argument can be set via the alignment property, to any power of 2.
+llvm.core.Value +
++ The alignment of the argument. Must be a power of 2. +
++ Add an attribute attr to the argument, from the set listed above. +
++ Remove the attribute attr of the argument. +
+An llvm.core.Instruction object represents an LLVM instruction. This +class is the root of a small hierarchy:
Instruction + CallOrInvokeInstruction + PHINode + SwitchInstruction + CompareInstruction+
Instructions are not created directly, but via a builder. The builder +both creates instructions and adds them to a basic block at the same +time. One way of getting instruction objects are from basic blocks.
Being derived from llvm.core.User, the instruction +is-a user, i.e., an instruction in turn uses other values. The values +an instruction uses are its operands. These may be accessed using +operands property from the llvm.core.User base.
The name of the instruction (like add, mul etc) can be got +via the opcode_name property. The basic_block property gives +the basic block to which the instruction belongs to. Note that +llvm-py does not allow free-standing instruction objects (i.e., +all instructions are created contained within a basic block).
Classes of instructions can be got via the properties +is_terminator, is_binary_op, is_shift etc. See below for +the full list.
+llvm.core.User +
++ The basic block to which this instruction belongs to. +
++ True if the instruction is a terminator instruction. +
++ True if the instruction is a binary operator. +
++ True if the instruction is a shift instruction. +
++ True if the instruction is a cast instruction. +
++ True if the instruction is a logical shift instruction. +
++ True if the instruction is an arithmetic shift instruction. +
++ True if the instruction is associative. +
++ True if the instruction is commutative. +
++ True if the instruction is a volatile load or store. +
++ The numeric opcode value of the instruction. Do not rely + on the absolute value of this number, it may change with + LLVM version. +
++ The name of the instruction, like add, sub etc. +
+The llvm.core.CallOrInvokeInstruction is a subclass of +llvm.core.Instruction, and represents either a call or an +invoke instruction.
+llvm.core.Instruction +
++ Get or set the calling convention. See the list above + for possible values. +
++ Add an attribute attr to the idx-th argument. See + above for possible values of attr. +
++ Remove an attribute attr from the idx-th argument. See + above for possible values of attr. +
++ Set the alignment of the idx-th argument to align. + align should be a power of two. +
+The llvm.core.PHINode is a subclass of +llvm.core.Instruction, and represents the phi instruction. When +created (using Builder.phi) the phi node contains no incoming +blocks (nor their corresponding values). To add an incoming arc to +the phi node, use the add_incoming method, which takes a source +block (llvm.core.BasicBlock object) and a value (object of +llvm.core.Value or of a class derived from it) that the phi node +will take on if control branches in from that block.
+llvm.core.Instruction +
++ The number of incoming arcs for this phi node. +
++ Add an incoming arc, from the llvm.core.BasicBlock object + block, with the corresponding value value. value should + be an object of llvm.core.Value (or of a descendent class). + See above for possible values of attr. +
++ Returns the idx-th incoming arc’s value. +
++ Returns the idx-th incoming arc’s block. +
+(TODO describe)
+llvm.core.Instruction +
++ Add another case to the switch statement. When the expression + being evaluated equals const, then control branches to + block. Here const must be of type llvm.core.ConstantInt. +
+(TODO describe)
+llvm.core.Instruction +
++ The predicate of the compare instruction, one of the ICMP_* or + FCMP_* constants. +
+TODO
TODO
TODO
TODO
TODO. For now, see test/example-jit.py.
TODO. For now, see test/passes.py.
llvm-py lives at @@ -3324,11 +3598,10 @@ are most welcome. You can checkout the latest SVN HEAD from
Mahadevan R wrote llvm-py and works on it in his spare time. He can be reached at mdevan@mdevan.org.