Atomic types¶

class llvmlite.ir.PointerType(pointee, addrspace=0)¶

The type of pointers to another type. pointee is the type pointed to. The optional addrspace integer allows you to choose a non-default address space (the meaning is platform-dependent).

Pointer types exposes the following attributes:

addrspace¶

The pointer’s address space number.

pointee¶

The type pointed to.

class llvmlite.ir.IntType(bits)¶

The type of integers. bits, a Python integer, specifies the bitwidth of the integers having this type.

width¶

The width in bits.

class llvmlite.ir.FloatType¶

The type of single-precision floating-point real numbers.

class llvmlite.ir.DoubleType¶

The type of double-precision floating-point real numbers.

class llvmlite.ir.VoidType¶

The class for void types; only used as the return type of a function without a return value.

Aggregate types¶

class llvmlite.ir.Aggregate¶

The base class for aggregate types. You should never instantiate it directly. Aggregate types have the following attribute in common:

elements¶

A tuple-like immutable sequence of element types for this aggregate type.

class llvmlite.ir.ArrayType(element, count)¶

The class for array types. element is the type of every element, count the number of elements (a Python integer).

class llvmlite.ir.LiteralStructType(elements)¶

The class for literal struct types. elements is a sequence of element types for each member of the structure.

Other types¶

class llvmlite.ir.FunctionType(return_type, args, var_arg=False)¶

The type of a function. return_type is the return type of the function. args is a sequence describing the types of argument to the function. If var_arg is true, the function takes a variable number of additional arguments (of unknown types) after the explicit args.

Example:

int32 = ir.IntType(32)
fnty = ir.FunctionType(int32, (ir.DoubleType(), ir.PointerType(int32)))

An equivalent C declaration would be:

typedef int32_t (*fnty)(double, int32_t *);

class llvmlite.ir.LabelType¶

The type for labels. You don’t need to instantiate this type.

class llvmlite.ir.MetaData¶

The type for metadata. You don’t need to instantiate this type.

Global values¶

Global values are values accessible using a module-wide name.

class llvmlite.ir.GlobalValue¶

The base class for global values. Global values have the following writable attribute:

linkage¶

A Python string describing the linkage behaviour of the global value (e.g. whether it is visible from other modules). Default is the empty string, meaning “external”.

storage_class¶

A Python string describing the storage class of the global value. Default is the empty string, meaning “default”. Other possible values include “dllimport” and “dllexport”.

class llvmlite.ir.GlobalVariable(module, typ, name, addrspace=0)¶

A global variable. module is where the variable will be defined. typ is the variable’s type. name is the variable’s name (a Python string). addrspace is an optional address space to store the variable in.

typ cannot be a function type. To declare a global function, use Function.

The returned Value’s actual type is a pointer to typ. To read (respectively write) the variable’s contents, you need to load() from (respectively store() to) the returned Value.

Global variables have the following writable attributes:

global_constant¶

If true, the variable is declared a constant, i.e. its contents cannot be ever modified. Default is False.

unnamed_addr¶

If true, the address of the variable is deemed insignificant, i.e. it will be merged with other variables which have the same initializer. Default is False.

initializer¶

The variable’s initialization value (probably a Constant of type typ). Default is None, meaning the variable is uninitialized.

class llvmlite.ir.Function(module, typ, name)¶

A global function. module is where the function will be defined. typ is the function’s type (a FunctionType instance). name is the function’s name (a Python string).

If a global function has any basic blocks, it is a function definition. Otherwise, it is a function declaration.

Functions have the following methods and attributes:

append_basic_block(name='')¶

Append a basic block to this function’s body. If name is non empty, it names the block’s entry label.

A new Block is returned.

insert_basic_block(before, name='')¶

Similar to append_basic_block(), but inserts it before the basic block before in the function’s list of basic blocks.

args¶

The function’s arguments as a tuple of Argument instances.

attributes¶

A set of function attributes. Each optional attribute is a Python string. By default this is empty. Use the add() method to add an attribute:

fnty = ir.FunctionType(ir.DoubleType(), (ir.DoubleType(),))
fn = Function(module, fnty, "sqrt")
fn.attributes.add("alwaysinline")

calling_convention¶

The function’s calling convention (a Python string). Default is the empty string.

is_declaration¶

Whether the global function is a declaration (True) or a definition (False).

Instructions¶

Every instruction is also a value: it has a name (the recipient’s name), a well-defined type, and can be used as an operand in other instructions or in literals.

Instruction types should usually not be instantiated directly. Instead, use the helper methods on the IRBuilder class.

class llvmlite.ir.Instruction¶

The base class for all instructions. Instructions have the following method and attributes:

set_metadata(name, node)¶

Add an instruction-specific metadata named name pointing to the given metadata node (a MDValue).

function¶

The function this instruction is part of.

module¶

The module this instruction’s function is defined in.

class llvmlite.ir.PredictableInstr¶

The class of instructions for which we can specificy the probabilities of different outcomes (e.g. a switch or a conditional branch). Predictable instructions have the following method:

set_weights(weights)¶

Set the weights of the instruction’s possible outcomes. weights is a sequence of positive integers, each corresponding to a different outcome and specifying its relative probability compared to other outcomes (the greater, the likelier).

class llvmlite.ir.SwitchInstr¶

A switch instruction. Switch instructions have the following method:

add_case(val, block)¶

Add a case to the switch instruction. val should be a Constant or a Python value compatible with the switch instruction’s operand type. block is a Block to jump to if, and only if, val and the switch operand compare equal.

class llvmlite.ir.IndirectBranch¶

An indirect branch instruction. Indirect branch instructions have the following method:

add_destination(value, block)¶

Add an outgoing edge. The indirect branch instruction must refer to every basic block it can transfer control to.

class llvmlite.ir.PhiInstr¶

A phi instruction. Phi instructions have the following method:

add_incoming(value, block)¶

Add an incoming edge. Whenever transfer is controlled from block (a Block), the phi instruction takes the given value.

class llvmlite.ir.LandingPad¶

A landing pad. Landing pads have the following method:

add_clause(value, block)¶

Add a catch or filter clause. Create catch clauses using CatchClause, and filter clauses using FilterClause.

Landing pad clauses¶

Landing pads have the following classes associated with them:

class llvmlite.ir.CatchClause(value)¶

A catch clause. Instructs the personality function to compare the in-flight exception typeinfo with value, which should have type IntType(8).as_pointer().as_pointer().

class llvmlite.ir.FilterClause(value)¶

A filter clause. Instructs the personality function to check inclusion of the the in-flight exception typeinfo in value, which should have type ArrayType(IntType(8).as_pointer().as_pointer(), ...).

Instantiation¶

class llvmlite.ir.IRBuilder(block=None)¶

Create a new IR builder. If block (a Block) is given, the builder starts right at the end of this basic block.

Properties¶

IRBuilder has the following attributes:

IRBuilder.block¶

The basic block the builder is operating on.

IRBuilder.function¶

The function the builder is operating on.

IRBuilder.module¶

The module the builder’s function is defined in.

IRBuilder.debug_metadata¶

If not None, the metadata that will be attached to any inserted instructions as !dbg, unless the instruction already has !dbg set.

Utilities¶

IRBuilder.append_basic_block(name='')¶

Append a basic block, with the given optional name, to the current function. The current block is not changed. A Block is returned.

Positioning¶

The following IRBuilder methods help you move the current instruction pointer around:

IRBuilder.position_before(instruction)¶

Position immediatly before the given instruction. The current block is also changed to the instruction’s basic block.

IRBuilder.position_after(instruction)¶

Position immediatly after the given instruction. The current block is also changed to the instruction’s basic block.

IRBuilder.position_at_start(block)¶

Position at the start of the basic block.

IRBuilder.position_at_end(block)¶

Position at the end of the basic block.

The following context managers allow you to temporarily switch to another basic block, then go back where you were:

IRBuilder.goto_block(block)¶

A context manager which positions the builder either at the end of the basic block, if it is not terminated, or just before the block‘s terminator:

new_block = builder.append_basic_block('foo')
with builder.goto_block(new_block):
   # Now the builder is at the end of *new_block*
   # ... add instructions

# Now the builder has returned to its previous position

IRBuilder.goto_entry_block()¶

Just like goto_block(), but with the current function’s entry block.

Flow control helpers¶

The following context managers make it easier to create conditional code.

IRBuilder.if_then(pred, likely=None)¶

A context manager which creates a basic block whose execution is conditioned on predicate pred (a value of type IntType(1)). Another basic block is created for instructions after the conditional block. The current basic block is terminated with a conditional branch based on pred.

When the context manager is entered, the builder positions at the end of the conditional block. When the context manager is exited, the builder positions at the start of the continuation block.

If likely is not None, it indicates whether pred is likely to be true, and metadata is emitted to specify branch weights in accordance.

IRBuilder.if_else(pred, likely=None)¶

A context manager which sets up two basic blocks whose execution is condition on predicate pred (a value of type IntType(1)). likely has the same meaning as in if_then().

A pair of context managers is yield’ed. Each of them acts as a if_then() context manager: the first one for the block to be executed if pred is true, the second one for the block to be executed if pred is false.

When the context manager is exited, the builder is positioned on a new continuation block which both conditional blocks jump into.

Typical use:

with builder.if_else(pred) as (then, otherwise):
    with then:
        # emit instructions for when the predicate is true
    with otherwise:
        # emit instructions for when the predicate is false
# emit instructions following the if-else block

Instruction building¶

The following methods all insert a new instruction (a Instruction instance) at the current index in the current block. The new instruction is returned.

An instruction’s operands are most always values.

Many of these methods also take an optional name argument, specifying the local name of the result value. If not given, a unique name is automatically generated.

A trivial function¶

Define a function adding two double-precision floating-point numbers.

"""
This file demonstrates a trivial function "fpadd" returning the sum of
two floating-point numbers.
"""

from llvmlite import ir

# Create some useful types
double = ir.DoubleType()
fnty = ir.FunctionType(double, (double, double))

# Create an empty module...
module = ir.Module(name=__file__)
# and declare a function named "fpadd" inside it
func = ir.Function(module, fnty, name="fpadd")

# Now implement the function
block = func.append_basic_block(name="entry")
builder = ir.IRBuilder(block)
a, b = func.args
result = builder.fadd(a, b, name="res")
builder.ret(result)

# Print the module IR
print(module)

The generated LLVM IR is printed out at the end, and should look like this:

; ModuleID = "examples/ir_fpadd.py"
target triple = "unknown-unknown-unknown"
target datalayout = ""

define double @"fpadd"(double %".1", double %".2")
{
entry:
  %"res" = fadd double %".1", %".2"
  ret double %"res"
}

To learn how to compile and execute this function, refer to the binding layer documentation.

Functions¶

llvmlite.binding.get_default_triple()¶

Return the default target triple LLVM is configured to produce code for, as a string. This represents the host’s architecture and platform.

llvmlite.binding.get_process_triple()¶

Return a target triple suitable for generating code for the current process. An example when the default triple from get_default_triple() is not be suitable is when LLVM is compiled for 32-bit but the process is executing in 64-bit mode.

llvmlite.binding.get_object_format(triple=None)¶

Get the object format for the given triple string (or the default triple if None). A string is returned such as "ELF", "COFF" or "MachO".

llvmlite.binding.get_host_cpu_name()¶

Get the name of the host’s CPU as a string. You can use the return value with Target.create_target_machine().

llvmlite.binding.get_host_cpu_features()¶

Returns a dictionary-like object indicating the CPU features for current architecture and whether they are enabled for this CPU. The key-value pairs are the feature name as string and a boolean indicating whether the feature is available. The returned value is an instance of FeatureMap class, which adds a new method .flatten() for returning a string suitable for use as the “features” argument to Target.create_target_machine().

llvmlite.binding.create_target_data(data_layout)¶

Create a TargetData representing the given data_layout (a string).

Classes¶

class llvmlite.binding.TargetData¶

A class providing functionality around a given data layout. It specifies how the different types are to be represented in memory. Use create_target_data() to instantiate.

add_pass(pm)¶

Add an optimization pass based on this data layout to the PassManager instance pm.

get_abi_size(type)¶

Get the ABI-mandated size of the LLVM type (as returned by ValueRef.type). An integer is returned.

get_pointee_abi_size(type)¶

Similar to get_abi_size(), but assumes type is a LLVM pointer type, and returns the ABI-mandated size of the type pointed to by. This is useful for global variables (whose type is really a pointer to the declared type).

get_pointee_abi_alignment(type)¶

Similar to get_pointee_abi_size(), but return the ABI-mandated alignment rather than the ABI size.

class llvmlite.binding.Target¶

A class representing a compilation target. The following factories are provided:

classmethod from_triple(triple)¶

Create a new Target instance for the given triple string denoting the target platform.

classmethod from_default_triple()¶

Create a new Target instance for the default platform LLVM is configured to produce code for. This is equivalent to calling Target.from_triple(get_default_triple())

The following methods and attributes are available:

description¶

A description of the target.

name¶

The name of the target.

triple¶

The triple (a string) uniquely identifying the target, for example "x86_64-pc-linux-gnu".

create_target_machine(cpu='', features='', opt=2, reloc='default', codemodel='jitdefault')¶

Create a new TargetMachine instance for this target and with the given options. cpu is an optional CPU name to specialize for. features is a comma-separated list of target-specific features to enable or disable. opt is the optimization level, from 0 to 3. reloc is the relocation model. codemodel is the code model. The defaults for reloc and codemodel are appropriate for JIT compilation.

Tip

To list the available CPUs and features for a target, execute llc -mcpu=help on the command line.

class llvmlite.binding.TargetMachine¶

A class holding all the settings necessary for proper code generation (including target information and compiler options). Instantiate using Target.create_target_machine().

add_analysis_passes(pm)¶

Register analysis passes for this target machine with the PassManager instance pm.

emit_object(module)¶

Represent the compiled module (a ModuleRef instance) as a code object, suitable for use with the platform’s linker. A bytestring is returned.

emit_assembly(module)¶

Return the compiled module‘s native assembler, as a string.

initialize_native_asmprinter() must have been called first.

target_data¶

The TargetData associated with this target machine.

class llvmlite.binding.FeatureMap¶

For storing processor feature information in a dictionary-like object. This class extends dict and only adds the .flatten() method.

flatten(sort=True)¶

Returns a string representation of the stored information that is suitable for use in the “features” argument of Target.create_target_machine(). If sort keyword argument is True (the default), the features are sorted by name to give a stable ordering between python session.

Factory functions¶

A module can be created from the following factory functions:

llvmlite.binding.parse_assembly(llvmir)¶

Parse the given llvmir, a string containing some LLVM IR code. If parsing is successful, a new ModuleRef instance is returned.

llvmir can be obtained, for example, by calling str() on a llvmlite.ir.Module object.

llvmlite.binding.parse_bitcode(bitcode)¶

Parse the given bitcode, a bytestring containing the LLVM bitcode of a module. If parsing is successful, a new ModuleRef instance is returned.

bitcode can be obtained, for example, by calling ModuleRef.as_bitcode().

The ModuleRef class¶

class llvmlite.binding.ModuleRef¶

A wrapper around a LLVM module object. The following methods and properties are available:

as_bitcode()¶

Return the bitcode of this module as a bytes object.

get_function(name)¶

Get the function with the given name in this module. If found, a ValueRef is returned. Otherwise, NameError is raised.

get_global_variable(name)¶

Get the global variable with the given name in this module. If found, a ValueRef is returned. Otherwise, NameError is raised.

link_in(other, preserve=False)¶

Link the other module into this module, resolving references wherever possible. If preserve is true, the other module is first copied in order to preserve its contents; if preserve is false, the other module is not usable after this call anymore.

verify()¶

Verify the module’s correctness. RuntimeError is raised on error.

data_layout¶

The data layout string for this module. This attribute is settable.

functions¶

An iterator over the functions defined in this module. Each function is a ValueRef instance.

global_variables¶

An iterator over the global variables defined in this module. Each global variable is a ValueRef instance.

name¶

The module’s identifier, as a string. This attribute is settable.

triple¶

The platform “triple” string for this module. This attribute is settable.

Enumerations¶

class llvmlite.binding.Linkage¶

The different linkage types allowed for global values. The following values are provided:

external¶

available_externally¶

linkonce_any¶

linkonce_odr¶

linkonce_odr_autohide¶

weak_any¶

weak_odr¶

appending¶

internal¶

private¶

dllimport¶

dllexport¶

external_weak¶

ghost¶

common¶

linker_private¶

linker_private_weak¶

class llvmlite.binding.Visibility¶

The different visibility styles allowed for global values. The following values are provided:

default¶

hidden¶

protected¶

class llvmlite.binding.StorageClass¶

The different storage classes allowed for global values. The following values are provided:

default¶

dllimport¶

dllexport¶

The ValueRef class¶

class llvmlite.binding.ValueRef¶

A wrapper around a LLVM value. The following properties are available:

is_declaration¶

True if the global value is a mere declaration, False if it is defined in the given module.

linkage¶

The linkage type (a Linkage instance) for this value. This attribute is settable.

module¶

The module (a ModuleRef instance) this value is defined in.

name¶

This value’s name, as a string. This attribute is settable.

type¶

This value’s LLVM type. An opaque object is returned. It can be used with e.g. TargetData.get_abi_size().

storage_class¶

The storage class (a StorageClass instance) for this value. This attribute is settable.

visibility¶

The visibility style (a Visibility instance) for this value. This attribute is settable.

Functions¶

llvmlite.binding.create_mcjit_compiler(module, target_machine)¶

Create a MCJIT-powered engine from the given module and target_machine. A ExecutionEngine instance is returned. The module need not contain any code.

llvmlite.binding.check_jit_execution()¶

Ensure the system allows creation of executable memory ranges for JIT-compiled code. If some security mechanism (such as SELinux) prevents it, an exception is raised. Otherwise the function returns silently.

Calling this function early can help diagnose system configuration issues, instead of letting JIT-compiled functions crash mysteriously.

The ExecutionEngine class¶

class llvmlite.binding.ExecutionEngine¶

A wrapper around a LLVM execution engine. The following methods and properties are available:

add_module(module)¶

Add the module (a ModuleRef instance) for code generation. When this method is called, ownership of the module is transferred to the execution engine.

finalize_object()¶

Make sure all modules owned by the execution engine are fully processed and “usable” for execution.

get_pointer_to_function(gv)¶

Warning

This function is deprecated. User should use ExecutionEngine.get_function_address() and ExecutionEngine.get_global_value_address() instead

Return the address of the function value gv, as an integer. The value should have been looked up on one of the modules owned by the execution engine.

Note

This method may implicitly generate code for the object being looked up.

Note

This function is formerly an alias to get_pointer_to_global(), which is now removed because it returns an invalid address in MCJIT when given a non-function global value.

get_function_address(name)¶

Return the address of the function named name as an integer.

get_global_value_address(name)¶

Return the address of the global value named name as an integer.

remove_module(module)¶

Remove the module (a ModuleRef instance) from the modules owned by the execution engine. This allows releasing the resources owned by the module without destroying the execution engine.

set_object_cache(notify_func=None, getbuffer_func=None)¶

Set the object cache callbacks for this engine.

notify_func, if given, is called whenever the engine has finished compiling a module. It is passed two arguments (module, buffer). The first argument module is a ModuleRef instance. The second argument buffer is a bytes object of the code generated for the module. The return value is ignored.

getbuffer_func, if given, is called before the engine starts compiling a module. It is passed one argument, module, a ModuleRef instance of the module being compiled. The function can return None, in which case the module will be compiled normally. Or it can return a bytes object of native code for the module, which will bypass compilation entirely.

target_data¶

The TargetData used by the execution engine.

Compiling a trivial function¶

Compile and execute the function defined in A trivial function. The function is compiled with no specific optimizations.

from __future__ import print_function

from ctypes import CFUNCTYPE, c_double

import llvmlite.binding as llvm


# All these initializations are required for code generation!
llvm.initialize()
llvm.initialize_native_target()
llvm.initialize_native_asmprinter()  # yes, even this one

llvm_ir = """
   ; ModuleID = "examples/ir_fpadd.py"
   target triple = "unknown-unknown-unknown"
   target datalayout = ""

   define double @"fpadd"(double %".1", double %".2")
   {
   entry:
     %"res" = fadd double %".1", %".2"
     ret double %"res"
   }
   """

def create_execution_engine():
    """
    Create an ExecutionEngine suitable for JIT code generation on
    the host CPU.  The engine is reusable for an arbitrary number of
    modules.
    """
    # Create a target machine representing the host
    target = llvm.Target.from_default_triple()
    target_machine = target.create_target_machine()
    # And an execution engine with an empty backing module
    backing_mod = llvm.parse_assembly("")
    engine = llvm.create_mcjit_compiler(backing_mod, target_machine)
    return engine


def compile_ir(engine, llvm_ir):
    """
    Compile the LLVM IR string with the given engine.
    The compiled module object is returned.
    """
    # Create a LLVM module object from the IR
    mod = llvm.parse_assembly(llvm_ir)
    mod.verify()
    # Now add the module and make sure it is ready for execution
    engine.add_module(mod)
    engine.finalize_object()
    return mod


engine = create_execution_engine()
mod = compile_ir(engine, llvm_ir)

# Look up the function pointer (a Python int)
func_ptr = engine.get_function_address("fpadd")

# Run the function via ctypes
cfunc = CFUNCTYPE(c_double, c_double, c_double)(func_ptr)
res = cfunc(1.0, 3.5)
print("fpadd(...) =", res)