Values

A Module consists mostly of values.

llvmlite.ir.Undefined

An undefined value, mapping to LLVM’s undef.

class llvmlite.ir.Value

The base class for all IR values.

class llvmlite.ir._ConstOpMixin

This is the base class for Constant and GlobalValue; do not instantiate it directly.

Integer arithmetic operations:

• add(other)

  Integer add self and other.

• sub(other)

  Integer subtract other from self.

• mul(other)

  Integer multiply self with other.

• udiv(other)

  Unsigned integer divide self by other.

• sdiv(other)a

  Signed integer divide self by other.

• urem(other)

  Unsigned integer remainder of self divided by other.

• srem(other)

  Signed integer remainder of self divided by other.

• neg()

  Negate self.

Integer logical operations:

• shl(other)

  Left-shift self by other bits.

• ashr(other)

  Arithmetic, signed, right-shift self by other bits.

• lshr(other)

  Logical right-shift self by other bits.

• or_(other)

  Bitwise OR self with other.

• and_(other)

  Bitwise AND self with other.

• xor(other)

  Bitwise XOR self with other.

Floating point arithmetic:

• fadd(other)

  Floating-point add self and other.

• fsub(other)

  Floating-point subtract other from self.

• fmul(other)

  Floating-point multiply self by other.

• fdiv(other)

  Floating-point divide self by other.

• frem(other)

  Floating-point remainder of self divided by other.

Comparisons:

• icmp_signed(cmpop, other)

  Signed integer compare self with other. The string cmpop can be one of <, <=, ==, !=, >= or >.

• icmp_unsigned(cmpop, other)

  Unsigned integer compare self with other. The string cmpop can be one of <, <=, ==, !=, >= or >.

• fcmp_ordered(cmpop, other)

  Floating-point ordered compare self with other. The string cmpop can be one of <, <=, ==, !=, >= or >.

• fcmp_unordered(cmpop, other)

  Floating-point unordered compare self with other. The string cmpop can be one of <, <=, ==, !=, >= or >.

Integer casts:

• trunc(typ)

  Truncate self to integer type typ.

• zext(typ)

  Zero-extend self to integer type typ.

• sext(typ)

  Sign-extend self to integer type typ.

• bitcast(typ)

  Convert this pointer constant to a constant of the given pointer type typ.

Floating-point casts:

• fptrunc(typ)

  Truncate (approximate) floating-point value self to floating-point type typ.

• fpext(typ)

  Extend floating-point value self to floating-point type typ.

Integer / floating-point conversion:

• fptoui(typ)

  Convert floating-point value self to unsigned integer type typ.

• uitofp(typ)

  Convert unsigned integer value self to floating-point type typ.

• fptosi(typ)

  Convert floating-point value self to signed integer type typ.

• sitofp(typ)

  Convert signed integer value self to floating-point type typ.

Integer / pointer conversions:

• inttoptr(typ)

  Convert this integer constant self to a constant of the given pointer type typ.

• ptrtoint(typ)

  Convert this pointer constant self to a constant of the given integer type typ.

class llvmlite.ir.Constant(typ, constant)

A literal value.

• typ is the type of the represented value—a Type instance.

• constant is the Python value to be represented.

Which Python types are allowed for constant depends on typ:

• All types accept Undefined and convert it to LLVM’s undef.

• All types accept None and convert it to LLVM’s zeroinitializer.

• IntType accepts any Python integer or boolean.

• FloatType and DoubleType accept any Python real number.

• Aggregate types—array and structure types—accept a sequence of Python values corresponding to the type’s element types.

• ArrayType accepts a single bytearray instance to initialize the array from a string of bytes. This is useful for character constants.

See also _ConstOpMixin.

classmethod literal_array(elements)

An alternate constructor for constant arrays.

• elements is a sequence of values, Constant or otherwise.

• All elements must have the same type.

• Returns a constant array containing the elements, in order.

classmethod literal_struct(elements, packed=False)

An alternate constructor for constant structs.

• elements is a sequence of values, Constant or otherwise.

• packed controls whether to use packed layout.

• Returns a constant struct containing the elements in order.

gep(indices)

Compute the address of the inner element given by the sequence of indices. The constant must have a pointer type.

NOTE: You cannot define constant functions. Use a Function declaration instead.

class llvmlite.ir.Argument

One of a function’s arguments. Arguments have the add_attribute() method.

add_attribute(attr)

Add an argument attribute to this argument. attr is a Python string.

class llvmlite.ir.Block

A Basic block. Do not instantiate or mutate this type directly. Instead, call the helper methods on Function and IRBuilder.

Basic blocks have the following methods and attributes:

• replace(old, new)

  Replace the instruction old with the other instruction new in this block’s list of instructions. All uses of old in the whole function are also patched. old and new are Instruction objects.

• function

  The function this block is defined in.

• is_terminated

  Whether this block ends with a terminator instruction.

• terminator

  The block’s terminator instruction, if any. Otherwise None.

class llvmlite.ir.BlockAddress

A constant representing an address of a basic block.

Block address constants have the following attributes:

• function

  The function in which the basic block is defined.

• basic_block

  The basic block. Must be a part of function.

Metadata

There are several kinds of Metadata values.

class llvmlite.ir.MetaDataString(module, value)

A string literal for use in metadata.

• module is the module that the metadata belongs to.

• value is a Python string.

class llvmlite.ir.MDValue

A metadata node. To create an instance, call Module.add_metadata().

class llvmlite.ir.DIValue

A debug information descriptor, containing key-value pairs. To create an instance, call Module.add_debug_info().

class llvmlite.ir.DIToken(value)

A debug information “token,” representing a well-known enumeration value. value is the enumeration name.

EXAMPLE: 'DW_LANG_Python'

class llvmlite.ir.NamedMetaData

A named metadata node. To create an instance, call Module.add_named_metadata(). NamedMetaData has the add() method:

add(md)

Append the given piece of metadata to the collection of operands referred to by the NamedMetaData. md can be either a MetaDataString or a MDValue.

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 attributes:

• linkage

  A Python string describing the linkage behavior of the global value—for example, whether it is visible from other modules. The default is the empty string, meaning “external.”

• storage_class

  A Python string describing the storage class of the global value.

  • The default is the empty string, meaning “default.”

  • Other possible values include dllimport and dllexport.

• section

  A Python string describing the section a global value should be in after translation. The default is the empty string, meaning no specific section.

See also _ConstOpMixin.

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

A global variable.

• module is where the variable is defined.

• typ is the variable’s type. It cannot be a function type. To declare a global function, use Function.

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

• name is the variable’s name—a Python string.

• addrspace is an optional address space to store the variable in.

Global variables have the following writable attributes:

• set_metadata(name, node)

  Add metadata with the given name, pointing to the given metadata node—an instance of MDValue.

• global_constant

  • If True, the variable is declared a constant, meaning that its contents cannot be modified.

  • The default is False.

• unnamed_addr

  • If True, the address of the variable is deemed insignificant, meaning that it is merged with other variables that have the same initializer.

  • The default is False.

• initializer

  The variable’s initialization value—probably a Constant of type typ. The default is None, meaning that the variable is uninitialized.

• align

  An explicit alignment in bytes. The default is None, meaning that the default alignment for the variable’s type is used.

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

A global function.

• module is where the function is 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 not empty, it names the block’s entry Label.

  • Returns a new Block.

• 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.

• set_metadata(name, node)

  Add a function-specific metadata named name pointing to the given metadata node—an MDValue.

• 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. The default is the empty string.

• is_declaration

  Indicates whether the global function is a declaration or a definition.

  • If True, it is a declaration.

  • If False, it is a definition.

Instructions

Every Instruction is also a value:

• It has a name—the recipient’s name.

• It has a well-defined type.

• It can be used as an operand in other instructions or in literals.

Usually, you should not instantiate instruction types directly. 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 name pointing to the given metadata node—an MDValue.

• replace_usage(old, new)

  Replace the operand old with the other instruction new.

• function

  The function that contains this instruction.

• module

  The module that defines this instruction’s function.

class llvmlite.ir.PredictableInstr

The class of instructions for which we can specify the probabilities of different outcomes—for example, a switch or a conditional branch. Predictable instructions have the set_weights() 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 number, the likelier the outcome.

class llvmlite.ir.SwitchInstr

A switch instruction. Switch instructions have the add_case() 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 val and the switch operand compare equal.

class llvmlite.ir.IndirectBranch

An indirect branch instruction. Indirect branch instructions have the add_destination() 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 add_incoming() 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 add_clause() 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(), …).