IRBuilder

public class IRBuilder

An IRBuilder is a helper object that generates LLVM instructions.

IR builders keep track of a position (the “insertion point”) within a module, function, or basic block and has methods to insert instructions at that position. Other features include conveniences to insert calls to C standard library functions like malloc and free, the creation of global entities like © strings, and inline assembly.

Threading Considerations

An IRBuilder object is not thread safe. It is associated with a single module which is, in turn, associated with a single LLVM context object. In concurrent environments, exactly one IRBuilder should be created per thread, and that thread should be the one that ultimately created its parent module and context. Inserting instructions into the same IR builder object in a concurrent manner will result in malformed IR being generated in non-deterministic ways. If concurrent codegen is needed, a separate LLVM context, module, and IRBuilder should be created on each thread. Once each thread has finished generating code, the resulting modules should be merged together. See Module.link(_:) for more information.

IR Navigation

By default, the insertion point of a builder is undefined. To move the IR builder’s cursor, a basic block must be created, but not necessarily inserted into a function.

let module = Module(name: "Example")
let builder = IRBuilder(module: module)
// Create a freestanding basic block and insert an `ret`
// instruction into it.
let freestanding = BasicBlock(name: "freestanding")
// Move the IR builder to the end of the block's instruction list.
builder.positionAtEnd(of: freestanding)
let ret = builder.buildRetVoid()

Instructions serve as a way to position the IR builder to a point before their creation. This allows for instructions to be inserted before a given instruction rather than at the very end of a basic block.

// Move before the `ret` instruction
builder.positionBefore(ret)
// Insert an `alloca` instruction before the `ret`.
let intAlloca = builder.buildAlloca(type: IntType.int8)
// Move before the `alloca`
builder.positionBefore(intAlloca)
// Insert an `malloc` call before the `alloca`.
let intMalloc = builder.buildMalloc(IntType.int8)

To insert this block into a function, see Function.append.

Sometimes it is necessary to reset the insertion point. When the insertion point is reset, instructions built with the IR builder are still created, but are not inserted into a basic block. To clear the insertion point, call IRBuilder.clearInsertionPosition().

Building LLVM IR

All functions that build instructions are prefixed with build. Invoking these functions inserts the appropriate LLVM instruction at the insertion point, assuming it points to a valid location.

let module = Module(name: "Example")
let builder = IRBuilder(module: module)
let fun = builder.addFunction("test",
                              type: FunctionType([
                                      IntType.int8,
                                      IntType.int8,
                              ], FloatType.float))
let entry = fun.appendBasicBlock(named: "entry")
// Set the insertion point to the entry block of this function
builder.positionAtEnd(of: entry)
// Build an `add` instruction at the insertion point
let result = builder.buildAdd(fun.parameters[0], fun.parameters[1])

Customizing LLVM IR

To be well-formed, certain instructions may involve more setup than just being built. In such cases, LLVMSwift will yield a specific instance of IRInstruction that will allow for this kind of configuration.

A prominent example of this is the PHI node. Building a PHI node produces an empty PHI node - this is not a well-formed instruction. A PHI node must have its incoming basic blocks attached. To do so, PhiNode.addIncoming(_:) is called with a list of pairs of incoming values and their enclosing basic blocks.

// Build a function that selects one of two floating parameters based
// on a given boolean value.
let module = Module(name: "Example")
let builder = IRBuilder(module: module)
let select = builder.addFunction("select",
                                 type: FunctionType([
                                         IntType.int1,
                                         FloatType.float,
                                         FloatType.float,
                                 ], FloatType.float))
let entry = select.appendBasicBlock(named: "entry")
builder.positionAtEnd(of: entry)

let thenBlock = select.appendBasicBlock(named: "then")
let elseBlock = select.appendBasicBlock(named: "else")
let mergeBB = select.appendBasicBlock(named: "merge")
let branch = builder.buildCondBr(condition: select.parameters[0],
                                 then: thenBlock,
                                 else: elseBlock)
builder.positionAtEnd(of: thenBlock)
let opThen = builder.buildAdd(select.parameters[1], select.parameters[2])
builder.buildBr(mergeBB)
builder.positionAtEnd(of: elseBlock)
let opElse = builder.buildSub(select.parameters[1], select.parameters[2])
builder.buildBr(mergeBB)
builder.positionAtEnd(of: mergeBB)

// Build the PHI node
let phi = builder.buildPhi(FloatType.float)
// Attach the incoming blocks.
phi.addIncoming([
  (opThen, thenBlock),
  (opElse, elseBlock),
])
builder.buildRet(phi)

  • The module this IRBuilder is associated with.

    Declaration

    Swift

    public let module: Module

  • Creates an IRBuilder object with the given module.

    Declaration

    Swift

    public init(module: Module)

    Parameters

    module

    The module into which instructions will be inserted.

IR Navigation

  • Repositions the IR Builder at the end of the given basic block.

    Declaration

    Swift

    public func positionAtEnd(of block: BasicBlock)

    Parameters

    block

    The basic block to reposition the IR Builder after.

  • Repositions the IR Builder before the start of the given instruction.

    Declaration

    Swift

    public func positionBefore(_ inst: IRInstruction)

    Parameters

    inst

    The instruction to reposition the IR Builder before.

  • Repositions the IR Builder at the point specified by the given instruction in the given basic block.

    This is equivalent to calling positionAtEnd(of:) with the given basic block then calling positionBefore(_:) with the given instruction.

    Declaration

    Swift

    public func position(_ inst: IRInstruction, block: BasicBlock)

    Parameters

    inst

    The instruction to reposition the IR Builder before.
    block

    The basic block to reposition the IR builder in.

  • Clears the insertion point.

    Subsequent instructions will not be inserted into a block.

    Declaration

    Swift

    public func clearInsertionPosition()

  • Gets the basic block built instructions will be inserted into.

    Declaration

    Swift

    public var insertBlock: BasicBlock? { get }

  • Gets the function this builder is building into.

    Declaration

    Swift

    public var currentFunction: Function? { get }

  • Inserts the given instruction into the IR Builder.

    Declaration

    Swift

    public func insert(_ inst: IRInstruction, name: String? = nil)

    Parameters

    inst

    The instruction to insert.
    name

    The name for the newly inserted instruction.

Debug Information

  • Access location information used by debugging information.

    Declaration

    Swift

    public var currentDebugLocation: DebugLocation? { get set }

  • Set the floating point math metadata to be used for floating-point operations.

    Declaration

    Swift

    public var defaultFloatingPointMathTag: MDNode? { get set }

Convenience Instructions

  • Builds the specified binary operation instruction with the given arguments.

    Declaration

    Swift

    public func buildBinaryOperation(_ op: OpCode.Binary, _ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue

    Parameters

    op

    The operation to build.
    lhs

    The first operand.
    rhs

    The second operand.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of perfomring the given binary operation with the given values as arguments.

  • Builds the specified cast operation instruction with the given value and destination type.

    Declaration

    Swift

    public func buildCast(_ op: OpCode.Cast, value: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    op

    The cast operation to build.
    value

    The value to cast.
    type

    The destination type to cast to.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of casting the given value to the given destination type using the given operation.

  • Builds a cast operation from a value of pointer type to any other integral, pointer, or vector of integral/pointer type.

    There are a number of restrictions on the form of the input value and destination type. The source value of a pointer cast must be either a pointer or a vector of pointers. The destination type must either be an integer type, a pointer type, or a vector type with integral or pointer element type.

    If the destination type is an integral type or a vector of integral elements, this builds a ptrtoint instruction. Else, if the destination is a pointer type or vector of pointer type, and it has an address space that differs from the address space of the source value, an addrspacecast instruction is built. If none of these are true, a bitcast instruction is built.

    Declaration

    Swift

    public func buildPointerCast(of value: IRValue, to type: IRType, name: String = "") -> IRValue

    Parameters

    value

    The value to cast. The value must have pointer type.
    type

    The destination type to cast to. This must be a pointer type, integer type, or vector of the same.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of casting the given value to the given destination type using the appropriate pointer cast operation.

  • Builds a cast operation from a value of integral type to given integral type by zero-extension, sign-extension, bitcast, or truncation as necessary.

    Declaration

    Swift

    public func buildIntCast(of value: IRValue, to type: IntType, signed: Bool = true, name: String = "") -> IRValue

    Parameters

    value

    The value to cast.
    type

    The destination integer type to cast to.
    signed

    If true, if an extension is required it will be a sign-extension. Else, all required extensions will be zero-extensions.
    name

    The name for the newly inserted instruction.

    Return Value

    A value reprresenting the result of casting the given value to the given destination integer type using the appropriate integral cast operation.

Arithmetic Instructions

  • Build a negation instruction with the given value as an operand.

    Whether an integer or floating point negate instruction is built is determined by the type of the given value. Providing an operand that is neither an integer nor a floating value is a fatal condition.

    Declaration

    Swift

    public func buildNeg(_ value: IRValue,
                     overflowBehavior: OverflowBehavior = .default,
                     name: String = "") -> IRValue

    Parameters

    value

    The value to negate.
    overflowBehavior

    Should overflow occur, specifies the behavior of the program.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the negation of the given value.

  • Build an add instruction with the given values as operands.

    Whether an integer or floating point add instruction is built is determined by the type of the first given value. Providing operands that are neither integers nor floating values is a fatal condition.

    Declaration

    Swift

    public func buildAdd(_ lhs: IRValue, _ rhs: IRValue,
                     overflowBehavior: OverflowBehavior = .default,
                     name: String = "") -> IRValue

    Parameters

    lhs

    The first summand value (the augend).
    rhs

    The second summand value (the addend).
    overflowBehavior

    Should overflow occur, specifies the behavior of the program.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the sum of the two operands.

  • Build a subtract instruction with the given values as operands.

    Whether an integer or floating point subtract instruction is built is determined by the type of the first given value. Providing operands that are neither integers nor floating values is a fatal condition.

    Declaration

    Swift

    public func buildSub(_ lhs: IRValue, _ rhs: IRValue,
                     overflowBehavior: OverflowBehavior = .default,
                     name: String = "") -> IRValue

    Parameters

    lhs

    The first value (the minuend).
    rhs

    The second value (the subtrahend).
    overflowBehavior

    Should overflow occur, specifies the behavior of the program.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the difference of the two operands.

  • Build a multiply instruction with the given values as operands.

    Whether an integer or floating point multiply instruction is built is determined by the type of the first given value. Providing operands that are neither integers nor floating values is a fatal condition.

    Declaration

    Swift

    public func buildMul(_ lhs: IRValue, _ rhs: IRValue,
                     overflowBehavior: OverflowBehavior = .default,
                     name: String = "") -> IRValue

    Parameters

    lhs

    The first factor value (the multiplier).
    rhs

    The second factor value (the multiplicand).
    overflowBehavior

    Should overflow occur, specifies the behavior of the program.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the product of the two operands.

  • Build a remainder instruction that provides the remainder after divison of the first value by the second value.

    Whether an integer or floating point remainder instruction is built is determined by the type of the first given value. Providing operands that are neither integers nor floating values is a fatal condition.

    Declaration

    Swift

    public func buildRem(_ lhs: IRValue, _ rhs: IRValue,
                     signed: Bool = true,
                     name: String = "") -> IRValue

    Parameters

    lhs

    The first value (the dividend).
    rhs

    The second value (the divisor).
    signed

    Whether to emit a signed or unsigned remainder instruction. Defaults to emission of a signed remainder instruction.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the remainder of division of the first operand by the second operand.

  • Build a division instruction that divides the first value by the second value.

    Whether an integer or floating point divide instruction is built is determined by the type of the first given value. Providing operands that are neither integers nor floating values is a fatal condition.

    Declaration

    Swift

    public func buildDiv(_ lhs: IRValue, _ rhs: IRValue,
                     signed: Bool = true, exact: Bool = false,
                     name: String = "") -> IRValue

    Parameters

    lhs

    The first value (the dividend).
    rhs

    The second value (the divisor).
    signed

    Whether to emit a signed or unsigned remainder instruction. Defaults to emission of a signed divide instruction.
    exact

    Whether this division must be exact. Defaults to inexact.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the quotient of the first and second operands.

  • Build an integer comparison between the two provided values using the given predicate.

    Precondition

    Arguments must be integer or pointer or integer vector typed

    Precondition

    lhs.type == rhs.type

    Declaration

    Swift

    public func buildICmp(_ lhs: IRValue, _ rhs: IRValue,
                      _ predicate: IntPredicate,
                      name: String = "") -> IRValue

    Parameters

    lhs

    The first value to compare.
    rhs

    The second value to compare.
    predicate

    The method of comparison to use.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of the comparision of the given operands.

  • Build a floating comparison between the two provided values using the given predicate.

    Attempting to compare operands that are not floating is a fatal condition.

    Declaration

    Swift

    public func buildFCmp(_ lhs: IRValue, _ rhs: IRValue,
                      _ predicate: RealPredicate,
                      name: String = "") -> IRValue

    Parameters

    lhs

    The first value to compare.
    rhs

    The second value to compare.
    predicate

    The method of comparison to use.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of the comparision of the given operands.

Logical Instructions

  • Build a bitwise logical not with the given value as an operand.

    Declaration

    Swift

    public func buildNot(_ val: IRValue, name: String = "") -> IRValue

    Parameters

    val

    The value to negate.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the logical negation of the given operand.

  • Build a bitwise logical exclusive OR with the given values as operands.

    Declaration

    Swift

    public func buildXor(_ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue

    Parameters

    lhs

    The first operand.
    rhs

    The second operand.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the exclusive OR of the values of the two given operands.

  • Build a bitwise logical OR with the given values as operands.

    Declaration

    Swift

    public func buildOr(_ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue

    Parameters

    lhs

    The first operand.
    rhs

    The second operand.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the logical OR of the values of the two given operands.

  • Build a bitwise logical AND with the given values as operands.

    Declaration

    Swift

    public func buildAnd(_ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue

    Parameters

    lhs

    The first operand.
    rhs

    The second operand.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the logical AND of the values of the two given operands.

  • Build a left-shift instruction of the first value by an amount in the second value.

    Declaration

    Swift

    public func buildShl(_ lhs: IRValue, _ rhs: IRValue,
                     name: String = "") -> IRValue

    Parameters

    lhs

    The first operand.
    rhs

    The number of bits to shift the first operand left by.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the value of the first operand shifted left by the number of bits specified in the second operand.

  • Build a right-shift instruction of the first value by an amount in the second value. If isArithmetic is true the value of the first operand is bitshifted with sign extension. Else the value is bitshifted with zero-fill.

    Declaration

    Swift

    public func buildShr(_ lhs: IRValue, _ rhs: IRValue,
                     isArithmetic: Bool = false,
                     name: String = "") -> IRValue

    Parameters

    lhs

    The first operand.
    rhs

    The number of bits to shift the first operand right by.
    isArithmetic

    Whether this instruction performs an arithmetic or logical right-shift. The default is a logical right-shift.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the value of the first operand shifted right by the numeber of bits specified in the second operand.

Conditional Instructions

  • Build a phi node with the given type acting as the result of any incoming basic blocks.

    Declaration

    Swift

    public func buildPhi(_ type: IRType, name: String = "") -> PhiNode

    Parameters

    type

    The type of incoming values.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the newly inserted phi node.

  • Build a select instruction to choose a value based on a condition without IR-level branching.

    Declaration

    Swift

    public func buildSelect(_ cond: IRValue, then: IRValue, else: IRValue, name: String = "") -> IRInstruction

    Parameters

    cond

    The condition to evaluate. It must have type i1 or be a vector of i1.
    then

    The value to select if the given condition is true.
    else

    The value to select if the given condition is false.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the value selected for by the condition.

  • Build a branch table that branches on the given value with the given default basic block.

    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.

    This function returns a value that acts as a representation of the branch table for the switch instruction. When the switch instruction is executed, this table is searched for the given value. If the value is found, control flow is transferred to the corresponding destination; otherwise, control flow is transferred to the default destination specified by the else block.

    To add branches to the switch table, see Switch.addCase(_:_:).

    Declaration

    Swift

    public func buildSwitch(_ value: IRValue, else: BasicBlock, caseCount: Int) -> Switch

    Parameters

    value

    The value to compare.
    else

    The default destination for control flow should the value not match a case in the branch table.
    caseCount

    The number of cases in the branch table.

    Return Value

    A value representing the newly inserted switch instruction.

Declaration Instructions

  • Build a named function body with the given type.

    Declaration

    Swift

    public func addFunction(_ name: String, type: FunctionType) -> Function

    Parameters

    name

    The name of the newly defined function.
    type

    The type of the newly defined function.

    Return Value

    A value representing the newly inserted function definition.

  • Build a named structure definition.

    Declaration

    Swift

    public func createStruct(name: String, types: [IRType]? = nil, isPacked: Bool = false) -> StructType

    Parameters

    name

    The name of the structure.
    types

    The type of fields that make up the structure’s body.
    isPacked

    Whether this structure should be 1-byte aligned with no padding between elements.

    Return Value

    A value representing the newly declared named structure.

Terminator Instructions

  • Build an unconditional branch to the given basic block.

    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. To build a conditional branch, see buildCondBr(condition:then:else:).

    Declaration

    Swift

    @discardableResult
public func buildBr(_ block: BasicBlock) -> IRInstruction

    Parameters

    block

    The target block to transfer control flow to.

    Return Value

    A value representing void.

  • Build a condition branch that branches to the first basic block if the provided condition is true, otherwise to the second basic block.

    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. To build an unconditional branch, see buildBr(_:).

    Declaration

    Swift

    @discardableResult
public func buildCondBr(
  condition: IRValue, then: BasicBlock, `else`: BasicBlock) -> IRInstruction

    Parameters

    condition

    A value of type i1 that determines which basic block to transfer control flow to.
    then

    The basic block to transfer control flow to if the condition evaluates to true.
    else

    The basic block to transfer control flow to if the condition evaluates to false.

    Return Value

    A value representing void.

  • Build an indirect branch to a label within the current function.

    The indirectbr instruction implements an indirect branch to a label within the current function, whose address is specified by the address parameter.

    All possible destination blocks must be listed in the destinations list, otherwise this instruction has undefined behavior. This implies that jumps to labels defined in other functions have undefined behavior as well.

    Declaration

    Swift

    @discardableResult
public func buildIndirectBr(address: BasicBlock.Address, destinations: [BasicBlock]) -> IRInstruction

    Parameters

    address

    The address of the label to branch to.
    destinations

    The set of possible destinations the address may point to. The same block may appear multiple times in this list, though this isn’t particularly useful.

    Return Value

    An IRValue representing void.

  • Build a return from the current function back to the calling function with the given value.

    Returning a value with a type that does not correspond to the return type of the current function is a fatal condition.

    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. To build the ret that does not return a value use buildRetVoid().

    Declaration

    Swift

    @discardableResult
public func buildRet(_ val: IRValue) -> IRInstruction

    Parameters

    val

    The value to return from the current function.

    Return Value

    A value representing void.

  • Build a void return from the current function.

    If the current function does not have a Void return value, failure to return a falue is a fatal condition.

    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. To build the ret that returns a value use buildRet(_:).

    Declaration

    Swift

    @discardableResult
public func buildRetVoid() -> IRInstruction

    Return Value

    A value representing void.

  • Build an unreachable instruction in the current function.

    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.

    Declaration

    Swift

    @discardableResult
public func buildUnreachable() -> IRInstruction

    Return Value

    A value representing void.

  • Build a return from the current function back to the calling function with the given array of values as members of an aggregate.

    Declaration

    Swift

    @discardableResult
public func buildRetAggregate(of values: [IRValue]) -> IRInstruction

    Parameters

    values

    The values to insert as members of the returned aggregate.

    Return Value

    A value representing void.

  • Build a call to the given function with the given arguments to transfer control to that function.

    Declaration

    Swift

    public func buildCall(_ fn: IRValue, args: [IRValue], name: String = "") -> Call

    Parameters

    fn

    The function to invoke.
    args

    A list of arguments.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of returning from the callee.

Exception Handling Instructions

  • Build a call to the given function with the given arguments with the possibility of control transfering to either the next basic block or the catch basic block if an exception occurs.

    If the callee function returns with the ret instruction, control flow will return to the next 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 catch block is a landing pad for the exception. As such, the first instruction of that block is required to be the landingpad instruction, which contains the information about the behavior of the program after unwinding happens.

    Declaration

    Swift

    public func buildInvoke(_ fn: IRValue, args: [IRValue], next: BasicBlock, catch: BasicBlock, name: String = "") -> Invoke

    Parameters

    fn

    The function to invoke.
    args

    A list of arguments.
    next

    The destination block if the invoke succeeds without exceptions.
    catch

    The destination block if the invoke encounters an exception.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of returning from the callee under normal circumstances. Under exceptional circumstances, the value represents the value of any resume instruction in the catch block.

  • Build a landing pad to specify that a basic block is where an exception lands, and corresponds to the code found in the catch portion of a try/catch sequence.

    The clauses are applied in order from top to bottom. If two landing pad instructions are merged together through inlining, the clauses from the calling function are appended to the list of clauses. When the call stack is being unwound due to an exception being thrown, the exception is compared against each clause in turn. If it doesn’t match any of the clauses, and the cleanup flag is not set, then unwinding continues further up the call stack.

    The landingpad instruction has several restrictions:

    • A landing pad block is a basic block which is the unwind destination of an invoke instruction.
    • A landing pad block must have a landingpad instruction as its first non-PHI instruction.
    • There can be only one landingpad instruction within the landing pad block.

    • A basic block that is not a landing pad block may not include a landingpad instruction.

    Declaration

    Swift

    public func buildLandingPad(returning type: IRType, personalityFn: Function? = nil, clauses: [LandingPadClause], cleanup: Bool = false, name: String = "") -> IRInstruction

    Parameters

    type

    The type of the resulting value from the landing pad.
    personalityFn

    The personality function.
    clauses

    A list of catch and filter clauses. This list must either be non-empty or the landing pad must be marked as a cleanup instruction.
    cleanup

    A flag indicating whether the landing pad is a cleanup.
    name

    The name for the newly inserted instruction.

    Return Value

    A value of the given type representing the result of matching a clause during unwinding.

  • Build a resume instruction to resume propagation of an existing (in-flight) exception whose unwinding was interrupted with a landingpad instruction.

    When all cleanups are finished, if an exception is not handled by the current function, unwinding resumes by calling the resume instruction, passing in the result of the landingpad instruction for the original landing pad.

    Declaration

    Swift

    @discardableResult
public func buildResume(_ val: IRValue) -> IRValue

    Return Value

    A value representing void.

  • Build a va_arg instruction to access arguments passed through the “variable argument” area of a function call.

    This instruction is used to implement the va_arg macro in C.

    Declaration

    Swift

    public func buildVAArg(_ list: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    list

    A value of type va_list*
    type

    The type of values in the variable argument area.
    name

    The name for the newly inserted instruction.

    Return Value

    A value of the specified argument type. In addition, the va_list pointer is incremented to point to the next argument.

Memory Access Instructions

  • Build an alloca to allocate stack memory to hold a value of the given type.

    The alloca instruction allocates sizeof(<type>)*count bytes of memory on the runtime stack, returning a pointer of the appropriate type to the program. If count is specified, it is the number of elements allocated, otherwise count is defaulted to be one. If a constant alignment is specified, the value result of the allocation is guaranteed to be aligned to at least that boundary. The alignment may not be greater than 1 << 29. If not specified, or if zero, the target will choose a default value that is convenient and compatible with the type.

    The returned value is allocated in the address space specified in the data layout string for the target. If no such value is specified, the value is allocated in the default address space.

    Declaration

    Swift

    public func buildAlloca(type: IRType, count: IRValue? = nil,
                        alignment: Alignment = .zero, name: String = "") -> IRInstruction

    Parameters

    type

    The sized type used to determine the amount of stack memory to allocate.
    count

    An optional number of slots to allocate, to simulate a C array.
    alignment

    The alignment of the access.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing void.

  • Build a store instruction that stores the first value into the location given in the second value.

    If alignment is not specified, or if zero, the target will choose a default value that is convenient and compatible with the type.

    Declaration

    Swift

    @discardableResult
public func buildStore(_ val: IRValue, to ptr: IRValue, ordering: AtomicOrdering = .notAtomic, volatile: Bool = false, alignment: Alignment = .zero) -> IRInstruction

    Parameters

    val

    The source value.
    ptr

    The destination pointer to store into.
    ordering

    The ordering effect of the fence for this store, if any. Defaults to a nonatomic store.
    volatile

    Whether this is a store to a volatile memory location.
    alignment

    The alignment of the access.

    Return Value

    A value representing void.

  • Build a load instruction that loads a value from the location in the given value.

    If alignment is not specified, or if zero, the target will choose a default value that is convenient and compatible with the type.

    Declaration

    Swift

    public func buildLoad(_ ptr: IRValue, type: IRType, ordering: AtomicOrdering = .notAtomic, volatile: Bool = false, alignment: Alignment = .zero, name: String = "") -> IRInstruction

    Parameters

    ptr

    The pointer value to load from.
    type

    The type of value loaded from the given pointer.
    ordering

    The ordering effect of the fence for this load, if any. Defaults to a nonatomic load.
    volatile

    Whether this is a load from a volatile memory location.
    alignment

    The alignment of the access.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of a load from the given pointer value.

  • Build a GEP (Get Element Pointer) instruction with a resultant value that is undefined if the address is outside the actual underlying allocated object and not the address one-past-the-end.

    The GEP instruction is often the source of confusion. LLVM provides a document to answer questions around its semantics and correct usage.

    Declaration

    Swift

    public func buildInBoundsGEP(_ ptr: IRValue, type: IRType, indices: [IRValue], name: String = "") -> IRValue

    Parameters

    ptr

    The base address for the index calculation.
    type

    The type used to calculate pointer offsets.
    indices

    A list of indices that indicate which of the elements of the aggregate object are indexed.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the address of a subelement of the given aggregate data structure value.

  • Build a GEP (Get Element Pointer) instruction.

    The GEP instruction is often the source of confusion. LLVM provides a document to answer questions around its semantics and correct usage.

    Declaration

    Swift

    public func buildGEP(_ ptr: IRValue, type: IRType, indices: [IRValue], name: String = "") -> IRValue

    Parameters

    ptr

    The base address for the index calculation.
    type

    The type used to calculate pointer offsets.
    indices

    A list of indices that indicate which of the elements of the aggregate object are indexed.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the address of a subelement of the given aggregate data structure value.

  • Build a GEP (Get Element Pointer) instruction suitable for indexing into a struct of a given type.

    Declaration

    Swift

    public func buildStructGEP(_ ptr: IRValue, type: IRType, index: Int, name: String = "") -> IRValue

    Parameters

    ptr

    The base address for the index calculation.
    type

    The type of the struct to index into.
    index

    The offset from the base for the index calculation.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the address of a subelement of the given struct value.

  • Build an ExtractValue instruction to retrieve an indexed value from a struct or array value.

    extractvalue function like a GEP, but has different indexing semantics:

    Since

    Since the value being indexed is not a pointer, the first index is omitted and assumed to be zero.

    • Not only struct indices but also array indices must be in bounds.

    Declaration

    Swift

    public func buildExtractValue(_ value: IRValue, index: Int,
                              name: String = "") -> IRValue

    Parameters

    value

    The struct or array you’re indexing into.
    index

    The index at which to extract.

    Return Value

    The value in the struct at the provided index.

Null Test Instructions

  • Build a comparision instruction that returns whether the given operand is null.

    Declaration

    Swift

    public func buildIsNull(_ val: IRValue, name: String = "") -> IRValue

    Parameters

    val

    The value to test.
    name

    The name for the newly inserted instruction.

    Return Value

    An i1value representing the result of a test to see if the value isnull`.

  • Build a comparision instruction that returns whether the given operand is not null.

    Declaration

    Swift

    public func buildIsNotNull(_ val: IRValue, name: String = "") -> IRValue

    Parameters

    val

    The value to test.
    name

    The name for the newly inserted instruction.

    Return Value

    An i1value representing the result of a test to see if the value is notnull`.

Conversion Instructions

  • Build an instruction that either performs a truncation or a bitcast of the given value to a value of the given type.

    Declaration

    Swift

    public func buildTruncOrBitCast(_ val: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    val

    The value to cast or truncate.
    type

    The destination type.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of truncating or bitcasting the given value to fit the given type.

  • Build an instruction that either performs a zero extension or a bitcast of the given value to a value of the given type with a wider width.

    Declaration

    Swift

    public func buildZExtOrBitCast(_ val: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    val

    The value to zero extend.
    type

    The destination type.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of zero extending or bitcasting the given value to fit the given type.

  • Build a bitcast instruction to convert the given value to a value of the given type by just copying the bit pattern.

    The bitcast instruction is always a no-op cast because no bits change with this conversion. The conversion is done as if the value had been stored to memory and read back as the given type. Pointer (or vector of pointer) types may only be converted to other pointer (or vector of pointer) types with the same address space through this instruction. To convert pointers to other types, see buildIntToPtr(_:type:name:) or buildPtrToInt(_:type:name:).

    Declaration

    Swift

    public func buildBitCast(_ val: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    val

    The value to bitcast.
    type

    The destination type.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of bitcasting the given value to fit the given type.

  • Build a cast instruction to convert the given floating-point value to a value of the given type.

    Declaration

    Swift

    public func buildFPCast(_ val: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    val

    The value to cast.
    type

    The destination type.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of casting the given value to fit the given type.

  • Build an address space cast instruction that converts a pointer value to a given type in a different address space.

    The addrspacecast instruction can be a no-op cast or a complex value modification, depending on the target and the address space pair. Pointer conversions within the same address space must be performed with the bitcast instruction. Note that if the address space conversion is legal then both result and operand refer to the same memory location.

    This instruction must be used in lieu of a bitcast even if the cast is between types of the same size.

    The address spaces of the value and the destination pointer types must be distinct.

    Declaration

    Swift

    public func buildAddrSpaceCast(_ val: IRValue, type: IRType, name: String = "") -> IRValue

  • Build a truncate instruction to truncate the given value to the given type with a shorter width.

    Declaration

    Swift

    public func buildTrunc(_ val: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    val

    The value to truncate.
    type

    The destination type.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of truncating the given value to fit the given type.

  • Build a sign extension instruction to sign extend the given value to the given type with a wider width.

    Declaration

    Swift

    public func buildSExt(_ val: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    val

    The value to sign extend.
    type

    The destination type.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of sign extending the given value to fit the given type.

  • Build a zero extension instruction to zero extend the given value to the given type with a wider width.

    Declaration

    Swift

    public func buildZExt(_ val: IRValue, type: IRType, name: String = "") -> IRValue

    Parameters

    val

    The value to zero extend.
    type

    The destination type.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of zero extending the given value to fit the given type.

  • Build an integer-to-pointer instruction to convert the given value to the given pointer type.

    The inttoptr instruction converts the given value to the given pointer type by applying either a zero extension or a truncation depending on the size of the integer value. If value is larger than the size of a pointer then a truncation is done. If value is smaller than the size of a pointer then a zero extension is done. If they are the same size, nothing is done (no-op cast).

    Declaration

    Swift

    public func buildIntToPtr(_ val: IRValue, type: PointerType, name: String = "") -> IRValue

    Parameters

    val

    The integer value.
    type

    The destination pointer type.
    name

    The name for the newly inserted instruction.

    Return Value

    A pointer value representing the value of the given integer converted to the given pointer type.

  • Build a pointer-to-integer instruction to convert the given pointer value to the given integer type.

    The ptrtoint instruction converts the given pointer value to the given integer type by interpreting the pointer value as an integer and either truncating or zero extending that value to the size of the integer type. If the pointer value is smaller than the integer type then a zero extension is done. If the pointer value is larger than the integer type then a truncation is done. If they are the same size, then nothing is done (no-op cast) other than a type change.

    Declaration

    Swift

    public func buildPtrToInt(_ val: IRValue, type: IntType, name: String = "") -> IRValue

    Parameters

    val

    The pointer value.
    type

    The destination integer type.
    name

    The name for the newly inserted instruction.

    Return Value

    An integer value representing the value of the given pointer converted to the given integer type.

  • Build an integer-to-floating instruction to convert the given integer value to the given floating type.

    Declaration

    Swift

    public func buildIntToFP(_ val: IRValue, type: FloatType, signed: Bool, name: String = "") -> IRValue

    Parameters

    val

    The integer value.
    type

    The destination integer type.
    signed

    Whether the destination is a signed or unsigned integer.
    name

    The name for the newly inserted instruction.

    Return Value

    A floating value representing the value of the given integer converted to the given floating type.

  • Build a floating-to-integer instruction to convert the given floating value to the given integer type.

    Declaration

    Swift

    public func buildFPToInt(_ val: IRValue, type: IntType, signed: Bool, name: String = "") -> IRValue

    Parameters

    val

    The floating value.
    type

    The destination integer type.
    signed

    Whether the destination is a signed or unsigned integer.
    name

    The name for the newly inserted instruction.

    Return Value

    An integer value representing the value of the given float converted to the given integer type.

  • Build an expression that returns the difference between two pointer values, dividing out the size of the pointed-to objects.

    This is intended to implement C-style pointer subtraction. As such, the pointers must be appropriately aligned for their element types and pointing into the same object.

    Declaration

    Swift

    public func buildPointerDifference(_ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue

    Parameters

    lhs

    The first pointer (the minuend).
    rhs

    The second pointer (the subtrahend).
    name

    The name for the newly inserted instruction.

    Return Value

    A IRValue representing a 64-bit integer value of the difference of the two pointer values modulo the size of the pointed-to objects.

Type Information

  • Build a constant expression that returns the alignment of the given type in bytes.

    Declaration

    Swift

    public func buildAlignOf(_ val: IRType) -> IRValue

    Parameters

    val

    The type to evaluate the alignment of.

    Return Value

    An integer value representing the alignment of the given type in bytes.

  • Build a constant expression that returns the size of the given type in bytes.

    Declaration

    Swift

    public func buildSizeOf(_ val: IRType) -> IRValue

    Parameters

    val

    The type to evaluate the size of.

    Return Value

    An integer value representing the size of the given type in bytes.

Atomic Instructions

  • Build a fence instruction that introduces “happens-before” edges between operations.

    A fence A which has (at least) release ordering semantics synchronizes with a fence B with (at least) acquire ordering semantics if and only if there exist atomic operations X and Y, both operating on some atomic object M, such that A is sequenced before X, X modifies M (either directly or through some side effect of a sequence headed by X), Y is sequenced before B, and Y observes M. This provides a happens-before dependency between A and B. Rather than an explicit fence, one (but not both) of the atomic operations X or Y might provide a release or acquire (resp.) ordering constraint and still synchronize-with the explicit fence and establish the happens-before edge.

    A fence which has sequentiallyConsistent ordering, in addition to having both acquire and release semantics specified above, participates in the global program order of other sequentiallyConsistent operations and/or fences.

    Declaration

    Swift

    @discardableResult
public func buildFence(ordering: AtomicOrdering, singleThreaded: Bool = false, name: String = "") -> IRInstruction

    Parameters

    ordering

    Defines the kind of “synchronizes-with” edge this fence adds.
    singleThreaded

    Specifies that the fence only synchronizes with other atomics in the same thread. (This is useful for interacting with signal handlers.) Otherwise this fence is atomic with respect to all other code in the system.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing void.

  • Build an atomic compare-and-exchange instruction 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.

    Declaration

    Swift

    public func buildAtomicCmpXchg(
  ptr: IRValue, of old: IRValue, to new: IRValue,
  successOrdering: AtomicOrdering, failureOrdering: AtomicOrdering,
  singleThreaded: Bool = false
) -> IRValue

    Parameters

    ptr

    The address of data to update atomically.
    old

    The value to base the comparison on.
    new

    The new value to write if comparison with the old value returns true.
    successOrdering

    Specifies how this cmpxchg synchronizes with other atomic operations when it succeeds.
    failureOrdering

    Specifies how this cmpxchg synchronizes with other atomic operations when it fails.
    singleThreaded

    Specifies that this cmpxchg only synchronizes with other atomics in the same thread. (This is useful for interacting with signal handlers.) Otherwise this cmpxchg is atomic with respect to all other code in the system.

    Return Value

    A value representing the original value at the given location is together with a flag indicating success (true) or failure (false).

  • Build an atomic read-modify-write instruction to atomically modify memory.

    Declaration

    Swift

    public func buildAtomicRMW(
  atomicOp: AtomicReadModifyWriteOperation, ptr: IRValue, value: IRValue,
  ordering: AtomicOrdering, singleThreaded: Bool = false
) -> IRValue

    Parameters

    atomicOp

    The atomic operation to perform.
    ptr

    The address of a value to modify.
    value

    The second argument to the given operation.
    ordering

    Defines the kind of “synchronizes-with” edge this atomic operation adds.
    singleThreaded

    Specifies that this atomicRMW instruction only synchronizes with other atomics in the same thread. (This is useful for interacting with signal handlers.) Otherwise this atomicRMW is atomic with respect to all other code in the system.

    Return Value

    A value representing the old value of the given pointer before the atomic operation was executed.

C Standard Library Instructions

  • Build a call to the C standard library malloc instruction.

    (type *)malloc(sizeof(type));

    If count is provided, it is equivalent to:

    (type *)malloc(sizeof(type) * count);

    Declaration

    Swift

    public func buildMalloc(_ type: IRType, count: IRValue? = nil,
                        name: String = "") -> IRInstruction

    Parameters

    type

    The intended result type being allocated. The result of the malloc will be a pointer to this type.
    count

    An optional number of slots to allocate, to simulate a C array.
    name

    The intended name for the malloc‘d value.

  • Build a call to the C standard library free function, with the provided pointer.

    Declaration

    Swift

    @discardableResult
public func buildFree(_ ptr: IRValue) -> IRInstruction

    Parameters

    ptr

    The pointer to free.

    Return Value

    The free instruction.

Memory Intrinsics

  • Builds a call to the llvm.memset.* family of intrinsics to fill a given block of memory with a given byte value.

    Note

    Unlike the standard function memset defined in libc, llvm.memset does not return a value and may be volatile. The address space of the source and destination values need not match.

    Declaration

    Swift

    @discardableResult
public func buildMemset(
  to dest: IRValue, of value: IRValue, length: IRValue,
  alignment: Alignment, volatile: Bool = false
) -> IRInstruction

    Parameters

    dest

    A pointer value to the destination that will be filled.
    value

    A byte value to fill the destination with.
    length

    The number of bytes to fill.
    alignment

    The alignment of the destination pointer value.
    volatile

    If true, builds a volatile llvm.memset intrinsic, else builds a non-volatile llvm.memset instrinsic. The exact behavior of volatile memory intrinsics is platform-dependent and should not be relied upon to perform consistently. For more information, see the language reference’s section on Volatile Memory Access.

  • Builds a call to the llvm.memcpy.* family of intrinsics to copy a block of memory to a given destination memory location from a given source memory location.

    Warning

    It is illegal for the destination and source locations to overlap each other.

    Note

    Unlike the standard function memcpy defined in libc, llvm.memcpy does not return a value and may be volatile. The address space of the source and destination values need not match.

    Declaration

    Swift

    @discardableResult
public func buildMemCpy(
  to dest: IRValue, _ destAlign: Alignment,
  from src: IRValue, _ srcAlign: Alignment,
  length: IRValue, volatile: Bool = false
) -> IRInstruction

    Parameters

    dest

    A pointer to the destination that will be filled.
    destAlign

    The alignment of the destination pointer value.
    src

    A pointer to the source that will be copied from.
    srcAlign

    The alignment of the source pointer value.
    length

    The number of bytes to fill.
    volatile

    If true, builds a volatile llvm.memcpy intrinsic, else builds a non-volatile llvm.memcpy instrinsic. The exact behavior of volatile memory intrinsics is platform-dependent and should not be relied upon to perform consistently. For more information, see the language reference’s section on Volatile Memory Access.

  • Builds a call to the llvm.memmove.* family of intrinsics to move a block of memory to a given destination memory location from a given source memory location.

    Unlike llvm.memcpy.*, the destination and source memory locations may overlap with each other.

    Note

    Unlike the standard function memmove defined in libc, llvm.memmove does not return a value and may be volatile. The address space of the source and destination values need not match.

    Declaration

    Swift

    @discardableResult
public func buildMemMove(
  to dest: IRValue, _ destAlign: Alignment,
  from src: IRValue, _ srcAlign: Alignment,
  length: IRValue, volatile: Bool = false
) -> IRInstruction

    Parameters

    dest

    A pointer to the destination that will be filled.
    destAlign

    The alignment of the destination pointer value.
    src

    A pointer to the source that will be copied from.
    srcAlign

    The alignment of the source pointer value.
    length

    The number of bytes to fill.
    volatile

    If true, builds a volatile llvm.memmove intrinsic, else builds a non-volatile llvm.memmove instrinsic. The exact behavior of volatile memory intrinsics is platform-dependent and should not be relied upon to perform consistently. For more information, see the language reference’s section on Volatile Memory Access.

Aggregate Instructions

  • Build an instruction to insert a value into a member field in an aggregate value.

    Declaration

    Swift

    public func buildInsertValue(aggregate: IRValue, element: IRValue, index: Int, name: String = "") -> IRValue

    Parameters

    aggregate

    A value of array or structure type.
    element

    The value to insert.
    index

    The index at which at which to insert the value.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing an aggregate that has been updated with the given value at the given index.

  • Build an instruction to extract a value from a member field in an aggregate value.

    An extract value instruction differs from a get element pointer instruction because the value being indexed is not a pointer and the first index is unnecessary (as it is assumed to be zero).

    Declaration

    Swift

    public func buildExtractValue(aggregate: IRValue, index: Int, name: String = "") -> IRValue

    Parameters

    aggregate

    A value of array or structure type.
    index

    The index at which at which to extract a value.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing an aggregate that has been updated with the given value at the given index.

Vector Instructions

  • Build a vector insert instruction to nondestructively insert the given value into the given vector.

    Declaration

    Swift

    public func buildInsertElement(vector: IRValue, element: IRValue, index: IRValue, name: String = "") -> IRValue

    Parameters

    vector

    A value of vector type.
    element

    The value to insert.
    index

    The index at which to insert the value.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing a vector that has been updated with the given value at the given index.

  • Build an instruction to extract a single scalar element from a vector at a specified index.

    Declaration

    Swift

    public func buildExtractElement(vector: IRValue, index: IRValue, name: String = "") -> IRValue

    Parameters

    vector

    A value of vector type.
    index

    The index at which to insert the value.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing a scalar at the given index.

  • Build a vector shuffle instruction to construct a permutation of elements from the two given input vectors, returning a vector with the same element type as the inputs and length that is the same as the shuffle mask.

    The elements of the two input vectors are numbered from left to right across both of the vectors. The shuffle mask operand specifies, for each element of the result vector, which element of the two input vectors the result element gets. If the shuffle mask is undef, the result vector is also undef. If any element of the mask operand is undef, that element of the result is undef. If the shuffle mask selects an undef element from one of the input vectors, the resulting element is undef.

    Declaration

    Swift

    public func buildShuffleVector(_ vector1: IRValue, and vector2: IRValue, mask: IRValue, name: String = "") -> IRValue

    Parameters

    vector1

    The first vector to shuffle.
    vector2

    The second vector to shuffle.
    mask

    A constant vector of i32 values that acts as a mask for the shuffled vectors.

    Return Value

    A value representing a vector with the same element type as the inputs and length that is the same as the shuffle mask.

Global Variable Instructions

  • Build a named global of the given type.

    Declaration

    Swift

    public func addGlobal(_ name: String, type: IRType, addressSpace: AddressSpace = .zero) -> Global

    Parameters

    name

    The name of the newly inserted global value.
    type

    The type of the newly inserted global value.
    addressSpace

    The optional address space where the global variable resides.

    Return Value

    A value representing the newly inserted global variable.

  • Build a named global of the given type.

    Declaration

    Swift

    public func addGlobal(_ name: String, initializer: IRValue, addressSpace: AddressSpace = .zero) -> Global

    Parameters

    name

    The name of the newly inserted global value.
    initializer

    The initial value for the global variable.
    addressSpace

    The optional address space where the global variable resides.

    Return Value

    A value representing the newly inserted global variable.

  • Build a named global string consisting of an array of i8 type filled in with the nul terminated string value.

    Declaration

    Swift

    public func addGlobalString(name: String, value: String) -> Global

    Parameters

    name

    The name of the newly inserted global string value.
    value

    The character contents of the newly inserted global.

    Return Value

    A value representing the newly inserted global string variable.

  • Build a named global variable containing the characters of the given string value as an array of i8 type filled in with the nul terminated string value.

    Declaration

    Swift

    public func buildGlobalString(_ string: String, name: String = "") -> Global

    Parameters

    string

    The character contents of the newly inserted global.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the newly inserted global string variable.

  • Build a named global variable containing a pointer to the contents of the given string value.

    Declaration

    Swift

    public func buildGlobalStringPtr(_ string: String, name: String = "") -> IRValue

    Parameters

    string

    The character contents of the newly inserted global.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing a pointer to the newly inserted global string variable.

  • Build a named alias to a global value or a constant expression.

    Aliases, unlike function or variables, don’t create any new data. They are just a new symbol and metadata for an existing position.

    Declaration

    Swift

    public func addAlias(name: String, to aliasee: IRGlobal, type: IRType) -> Alias

    Parameters

    name

    The name of the newly inserted alias.
    aliasee

    The value or constant to alias.
    type

    The type of the aliased value or expression.

    Return Value

    A value representing the newly created alias.

Inline Assembly

  • Build a value representing an inline assembly expression (as opposed to module-level inline assembly).

    LLVM represents inline assembler as a template string (containing the instructions to emit), a list of operand constraints (stored as a string), and some flags.

    The template string supports argument substitution of the operands using “$” followed by a number, to indicate substitution of the given register/memory location, as specified by the constraint string. “${NUM:MODIFIER}” may also be used, where MODIFIER is a target-specific annotation for how to print the operand (see Asm Template Argument Modifiers).

    LLVM’s support for inline asm is modeled closely on the requirements of Clang’s GCC-compatible inline-asm support. Thus, the feature-set and the constraint and modifier codes are similar or identical to those in GCC’s inline asm support.

    However, the syntax of the template and constraint strings is not the same as the syntax accepted by GCC and Clang, and, while most constraint letters are passed through as-is by Clang, some get translated to other codes when converting from the C source to the LLVM assembly.

    Declaration

    Swift

    public func buildInlineAssembly(
  _ asm: String, dialect: InlineAssemblyDialect, type: FunctionType,
  constraints: String = "",
  hasSideEffects: Bool = true, needsAlignedStack: Bool = true
) -> IRValue

    Parameters

    asm

    The inline assembly expression template string.
    type

    The type of the parameters and return value of the assembly expression string.
    constraints

    A comma-separated string, each element containing one or more constraint codes.
    hasSideEffects

    Whether this inline asm expression has side effects. Defaults to false.
    needsAlignedStack

    Whether the function containing the asm needs to align its stack conservatively. Defaults to true.

    Return Value

    A representation of the newly created inline assembly expression.

Deprecated APIs

  • Build a load instruction that loads a value from the location in the given value.

    If alignment is not specified, or if zero, the target will choose a default value that is convenient and compatible with the type.

    Declaration

    Swift

    @available(*, deprecated, message: "Use buildLoad(_:type:ordering:volatile:alignment:name﹚ instead")
public func buildLoad(_ ptr: IRValue, ordering: AtomicOrdering = .notAtomic, volatile: Bool = false, alignment: Alignment = .zero, name: String = "") -> IRInstruction

    Parameters

    ptr

    The pointer value to load from.
    ordering

    The ordering effect of the fence for this load, if any. Defaults to a nonatomic load.
    volatile

    Whether this is a load from a volatile memory location.
    alignment

    The alignment of the access.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the result of a load from the given pointer value.

  • Build a GEP (Get Element Pointer) instruction suitable for indexing into a struct.

    Declaration

    Swift

    @available(*, deprecated, message: "Use buildStructGEP(_:type:index:name﹚ instead")
public func buildStructGEP(_ ptr: IRValue, index: Int, name: String = "") -> IRValue

    Parameters

    ptr

    The base address for the index calculation.
    index

    The offset from the base for the index calculation.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the address of a subelement of the given struct value.

  • Build a GEP (Get Element Pointer) instruction.

    The GEP instruction is often the source of confusion. LLVM provides a document to answer questions around its semantics and correct usage.

    Declaration

    Swift

    @available(*, deprecated, message: "Use buildGEP(_:type:indices:name﹚ instead")
public func buildGEP(_ ptr: IRValue, indices: [IRValue], name: String = "") -> IRValue

    Parameters

    ptr

    The base address for the index calculation.
    indices

    A list of indices that indicate which of the elements of the aggregate object are indexed.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the address of a subelement of the given aggregate data structure value.

  • Build a GEP (Get Element Pointer) instruction with a resultant value that is undefined if the address is outside the actual underlying allocated object and not the address one-past-the-end.

    The GEP instruction is often the source of confusion. LLVM provides a document to answer questions around its semantics and correct usage.

    Declaration

    Swift

    @available(*, deprecated, message: "Use buildInBoundsGEP(_:type:indices:name﹚ instead")
public func buildInBoundsGEP(_ ptr: IRValue, indices: [IRValue], name: String = "") -> IRValue

    Parameters

    ptr

    The base address for the index calculation.
    indices

    A list of indices that indicate which of the elements of the aggregate object are indexed.
    name

    The name for the newly inserted instruction.

    Return Value

    A value representing the address of a subelement of the given aggregate data structure value.