IRBuilder
public class IRBuilder
An IRBuilder is a helper object that generates LLVM instructions. IR
Builders keep track of a position within a function or basic block and has
methods to insert instructions at that position.
-
Repositions the IR Builder at the end of the given basic block.
Declaration
Swift
public func positionAtEnd(of block: BasicBlock)Parameters
blockThe 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: IRValue)Parameters
instThe 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 callingpositionBefore(_:)with the given instruction.Declaration
Swift
public func position(_ inst: IRValue, block: BasicBlock)Parameters
instThe instruction to reposition the IR Builder before.
blockThe 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? -
Gets the function this builder is building into.
Declaration
Swift
public var currentFunction: Function? -
Inserts the given instruction into the IR Builder.
Declaration
Swift
public func insert(_ inst: IRValue, name: String? = nil)Parameters
instThe instruction to insert.
nameThe name for the newly inserted instruction.
-
Builds 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.
name: The name for the newly inserted instruction.
Declaration
Swift
public func buildNeg(_ value: IRValue, overflowBehavior: OverflowBehavior = .default, name: String = "") -> IRValueParameters
valueThe value to negate.
overflowBehaviorShould overflow occur, specifies the behavior of the program.
Return Value
A value representing the negation of the given value.
-
Builds 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 = "") -> IRValueParameters
lhsThe first summand value (the augend).
rhsThe second summand value (the addend).
overflowBehaviorShould overflow occur, specifies the behavior of the program.
nameThe name for the newly inserted instruction.
Return Value
A value representing the sum of the two operands.
-
Builds 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 = "") -> IRValueParameters
lhsThe first value (the minuend).
rhsThe second value (the subtrahend).
overflowBehaviorShould overflow occur, specifies the behavior of the program.
nameThe name for the newly inserted instruction.
Return Value
A value representing the difference of the two operands.
-
Builds 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 = "") -> IRValueParameters
lhsThe first factor value (the multiplier).
rhsThe second factor value (the multiplicand).
overflowBehaviorShould overflow occur, specifies the behavior of the program.
nameThe 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
Parameters
lhsThe first value (the dividend).
rhsThe second value (the divisor).
signedWhether to emit a signed or unsigned remainder instruction. Defaults to emission of a signed remainder instruction.
nameThe 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
Parameters
lhsThe first value (the dividend).
rhsThe second value (the divisor).
signedWhether to emit a signed or unsigned remainder instruction. Defaults to emission of a signed divide instruction.
exactWhether this division must be exact. Defaults to inexact.
nameThe 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.
Attempting to compare operands that are not integers is a fatal condition.
Declaration
Swift
public func buildICmp(_ lhs: IRValue, _ rhs: IRValue, _ predicate: IntPredicate, name: String = "") -> IRValueParameters
lhsThe first value to compare.
rhsThe second value to compare.
predicateThe method of comparison to use.
nameThe 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 = "") -> IRValueParameters
lhsThe first value to compare.
rhsThe second value to compare.
predicateThe method of comparison to use.
nameThe name for the newly inserted instruction.
Return Value
A value representing the result of the comparision of the given operands.
-
Builds a bitwise logical not with the given value as an operand.
Parameters
valThe value to negate.
nameThe name for the newly inserted instruction.
Return Value
A value representing the logical negation of the given operand.
-
Builds a bitwise logical exclusive OR with the given values as operands.
Declaration
Parameters
lhsThe first operand.
rhsThe second operand.
nameThe name for the newly inserted instruction.
Return Value
A value representing the exclusive OR of the values of the two given operands.
-
Builds a bitwise logical OR with the given values as operands.
Parameters
lhsThe first operand.
rhsThe second operand.
nameThe name for the newly inserted instruction.
Return Value
A value representing the logical OR of the values of the two given operands.
-
Builds a bitwise logical AND with the given values as operands.
Declaration
Parameters
lhsThe first operand.
rhsThe second operand.
nameThe name for the newly inserted instruction.
Return Value
A value representing the logical AND of the values of the two given operands.
-
Builds a left-shift instruction of the first value by an amount in the second value.
Declaration
Parameters
lhsThe first operand.
rhsThe number of bits to shift the first operand left by.
nameThe 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.
-
Builds a right-shift instruction of the first value by an amount in the second value. If
isArithmeticis true the value of the first operand is bitshifted with sign extension. Else the value is bitshifted with zero-fill.Declaration
Parameters
lhsThe first operand.
rhsThe number of bits to shift the first operand right by.
isArithmeticWhether this instruction performs an arithmetic or logical right-shift. The default is a logical right-shift.
nameThe 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.
-
Build a phi node with the given type acting as the result of any incoming basic blocks.
Parameters
typeThe type of incoming values.
nameThe 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
Parameters
condThe condition to evaluate. It must have type
i1or be a vector ofi1.thenThe value to select if the given condition is true.
elseThe value to select if the given condition is false.
nameThe 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.
Declaration
Swift
public func buildSwitch(_ value: IRValue, else: BasicBlock, caseCount: Int) -> SwitchParameters
valueThe value to compare.
elseThe default destination for control flow should the value not match a case in the branch table.
caseCountThe number of cases in the branch table.
Return Value
A value representing the newly inserted
switchinstruction.
-
Build a named function body with the given type.
Declaration
Swift
public func addFunction(_ name: String, type: FunctionType) -> FunctionParameters
nameThe name of the newly defined function.
typeThe 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) -> StructTypeParameters
nameThe name of the structure.
typesThe type of fields that make up the structure’s body.
isPackedWhether this structure should be 1-byte aligned with no padding between elements.
Return Value
A value representing the newly declared named structure.
-
Build an unconditional branch to the given basic block.
Declaration
Swift
public func buildBr(_ block: BasicBlock) -> IRValueParameters
blockThe 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.Declaration
Swift
public func buildCondBr(condition: IRValue, then: BasicBlock, `else`: BasicBlock) -> IRValueParameters
conditionA value of type
i1that determines which basic block to transfer control flow to.thenThe basic block to transfer control flow to if the condition evaluates to
true.elseThe 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.
Declaration
Swift
public func buildIndirectBr(address: BasicBlock.Address, destinations: [BasicBlock]) -> IRValueParameters
addressThe address of the label to branch to.
destinationsThe 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. -
Builds a void return from the current function.
Declaration
Swift
public func buildRetVoid() -> IRValueReturn Value
A value representing
void. -
Builds an unreachable instruction in the current function.
Declaration
Swift
public func buildUnreachable() -> IRValueReturn 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.
Parameters
valuesThe 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
Parameters
fnThe function to invoke.
argsA list of arguments.
nameThe name for the newly inserted instruction.
Return Value
A value representing
void.
-
Build an
allocato allocate stack memory to hold a value of the given type.Parameters
typeThe sized type used to determine the amount of stack memory to allocate.
nameThe name for the newly inserted instruction.
Return Value
A value representing
void. -
Builds a load instruction that loads a value from the location in the given value.
Parameters
ptrThe pointer value to load from.
nameThe name for the newly inserted instruction.
Return Value
A value representing the result of a load from the given pointer value.
-
Builds 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
GEPinstruction is often the source of confusion. LLVM provides a document to answer questions around its semantics and correct usage.Declaration
Parameters
ptrThe base address for the index calculation.
indicesA list of indices that indicate which of the elements of the aggregate object are indexed.
nameThe name for the newly inserted instruction.
Return Value
A value representing the address of a subelement of the given aggregate data structure value.
-
Builds a GEP (Get Element Pointer) instruction.
The
GEPinstruction is often the source of confusion. LLVM provides a document to answer questions around its semantics and correct usage.Declaration
Parameters
ptrThe base address for the index calculation.
indicesA list of indices that indicate which of the elements of the aggregate object are indexed.
nameThe name for the newly inserted instruction.
Return Value
A value representing the address of a subelement of the given aggregate data structure value.
-
Builds a GEP (Get Element Pointer) instruction suitable for indexing into a struct.
Declaration
Parameters
ptrThe base address for the index calculation.
indexThe offset from the base for the index calculation.
nameThe name for the newly inserted instruction.
Return Value
A value representing the address of a subelement of the given struct value.
-
Builds an ExtractElement instruction to retrieve an indexed value from a vector value.
Declaration
Parameters
vecThe vector you’re indexing into.
indexThe index at which to extract.
Return Value
The value in the vector at the provided index.
-
Builds an ExtractValue instruction to retrieve an indexed value from a struct or array value.
Declaration
Parameters
valueThe struct or array you’re indexing into.
indexThe index at which to extract.
Return Value
The value in the struct at the provided index.
-
Builds a comparision instruction that returns whether the given operand is
null.Parameters
valThe value to test.
nameThe name for the newly inserted instruction.
Return Value
An
i1value representing the result of a test to see if the value isnull`. -
Builds a comparision instruction that returns whether the given operand is not
null.Parameters
valThe value to test.
nameThe name for the newly inserted instruction.
Return Value
An
i1value representing the result of a test to see if the value is notnull`.
-
Builds an instruction that either performs a truncation or a bitcast of the given value to a value of the given type.
Declaration
Parameters
valThe value to cast or truncate.
typeThe destination type.
nameThe 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.
-
Builds a bitcast instruction to convert the given value to a value of the given type by just copying the bit pattern.
Declaration
Parameters
valThe value to bitcast.
typeThe destination type.
nameThe name for the newly inserted instruction.
Return Value
A value representing the result of bitcasting the given value to fit the given type.
-
Builds a cast instruction to convert the given floating-point value to a value of the given type.
Declaration
Parameters
valThe value to cast.
typeThe destination type.
nameThe name for the newly inserted instruction.
Return Value
A value representing the result of casting the given value to fit the given type.
-
Builds an address space cast instruction that converts a pointer value to a given type in a different address space.
The address spaces of the value and the destination pointer types must be distinct.
-
Builds a truncate instruction to truncate the given value to the given type with a shorter width.
Declaration
Parameters
valThe value to truncate.
typeThe destination type.
nameThe name for the newly inserted instruction.
Return Value
A value representing the result of truncating the given value to fit the given type.
-
Builds a sign extension instruction to sign extend the given value to the given type with a wider width.
Parameters
valThe value to sign extend.
typeThe destination type.
nameThe name for the newly inserted instruction.
Return Value
A value representing the result of sign extending the given value to fit the given type.
-
Builds a zero extension instruction to zero extend the given value to the given type with a wider width.
Parameters
valThe value to zero extend.
typeThe destination type.
nameThe name for the newly inserted instruction.
Return Value
A value representing the result of zero extending the given value to fit the given type.
-
Builds an integer-to-pointer instruction to convert the given value to the given pointer type.
Declaration
Swift
public func buildIntToPtr(_ val: IRValue, type: PointerType, name: String = "") -> IRValueParameters
valThe integer value.
typeThe destination pointer type.
nameThe name for the newly inserted instruction.
Return Value
A pointer value representing the value of the given integer converted to the given pointer type.
-
Builds a pointer-to-integer instruction to convert the given pointer value to the given integer type.
Declaration
Parameters
valThe pointer value.
typeThe destination integer type.
nameThe name for the newly inserted instruction.
Return Value
An integer value representing the value of the given pointer converted to the given integer type.
-
Builds an integer-to-floating instruction to convert the given integer value to the given floating type.
Declaration
Parameters
valThe integer value.
typeThe destination integer type.
signedWhether the destination is a signed or unsigned integer.
nameThe name for the newly inserted instruction.
Return Value
A floating value representing the value of the given integer converted to the given floating type.
-
Builds a floating-to-integer instruction to convert the given floating value to the given integer type.
Declaration
Parameters
valThe floating value.
typeThe destination integer type.
signedWhether the destination is a signed or unsigned integer.
nameThe name for the newly inserted instruction.
Return Value
An integer value representing the value of the given float converted to the given integer type.
-
Builds 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
Parameters
lhsThe first pointer (the minuend).
rhsThe second pointer (the subtrahend).
nameThe 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.
-
Builds a fence instruction that introduces
happens-before
edges between operations.Declaration
Swift
public func buildFence(ordering: AtomicOrdering, singleThreaded: Bool = false, name: String = "") -> IRValueParameters
orderingDefines the kind of “synchronizes-with” edge this fence adds.
singleThreadedSpecifies 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.
nameThe name for the newly inserted instruction.
Return Value
A value representing
void. -
Builds 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 ) -> IRValueParameters
ptrThe address of data to update atomically.
oldThe value to base the comparison on.
newThe new value to write if comparison with the old value returns true.
successOrderingSpecifies how this cmpxchg synchronizes with other atomic operations when it succeeds.
failureOrderingSpecifies how this cmpxchg synchronizes with other atomic operations when it fails.
singleThreadedSpecifies 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).
-
Builds 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 ) -> IRValueParameters
atomicOpThe atomic operation to perform.
ptrThe address of a value to modify.
valueThe second argument to the given operation.
orderingDefines the kind of “synchronizes-with” edge this atomic operation adds.
singleThreadedSpecifies 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.
-
Builds a call to the C standard library
mallocinstruction.(type *)malloc(sizeof(type));Ifcountis provided, it is equivalent to:(type *)malloc(sizeof(type) * count);Declaration
Parameters
typeThe intended result type being allocated. The result of the
mallocwill be a pointer to this type.countAn optional number of slots to allocate, to simulate a C array. This is equivalent to
nameThe intended name for the
malloc’d value.
-
Builds an instruction to insert a value into a member field in an aggregate value.
Declaration
Parameters
aggregateA value of array or structure type.
elementThe value to insert.
indexThe index at which at which to insert the value.
nameThe 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.
-
Builds a vector insert instruction to nondestructively insert the given value into the given vector.
Declaration
Parameters
vectorA value of vector type.
elementThe value to insert.
indexThe index at which to insert the value.
nameThe 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.
-
Builds an instruction to extract a single scalar element from a vector at a specified index.
Declaration
Parameters
vectorA value of vector type.
indexThe index at which to insert the value.
nameThe name for the newly inserted instruction.
Return Value
A value representing a scalar at the given index.
-
Build a named global of the given type.
Declaration
Parameters
nameThe name of the newly inserted global value.
typeThe type of the newly inserted global value.
addressSpaceThe 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
i8type filled in with the nul terminated string value.Declaration
Swift
public func addGlobalString(name: String, value: String) -> GlobalParameters
nameThe name of the newly inserted global string value.
valueThe character contents of the newly inserted global.
Return Value
A value representing the newly inserted global string variable.
-
Builds a named global variable containing the characters of the given string value as an array of
i8type filled in with the nul terminated string value.Declaration
Swift
public func buildGlobalString(_ string: String, name: String = "") -> GlobalParameters
stringThe character contents of the newly inserted global.
nameThe name for the newly inserted instruction.
Return Value
A value representing the newly inserted global string variable.
-
Builds a named global variable containing a pointer to the contents of the given string value.
Declaration
Swift
public func buildGlobalStringPtr(_ string: String, name: String = "") -> IRValueParameters
stringThe character contents of the newly inserted global.
nameThe name for the newly inserted instruction.
Return Value
A value representing a pointer to the newly inserted global string variable.
-
Builds 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.
Parameters
nameThe name of the newly inserted alias.
aliaseeThe value or constant to alias.
typeThe type of the aliased value or expression.
Return Value
A value representing the newly created alias.
IRBuilder Class Reference