Updated documentation and added more examples.

git-svn-id: http://llvm-py.googlecode.com/svn/trunk@34 8d1e9007-1d4e-0410-b67e-1979fd6579aa

test/example-jit.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+
+# Import the llvm-py modules.
+from llvm import *
+from llvm.core import *
+from llvm.ee import *          # new import: ee = Execution Engine
+
+# Create a module, as in the previous example.
+my_module = Module.new('my_module')
+ty_int = Type.int()   # by default 32 bits
+ty_func = Type.function(ty_int, [ty_int, ty_int])
+f_sum = my_module.add_function(ty_func, "sum")
+f_sum.args[0].name = "a"
+f_sum.args[1].name = "b"
+bb = f_sum.append_basic_block("entry")
+builder = Builder.new(bb)
+tmp = builder.add(f_sum.args[0], f_sum.args[1], "tmp")
+builder.ret(tmp)
+
+# Create a module provider object first. Modules can come from
+# in-memory IRs like what we created now, or from bitcode (.bc)
+# files. The module provider abstracts this detail.
+mp = ModuleProvider.new(my_module)
+
+# Create an execution engine object. This will create a JIT compiler
+# on platforms that support it, or an interpreter otherwise.
+ee = ExecutionEngine.new(mp)
+
+# The arguments needs to be passed as "GenericValue" objects.
+arg1 = GenericValue.int(ty_int, 100)
+arg2 = GenericValue.int(ty_int, 42)
+
+# Now let's compile and run!
+retval = ee.run_function(f_sum, [arg1, arg2])
+
+# The return value is also GenericValue. Let's print it.
+print "returned", retval.as_int()
+

test/example.py

@@ -1,42 +1,45 @@
 #!/usr/bin/env python
 
+# Import the llvm-py modules.
+from llvm import *
 from llvm.core import *
 
-## create a module
-module = Module.new("my_module")
+# Create an (empty) module.
+my_module = Module.new('my_module')
 
-## create a function type taking two doubles and returning a (32-bit) integer
-ty_double = Type.double()
-ty_int    = Type.int()
-ty_func   = Type.function( ty_int, [ ty_double, ty_double ] )
+# All the types involved here are "int"s. This type is represented
+# by an object of the llvm.core.Type class:
+ty_int = Type.int()   # by default 32 bits
 
-## create a function of this type
-func      = Function.new( module, ty_func, "foobar" )
+# We need to represent the class of functions that accept two integers
+# and return an integer. This is represented by an object of the
+# function type (llvm.core.FunctionType):
+ty_func = Type.function(ty_int, [ty_int, ty_int])
 
-# name function args
-func.args[0].name = "arg1"
-func.args[1].name = "arg2"
+# Now we need a function named 'sum' of this type. Functions are not
+# free-standing (in llvm-py); it needs to be contained in a module.
+f_sum = my_module.add_function(ty_func, "sum")
 
-## implement the function
+# Let's name the function arguments as 'a' and 'b'.
+f_sum.args[0].name = "a"
+f_sum.args[1].name = "b"
 
-# add a basic block
-entry = func.append_basic_block("entry")
+# Our function needs a "basic block" -- a set of instructions that
+# end with a terminator (like return, branch etc.). By convention
+# the first block is called "entry".
+bb = f_sum.append_basic_block("entry")
 
-# create an llvm::IRBuilder
-builder = Builder.new(entry)
+# Let's add instructions into the block. For this, we need an
+# instruction builder:
+builder = Builder.new(bb)
 
-# add two args into tmp1
-tmp1 = builder.add(func.args[0], func.args[1], "tmp1")
+# OK, now for the instructions themselves. We'll create an add
+# instruction that returns the sum as a value, which we'll use
+# a ret instruction to return.
+tmp = builder.add(f_sum.args[0], f_sum.args[1], "tmp")
+builder.ret(tmp)
 
-# sub `1' from that
-one = Constant.real( ty_double, 1.0 )
-tmp2 = builder.sub(tmp1, one, "tmp2")
+# We've completed the definition now! Let's see the LLVM assembly
+# language representation of what we've created:
+print my_module
 
-# convert to integer
-tmp3 = builder.fptoui(tmp2, ty_int, "tmp3")
-
-# return it
-builder.ret(tmp3)
-
-# dump the module to see the llvm "assembly" code
-print module

test/intrinsic.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python
+
+# This example shows how to use LLVM intrinsics.
+
+from llvm.core import *
+from llvm.ee import *
+
+# setup a function and a builder
+mod    = Module.new('test')
+functy = Type.function(Type.void(), [])
+func   = mod.add_function(functy, "showme")
+block  = func.append_basic_block("entry")
+b      = Builder.new(block)
+
+# let's do bswap on a 32-bit integer using llvm.bswap
+val   = Constant.int(Type.int(), 42)
+bswap = Function.intrinsic(mod, INTR_BSWAP, [Type.int()])
+b.call(bswap, [val])
+print mod
+
+# the output is:
+#
+#   ; ModuleID = 'test'
+#   
+#   define void @showme() {
+#   entry:
+#   	call i32 @llvm.bswap.i32( i32 42 )		; <i32>:0 [#uses=0]
+#   }
+#   
+#   declare i32 @llvm.bswap.i32(i32) nounwind readnone 
+#
+
+# mysin(x) = sqrt(1.0 - pow(cos(x), 2))
+
+float   = Type.float()
+mysinty = Type.function( float, [float] )
+mysin   = mod.add_function(mysinty, "mysin")
+block   = mysin.append_basic_block("entry")
+b       = Builder.new(block)
+
+sqrt = Function.intrinsic(mod, INTR_SQRT, [float])
+pow  = Function.intrinsic(mod, INTR_POWI, [float])
+cos  = Function.intrinsic(mod, INTR_COS,  [float])
+
+mysin.args[0].name = "x"
+x    = mysin.args[0]
+one  = Constant.real(float, "1")
+cosx = b.call(cos, [x], "cosx")
+cos2 = b.call(pow, [cosx, Constant.int(Type.int(), 2)], "cos2")
+onemc2 = b.sub(one, cos2, "onemc2")
+sin  = b.call(sqrt, [onemc2], "sin")
+b.ret(sin)
+print mod
+
+#
+#   ; ModuleID = 'test'
+#   
+#   define void @showme() {
+#   entry:
+#   	call i32 @llvm.bswap.i32( i32 42 )		; <i32>:0 [#uses=0]
+#   }
+#   
+#   declare i32 @llvm.bswap.i32(i32) nounwind readnone 
+#   
+#   define float @mysin(float %x) {
+#   entry:
+#   	%cosx = call float @llvm.cos.f32( float %x )		; <float> [#uses=1]
+#   	%cos2 = call float @llvm.powi.f32( float %cosx, i32 2 )		; <float> [#uses=1]
+#   	%onemc2 = sub float 1.000000e+00, %cos2		; <float> [#uses=1]
+#   	%sin = call float @llvm.sqrt.f32( float %onemc2 )		; <float> [#uses=1]
+#   	ret float %sin
+#   }
+#   
+#   declare float @llvm.sqrt.f32(float) nounwind readnone 
+#   
+#   declare float @llvm.powi.f32(float, i32) nounwind readnone 
+#   
+#   declare float @llvm.cos.f32(float) nounwind readnone 
+#