.. _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 `. * .. attribute:: terminator The block's :ref:`terminator instruction `, 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(), ...)`.