llvm2py.ir.instruction module

Terminator instructions

Every basic block in a program ends with a “Terminator” instruction, which indicates which block should be executed after the current block is finished.

class Ret(value: Value | None = None)

Ret instruction.

The ‘ret’ instruction is used to return control flow (and optionally a value) from a function back to the caller.

There are two forms of the ‘ret’ instruction: one that returns a value and then causes control flow, and one that just causes control flow to occur.

Parameters:

value (Value | None) – A return value.

Conversation:

ret <type> <value>       ; Return a value from a non-void function
Ret(
    Value(value, type),
)

ret void                 ; Return from void function
Ret(None)
class Br(cond: Value | None, label_false: Value, label_true: Value | None)

Branch instruction.

The ‘br’ instruction is used to cause control flow to transfer to a different basic block in the current function. There are two forms of this instruction, corresponding to a conditional branch and an unconditional branch.

Parameters:

  • cond (Value) – A condition.

  • label_false (Value) – If cond is False, control flows to the label_false.

  • label_true (Value | None) – If cond is True, control flows to the label_true.

Conversation:

br i1 <cond>, label <iftrue>, label <iffalse>
Br(
    Value(cond, IntegerType(1)),
    Value(iffalse, LabelType()),
    Value(iftrue, LabelType()),
)

br label <dest>          ; Unconditional branch
Br(
    None,
    Value(dest, LabelType()),
    None
)
class Switch(cond: Value, label_default: Value, cases: list[tuple[Value, Value]])

Switch instruction.

The ‘switch’ instruction is used to transfer control flow to one of several different places. It is a generalization of the ‘br’ instruction, allowing a branch to occur to one of many possible destinations.

Parameters:

  • cond (Value) – A comparison value.

  • label_default (Value) – A default destination label.

  • cases (list[tuple[Value, Value]]) – A list of pairs of comparison values and labels.

Conversation:

switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
Switch(
    Value(value, intty),
    Value(defaultdest, LabelType()),
    [
        (Value(val, intty), Value(dest, LabelType())),
        ...
    ]
)
class IndirectBr(addr: Value, possible_dests: list[Value])

Indirect branch instruction.

The ‘indirectbr’ instruction implements an indirect branch to a label within the current function, whose address is specified by “address”. Address must be derived from a blockaddress constant.

Parameters:

  • addr (Value) – The address of the label to jump to.

  • possible_dests (list[Value]) – A list, indicating the full set of possible destinations that the address may point to.

Conversation:

indirectbr ptr <address>, [ label <dest1>, label <dest2>, ... ]
IndirectBr(
    Value(address, PtrType(...)),
    [
        Value(dest1, LabelType()),
        Value(dest2, LabelType()),
        ...
    ]
)
class Invoke(result: Value, callee: Value, args: list[Value], label_ok: Value, label_err: Value, calling_conv: CallingConv, call_attrs: list[dict[str, tuple | tuple[Any] | tuple[Any, Any]]])

Invoke instruction.

The ‘invoke’ instruction causes control to transfer to a specified function, with the possibility of control flow transfer to either the ‘normal’ label or the ‘exception’ label. If the callee function returns with the “ret” instruction, control flow will return to the “normal” label. If the callee (or any indirect callees) returns via the “resume” instruction or other exception handling mechanism, control is interrupted and continued at the dynamically nearest “exception” label.

The ‘exception’ label is a landing pad for the exception. As such, ‘exception’ label is required to have the “landingpad” instruction, which contains the information about the behavior of the program after unwinding happens, as its first non-PHI instruction. The restrictions on the “landingpad” instruction’s tightly couples it to the “invoke” instruction, so that the important information contained within the “landingpad” instruction can’t be lost through normal code motion.

Parameters:

  • result (Value) – A returned value.

  • callee (Value) – The function to be invoked, pointer or function name.

  • args (list[Value]) – An argument list.

  • label_ok (Value) – The label reached when the called function executes a ‘ret’ instruction.

  • label_err (Value) – The label reached when a callee returns via the resume instruction or other exception handling mechanism.

  • calling_conv (CallingConv) – The calling convention that should be used in a call.

  • call_attrs (list[Attrs]) – A list containing all call-related attributes.

Conversation:

<result> = invoke [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
      [operand bundles] to label <normal label> unwind label <exception label>
Invoke(
    Value(result, Type),
    Value(fnptrval, FunctionType | Type),
    [
        Value(arg0, Type),
        Value(arg1, Type),
        ...
    ],
    Value(label_ok, LabelType()),
    Value(label_err, LabelType()),
    cconv,
    [call_attrs]
)
class CallBr(result: Value, callee: Value, args: list[Value], fallthrough_label: Value, indirect_labels: list[Value], calling_conv: CallingConv, call_attrs: list[dict[str, tuple | tuple[Any] | tuple[Any, Any]]])

CallBr instruction.

The ‘callbr’ instruction causes control to transfer to a specified function, with the possibility of control flow transfer to either the ‘fallthrough’ label or one of the ‘indirect’ labels.

This instruction should only be used to implement the “goto” feature of gcc style inline assembly. Any other usage is an error in the IR verifier.

Note that in order to support outputs along indirect edges, LLVM may need to split critical edges, which may require synthesizing a replacement block for the indirect labels. Therefore, the address of a label as seen by another callbr instruction, or for a blockaddress constant, may not be equal to the address provided for the same block to this instruction’s indirect labels operand. The assembly code may only transfer control to addresses provided via this instruction’s indirect labels.

Parameters:

  • result (Value) – A return value.

  • callee (Value) – The function to be invoked, inline asm or pointer.

  • args (list[Value]) – An argument list.

  • fallthrough_label (Value) – The label reached when the inline assembly’s execution exits the bottom.

  • indirect_labels (list[Value]) – The labels reached when a callee transfers control to a location other than the ‘fallthrough label’. The label constraints refer to these destinations.

  • calling_conv (CallingConv) – The calling convention that should be used in a call.

  • call_attrs (list[Attrs]) – A list containing all call-related attributes.

Conversation:

<result> = callbr [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
      [operand bundles] to label <fallthrough label> [indirect labels]
CallBr(
    Value(result, Type),
    Value(fnptrval, FunctionType | Type),
    [
        Value(arg0, Type),
        Value(arg1, Type),
        ...
    ],
    Value(fallthrough label, LabelType()),
    [
        Value(label0, LabelType()),
        Value(label1, LabelType()),
        ...
    ]
    cconv,
    [call_attrs],
    attrs
)

Note

addrspace can be retrieved from a function global object

class Resume(val: Value)

Resume instruction.

The ‘resume’ instruction is a terminator instruction that has no successors.

Parameters:

val (Value) – An exception whose propagation to resume.

Conversation:

resume <type> <value>
Resume(
    Value(value, type),
)
class CatchSwitch(result: Value, parent: Value, handler_labels: list[Value], label_default: Value | None = None)

CatchSwitch instruction.

The ‘catchswitch’ instruction is used by LLVM’s exception handling system to describe the set of possible catch handlers that may be executed by the EH personality routine.

Parameters:

  • result (Value) – A result value.

  • parent (Value) – The token of the funclet that contains the catchswitch instruction. If the catchswitch is not inside a funclet, this operand may be the token none.

  • handler_labels (list[Value]) – A list of successor blocks that each begin with a catchpad instruction.

  • label_default (Value | None) – The label of another basic block beginning with either a cleanuppad or catchswitch instruction.

Conversation:

<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller
CatchSwitch(
    Value(resultval, TokenType()),
    Value(parent, Type),
    [
        Value(handler1, LabelType()),
        Value(handler2, LabelType()),
        ...
    ]
)

<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default>
CatchSwitch(
    Value(resultval, Type),
    Value(parent, Type),
    [
        Value(handler1, LabelType()),
        Value(handler2, LabelType()),
        ...
    ]
    Value(default, LabelType())
)
class CatchRet(catch: Value, succ_label: Value)

CatchRet instruction.

The ‘catchret’ instruction is a terminator instruction that has a single successor.

Parameters:

  • catch (Value) – A token indicating which catchpad it exits.

  • succ_label (Value) – A label to which control will be transferred.

Conversation:

catchret from <token> to label <normal>
CatchRet(
    Value(token, TokenType()),
    Value(normal, LabelType())
)
class CleanupRet(cleanup: Value, succ_label: Value | None = None)

CleanupRet instruction.

The ‘cleanupret’ instruction is a terminator instruction that has an optional successor.

Parameters:

  • cleanup (Value) – A token indicating which cleanuppad it exits, must be a cleanuppad.

  • succ_label (Value | None) – A successor, the label of another basic block beginning with either a cleanuppad or catchswitch instruction.

Conversation:

cleanupret from <value> unwind label <continue>
CleanupRet(
    Value(value, TokenType()),
    Value(continue, LabelType())
)

cleanupret from <value> unwind to caller
CleanupRet(
    Value(value, TokenType())
)
class Unreacheble

Unreacheble instruction.

The ‘unreachable’ instruction has no defined semantics. This instruction is used to inform the optimizer that a particular portion of the code is not reachable. This can be used to indicate that the code after a no-return function cannot be reached, and other facts.

Conversation:

unreachable
Unreacheble()

Unary operations

class UnaryOp(opcode: str, result: Value, operand: Value, fast_math_flags: frozenset[str] = frozenset({}))

Unary operations.

Unary operators require a single operand, execute an operation on it, and produce a single value. The operand might represent multiple data, as is the case with the vector data type. The result value has the same type as its operand.

This class generalizes all unary operations

Parameters:

  • opcode (str) – An instuction opcode, one of {‘fneg’}.

  • result (Value) – The produced value.

  • operand (Value) – An operand.

  • fast_math_flags (frozenset[str]) – The set of fast math flags.

Conversation:

<result> = fneg [fast-math flags]* <ty> <op1>   ; yields ty:result
UnaryOp(
    'fneg'
    Value(result, ty),
    Value(op1, ty),
    {*fast-math flags}
)

Binary operations

class BinOp(opcode: str, result: Value, fst_operand: Value, snd_operand: Value, fast_math_flags: frozenset[str] = frozenset({}), is_nuw: bool = False, is_nsw: bool = False, is_exact: bool = False, is_disjoint: bool = False)

BinOp instruction.

Binary operators are used to do most of the computation in a program. They require two operands of the same type, execute an operation on them, and produce a single value. The operands might represent multiple data, as is the case with the vector data type. The result value has the same type as its operands.

This class generalizes all binary operations.

Parameters:

  • opcode (str) – An instuction opcode, one of { ‘add’, ‘fadd’, ‘sub’, ‘fsub’, ‘mul’, ‘fmul’, ‘udiv’, ‘sdiv’, ‘fdiv’, ‘urem’, ‘srem’, ‘frem’, ‘shl’, ‘lshr’, ‘ashr’, ‘and’, ‘or’, ‘xor’ }.

  • result (Value) – The produced value.

  • fst_operand (Value) – The first operand.

  • snd_operand (Value) – The second operand.

  • fast_math_flags (frozenset[str]) – The set of fast math flags.

  • is_nuw (bool) – If True, the instruction has a “nuw” flag.

  • is_nsw (bool) – If True, the instruction has a “nsw” flag.

  • is_exact (bool) – If True, the instruction has a “exact” flag.

  • is_disjoint (bool) – If True, the instruction has a “disjoint” flag.

Conversation:

<result> = <opcode> [fast-math flags]* [nuw] [nsw] [exact] [disjoint] <ty> <op1>, <op2>  ; yields ty:result
BinOp(
    opcode
    Value(result, ty),
    Value(op1, ty),
    Value(op2, ty),
    attrs
)

Vector operations

Instructions representing vector operations in a target-independent manner.

class ExtractElement(result: Value, vector: Value, index: Value)

ExtractElement instruction.

The ‘extractelement’ instruction extracts a single scalar element from a vector at a specified index.

Parameters:

  • result (Value) – A scalar of the same type as the element type of vector.

  • vector (Value) – A value of vector type.

  • index (Value) – An index indicating the position from which to extract the element.

Conversation:

<result> = extractelement <n x <ty>> <val>, <ty2> <idx>  ; yields <ty>
ExtractElement(
    Value(result, ty),
    Value(val, VectorType(n, ty)),
    Value(idx, ty2),
)

<result> = extractelement <vscale x n x <ty>> <val>, <ty2> <idx> ; yields <ty>
ExtractElement(
    Value(result, ty)),
    Value(val, VectorType(n, ty, True)),
    Value(idx, ty2),
)
class InsertElement(result: Value, vector: Value, elem: Value, index: Value)

InsertElement instruction.

The ‘insertelement’ instruction inserts a scalar element into a vector at a specified index.

Parameters:

  • result (Value) – A vector of the same type as val.

  • vector (Value) – A value of vector type.

  • elem (Value) – A scalar value whose type must equal the element type of the first operand.

  • index (Value) – An index indicating the position at which to insert the value.

Conversation:

<result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx>    ; yields <n x <ty>>
InsertElement(
    Value(result, VectorType(n, ty)),
    Value(val, VectorType(n, ty)),
    Value(elt, ty),
    Value(idx, ty2),
)

<result> = insertelement <vscale x n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <vscale x n x <ty>>
InsertElement(
    Value(result, VectorType(n, ty, True)),
    Value(val, VectorType(n, ty, True)),
    Value(elt, ty),
    Value(idx, ty2),
)
class ShuffleVector(result: Value, fst_vector: Value, snd_vector: Value, mask_vector: list[int])

ShuffleVector instruction.

The ‘shufflevector’ instruction constructs a permutation of elements from two input vectors, returning a vector with the same element type as the input and length that is the same as the shuffle mask.

Parameters:

  • result (Value) – A vector whose length is the same as the shuffle mask and whose element type is the same as the element type of the first two operands.

  • fst_vector (Value) – A value of vector type.

  • snd_vector (Value) – A value of vector type with the same type as fst_vector.

  • mask_vector (list[int]) – A shuffle mask vector constant whose element type is i32, if the value of the mask_vector element is -1, the result element must have the poison or undef value. A “zeroinitializer” represented as an array of zeros.

Conversation:

<result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask>    ; yields <m x <ty>>
ShuffleVector(
    Value(result, VectorType(m, ty)),
    Value(v1, VectorType(n, ty)),
    Value(v2, VectorType(n, ty)),
    [mask_0, ..., mask_(m-1)],
)

<result> = shufflevector <vscale x n x <ty>> <v1>, <vscale x n x <ty>> v2, <vscale x m x i32> <mask>  ; yields <vscale x m x <ty>>
ShuffleVector(
    Value(result, VectorType(m, ty, True)),
    Value(v1, VectorType(n, ty, True)),
    Value(v2, VectorType(n, ty, True)),
    [mask_0, ..., mask_(m-1)],
)

Aggregate operations

Instructions for working with aggregate values.

class ExtractValue(result: Value, aggregate: Value, indices: list[int])

ExtractValue instruction.

The ‘extractvalue’ instruction extracts the value of a member field from an aggregate value.

Parameters:

  • result (Value) – The value at the position in the aggregate specified by the index operands.

  • aggregate (Value) – A value of struct or array type.

  • indices (list[int]) – A list of constant indices to specify which value to extract in a similar manner as indices in a ‘getelementptr’ instruction.

Conversation:

<result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
ExtractValue(
    Value(result, Type),
    Value(val, aggregate type),
    [idx0, idx1, ...],
)
class InsertValue(result: Value, aggregate: Value, elem: Value, indices: list[int])

InsertValue instruction.

The ‘insertvalue’ instruction inserts a value into a member field in an aggregate value.

Parameters:

  • result (Value) – A value of the same type as aggregate. Its value is that of aggregate except that the value at the position specified by the indices is that of elem.

  • aggregate (Value) – A value of struct or array type.

  • elem (Value) – A value to insert.

  • indices (list[int]) – A list of constant indices indicating the position at which to insert the value in a similar manner as indices in a ‘extractvalue’ instruction.

Conversation:

<result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}*    ; yields <aggregate type>
InsertValue(
    Value(result, aggregate type),
    Value(val, aggregate type),
    Value(elt, ty)
    [idx0, idx1, ...],
)

Memory access and addressing operations

A key design point of an SSA-based representation is how it represents memory. In LLVM IR, no memory locations are in SSA form, which makes things very simple. This section describes how to read, write, and allocate memory in LLVM IR.

class Alloca(result: Value, allocated_ty: VoidType | FunctionType | IntegerType | FPType | X86_amxType | PtrType | TargetExtensionType | VectorType | LabelType | TokenType | MetadataType | ArrayType | StructureType | OpaqueType, num_elements: Value, align: int = 0, is_inalloca: bool = False)

Alloca instruction.

The ‘alloca’ instruction allocates memory on the stack frame of the currently executing function, to be automatically released when this function returns to its caller.

Parameters:

  • result (Value) – A pointer to uninitialized allocated memory.

  • allocated_ty (Type) – The type to allocate.

  • num_elements (Value) – The number of elements to allocate.

  • align (int) – If specified, the value result of the allocation is guaranteed to be aligned to at least that boundary.

  • is_inalloca (bool) – If True, the instruction has a “inalloca” flag.

Conversation:

<result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] [, addrspace(<num>)]     ; yields type addrspace(num)*:result
Alloca(
    Value(result, PtrType(num)),
    type
    Value(NumElements, ty),
    alignment,
    inalloca?
)
class Load(result: Value, address: Value, align: int = 0, is_volatile: bool = False, is_atomic: bool = False, ordering: Ordering = Ordering.NotAtomic, syncscope: int | None = None)

Load instruction.

The ‘load’ instruction is used to read from memory.

Parameters:

Conversation:

<result> = load [volatile] <ty>, ptr <pointer>[, align <alignment>]
Load(
    Value(result, ty),
    Value(pointer, ptr),
    alignment,
    volatile?
)

<result> = load atomic [volatile] <ty>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment>
Load(
    Value(result, ty),
    Value(pointer, ptr),
    alignment,
    volatile?
    True
    ordering
    target-scope
)
class Store(value: Value, address: Value, align: int = 0, is_volatile: bool = False, is_atomic: bool = False, ordering: Ordering = Ordering.NotAtomic, syncscope: int | None = None)

Store instruction.

The ‘store’ instruction is used to write to memory.

Parameters:

Conversation:

store [volatile] <ty> <value>, ptr <pointer>[, align <alignment>] yields void
Store(
    Value(value, ty),
    Value(pointer, ptr),
    alignment,
    volatile?
)

store atomic [volatile] <ty> <value>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> ; yields void
Store(
    Value(value, ty),
    Value(pointer, ptr),
    alignment,
    volatile?
    True
    ordering
    target-scope
)
class CmpXchg(result: Value, address: Value, compare_value: Value, new_value: Value, ordering_ok: Ordering, ordering_err: Ordering, align: int = 0, is_weak: bool = False, is_volatile: bool = False, syncscope: int | None = None)

CmpXchg instruction.

The ‘cmpxchg’ instruction is used to atomically modify memory. It loads a value in memory and compares it to a given value. If they are equal, it tries to store a new value into the memory.

Parameters:

Conversation:

<result> = cmpxchg [weak] [volatile] ptr <pointer>, <ty> <cmp>, <ty> <new> [syncscope("<target-scope>")] <success ordering> <failure ordering>[, align <alignment>] ; yields  { ty, i1 }
CmpXchg(
    Value(result, StructureType(elem_tys=[ty, IntegerType(1)])),
    Value(pointer, ptr),
    Value(cmp, ty),
    Value(new, ty),
    success ordering,
    failure ordering,
    alignment,
    weak?
    volatile?
    target-scope
)
class AtomicRmw(op: str, result: Value, address: Value, operand: Value, ordering: Ordering, align: int = 0, is_volatile: bool = False, syncscope: int | None = None)

AtomicRmw instruction.

The ‘atomicrmw’ instruction is used to atomically modify memory.

Parameters:

  • op (str) – An operation to apply, one of { ‘xchg’, ‘add’, ‘sub’, ‘and’, ‘nand’, ‘or’, ‘xor’, ‘max’, ‘min’, ‘umax’, ‘umin’, ‘fadd’, ‘fsub’, ‘fmax’, ‘fmin’, ‘uinc_wrap’, ‘udec_wrap’, ‘usub_cond’, ‘usub_sat’ }.

  • result (Value) – The original value at the location.

  • address (Value) – An address whose value to modify.

  • operand (Value) – An argument to the operation.

  • ordering (Ordering) – https://llvm.org/docs/LangRef.html#ordering

  • align (int) – An alignment.

  • is_volatile (bool) – If True, the instruction has a “volatile” flag.

  • syncscope (int | None) – https://llvm.org/docs/LangRef.html#syncscope

Conversation:

<result> = atomicrmw [volatile] <operation> ptr <pointer>, <ty> <value> [syncscope("<target-scope>")] <ordering>[, align <alignment>]  ; yields ty
AtomicRmw(
    operation,
    Value(result, ty),
    Value(pointer, ptr),
    Value(value, ty),
    ordering,
    alignment,
    volatile?
    target-scope
)
class GetElementPtr(result: Value, source_ty: VoidType | FunctionType | IntegerType | FPType | X86_amxType | PtrType | TargetExtensionType | VectorType | LabelType | TokenType | MetadataType | ArrayType | StructureType | OpaqueType, base_addr: Value, indices: list[Value], dest_ty: VoidType | FunctionType | IntegerType | FPType | X86_amxType | PtrType | TargetExtensionType | VectorType | LabelType | TokenType | MetadataType | ArrayType | StructureType | OpaqueType | None = None, is_inbounds: bool = False)

GetElementPtr instruction.

The ‘getelementptr’ instruction is used to get the address of a subelement of an aggregate data structure. It performs address calculation only and does not access memory. The instruction can also be used to calculate a vector of such addresses.

Parameters:

  • result (Value) – The resulting address.

  • source_ty (Type) – A type used as the basis for the calculations.

  • base_addr (Value) – A pointer, or vector of pointers, the base address to start with.

  • indices (list[Value]) – A list indicationg which of the elements of the aggregate object are indexed.

  • dest_ty (Type) – The type pointed to by the received address.

  • is_inbounds (str | None) – If True, the instruction has a “inbounds” flag.

Conversation:

<result> = getelementptr [inbounds] <ty>, ptr <ptrval>{, <ty> <idx>}*
GetElementPtr(
    Value(result, PtrType(...)),
    ty,
    Value(ptrval, ptr),
    [
        Value(idx0, ty),
        Value(idx1, ty),
        ...
    ]
)

Conversion operations

class Conversion(opcode: str, result: Value, value: Value, fast_math_flags: frozenset[str] = frozenset({}), is_nuw: bool = False, is_nsw: bool = False)

Conversion operations.

These instructions are the conversion instructions (casting) which all take a single operand and a type. They perform various bit conversions on the operand.

This class generalizes all conversion operations.

Parameters:

  • opcode (str) – An instuction opcode, one of { ‘trunc’, ‘zext’, ‘sext’, ‘fptrunc’, ‘fpext’, ‘fptoui’, ‘fptosi’, ‘uitofp’, ‘sitofp’, ‘ptrtoint’, ‘inttoptr’, ‘bitcast’, ‘addrspacecast’ }.

  • result (Value) – The converted value.

  • value (Value) – A value to convert.

  • fast_math_flags (frozenset[str]) – A set of fast math flags.

  • is_nuw (bool) – If True, the instruction has a “nuw” flag.

  • is_nsw (bool) – If True, the instruction has a “nsw” flag.

Conversation:

<result> = opcode [fast-math flags]* [nuw] [nsw] <ty> <value> to <ty2>     ; yields ty2
Conversion(
    opcode,
    Value(result, ty2),
    Value(value, ty),
    {*fast-math flags},
    nuw?
    nsw?
)

Other operations

class ICmp(cond: str, result: Value, fst_operand: Value, snd_operand: Value)

ICmp instruction.

The ‘icmp’ instruction returns a boolean value or a vector of boolean values based on comparison of its two integer, integer vector, pointer, or pointer vector operands.

Parameters:

  • cond (str) – The condition code indicating the kind of comparison to perform, one of { ‘eq’, ‘ne’, ‘ugt’, ‘uge’, ‘ult’, ‘ule’, ‘sgt’, ‘sge’, ‘slt’, ‘sle’, }.

  • result (Value) – The converted value.

  • fst_operand (Value) – A first operand to compare.

  • snd_operand (Value) – A second operand to compare.

Conversation:

<result> = icmp <cond> <ty> <op1>, <op2>   ; yields i1 or <N x i1>:result
ICmp(
    cond,
    Value(result, IntegerType(1) or VectorType(N, IntegerType(1))),
    Value(op1, ty),
    Value(op2, ty),
)
class FCmp(cond: str, result: Value, fst_operand: Value, snd_operand: Value, fast_math_flags: frozenset[str] = frozenset({}))

FCmp instruction.

The ‘fcmp’ instruction returns a boolean value or vector of boolean values based on comparison of its operands.

If the operands are floating-point scalars, then the result type is a boolean (i1).

If the operands are floating-point vectors, then the result type is a vector of boolean with the same number of elements as the operands being compared.

Parameters:

  • cond (str) – The condition code indicating the kind of comparison to perform, one of { ‘eq’, ‘ne’, ‘ugt’, ‘uge’, ‘ult’, ‘ule’, ‘sgt’, ‘sge’, ‘slt’, ‘sle’, }.

  • result (Value) – The converted value.

  • fst_operand (Value) – A first operand to compare.

  • snd_operand (Value) – A second operand to compare.

  • fast_math_flags (frozenset[str]) – A set of fast math flags.

Conversation:

<result> = icmp [fast-math flags]* <cond> <ty> <op1>, <op2>   ; yields i1 or <N x i1>:result
ICmp(
    cond,
    Value(result, IntegerType(1) or VectorType(N, IntegerType(1))),
    Value(op1, ty),
    Value(op2, ty),
    {*fast-math flags}
)
class Phi(result: Value, vals: list[tuple[Value, Value]], fast_math_flags: frozenset[str] = frozenset({}))

Phi instruction.

The ‘phi’ instruction is used to implement the φ node in the SSA graph representing the function.

Parameters:

  • result (Value) – A taken value specified by the pair corresponding to the predecessor basic block that executed just prior to the current block.

  • vals (list[tuple[Value, Value]]) – A list of pairs of values and predecessor blocks, with one pair for each predecessor basic block of the current block.

  • fast_math_flags (frozenset[str]) – A set of fast math flags.

Conversation:

<result> = phi [fast-math-flags] <ty> [ <val0>, <label0>], ...
Phi(
    Value(result, Type),
    [
        (Value(val0, ty), Value(label0, LabelType())),
        ...
    ],
    {*fast-math flags}
)
class Select(result: Value, cond: Value, true_value: Value, false_value: Value, fast_math_flags: frozenset[str] = frozenset({}))

Select instruction.

The ‘select’ instruction is used to choose one value based on a condition, without IR-level branching.

Parameters:

  • result (Value) – The converted value.

  • cond (Value) – A value indicating the condition.

  • true_value (Value) – A value returned if cond is True.

  • false_value (Value) – A value returned if cond is false.

  • fast_math_flags (frozenset[str]) – A set of fast math flags.

Conversation:

<result> = select [fast-math flags] (i1 or {<N x i1>}) <cond>, <ty> <val1>, <ty> <val2>             ; yields ty
Select(
    Value(result, ty),
    Value(cond, IntegerType(1) or VectorType(N, IntegerType(1)))
    Value(val1, ty),
    Value(val2, ty),
    {*fast-math flags}
)
class Freeze(result: Value, value: Value)

Freeze instruction.

The ‘freeze’ instruction is used to stop propagation of undef and poison values.

Parameters:

  • result (Value) – An arbitrary fixed value, if the value is undef or poison, otherwise value.

  • value (Value) – A value, which can be poison or undef.

Conversation:

<result> = freeze ty <val>    ; yields ty:result
Freeze(
    Value(result, ty),
    Value(val, ty)
)
class Call(result: Value, callee: Value, args: list[Value], calling_conv: CallingConv, call_attrs: list[dict[str, tuple | tuple[Any] | tuple[Any, Any]]], tail_kind: str | None = None, fast_math_flags: frozenset[str] = frozenset({}))

Call instruction.

The ‘call’ instruction represents a simple function call.

Parameters:

  • result (Value) – The returned value.

  • callee (Value) – The function to be invoked, pointer or function name.

  • args (list[Value]) – An argument list.

  • calling_conv (CallingConv) – The calling convention that should be used in a call.

  • call_attrs (list[Attrs]) – A list containing all call-related attributes.

  • tail_kind (str) – A marker indicating that the optimizers should perform tail call optimization, one of {‘tail’, ‘musttail’, ‘notail’}.

  • fast_math_flags (frozenset[str]) – A set of fast math flags.

Conversation:

<result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)]
   <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ]
Call(
    Value(result, Type),
    Value(fnptrval, FunctionType | Type),
    [
        Value(arg0, Type),
        Value(arg1, Type),
        ...
    ],
    "tail" | "musttail" | "notail" | None
    cconv,
    [call_attrs]
    {*fast-math flags}
)
class VaArg(result: Value, value: Value)

VaArg instruction.

The ‘va_arg’ instruction is used to access arguments passed through the “variable argument” area of a function call. It is used to implement the va_arg macro in C.

Parameters:

  • result (Value) – The va_list* value.

  • value (Value) – The value of the specified argument type.

Conversation:

<resultval> = va_arg <va_list*> <arglist>, <argty>
VaArg(
    Value(resultval, argty),
    Value(arglist, PtrType(...))
)
class LandingPad(result: Value, is_cleanup: bool, is_catchs: list[bool], clauses: list[Value])

LandingPad instruction.

The ‘landingpad’ instruction is used by LLVM’s exception handling system to specify that a basic block is a landing pad — one where the exception lands, and corresponds to the code found in the catch portion of a try/catch sequence. It defines values supplied by the personality function upon re-entry to the function. The resultval has the type resultty.

Parameters:

Conversation:

<resultval> = landingpad <resultty> <clause>+
<clause> := catch <type> <value>
<clause> := filter <array constant type> <array constant>
LangingPad(
    Value(resultval, Type),
    False,
    [True if clause is catch else False, ...]
    [Value(value, type), ...]
)

<resultval> = landingpad <resultty> cleanup <clause>*
LangingPad(
    Value(resultval, Type),
    True,
    [True if clause is catch else False, ...]
    [Value(value, type), ...]
)
class CatchPad(result: Value, catchswith: Value, args: list[Value])

CatchPad instruction.

The ‘catchpad’ instruction is used by LLVM’s exception handling system to specify that a basic block begins a catch handler — one where a personality routine attempts to transfer control to catch an exception.

Parameters:

  • result (Value) – The token, used to match the catchpad to corresponding catchrets and other nested EH pads.

  • catchswith (Value) – A token produced by a catchswitch instruction in a predecessor block.

  • args (list[Value]) – A list corresponding to whatever information the personality routine requires to know if this is an appropriate handler for the exception.

Conversation:

<resultval> = catchpad within <catchswitch> [<args>*]
CatchPad(
    Value(resultval, TokenType()),
    Value(catchswitch, TokenType()),
    [
        Value(arg0, Type),
        Value(arg1, Type),
        ...
    ]
)
class CleanupPad(result: Value, parent: Value, args: list[Value])

CleanupPad instruction.

The ‘cleanuppad’ instruction is used by LLVM’s exception handling system to specify that a basic block is a cleanup block — one where a personality routine attempts to transfer control to run cleanup actions. The args correspond to whatever additional information the personality function requires to execute the cleanup. The resultval has the type token and is used to match the cleanuppad to corresponding cleanuprets. The parent argument is the token of the funclet that contains the cleanuppad instruction. If the cleanuppad is not inside a funclet, this operand may be the token none.

Parameters:

  • result (Value) – A token, used to match the cleanuppad to corresponding cleanuprets.

  • parent (Value) – The token of the funclet that contains the cleanuppad instruction. If the cleanuppad is not inside a funclet, this operand may be the token none.

  • args (list[Value]) – A list corresponding to whatever additional information the personality function requires to execute the cleanup.

Conversation:

<resultval> = cleanuppad within <parent> [<args>*]
CleanupPad(
    Value(resultval, TokenType()),
    Value(parent, TokenType()),
    [
        Value(arg0, Type),
        Value(arg1, Type),
        ...
    ]
)