LLVM Bindings for Lua/Ravi

As part of the Ravi Programming Language, it is my intention to provide a Lua 5.3 compatible LLVM binding. This will allow Lua programmers to write their own JIT compilers in Lua!

Right now this is in early development so there is no documentation. But the Lua programs here demonstrate the features available to date.

LLVM Modules and Execution Engines

One of the complexities of LLVM is the handling of modules and execution engines in a JIT environment. In Ravi I made the simple decision that each Lua function would get its own module and EE. This allows the function to be garbage collected as normal and release the associated module and EE. One of the things that is possible but not yet implemented is releasing the module and EE early; this requires implementing a custom memory manager (issue #48).

To mimic the Ravi model, the LLVM bindings provide a shortcut to setup an LLVM module and execution engine for a Lua C function. The following example illustrates:

-- Get the LLVM context - right now this is the
-- global context
local context = llvm.context()

-- Create a lua_CFunction instance
-- At this stage the function will get a module and
-- execution engine but no body
local mainfunc = context:lua_CFunction("demo")

Above creates an llvm::Function instance within a new module. An EE is automatically attached. You can get hold of the module as shown below:

-- Get hold of the module
local module = mainfunc:module()

Other native functions may be created within the same module as normal. However note that once the Lua function is compiled then no further updates to the module are possible.

The model I recommend when using this feature is to create one exported Lua C function in the module, with several private ‘internal’ supporting functions within the module.

Creating Modules and Execution Engines

The LLVM api for these functions are not exposed yet.


For examples that illustrate the bindings please visit the llvmbindings folder in the repository.

Type Hierarchy

The bindings provide a number of Lua types:

+ LLVMcontext
+ LLVMfunction
  + LLVMmainfunction
+ LLVMmodule
+ LLVMtype
  + LLVMstructtype
  + LLVMpointertype
  + LLVMfunctiontype
+ LLVMvalue
  + LLVMinstruction
  + LLVMconstant
  + LLVMphinode
+ LLVMirbuilder
+ LLVMbasicblock

Available Bindings

The following table lists the Lua LLVM api functions available.

llvm.context() -> LLVMcontext
Returns global llvm::Context
LLVMcontext methods
lua_CFunction(name) -> LLVMmainfunction
Creates an llvm::Function within a new llvm::Module; and associates an llvm::ExecutionEngine with the module
types() -> table of predefined type bindings
Returns a table of predefined LLVM type bindings
structtype(name) -> LLVMstructtype
Opaque struct type; body can be added
pointertype(type) -> LLVMpointertype
Given a type returns a pointertype
functiontype(return_type, {argtypes}, {options}) -> LLVMfunctiontype
Creates a function type with specified return type, argument types. Takes the option ‘vararg’ which is false by default.
basicblock(name) -> LLVMbasicblock
Create a basic block
intconstant(intgervalue) -> LLVMvalue
Returns an integer constant value
nullconstant(pointertype) -> LLVMvalue
Returns a NULL constant of specified pointertype
LLVMstructtype methods
Adds members to the struct type
LLVMmainfunction methods
Adds a basic block to the end
Compiles the module and returns a reference to the C Closure
arg(position) -> LLVMvalue
Returns the argument at position; position >= 1; returns nil if argument not available
module() -> LLVMmodule
Returns the module associated with the function
extern(name[, functiontype]) -> LLVMconstant
Returns an extern declaration; A number of Lua Api functions are predefined.
LLVMmodule methods
newfunction(name, functiontype) -> LLVMfunction
Returns an internal linkage function within the module
Dumps the module
LLVMfunction methods
Adds a basic block to the end
arg(position) -> LLVMvalue
Returns the argument at position; position >= 1; returns nil if argument not available
alloca(type[, name [,arraysize]]) -> LLVMinstruction
Creates a variable in the first block of the function
LLVMirbuilder methods
Set current basicblock
Emit return instruction
stringconstant(string) -> LLVMvalue
Create a global string constant
call({args}, {options}) -> LLVMinstruction
Emit call instruction; ‘tailcall’ option is false by default
br(basicblock) -> LLVMinstruction
Emit a branch instruction
condbr(value, true_block, false_block) -> LLVMinstruction
Emit a conditional branch
phi(type, num_values[, name]) -> LLVMphinode
Generate a PHINode

GEP Operators

gep(value, {offsets}) -> LLVMvalue
getelementptr to obtain ptr to an array or struct element
inboundsgep(value, {offsets}) -> LLVMvalue
inbounds version of getelementptr

Memory Operators

load(ptr) -> LLVMinstruction
Loads the value at ptr
store(value, ptr) -> LLVMinstruction
Stores the value to ptr

Binary Operators of the form op(value1, value2) -> LLVMvalue

  • icmpeq
  • icmpne
  • icmpugt
  • icmpuge
  • icmpult
  • icmpule
  • icmpsgt
  • icmpsge
  • icmpslt
  • icmpsle
  • fcmpoeq
  • fcmpogt
  • fcmpoge
  • fcmpolt
  • fcmpole
  • fcmpone
  • fcmpord
  • fcmpun
  • fcmpueq
  • fcmpugt
  • fcmpuge
  • fcmpult
  • fcmpule
  • fcmpune
  • nswadd
  • nuwadd
  • nswsub
  • nuwsub
  • udiv
  • exactudiv
  • sdiv
  • exactsdiv
  • urem
  • srem
  • and
  • or
  • xor
  • fadd
  • fsub
  • fmul
  • fdiv
  • frem

Unary Operators of the form op(value) -> LLVMvalue

  • not
  • neg
  • fneg

Conversion Operators of the form op(value,type) -> LLVMvalue

  • trunc
  • zext
  • sext
  • zextortrunc
  • sextortrunc
  • fptoui
  • fptosi
  • uitofp
  • sitofp
  • fptrunc
  • fpext
  • ptrtoint
  • inttoptr
  • bitcast
  • sextorbitcast
  • zextorbitcast
  • truncorbitcast
  • pointercast
  • fpcast
LLVMphinode methods
addincoming(value, basicblock)
Adds incoming edge