.. _ir-values:
======
Values
======
.. currentmodule:: llvmlite.ir
.. contents::
:local:
:depth: 1
A :ref:`module` consists mostly of values.
.. data:: Undefined
An undefined value, mapping to LLVM's ``undef``.
.. class:: Value
The base class for all IR values.
.. class:: _ConstOpMixin
This is the base class for :class:`Constant` and :class:`GlobalValue`; do
not instantiate it directly.
Integer arithmetic operations:
* .. method:: add(other)
Integer add `self` and `other`.
* .. method:: sub(other)
Integer subtract `other` from `self`.
* .. method:: mul(other)
Integer multiply `self` with `other`.
* .. method:: udiv(other)
Unsigned integer divide `self` by `other`.
* .. method:: sdiv(other)a
Signed integer divide `self` by `other`.
* .. method:: urem(other)
Unsigned integer remainder of `self` divided by `other`.
* .. method:: srem(other)
Signed integer remainder of `self` divided by `other`.
* .. method:: neg()
Negate `self`.
Integer logical operations:
* .. method:: shl(other)
Left-shift `self` by `other` bits.
* .. method:: ashr(other)
Arithmetic, signed, right-shift `self` by `other` bits.
* .. method:: lshr(other)
Logical right-shift `self` by `other` bits.
* .. method:: or_(other)
Bitwise OR `self` with `other`.
* .. method:: and_(other)
Bitwise AND `self` with `other`.
* .. method:: xor(other)
Bitwise XOR `self` with `other`.
Floating point arithmetic:
* .. method:: fadd(other)
Floating-point add `self` and `other`.
* .. method:: fsub(other)
Floating-point subtract `other` from `self`.
* .. method:: fmul(other)
Floating-point multiply `self` by `other`.
* .. method:: fdiv(other)
Floating-point divide `self` by `other`.
* .. method:: frem(other)
Floating-point remainder of `self` divided by `other`.
Comparisons:
* .. method:: icmp_signed(cmpop, other)
Signed integer compare `self` with `other`. The string `cmpop` can be one
of ``<``, ``<=``, ``==``, ``!=``, ``>=`` or ``>``.
* .. method:: icmp_unsigned(cmpop, other)
Unsigned integer compare `self` with `other`. The string `cmpop` can be
one of ``<``, ``<=``, ``==``, ``!=``, ``>=`` or ``>``.
* .. method:: fcmp_ordered(cmpop, other)
Floating-point ordered compare `self` with `other`. The string `cmpop`
can be one of ``<``, ``<=``, ``==``, ``!=``, ``>=`` or ``>``.
* .. method:: fcmp_unordered(cmpop, other)
Floating-point unordered compare `self` with `other`. The string `cmpop`
can be one of ``<``, ``<=``, ``==``, ``!=``, ``>=`` or ``>``.
Integer casts:
* .. method:: trunc(typ)
Truncate `self` to integer type `typ`.
* .. method:: zext(typ)
Zero-extend `self` to integer type `typ`.
* .. method:: sext(typ)
Sign-extend `self` to integer type `typ`.
* .. method:: bitcast(typ)
Convert this pointer constant to a constant of the given pointer type
`typ`.
Floating-point casts:
* .. method:: fptrunc(typ)
Truncate (approximate) floating-point value `self` to floating-point
type `typ`.
* .. method:: fpext(typ)
Extend floating-point value `self` to floating-point type `typ`.
Integer / floating-point conversion:
* .. method:: fptoui(typ)
Convert floating-point value `self` to unsigned integer type `typ`.
* .. method:: uitofp(typ)
Convert unsigned integer value `self` to floating-point type `typ`.
* .. method:: fptosi(typ)
Convert floating-point value `self` to signed integer type `typ`.
* .. method:: sitofp(typ)
Convert signed integer value `self` to floating-point type `typ`.
Integer / pointer conversions:
* .. method:: inttoptr(typ)
Convert this integer constant `self` to a constant of the given pointer
type `typ`.
* .. method:: ptrtoint(typ)
Convert this pointer constant `self` to a constant of the given integer
type `typ`.
.. class:: Constant(typ, constant)
A literal value.
* *typ* is the type of the represented value---a
:class:`~llvmlite.ir.Type` instance.
* *constant* is the Python value to be represented.
Which Python types are allowed for *constant* depends on *typ*:
* All types accept :data:`Undefined` and convert it to
LLVM's ``undef``.
* All types accept ``None`` and convert it to LLVM's
``zeroinitializer``.
* :class:`IntType` accepts any Python integer or boolean.
* :class:`FloatType` and :class:`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.
* :class:`ArrayType` accepts a single :class:`bytearray`
instance to initialize the array from a string of bytes.
This is useful for character constants.
See also :class:`_ConstOpMixin`.
.. classmethod:: literal_array(elements)
An alternate constructor for constant arrays.
* *elements* is a sequence of values, :class:`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, :class:`Constant` or
otherwise.
* *packed* controls whether to use packed layout.
* Returns a constant struct containing the
*elements* in order.
.. method:: 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
:ref:`function declaration` instead.
.. class:: Argument
One of a function's arguments. Arguments have the
:meth:`add_attribute` method.
.. method:: add_attribute(attr)
Add an argument attribute to this argument. *attr* is a
Python string.
.. class:: Block
A :ref:`basic block`. Do not instantiate or mutate this type
directly. Instead, call the helper methods on
:class:`Function` and :class:`IRBuilder`.
Basic blocks have the following methods and attributes:
* .. method:: 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 :class:`Instruction` objects.
* .. attribute:: function
The function this block is defined in.
* .. attribute:: is_terminated
Whether this block ends with a
:ref:`terminator instruction <terminator>`.
* .. attribute:: terminator
The block's :ref:`terminator instruction <terminator>`, if any.
Otherwise ``None``.
.. class:: BlockAddress
A constant representing an address of a basic block.
Block address constants have the following attributes:
* .. attribute:: function
The function in which the basic block is defined.
* .. attribute:: basic_block
The basic block. Must be a part of :attr:`function`.
Metadata
========
There are several kinds of :ref:`metadata` values.
.. class:: 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:: MDValue
A metadata node. To create an instance, call
:meth:`Module.add_metadata`.
.. class:: DIValue
A debug information descriptor, containing key-value pairs.
To create an instance, call :meth:`Module.add_debug_info`.
.. class:: DIToken(value)
A debug information "token," representing a well-known
enumeration value. *value* is the enumeration name.
EXAMPLE: ``'DW_LANG_Python'``
.. class:: NamedMetaData
A named metadata node. To create an instance, call
:meth:`Module.add_named_metadata`. :class:`NamedMetaData` has
the :meth:`add` method:
.. method:: add(md)
Append the given piece of metadata to the collection of
operands referred to by the :class:`NamedMetaData`. *md* can
be either a :class:`MetaDataString` or a :class:`MDValue`.
Global values
==============
Global values are values accessible using a module-wide name.
.. class:: GlobalValue
The base class for global values. Global values have the
following writable attributes:
* .. attribute:: 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."
* .. attribute:: 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``.
* .. attribute:: 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 :class:`_ConstOpMixin`.
.. class:: 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 :class:`Function`.
The type of the returned Value is a pointer to *typ*.
To read the contents of the variable, you need to
:meth:`~IRBuilder.load` from the returned Value.
To write to the variable, you need to
:meth:`~IRBuilder.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:
* .. method:: set_metadata(name, node)
Add metadata with the given *name*, pointing to the given
metadata *node*---an instance of :class:`MDValue`.
* .. attribute:: global_constant
* If ``True``, the variable is declared a constant,
meaning that its contents cannot be modified.
* The default is ``False``.
* .. attribute:: 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``.
* .. attribute:: initializer
The variable's initialization value---probably a
:class:`Constant` of type *typ*. The default is ``None``,
meaning that the variable is uninitialized.
* .. attribute:: align
An explicit alignment in bytes. The default is ``None``,
meaning that the default alignment for the variable's
type is used.
.. class:: Function(module, typ, name)
A global function.
* *module* is where the function is defined.
* *typ* is the function's type---a :class:`FunctionType`
instance.
* *name* is the function's name---a Python string.
If a global function has any basic blocks, it is a
:ref:`function definition`. Otherwise, it is a
:ref:`function declaration`.
Functions have the following methods and attributes:
* .. method:: append_basic_block(name='')
Append a :ref:`basic block` to this function's body.
* If *name* is not empty, it names the block's entry
:ref:`label`.
* Returns a new :class:`Block`.
* .. method:: insert_basic_block(before, name='')
Similar to :meth:`append_basic_block`, but inserts it
before the basic block *before* in the function's list
of basic blocks.
* .. method:: set_metadata(name, node)
Add a function-specific metadata named *name* pointing to the
given metadata *node*---an :class:`MDValue`.
* .. attribute:: args
The function's arguments as a tuple of :class:`Argument`
instances.
* .. attribute:: 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")
* .. attribute:: calling_convention
The function's calling convention---a Python string. The
default is the empty string.
* .. attribute:: 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 :ref:`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 :class:`IRBuilder` class.
.. class:: Instruction
The base class for all instructions. Instructions have the
following method and attributes:
* .. method:: set_metadata(name, node)
Add an instruction-specific metadata *name* pointing to the
given metadata *node*---an :class:`MDValue`.
* .. method:: replace_usage(old, new)
Replace the operand *old* with the other instruction *new*.
* .. attribute:: function
The function that contains this instruction.
* .. attribute:: module
The module that defines this instruction's function.
.. class:: 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
:meth:`set_weights` method.
.. 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:: SwitchInstr
A switch instruction. Switch instructions have the
:meth:`add_case` method.
.. method:: add_case(val, block)
Add a case to the switch instruction.
* *val* should be a :class:`Constant` or a Python value
compatible with the switch instruction's operand type.
* *block* is a :class:`Block` to jump to if val and the
switch operand compare equal.
.. class:: IndirectBranch
An indirect branch instruction. Indirect branch instructions
have the :meth:`add_destination` method.
.. 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:: PhiInstr
A phi instruction. Phi instructions have the
:meth:`add_incoming` method.
.. method:: add_incoming(value, block)
Add an incoming edge. Whenever transfer is controlled
from *block*---a :class:`Block`---the phi instruction
takes the given *value*.
.. class:: LandingPad
A landing pad. Landing pads have the :meth:`add_clause` method:
.. method:: add_clause(value, block)
Add a catch or filter clause. Create catch clauses using
:class:`CatchClause` and filter clauses using
:class:`FilterClause`.
Landing pad clauses
====================
Landing pads have the following classes associated with them.
.. class:: 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:: 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(), ...)`.
