An address space is an identifier for a target-specific range of address values. An address space is a fundamental part of the type of a pointer value and the type of operations that manipulate memory.

LLVM affords a default address space (numbered zero) and places a number of assumptions on pointer values within that address space:

• The pointer must have a fixed integral value
• The null pointer has a bit-value of 0

These assumptions are not guaranteed to hold in any other address space. In particular, a target may allow pointers in non-default address spaces to have non-integral types. Non-integral pointer types represent pointers that have an unspecified bitwise representation; that is, the integral representation may be target dependent or have an unstable value. Further, outside of the default address space, it is not always the case that the null pointer value, especially as returned by IRType.constPointerNull() has a bit value of 0. e.g. A non-default address space may use an offset-based or segment-based addressing mode in which 0 is a valid, addressable pointer value.

Target-Level Address Space Overrides

A target may choose to override the default address space for code, data, and local allocations through the data layout string. This has multiple uses. For example, the address space of an alloca is only configurable via the data layout string, because it is a target-dependent property. There are also use-cases for overriding language standards e.g. the C standard requires the address-of operator applied to values on the stack to result in a pointer in the default address space. However, many OpenCL-based targets consider the stack to be a private region, and place such pointers in a non-default address space.

Care must be taken when interacting with these non-standard targets. The IR printer currently does not print anything when the default address space is attached to an instruction or value, and values will still report being assigned to that space. However, these values are still subject to the backend’s interpretation of the data layout string overrides and as such may not always reside in the default address space when it comes time to codegen them.

Restrictions

There are currently a number of artificial restrictions on values and operations that have non-default address spaces:

• A bitcast between two pointer values residing in different address spaces, even if those two values have the same size, is always an illegal operation. Use an addrspacecast instead or always use IRBuilder.buildPointerCast(of:to:name:) to get the correct operation.
• The so-called “null pointer” has a bit value that may differ from address space to address space. This exposes bugs in optimizer passes and lowerings that did not consider this possibility.
• A pointer value may not necessarily “round-trip” when converted between address spaces, even if annotated nonnull and dereferenceable. This is especially true of non-integral pointer types.
• Though the zero address space is the default, many backends and some errant passes interpret this to mean a “lack of address space” and may miscompile code with pointers in mixed address spaces.
• A number of intriniscs that operate on memory currently do not support a non-default address space.
• The address space is ultimately an integer value and in theory an address space identifier may take on any value. In practice, LLVM guarantees only 24 bits of precision, though higher address space identifiers may succeed in being properly represented.

See more

public struct AddressSpace : Equatable

An Alias represents a global alias in an LLVM module - a new symbol and corresponding metadata for an existing global value.

An Alias, unlike a function or global variable declaration, does not create any new data in the resulting object file. It is merely a new name for an existing symbol or constant. The aliased value (the aliasee) must be either another global value like a function, global variable, or even another alias, or it must be a constant expression.

Linkers make no guarantees that aliases will be preserved in the final object file. Aliases where the address is known to be relevant should be marked with the appropriate UnnamedAddressKind value. If this value is not none, the alias is guaranteed to have the same address as the aliasee. Else, the alias is guaranteed to point to the same content as the aliasee, but may reside at a different address.

If the aliasee is a constant value, LLVM places additional restrictions on its content in order to maintain compatibility with the expected behavior of most linkers:

• The constant expression may not involve aliases with weak linkage. Such weak aliases cannot be guaranteed to be stable in the final object file.
• The constant expression may not involve global values requiring a relocation such as a global function or global variable declared but not defined within its module.

See more

public struct Alias : IRGlobal

A value implementing arbitrary precision integer arithmetic.

APInt is a functional replacement for common case unsigned integer type like UInt or UInt64, but also allows non-byte-width integer sizes and large integer value types such as 3-bits, 15-bits, or more than 64-bits of precision. APInt provides a variety of arithmetic operators and methods to manipulate integer values of any bit-width. It supports both the typical integer arithmetic and comparison operations as well as bitwise manipulation.

See more

public struct APInt : IRConstant

extension APInt: Comparable

extension APInt: Numeric

ArrayType is a very simple derived type that arranges elements sequentially in memory. ArrayType requires a size (number of elements) and an underlying data type.

See more

public struct ArrayType : IRType

extension ArrayType: Equatable

A BasicBlock represents a basic block in an LLVM IR program. A basic block contains a sequence of instructions, a pointer to its parent block and its follower block, and an optional label that gives the basic block an entry in the symbol table. Because of this label, the type of every basic block is LabelType.

A basic block can be thought of as a sequence of instructions, and indeed its member instructions may be iterated over with a for-in loop. A well- formed basic block has as its last instruction a “terminator” that produces a transfer of control flow and possibly yields a value. All other instructions in the middle of the basic block may not be “terminator” instructions. Basic blocks are not required to be well-formed until code generation is complete.

Creating a Basic Block

By default, the initializer for a basic block merely creates the block but does not associate it with a function.

let module = Module(name: "Example")
let fun = builder.addFunction("example",
                              type: FunctionType([], VoidType()))

// This basic block is "floating" outside of a function.
let floatingBB = BasicBlock(name: "floating")
// Until we associate it with a function by calling `Function.append(_:)`.
fun.append(floatingBB)

A basic block may be created and automatically inserted at the end of a function by calling Function.appendBasicBlock(named:in:).

let module = Module(name: "Example")
let fun = builder.addFunction("example",
                              type: FunctionType([], VoidType()))

// This basic block is "attached" to the example function.
let attachedBB = fun.appendBasicBlock(named: "attached")

The Address of a Basic Block

Basic blocks (except the entry block) may have their labels appear in the symbol table. Naturally, these labels are associated with address values in the final object file. The value of that address may be accessed for the purpose of an indirect call or a direct comparisson by calling Function.address(of:) and providing one of the function’s child blocks as an argument. Providing any other basic block outside of the function as an argument value is undefined.

The Entry Block

The first basic block (the entry block) in a Function is special:

• The entry block is immediately executed when the flow of control enters its parent function.
• The entry block is not allowed to have predecessor basic blocks (i.e. there cannot be any branches to the entry block of a function).
• The address of the entry block is not a well-defined value.
• The entry block cannot have PHI nodes. This is enforced structurally, as the entry block can have no predecessor blocks to serve as operands to the PHI node.
• Static alloca instructions situated in the entry block are treated specially by most LLVM backends. For example, FastISel keeps track of static alloca values in the entry block to more efficiently reference them from the base pointer of the stack frame.

See more

public struct BasicBlock : IRValue

extension BasicBlock: Equatable

Represents a simple function call.

See more

public struct Call : IRInstruction

Represents a function call that may transfer control to an exception handler.

See more

public struct Invoke : IRInstruction

A Constant represents a value initialized to a constant. Constant values may be manipulated with standard Swift arithmetic operations and used with standard IR Builder instructions like any other operand. The difference being any instructions acting solely on constants and any arithmetic performed on constants is evaluated at compile-time only.

Constants keep track of the values they represent at the type level to disallow mixed-type arithmetic. Use the cast family of operations to safely convert constants to other representations.

See more

public struct Constant<Repr> : IRConstant where Repr : ConstantRepresentation

FloatType enumerates representations of a floating value of a particular bit width and semantics.

See more

public struct FloatType : IRType

extension FloatType: Equatable

An “enum” (a.k.a. target-independent) attribute.

See more

public struct EnumAttribute : Attribute

A “string” (a.k.a. target-dependent) attribute.

See more

public struct StringAttribute : Attribute

A Parameter represents an index into the parameters of a Function.

See more

public struct Parameter : IRValue

FunctionType represents a function’s type signature. It consists of a return type and a list of formal parameter types. The return type of a function type is a void type or first class type — except for LabelType and MetadataType.

See more

public struct FunctionType : IRType

extension FunctionType: Equatable

A DebugLocation represents a location in source.

Debug locations are de-duplicated by file and line. If more than one location inside a given scope needs to share a line, a discriminator value must be set or those locations will be considered equivalent.

See more

public struct DebugLocation : IRMetadata

CompileUnitMetadata nodes represent a compile unit, the root of a metadata hierarchy for a translation unit.

Compile unit descriptors provide the root scope for objects declared in a specific compilation unit. FileMetadata descriptors are defined using this scope.

These descriptors are collected by a named metadata node !llvm.dbg.cu. They keep track of global variables, type information, and imported entities (declarations and namespaces).

See more

public struct CompileUnitMetadata : DIScope

FileMetadata nodes represent files.

The file name does not necessarily have to be a proper file path. For example, it can include additional slash-separated path components.

See more

public struct FileMetadata : DIScope

DIBasicType nodes represent primitive types, such as int, bool and float.

Basic types carry an encoding describing the details of the type to influence how it is presented in debuggers. LLVM currently supports specific DWARF “Attribute Type Encodings” that are enumerated in DIAttributeTypeEncoding.

See more

public struct DIBasicType : DIType

DISubroutineType nodes represent subroutine types.

Subroutine types are meant to mirror their formal declarations in source: arguments are represented in order. The return type is optional and meant to represent the concept of void in C-like languages.

See more

public struct DISubroutineType : DIType

LexicalBlockMetadata nodes describe nested blocks within a subprogram. The line number and column numbers are used to distinguish two lexical blocks at same depth.

Usually lexical blocks are distinct to prevent node merging based on operands.

See more

public struct LexicalBlockMetadata : DIScope

LexicalBlockFile nodes are used to discriminate between sections of a lexical block. The file field can be changed to indicate textual inclusion, or the discriminator field can be used to discriminate between control flow within a single block in the source language.

See more

public struct LexicalBlockFileMetadata : DIScope

LocalVariableMetadata nodes represent local variables and function parameters in the source language.

See more

public struct LocalVariableMetadata : IRMetadata

ObjectiveCPropertyMetadata nodes represent Objective-C property nodes.

See more

public struct ObjectiveCPropertyMetadata : IRMetadata

ImportedEntityMetadata nodes represent entities (such as modules) imported into a compile unit.

See more

public struct ImportedEntityMetadata : DIType

NameSpaceMetadata nodes represent subroutines in the source program. They are attached to corresponding LLVM IR functions.

See more

public struct FunctionMetadata : DIScope

NameSpaceMetadata nodes represent entities like C++ modules.

See more

public struct ModuleMetadata : DIScope

NameSpaceMetadata nodes represent entities like C++ namespaces.

See more

public struct NameSpaceMetadata : DIScope

MDString nodes represent string constants in metadata nodes.

See more

public struct MDString : IRMetadata, ExpressibleByStringLiteral

MDNode objects represent generic nodes in a metadata graph.

A metadata node is a tuple of references to other metadata. In general, metadata graphs are acyclic and terminate in metadata nodes without operands.

See more

public struct MDNode : IRMetadata

ExpressionMetadata nodes represent expressions that are inspired by the DWARF expression language. They are used in debug intrinsics (such as llvm.dbg.declare and llvm.dbg.value) to describe how the referenced LLVM variable relates to the source language variable.

Debug intrinsics are interpreted left-to-right: start by pushing the value/address operand of the intrinsic onto a stack, then repeatedly push and evaluate opcodes from the ExpressionMetadata until the final variable description is produced.

Though DWARF supports hundreds of expressions, LLVM currently implements a very limited subset.

See more

public struct ExpressionMetadata : IRMetadata

An Instruction represents an instruction residing in a basic block.

See more

public struct Instruction : IRInstruction

A TerminatorInstruction represents an instruction that terminates a basic block.

See more

public struct TerminatorInstruction : IRInstruction

The IntType represents an integral value of a specified bit width.

The IntType is a very simple type that simply specifies an arbitrary bit width for the integer type desired. Any bit width from 1 bit to (2^23)-1 (about 8 million) can be specified.

See more

public struct IntType : IRType

extension IntType: Equatable

LabelType represents code labels.

See more

public struct LabelType : IRType

extension LabelType: Equatable

Represents a single field in a (C or C++) struct.

See more

public struct TBAAStructField

Enumerates the known attributes that can appear on an Objective-C property.

See more

public struct ObjectiveCPropertyAttribute : OptionSet

Enumerates a set of flags that can be applied to metadata nodes to change their interpretation at compile time or attach additional semantic significance at runtime.

See more

public struct DIFlags : OptionSet

The MetadataType type represents embedded metadata. No derived types may be created from metadata except for function arguments.

See more

public struct MetadataType : IRType

extension MetadataType: Equatable

A Section represents one of the binary sections in an object file.

See more

public struct Section

A symbol is a top-level addressable entity in an object file.

See more

public struct Symbol

A Relocation represents the contents of a relocated symbol in the dynamic linker.

See more

public struct Relocation

A PhiNode object represents a PHI node.

Because all instructions in LLVM IR are in SSA (Single Static Assignment) form, a PHI node is necessary when the value of a variable assignment depends on the path the flow of control takes through the program. For example:

var a = 1
if c == 42 {
  a = 2
}
let b = a

The value of b in this program depends on the value of the condition involving the variable c. Because b must be assigned to once, a PHI node is created and the program effectively is transformed into the following:

let aNoCond = 1
if c == 42 {
  let aCondTrue = 2
}
let b = PHI(aNoCond, aCondTrue)

If the flow of control reaches aCondTrue, the value of b is 2, else it is 1 and SSA semantics are preserved.

See more

public struct PhiNode : IRInstruction

PointerType is used to specify memory locations. Pointers are commonly used to reference objects in memory.

PointerType may have an optional address space attribute defining the numbered address space where the pointed-to object resides. The default address space is number zero. The semantics of non-zero address spaces are target-specific.

Note that LLVM does not permit pointers to void (void*) nor does it permit pointers to labels (label*). Use i8* instead.

See more

public struct PointerType : IRType

extension PointerType: Equatable

StructType is used to represent a collection of data members together in memory. The elements of a structure may be any type that has a size.

Structures in memory are accessed using load and store by getting a pointer to a field with the ‘getelementptr‘ instruction. Structures in registers are accessed using the extractvalue and insertvalue instructions.

Structures may optionally be “packed” structures, which indicate that the alignment of the struct is one byte, and that there is no padding between the elements. In non-packed structs, padding between field types is inserted as defined by the DataLayout of the module, which is required to match what the underlying code generator expects.

Structures can either be “literal” or “identified”. A literal structure is defined inline with other types (e.g. {i32, i32}*) whereas identified types are always defined at the top level with a name. Literal types are uniqued by their contents and can never be recursive or opaque since there is no way to write one. Identified types can be recursive, can be opaqued, and are never uniqued.

See more

public struct StructType : IRType

extension StructType: Equatable

A Switch represents a switch instruction. A switch instruction defines a jump table of values and destination basic blocks to pass the flow of control to if a condition value matches. If no match is made, control flow passes to the default basic block.

See more

public struct Switch : IRInstruction

A StructLayout encapsulates information about the layout of a StructType.

See more

public struct StructLayout

TokenType is used when a value is associated with an instruction but all uses of the value must not attempt to introspect or obscure it. As such, it is not appropriate to have a PHI or select of type TokenType.

See more

public struct TokenType : IRType

extension TokenType: Equatable

A Triple provides an abstraction over “Target Triples”.

A Target Triple encodes information about the target of a compilation session including the underlying processor architecture, OS, platform vendor, and additional information about the runtime environment.

A target triple is usually specified at the command line as a - delimited string in the format:

<arch><sub>-<vendor>-<sys>-<abi>

For example:

nvptx64-nvidia-cuda
x86_64-unknown-linux-gnu
x86_64-apple-ios8.3-simulator

For this reason, Triple provides an initializer that parses strings in this format.

See more

public struct Triple : Equatable

An alignment value, expressed in bytes.

See more

public struct Alignment : Comparable, Hashable

This is an opaque type for sizes expressed in aggregate bit units, usually 8 bits per unit.

Instances of this type represent a quantity as a multiple of a radix size

• e.g. the size of a char in bits on the target architecture. As an opaque type, Size protects you from accidentally combining operations on quantities in bit units and size units.

For portability, never assume that a target radix is 8 bits wide. Use Size values wherever you calculate sizes and offsets.

See more

public struct Size

extension Size: UnsignedInteger

Use represents an iterator over the uses and users of a particular value in an LLVM program.

See more

public struct Use

A VectorType is a simple derived type that represents a vector of elements. VectorTypes are used when multiple primitive data are operated in parallel using a single instruction (SIMD). A vector type requires a size (number of elements) and an underlying primitive data type.

See more

public struct VectorType : IRType

extension VectorType: Equatable

The Void type represents any value and has no size.

See more

public struct VoidType : IRType

extension VoidType: Equatable

X86MMXType represents a value held in an MMX register on an x86 machine.

The operations allowed on it are quite limited: parameters and return values, load and store, and bitcast. User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type. There are no arrays, vectors or constants of this type.

See more

public struct X86MMXType : IRType

extension X86MMXType: Equatable